SSO (Single-Sign-On) with OAuth or OIDC

You can connect LinkAce with an OAuth or OIDC provider to manage your users at a central place and let them login to LinkAce with a single click. No separate registration needed. No duplicate passwords to save.

LinkAce supports various OAuth or OIDC providers.

Supported providers

• Generic OIDC provider
• Auth0
• Authelia
• Authentik
• AWS Cognito
• FusionAuth
• Google
• GitHub
• GitLab
• Keycloak
• Microsoft Azure
• Okta
• Zitadel

General Configuration

To enable and configure Single Sign On, add the following configuration to your .env file. Please note that every SSO provider has its own configuration which must be added to the .env file and properly set up if you want to use it.

User handling

While a user tries to login with any SSO provider, this is how the user account is handled:

• Accounts are matched on the internal ID that the provider issues for the user, not on the email address. If an account with that ID exists, the user is logged in and the user name plus the authentication token (if applicable) are updated.
• If no account carries that ID, but an account with the same email address exists and has no SSO details yet, that account is connected to the SSO provider and the internal ID is stored. This is the migration path for users who already have a password account on your instance.
• If an account with the same email address exists and is already connected to a different identity of the same provider, the login is rejected. The same applies when the account is connected to a different provider.
• If no user with the same email address exists, a new user is registered and the user is automatically logged in.

Email address verification

Connecting an existing password account to an SSO identity relies on the email address your provider reports. If your provider lets users choose an arbitrary email address, or does not check that an address really belongs to the user, then someone could sign in to your provider using another user’s email address and gain access to that user’s LinkAce account.

Set SSO_REQUIRE_VERIFIED_EMAIL=true to reject any login unless the provider explicitly confirms that it verified the address. This is strongly recommended if you run your own OIDC provider, where email verification depends entirely on your own configuration.

The underlying email_verified claim is a standard OpenID Connect claim of the email scope, which LinkAce already requests from every provider that supports it. Providers are not required to return the claim, so a missing claim counts as unverified. You do not have to configure an additional claim or scope on your side.

Example Configuration

SSO_ENABLED=true
REGULAR_LOGIN_DISABLED=true

SSO_AUTH0_ENABLED=true
SSO_AUTH0_BASE_URL=https://example.auth0.com/
SSO_AUTH0_CLIENT_ID=W+qVVdlLP32a2F.....
SSO_AUTH0_CLIENT_SECRET=U5qo0Le2stKK2vO87TTl.....

After adding this to your .env file, the regular login form vanishes and a button to login with Auth0 will show up when users try to login.

Callback URL is https://[[YOUR.LINKACE.INSTALL]]/auth/sso/[[SERVICE]]/callback (replace service with whatever comes between SSO_[[SERVICE]]_ENABLED in your .env file)

Provider Configuration

Generic OpenID Connect Provider

The base URL must be set to the OpenID Configuration URL, but excluding the .well-known/openid-configuration part. Example: If https://auth.company.com/application/linkace/.well-known/openid-configuration is your OIDC configuration URL, then https://auth.company.com/application/linkace must be your base URL.

Auth0

Authelia

OIDC with Authelia works with the generic OIDC config. The critical succesfactor is the Authelia config, where PKCE needs to be disabled.

configuration.yml (Authelia)

identity_providers:
  oidc:
    clients:
      - client_id: 'linkace'
        client_name: 'linkace'
        client_secret: '[DIGEST OF SSO_OIDC_CLIENT_SECRET]'
        public: false
        authorization_policy: 'two_factor'
        require_pkce: false
        redirect_uris:
          - 'https://linkace.example.com/auth/sso/oidc/callback'
        scopes:
          - 'openid'
          - 'groups'
          - 'email'
          - 'profile'
        response_types:
          - 'code'
        grant_types:
          - 'authorization_code'
          - 'refresh_token'
        access_token_signed_response_alg: 'none'
        userinfo_signed_response_alg: 'none'
        token_endpoint_auth_method: 'client_secret_post'

LinkAce configuration

Authentik

AWS Cognito

FusionAuth

Google

GitHub

GitLab

Keycloak

Microsoft Azure

Okta

Zitadel