Learn how to configure Hashicorp Vault with Authentik OIDC authentication, including multi-group access control with admin and reader roles for secure secrets management.

1. Overview - Understanding the integration
2. Prerequisites - What you need before starting
3. Authentik Configuration - Setting up the OIDC provider
4. Vault Configuration - Enabling and configuring OIDC auth
5. Policy Creation - Creating admin and reader policies
6. Role Configuration - Setting up roles with group claims
7. External Groups - Managing group membership via Authentik
8. Testing - Verifying the configuration
9. Troubleshooting - Common issues and solutions

Overview

This guide demonstrates how to configure Hashicorp Vault with Authentik OIDC authentication, providing secure access control with different permission levels. The setup includes:

• Admin Role: Full access to all Vault paths and operations
• Reader Role: Read-only access to key-value secrets
• External Group Management: Group membership controlled through Authentik
• OIDC Authentication: Modern, secure authentication flow

This configuration is ideal for organizations using Authentik as their identity provider and needing granular access control to Hashicorp Vault secrets.

1. PREREQUISITES

Before starting this configuration, ensure you have:

• Hashicorp Vault: Running instance with admin access
• Authentik Instance: Configured and accessible
• Network Access: Vault and Authentik can communicate
• Admin Credentials: Access to both Vault and Authentik admin interfaces

Required Information:

• Authentik FQDN (e.g., authentik.company.com)
• Vault FQDN (e.g., vault.company.com)
• Authentik OIDC client credentials (will be created during setup)

2. AUTHENTIK CONFIGURATION

First, create an OIDC application and provider in Authentik:

Step 1: Create OIDC Application

1. Log into Authentik as an administrator
2. Navigate to Applications > Applications
3. Click Create with Provider
4. Configure the application:
   • Name: Hashicorp Vault
   • Provider Type: OAuth2/OpenID Connect
   • Authorization Flow: Choose an appropriate flow (e.g., Authorization Code)

Step 2: Configure OIDC Provider

Configure the OIDC provider with these settings:

• Name: Vault OIDC Provider
• Client ID: Note this value (will be used in Vault configuration)
• Client Secret: Note this value (will be used in Vault configuration)
• Redirect URIs: Add these three URIs:
  • https://vault.company.com/ui/vault/auth/oidc/oidc/callback
  • https://vault.company.com/oidc/callback
  • http://localhost:8250/oidc/callback

Step 3: Enable Group Claims

In the OIDC provider settings, under Advanced protocol settings:

• Add authentik default OAuth Mapping: OpenID 'profile' to include group mapping

Note: Save the Client ID, Client Secret, and application slug for use in the Vault configuration.

3. VAULT CONFIGURATION

Now configure Vault to use Authentik OIDC authentication:

Step 1: Enable OIDC Auth Method

vault auth enable oidc

Step 2: Configure OIDC Auth Method

vault write auth/oidc/config \
         oidc_discovery_url="https://authentik.company.com/application/o/<application_slug>/" \
         oidc_client_id="<idp_client_id>" \
         oidc_client_secret="<idp_secret>" \
         default_role="admin"

Replace the placeholders:

• <application_slug>: The slug from your Authentik application
• <idp_client_id>: The Client ID from Authentik
• <idp_secret>: The Client Secret from Authentik

4. POLICY CREATION

Create the necessary policies for admin and reader access:

Step 1: Create Admin Policy

cat > admin.hcl <<EOF
path "*" {
capabilities = ["sudo","read","create","update","delete","list","patch"]
}
EOF
vault policy write admin admin.hcl

Step 2: Create Reader Policy

cat > reader.hcl <<EOF
path "kv/*" {
capabilities = ["read", "list"]
}
EOF
vault policy write reader reader.hcl

Policy Breakdown:

• Admin Policy: Full access to all Vault paths with all capabilities
• Reader Policy: Read-only access to key-value secrets in the kv/ path

5. ROLE CONFIGURATION

Configure OIDC roles with group claims for access control:

Step 1: Create Reader Role

vault write auth/oidc/role/reader \
      bound_audiences="<idp_client_id>" \
      allowed_redirect_uris="https://vault.company.com/ui/vault/auth/oidc/oidc/callback" \
      allowed_redirect_uris="https://vault.company.com/oidc/callback" \
      allowed_redirect_uris="http://localhost:8250/oidc/callback" \
      user_claim="sub" \
      policies="reader" \
      groups_claim="groups" \
      oidc_scopes="openid,profile,email"

Step 2: Create Admin Role

vault write auth/oidc/role/admin \
      bound_audiences="<idp_client_id>" \
      allowed_redirect_uris="https://vault.company.com/ui/vault/auth/oidc/oidc/callback" \
      allowed_redirect_uris="https://vault.company.com/oidc/callback" \
      allowed_redirect_uris="http://localhost:8250/oidc/callback" \
      user_claim="sub" \
      policies="admin" \
      groups_claim="groups" \
      oidc_scopes="openid,profile,email"

Role Configuration Details:

• bound_audiences: Must match the Client ID from Authentik
• allowed_redirect_uris: URLs where users can be redirected after authentication
• user_claim: Uses the subject claim from the OIDC token
• groups_claim: Specifies where group information is found in the token
• oidc_scopes: Required OIDC scopes for group information

6. EXTERNAL GROUPS

Set up external groups to manage access through Authentik group membership:

Step 1: Create External Groups

vault write identity/group \
    name="admin" \
    policies="admin" \
    type="external"

vault write identity/group \
    name="reader" \
    policies="reader" \
    type="external"

Step 2: Get OIDC Accessor

vault auth list | grep auth_oidc_

This will output something like:

oidc/     oidc     auth_oidc_d2997c34     n/a                        n/a

Extract the accessor ID:

vault auth list | grep auth_oidc_ | tr -s ' ' | cut -d ' ' -f3

Step 3: Get Group IDs

vault list identity/group/id

This will show the canonical IDs for your groups.

Step 4: Create Group Aliases

Create aliases that map Authentik groups to Vault groups:

vault write identity/group-alias \
    mount_accessor="auth_oidc_d2997c34" \
    canonical_id="9fbb3c2e-da23-627e-fcb5-0393b880e358" \
    name="Admins"

vault write identity/group-alias \
    mount_accessor="auth_oidc_d2997c34" \
    canonical_id="f6074871-d4f5-79bc-b18f-45ad555ccb66" \
    name="Staff"

Replace the values:

• auth_oidc_d2997c34: Your actual OIDC accessor ID
• 9fbb3c2e-da23-627e-fcb5-0393b880e358: Admin group canonical ID
• f6074871-d4f5-79bc-b18f-45ad555ccb66: Reader group canonical ID
• "Admins" and "Staff": Group names in Authentik

7. TESTING

Verify your configuration is working correctly:

Step 1: Test OIDC Login

vault login -method=oidc role="reader"

Step 2: Verify Access

Test reader access:

# Should work for reader role
vault kv list kv/

# Should fail for reader role
vault kv put kv/test-secret key=value

Test admin access:

# Login as admin
vault login -method=oidc role="admin"

# Should work for admin role
vault kv put kv/test-secret key=value
vault kv get kv/test-secret

8. TROUBLESHOOTING

Common Issues and Solutions

Issue 1: OIDC Discovery URL Not Found

Error: failed to discover OIDC configuration

Solution: Verify the discovery URL format and ensure Authentik is accessible:

curl https://authentik.company.com/application/o/<application_slug>/.well-known/openid_configuration

Issue 2: Invalid Redirect URI

Error: redirect_uri_mismatch

Solution: Ensure all redirect URIs in Vault match exactly with those configured in Authentik.

Issue 3: Group Claims Not Working

Error: user is not a member of required groups

Solution: Verify group mapping in Authentik and check the groups_claim configuration.

Issue 4: Access Denied After Login

Error: permission denied

Solution: Check that the user's Authentik groups match the group aliases configured in Vault.

Debugging Commands

# Check OIDC configuration
vault read auth/oidc/config

# List OIDC roles
vault list auth/oidc/role

# Check group aliases
vault list identity/group-alias

# Verify policies
vault policy read admin
vault policy read reader

9. SECURITY CONSIDERATIONS

Best Practices

1. Principle of Least Privilege: Only grant necessary permissions
2. Regular Audits: Periodically review group memberships and policies
3. Secure Communication: Use HTTPS for all OIDC communications
4. Token Validation: Ensure proper token validation and expiration handling

Monitoring

Set up monitoring for:

• Failed authentication attempts
• Policy violations
• Group membership changes
• OIDC token validation errors

SUMMARY

This guide walked you through configuring Hashicorp Vault with Authentik OIDC authentication, including:

1. Authentik Setup: Created OIDC application and provider with group claims
2. Vault Configuration: Enabled and configured OIDC auth method
3. Policy Creation: Defined admin and reader policies with appropriate permissions
4. Role Configuration: Set up roles with group-based access control
5. External Groups: Configured group aliases for Authentik group management
6. Testing: Verified the configuration works correctly

The result is a secure, scalable authentication system that leverages your existing Authentik identity provider while providing granular access control to Hashicorp Vault secrets.

Next Steps

After completing this configuration, consider:

• Setting up monitoring and alerting for authentication events
• Implementing additional policies for specific use cases
• Creating documentation for end users
• Establishing regular security reviews

For more information about Hashicorp Vault OIDC authentication, visit the official Vault documentation.

Need help with your Hashicorp Vault deployment? Get $200 in free credits and start hosting your applications on Gozunga Cloud today!