authentik – SSO & Connector Permissions

This guide provides a comprehensive, step-by-step walkthrough for administrators to set up Single Sign-On (SSO) with authentik for FSI Server, secure the integration using OpenID Connect (OIDC) with PKCE and confidential client authentication, and manage fine-grained access to different Source Connectors on FSI Server.

It covers architecture considerations, provider and application pairing, custom Python scope mappings for token claims, user federation (such as Active Directory / LDAP synchronization), access policy bindings, and security hardening.

authentik Architecture: Applications vs. Providers vs. Outposts​

authentik decouples application identity management into distinct, modular layers:

In the following steps, an OAuth2/OpenID Provider is created, configured with a custom Scope Mapping, and assigned to an Application dedicated to FSI Server.

Identity Directory Models: Built-in Directory vs. LDAP/AD Synchronization vs. Upstream Federation​

authentik provides flexible options for managing user identities and synchronizing group memberships:

Architecture & Data Flow​

On FSI Server, digital assets are organized into Source Connectors (such as local storage directories, SAN/NAS shares, or cloud buckets). Access to each connector is governed by FSI Server Groups.

The following diagram illustrates how user attributes in authentik map to security groups, pass through the OIDC authorization code flow, and resolve to connector permissions on FSI Server:

Scenario Overview:​

authentik Administration Interface Configuration​

Step 1: Create Groups for Connectors​

In the authentik Admin Interface, navigate to:
👉 Directory → Groups → Create

1. Create the groups corresponding to your connector permissions:
   • fsi-marketing
   • fsi-products
   • fsi-archive
   • fsi-administrators
2. Click Create for each group.

Step 2: Create a Custom Scope Mapping for Groups​

By default, authentik's standard OpenID scopes (openid, profile, email) do not output a groups array in the ID token. To make group memberships available to FSI Server, create a custom Scope Mapping:

1. In the authentik Admin Interface, navigate to:
   👉 Customization → Property Mappings → Create.
2. Select Scope Mapping and click Next.
3. Configure the mapping parameters:
   • Name: FSI Server - Scope Mapping: groups
   • Scope name: openid (or profile – see important note below)
   • Description: Emits user groups array into the ID token for FSI Server.
   • Expression:

     return {
         "groups": [group.name for group in request.user.ak_groups.all()]
     }
     

4. Click Finish.

return {
    "groups": [
        group.name for group in request.user.ak_groups.all()
        if group.name.startswith("fsi-")
    ]
}

Step 3: Create the OAuth2/OpenID Provider​

1. In the left navigation, navigate to:
   👉 Applications → Providers → Create.
2. Select OAuth2/OpenID Provider and click Next.
3. Configure the following fields:
   • Name: FSI Server Provider
   • Authentication flow: Select your default browser flow (e.g., default-authentication-flow).
   • Authorization flow: Select default-provider-authorization-implicit-consent.
     (Important: Using implicit consent allows users to sign in seamlessly without encountering an interactive consent dialog on every login).
   • Client type: Confidential (Mandatory for FSI Server).
   • Client ID: e.g., fsi-server (or leave the automatically generated value).
   • Client Secret: Record the generated secret (or enter a secure secret string).
   • Redirect URIs:
     Enter: https://<fsi-domain>/fsi/interface/
     (Example: https://fsi.example.com/fsi/interface/ – Ensure the trailing slash / is included!)
   • Signing Key: Select an active certificate/key (e.g., authentik Self-signed Certificate or your internal RSA/EC key).
   • Backchannel logout URL:
     https://<fsi-domain>/service/oidc/logout
4. Expand Advanced protocol settings:
   • Under Scopes, ensure the following scopes are selected:
     • authentik default OAuth Mapping: OpenID 'openid'
     • authentik default OAuth Mapping: OpenID 'email'
     • authentik default OAuth Mapping: OpenID 'profile'
     • FSI Server - Scope Mapping: groups (the custom scope mapping created in Step 2).
   • Subject mode: Select Based on the User's username (or Based on the User's Email).
5. Click Finish.

Step 4: Create and Bind the Application​

In authentik, providers must be bound to an Application to activate their endpoints:

1. Navigate to:
   👉 Applications → Applications → Create.
2. Configure the following fields:
   • Name: FSI Server
   • Slug: fsi-server
     (Important: The slug defines the OIDC Issuer URL path!)
   • Provider: Select FSI Server Provider (created in Step 3).
   • Launch URL: https://<fsi-domain>/fsi/interface/
3. Click Create.

Step 5: Record Client Credentials & Issuer URL​

From the created Provider and Application, record the three parameters required for settings.yml:

• Client ID: e.g., fsi-server
• Client Secret: copied from the Provider settings
• Issuer URL: https://<authentik-domain>/application/o/<application-slug>/

Step 6: Assign Users, LDAP Synchronization & Access Policies​

Option A: Local authentik Users​

1. In the left navigation, navigate to: 👉 Directory → Users → Create.
2. Enter username, email, and name.
3. Under the Groups tab of the user profile, assign the user to the appropriate connector group (e.g., fsi-marketing or fsi-administrators).

Option B: Active Directory / LDAP Source Synchronization​

In enterprise environments, authentik can synchronize users and groups from Active Directory:

1. Navigate to: 👉 Directory → Federation and Social login (or Sources) → Create.
2. Select LDAP Source and configure server URI, Bind credentials, and Base DN.
3. In the LDAP Source settings:
   • Enable Sync Users and Sync Groups.
   • Specify Group Object Filter: (objectCategory=group) (for Active Directory) or (objectClass=groupOfNames) (for OpenLDAP).
4. Benefit: Security groups in Active Directory (e.g., fsi-marketing) are continuously mirrored into authentik groups and forwarded directly to FSI Server.

Option C: Restricting Application Access via Policy Bindings​

To prevent unauthorized users from even seeing or authenticating against FSI Server:

1. Navigate to: Applications → Applications → click FSI Server.
2. Go to the Policy / Group / Role Bindings tab.
3. Click Bind Policy / Group / Role.
4. Select Group and bind the allowed connector groups (fsi-marketing, fsi-products, fsi-archive, fsi-administrators).
5. Security Model: Any tenant user not belonging to one of these groups is immediately stopped at the authentik login gate with an "Access Denied" screen, before reaching FSI Server.

Option D: Multi-Factor Authentication (MFA / WebAuthn / Passkeys)​

• Under Flows and Stages → Flows, bind an MFA validation stage (WebAuthn / Passkeys, TOTP / Google Authenticator) to the authentication flow.
• authentik enforces MFA transparently before issuing the authorization code to FSI Server.

FSI Server Configuration (settings.yml)​

Configure the OIDC authentication module in settings.yml (located in the FSI Server configuration directory, e.g., /etc/fsi/fsi-server/config/settings.yml or ./config/settings.yml).

The example below shows all parameters, highlighting mandatory settings and default values:

authentication:
  authModules:
    - type: "oidc"                                # Mandatory: Module type
      enabled: true                               # Default: true
      name: "authentik (SSO)"                     # Display label on login button
      provider: "authentik"                       # Provider identifier

      # 1. Credentials from authentik OAuth2 Provider (Steps 3 & 5)
      clientId: "fsi-server"                      # Mandatory: Client ID from authentik
      clientSecret: "your-client-secret-from-authentik" # Mandatory: Client Secret value

      # 2. Issuer URL (Endpoints are automatically discovered via .well-known/openid-configuration)
      # Mandatory: authentik Application Issuer URL (must include /application/o/<slug>/ with trailing slash)
      issuerUrl: "https://auth.example.com/application/o/fsi-server/"

      # 3. Redirect URI
      # Default: Uses base request URL if omitted.
      # Recommendation: Specify explicitly with [IP_ADDRESS] to match authentik Redirect URIs.
      redirectUri: "https://[IP_ADDRESS]/fsi/interface/"

      # 4. Token Claims
      usernameClaim: "preferred_username"         # Default: "preferred_username" (or "email")
      groupsClaim: "groups"                       # Default: "groups"

      # 5. User Provisioning & Session Mode
      autoProvision: true                         # Default: true (provisions user upon first SSO login)

      # 6. Group Mapping: Map authentik Group Names to FSI Server Groups
      # Note: FSI Server groups must correspond to defined group names
      groupMapping:
        # Full Administrator (Access to server settings & all connectors)
        "fsi-administrators": "administrators"

        # Marketing Team (Mapped to marketing connector)
        "fsi-marketing": "marketing"

        # Products Team (Mapped to product catalog connector)
        "fsi-products": "products"

        # Archive Team (Mapped to internal archive connector)
        "fsi-archive": "archive"

    # Optional: File-based XML authentication module as local administrative fallback
    - type: "file"
      enabled: true

Troubleshooting & Common Issues​