Skip to main content

OAuth providers

identity-service supports 16 sign-in providers: 15 OAuth 2.0 and OpenID Connect providers, plus SAML 2.0. Each company creates its own app at the provider, then adds the credentials in Shellui admin under OAuth setup. Shellui admin offers exactly the providers on this page. For the sign-in flow itself, see OAuth login.

Register the callback URL​

Every provider app uses the same callback URL, on identity-service. Register it with no query string:

EnvironmentCallback URL
Localhttp://localhost:8000/api/v1/oauth/callback
Productionhttps://auth.example.com/api/v1/oauth/callback

Replace auth.example.com with your identity-service host. Do not register your shell's /login/callback URL at the provider: identity-service redirects there after sign-in. django-allauth docs mention /accounts/<provider>/login/callback/, a path identity-service does not serve.

Social and developer accounts​

People sign in with an account they already have at a public provider. Use these for products open to anyone.

ProviderCatalog IDProtocolCompany settingsLinks by email
AppleappleOAuth2Client ID, secret, key, certificate_keyWhen the provider marks the email verified
GitHubgithubOAuth2Client ID and secretVerified primary email
GitLabgitlabOAuth2Client ID, secret, gitlab_url (optional)When the provider marks the email verified
GooglegoogleOAuth2Client ID and secretVerified email in the ID token
LinelineOAuth2Client ID and secretWhen the provider marks the email verified
LinkedInlinkedinOpenID ConnectClient ID and secretVerified email in the ID token
MicrosoftmicrosoftOAuth2Client ID, secret, tenant (optional)Tenant check
RedditredditOAuth2Client ID and secretWhen the provider marks the email verified
ShopifyshopifyOAuth2Client ID and secretWhen the provider marks the email verified
SlackslackOAuth2Client ID and secretWhen the provider marks the email verified
TwitchtwitchOAuth2Client ID and secretEmail from Twitch

Company identity providers​

These providers are run by the company itself, for example its Okta org or Keycloak realm. Use them for workforce single sign-on (SSO). identity-service never links these sign-ins to an existing user by email.

ProviderCatalog IDProtocolCompany settingsLinks by email
Auth0auth0OAuth2Client ID, secret, AUTH0_URLNever
KeycloakkeycloakOpenID ConnectClient ID, secret, provider_id, server_urlNever
OktaoktaOAuth2Client ID, secret, OKTA_BASE_URLNever
OpenID Connectopenid_connectOpenID ConnectClient ID, secret, server_urlNever
SAMLsamlSAMLidp_entity_id, see SAMLTrusted domains only

How email linking works​

The first time someone signs in with a provider, identity-service looks for an existing user with the same provider account. When there is none, it can attach the sign-in to an existing user with the same email, but only when the provider proves the email belongs to that person. The Links by email column shows the proof each provider needs. Without it, identity-service matches by provider account ID only and never takes over another user by email.

Provider setup​

Each section lists where to create the app, the extra settings Shellui admin asks for, and provider-specific behavior.

Apple​

Follow the django-allauth Apple setup: the client ID is your Services ID and the client secret is the Key ID of your Sign in with Apple key.

Paste the .p8 file content in certificate_key. Shellui admin never shows it again.

Apple posts the callback as a form (form_post). identity-service handles that on the same callback URL.

  • Catalog ID: apple
  • Create the app:
    • App registration: https://developer.apple.com/account/resources/identifiers/list
    • App settings: https://developer.apple.com/account/resources/authkeys/list
  • Settings: key (Apple Team ID, required), certificate_key (Sign in with Apple private key (.p8), required, secret)
  • Email linking: Links by email when the profile has email_verified: true. Otherwise the account is matched by provider account ID only.
  • Apps per company: one
  • Reference: django-allauth Apple docs

Auth0​

Set AUTH0_URL to your tenant domain, for example https://your_tenant.eu.auth0.com.

  • Catalog ID: auth0
  • Create the app: https://manage.auth0.com/#/clients
  • Settings: AUTH0_URL (Auth0 domain URL, required)
  • Email linking: Never links by email. The company controls this identity provider, so its email claims are not proof of ownership. Accounts are matched by provider account ID, scoped to the issuer.
  • Apps per company: one
  • Reference: django-allauth Auth0 docs

GitHub​

Create an OAuth app and paste the callback URL as the Authorization callback URL.

  • Catalog ID: github
  • Create the app: https://github.com/settings/applications/new
  • Email linking: identity-service reads /user/emails and links by email only when the primary address is verified. Without a verified primary email, sign-in stops with an error.
  • Apps per company: one
  • Reference: django-allauth GitHub docs

GitLab​

Leave gitlab_url empty for gitlab.com. For a self-hosted GitLab, set its base URL.

A self-hosted GitLab counts as a company identity provider: it never links by email, and account IDs are prefixed with the GitLab base URL.

  • Catalog ID: gitlab
  • Settings: gitlab_url (GitLab base URL, optional)
  • Email linking: Links by email when the profile has email_verified: true. Otherwise the account is matched by provider account ID only.
  • Apps per company: one
  • Reference: django-allauth GitLab docs

Google​

Google skips the identity-service account confirmation page by default, because Google already shows its own account picker. Change this with OAUTH_SKIP_CONFIRM_PROVIDERS, see OAuth login.

  • Catalog ID: google
  • Create the app: https://console.developers.google.com/
  • Email linking: Links by email when the ID token has email_verified: true and the same email as the userinfo response.
  • Apps per company: one
  • Reference: django-allauth Google docs

Keycloak​

Set server_url to the realm issuer, for example https://keycloak.example.com/realms/acme. identity-service loads the OpenID Connect discovery document from it.

  • Catalog ID: keycloak
  • Settings: provider_id (Provider ID, required), server_url (OpenID Connect issuer URL, required)
  • Email linking: Never links by email. The company controls this identity provider, so its email claims are not proof of ownership. Accounts are matched by provider account ID, scoped to the issuer.
  • Apps per company: several, one per identity provider
  • Reference: django-allauth Keycloak docs

Line​

  • Catalog ID: line
  • Create the app: https://developers.line.biz/console/
  • Email linking: Links by email when the profile has email_verified: true. Otherwise the account is matched by provider account ID only.
  • Apps per company: one
  • Reference: django-allauth Line docs

LinkedIn​

Enable Sign In with LinkedIn using OpenID Connect on the app. The LinkedIn endpoints are fixed in identity-service, so there is nothing else to set.

  • Catalog ID: linkedin
  • Create the app: https://www.linkedin.com/secure/developer
  • Email linking: Links by email when the verified ID token has email_verified: true and the same email as userinfo. Otherwise the account is matched by provider account ID only.
  • Apps per company: several, one per identity provider
  • Reference: django-allauth LinkedIn docs

Microsoft​

Register the app in Microsoft Entra ID. Set tenant to your directory (GUID or domain) to accept only your organization, or leave it empty for any Microsoft account.

  • Catalog ID: microsoft
  • Create the app: https://portal.azure.com/#blade/Microsoft_AAD_RegisteredApps/ApplicationsListBlade
  • Settings: tenant (Tenant ID, optional)
  • Email linking: With a dedicated tenant (GUID or domain), the ID token tid must match it. With common or no tenant, the ID token must carry xms_edov: true. Otherwise sign-in stops with an error, so a personal account cannot claim a work email.
  • Apps per company: one
  • Reference: django-allauth Microsoft docs

Okta​

Set OKTA_BASE_URL to your Okta org URL, for example https://acme.okta.com.

  • Catalog ID: okta
  • Settings: OKTA_BASE_URL (Okta org URL, required)
  • Email linking: Never links by email. The company controls this identity provider, so its email claims are not proof of ownership. Accounts are matched by provider account ID, scoped to the issuer.
  • Apps per company: one
  • Reference: django-allauth Okta docs

OpenID Connect​

Use this entry for any standards-compliant OpenID Connect provider. Set server_url to the issuer URL or to its /.well-known/openid-configuration URL.

identity-service checks that the discovery document issuer matches, and verifies ID tokens against the provider keys.

  • Catalog ID: openid_connect
  • Settings: server_url (OpenID Connect issuer URL, required)
  • Email linking: Never links by email. The company controls this identity provider, so its email claims are not proof of ownership. Accounts are matched by provider account ID, scoped to the issuer.
  • Apps per company: several, one per identity provider
  • Reference: django-allauth OpenID Connect docs

Reddit​

  • Catalog ID: reddit
  • Create the app: https://www.reddit.com/prefs/apps/
  • Email linking: Links by email when the profile has email_verified: true. Otherwise the account is matched by provider account ID only.
  • Apps per company: one
  • Reference: django-allauth Reddit docs

SAML​

SAML has its own setup and endpoints. Follow SAML single sign-on.

  • Catalog ID: saml
  • Email linking: Matched by SAML NameID only. Email linking needs trusted_for_verified_domains and a verified company domain, see SAML email linking.
  • Apps per company: several, one per identity provider
  • Reference: django-allauth SAML docs

Shopify​

Sign-in needs the store domain. Add it to the authorize request: GET /api/v1/authorize?provider=shopify&shop=your_store.myshopify.com&….

  • Catalog ID: shopify
  • Email linking: Links by email when the profile has email_verified: true. Otherwise the account is matched by provider account ID only.
  • Apps per company: one
  • Reference: django-allauth Shopify docs

Slack​

Create the app at api.slack.com and add the callback URL under OAuth & Permissions.

  • Catalog ID: slack
  • Create the app: https://api.slack.com/apps/new
  • Email linking: Links by email when the profile has email_verified: true. Otherwise the account is matched by provider account ID only.
  • Apps per company: one
  • Reference: django-allauth Slack docs

Twitch​

identity-service requests one scope, user:read:email. Authorize and token calls go to id.twitch.tv and the profile call to https://api.twitch.tv/helix/users. These hosts are fixed: a company URL or scope setting returns oauth_setting_not_allowed.

When the Helix user id is missing, or the profile request fails, sign-in stops with token_exchange_failed. No account is created.

Twitch runs without PKCE. Sign-in relies on the signed OAuth state and the client secret.

  • Catalog ID: twitch
  • Create the app: https://dev.twitch.tv/console
  • Email linking: Twitch returns email only for verified addresses, so its presence is the check. When Twitch omits it, sign-in stops with oauth_identity_failed.
  • Apps per company: one
  • Reference: django-allauth Twitch docs

Providers that are not available​

django-allauth ships 98 more provider modules. They stay in GET /api/v1/oauth-provider-catalog with supported: false and an unsupported_reason, but Shellui admin hides them and POST /api/v1/oauth-social-apps refuses them with 400. A provider becomes available once identity-service has an adapter for it, covered by a hand-written sign-in test.

Update this page​

This page is generated from apps/authapi/provider_catalog.json (catalog version 2, django-allauth 65.19.5). After a catalog change, regenerate it:

uv run python tools/render_oauth_providers_doc.py

CI fails when this page does not match the catalog. Edit provider notes in tools/render_oauth_providers_doc.py, not here.