Last Updated: 3/9/2026

Single Sign-On (SSO)

LinkAce supports Single Sign-On (SSO) via OAuth and OpenID Connect (OIDC), allowing users to log in with their existing accounts from providers like Google, GitHub, Microsoft Azure, and more.

Why Use SSO?

Benefits:

• Centralized user management: Manage users in one place (your identity provider)
• No duplicate passwords: Users log in with existing credentials
• One-click login: No separate registration needed
• Enterprise ready: Integrate with corporate identity systems
• Enhanced security: Leverage your provider’s MFA and security policies

Use cases:

• Team or company deployments
• Family accounts (Google, Microsoft)
• Developer communities (GitHub, GitLab)
• Enterprise environments (Azure AD, Okta, Keycloak)

Supported Providers

LinkAce supports 13 SSO providers out of the box:

Can’t find your provider? Use the Generic OIDC configuration for any OpenID Connect-compliant provider.

General Configuration

SSO is configured via environment variables in your .env file.

Core SSO Settings

Add these settings to your .env file:

# Enable SSO
SSO_ENABLED=true

# Allow new users to register via SSO (true) or require pre-existing accounts (false)
SSO_REGISTRATION_ENABLED=true

# Disable the regular login form (optional, forces SSO-only login)
REGULAR_LOGIN_DISABLED=false

Configuration Options

Restart After Configuration

After editing .env, restart your LinkAce instance:

Docker:

docker compose restart app

Non-Docker:

php artisan config:clear
php artisan cache:clear

How User Accounts Are Handled

When a user logs in via SSO:

Scenario 1: Existing User, No SSO Details

• User email matches an existing LinkAce account
• No SSO details are stored yet
• Action: The existing account is automatically linked to the SSO provider
• Result: User logs in successfully, SSO ID is stored

Scenario 2: Existing User with SSO Details

• User email matches an existing LinkAce account
• SSO details exist (user previously logged in via SSO)
• Action: User logs in, profile is updated (name, token)
• Result: User logs in successfully

Scenario 3: New User

• No user with this email exists in LinkAce
• Action: A new account is created automatically (if SSO_REGISTRATION_ENABLED=true)
• Result: User logs in successfully

Scenario 4: SSO Disabled Later

If you disable SSO after users have registered:

• Users must reset their password via the “Forgot Password” link
• Accounts remain active, but SSO login is unavailable

Provider Setup Guides

Generic OpenID Connect (OIDC)

Use this for any OIDC-compliant provider not listed below.

Configuration

Add to .env:

SSO_OIDC_ENABLED=true
SSO_OIDC_BASE_URL=https://auth.example.com/application/linkace
SSO_OIDC_CLIENT_ID=your-client-id
SSO_OIDC_CLIENT_SECRET=your-client-secret
SSO_OIDC_SCOPES=openid,email,profile  # Optional, comma-separated

Base URL Format

The SSO_OIDC_BASE_URL must be the OpenID Configuration URL excluding .well-known/openid-configuration.

Example:

• Full URL: https://auth.company.com/application/linkace/.well-known/openid-configuration
• Base URL: https://auth.company.com/application/linkace

Callback URL

Configure this in your OIDC provider:

https://your-linkace.com/auth/sso/oidc/callback

Google

1. Create OAuth Credentials

1. Go to Google Cloud Console 
2. Create a new project (or select existing)
3. Navigate to APIs & Services → Credentials
4. Click Create Credentials → OAuth 2.0 Client ID
5. Application type: Web application
6. Add Authorized redirect URI:

   https://your-linkace.com/auth/sso/google/callback

7. Click Create
8. Copy the Client ID and Client Secret

2. Configure LinkAce

Add to .env:

SSO_GOOGLE_ENABLED=true
SSO_GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
SSO_GOOGLE_CLIENT_SECRET=your-client-secret

GitHub

1. Create OAuth App

1. Go to GitHub Developer Settings 
2. Click New OAuth App
3. Fill in:
   • Application name: LinkAce
   • Homepage URL: https://your-linkace.com
   • Authorization callback URL: https://your-linkace.com/auth/sso/github/callback
4. Click Register application
5. Copy the Client ID
6. Click Generate a new client secret and copy it

2. Configure LinkAce

Add to .env:

SSO_GITHUB_ENABLED=true
SSO_GITHUB_CLIENT_ID=your-client-id
SSO_GITHUB_CLIENT_SECRET=your-client-secret

Microsoft Azure (Azure AD / Entra ID)

1. Register Application

1. Go to Azure Portal 
2. Navigate to Azure Active Directory → App registrations
3. Click New registration
4. Fill in:
   • Name: LinkAce
   • Supported account types: Choose based on your needs
   • Redirect URI: https://your-linkace.com/auth/sso/azure/callback
5. Click Register
6. Copy the Application (client) ID
7. Copy the Directory (tenant) ID
8. Go to Certificates & secrets → New client secret
9. Copy the secret value (not the ID)

2. Configure LinkAce

Add to .env:

SSO_AZURE_ENABLED=true
SSO_AZURE_CLIENT_ID=your-client-id
SSO_AZURE_CLIENT_SECRET=your-client-secret
SSO_AZURE_TENANT_ID=your-tenant-id

Keycloak

1. Create Client

1. Log in to your Keycloak admin console
2. Select your realm
3. Navigate to Clients → Create
4. Fill in:
   • Client ID: linkace
   • Client Protocol: openid-connect
5. Click Save
6. Configure:
   • Access Type: confidential
   • Valid Redirect URIs: https://your-linkace.com/auth/sso/keycloak/callback
7. Click Save
8. Go to Credentials tab and copy the Secret

2. Configure LinkAce

Add to .env:

SSO_KEYCLOAK_ENABLED=true
SSO_KEYCLOAK_BASE_URL=https://keycloak.example.com
SSO_KEYCLOAK_REALM=your-realm
SSO_KEYCLOAK_CLIENT_ID=linkace
SSO_KEYCLOAK_CLIENT_SECRET=your-client-secret

Authelia

Authelia requires PKCE to be disabled in its configuration.

1. Configure Authelia

Edit configuration.yml:

identity_providers:
  oidc:
    clients:
      - client_id: 'linkace'
        client_name: 'LinkAce'
        client_secret: '[DIGEST OF YOUR SECRET]'
        public: false
        authorization_policy: 'two_factor'
        require_pkce: false  # CRITICAL: must be false
        redirect_uris:
          - 'https://linkace.example.com/auth/sso/oidc/callback'
        scopes:
          - 'openid'
          - 'email'
          - 'profile'
        response_types:
          - 'code'
        grant_types:
          - 'authorization_code'
          - 'refresh_token'
        token_endpoint_auth_method: 'client_secret_post'

2. Configure LinkAce

Add to .env:

SSO_OIDC_ENABLED=true
SSO_OIDC_BASE_URL=https://auth.example.com
SSO_OIDC_CLIENT_ID=linkace
SSO_OIDC_CLIENT_SECRET=your-plaintext-secret
SSO_OIDC_SCOPES=openid,email,profile

Other Providers

For other providers (Auth0, Authentik, AWS Cognito, FusionAuth, GitLab, Okta, Zitadel), the configuration pattern is similar:

1. Create an OAuth/OIDC application in your provider
2. Set the redirect URI to https://your-linkace.com/auth/sso/[provider]/callback
3. Copy the client ID and secret
4. Add configuration to .env:

SSO_[PROVIDER]_ENABLED=true
SSO_[PROVIDER]_BASE_URL=https://provider.example.com  # If applicable
SSO_[PROVIDER]_CLIENT_ID=your-client-id
SSO_[PROVIDER]_CLIENT_SECRET=your-client-secret
# Additional provider-specific settings (see reference below)

See the Configuration Reference for provider-specific settings.

Example: Complete SSO Setup

Here’s a complete example using Auth0:

.env Configuration

# Enable SSO
SSO_ENABLED=true
SSO_REGISTRATION_ENABLED=true
REGULAR_LOGIN_DISABLED=true  # Force SSO-only login

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

Result

• Regular login form is hidden
• “Login with Auth0” button appears
• Users click the button and authenticate via Auth0
• New users are automatically registered

Testing Your SSO Setup

1. Verify Configuration

1. Check .env file: Ensure all settings are correct
2. Restart LinkAce: Apply configuration changes
3. Check System Logs: Look for SSO-related errors

2. Test Login Flow

1. Log out of LinkAce (or use an incognito window)
2. Navigate to the login page
3. Verify the SSO button appears (e.g., “Login with Google”)
4. Click the button
5. Authenticate with your SSO provider
6. Verify you’re logged in to LinkAce

3. Test User Creation

1. Use an email address not yet registered in LinkAce
2. Log in via SSO
3. Verify a new account is created (check User Management)
4. Verify user details are populated (name, email)

4. Test Existing User Linking

1. Create a user via regular registration (or admin invite)
2. Log out
3. Log in via SSO using the same email
4. Verify the account is linked (no duplicate created)

Troubleshooting

SSO Button Not Showing

• Check SSO_ENABLED=true in .env
• Check provider is enabled: SSO_[PROVIDER]_ENABLED=true
• Restart LinkAce to apply changes
• Clear cache: php artisan config:clear (or via Docker)

“Invalid Redirect URI” Error

• Check the redirect URI in your SSO provider matches exactly:

  https://your-linkace.com/auth/sso/[provider]/callback

• No trailing slashes
• HTTPS required (unless testing locally)

“Client ID or Secret Invalid” Error

• Verify credentials in .env match your provider
• No extra spaces or quotes around values
• Regenerate secret if unsure

User Not Logging In

• Check System Logs: Username dropdown → System Logs
• Verify email scopes: Ensure your provider sends email in the response
• Check SSO_REGISTRATION_ENABLED: If false, user must exist first

”PKCE Required” Error (Authelia)

• Disable PKCE in Authelia configuration: require_pkce: false
• Restart Authelia after configuration change

Email Not Matching

• Some providers (e.g., GitHub) don’t always return email addresses
• Check provider scopes: Ensure email scope is requested
• Check provider settings: Ensure email is public or accessible

For more help, see the Troubleshooting guide or GitHub Discussions .

Configuration Reference

Complete list of all SSO provider settings:

Auth0

SSO_AUTH0_ENABLED=true
SSO_AUTH0_BASE_URL=https://example.auth0.com/
SSO_AUTH0_CLIENT_ID=your-client-id
SSO_AUTH0_CLIENT_SECRET=your-client-secret

Authelia (via Generic OIDC)

SSO_OIDC_ENABLED=true
SSO_OIDC_BASE_URL=https://auth.example.com
SSO_OIDC_CLIENT_ID=linkace
SSO_OIDC_CLIENT_SECRET=your-client-secret
SSO_OIDC_SCOPES=openid,email,profile

Authentik

SSO_AUTHENTIK_ENABLED=true
SSO_AUTHENTIK_BASE_URL=https://authentik.example.com
SSO_AUTHENTIK_CLIENT_ID=your-client-id
SSO_AUTHENTIK_CLIENT_SECRET=your-client-secret

AWS Cognito

SSO_COGNITO_ENABLED=true
SSO_COGNITO_HOST=https://your-pool.auth.region.amazoncognito.com
SSO_COGNITO_CLIENT_ID=your-client-id
SSO_COGNITO_CLIENT_SECRET=your-client-secret
SSO_COGNITO_LOGIN_SCOPE=openid,email,profile
SSO_COGNITO_SIGN_OUT_URL=/

FusionAuth

SSO_FUSIONAUTH_ENABLED=true
SSO_FUSIONAUTH_BASE_URL=https://fusionauth.example.com
SSO_FUSIONAUTH_CLIENT_ID=your-client-id
SSO_FUSIONAUTH_CLIENT_SECRET=your-client-secret

Google

SSO_GOOGLE_ENABLED=true
SSO_GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
SSO_GOOGLE_CLIENT_SECRET=your-client-secret

GitHub

SSO_GITHUB_ENABLED=true
SSO_GITHUB_CLIENT_ID=your-client-id
SSO_GITHUB_CLIENT_SECRET=your-client-secret

GitLab

SSO_GITLAB_ENABLED=true
SSO_GITLAB_HOST=https://gitlab.com  # Or your self-hosted instance
SSO_GITLAB_BASE_URL=https://gitlab.com
SSO_GITLAB_CLIENT_ID=your-client-id
SSO_GITLAB_CLIENT_SECRET=your-client-secret

Keycloak

SSO_KEYCLOAK_ENABLED=true
SSO_KEYCLOAK_BASE_URL=https://keycloak.example.com
SSO_KEYCLOAK_REALM=your-realm
SSO_KEYCLOAK_CLIENT_ID=linkace
SSO_KEYCLOAK_CLIENT_SECRET=your-client-secret

Microsoft Azure

SSO_AZURE_ENABLED=true
SSO_AZURE_CLIENT_ID=your-client-id
SSO_AZURE_CLIENT_SECRET=your-client-secret
SSO_AZURE_TENANT_ID=your-tenant-id

Okta

SSO_OKTA_ENABLED=true
SSO_OKTA_BASE_URL=https://your-org.okta.com
SSO_OKTA_CLIENT_ID=your-client-id
SSO_OKTA_CLIENT_SECRET=your-client-secret

Zitadel

SSO_ZITADEL_ENABLED=true
SSO_ZITADEL_BASE_URL=https://zitadel.example.com
SSO_ZITADEL_CLIENT_ID=your-client-id
SSO_ZITADEL_CLIENT_SECRET=your-client-secret
SSO_ZITADEL_ORGANIZATION_ID=your-org-id
SSO_ZITADEL_PROJECT_ID=your-project-id
SSO_ZITADEL_POST_LOGOUT_REDIRECT_URI=/

Security Considerations

Disabling Regular Login

If you set REGULAR_LOGIN_DISABLED=true:

• Ensure SSO is working before disabling regular login
• Test with a non-admin account first
• Keep one admin account with a password as backup

Restricting Registration

If you set SSO_REGISTRATION_ENABLED=false:

• Pre-create user accounts via User Management
• Users must have an existing account to log in via SSO
• Useful for closed teams where you control membership

Email Verification

LinkAce trusts email addresses from SSO providers:

• Ensure your provider verifies emails (most do by default)
• For self-hosted providers, configure email verification

Next Steps

• Invite users: User Management
• Configure permissions: System Settings
• Set up API tokens: API Tokens
• Configure backups: Application Backups