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:
| Environment | Callback URL |
|---|---|
| Local | http://localhost:8000/api/v1/oauth/callback |
| Production | https://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.
| Provider | Catalog ID | Protocol | Company settings | Links by email |
|---|---|---|---|---|
| Apple | apple | OAuth2 | Client ID, secret, key, certificate_key | When the provider marks the email verified |
| GitHub | github | OAuth2 | Client ID and secret | Verified primary email |
| GitLab | gitlab | OAuth2 | Client ID, secret, gitlab_url (optional) | When the provider marks the email verified |
google | OAuth2 | Client ID and secret | Verified email in the ID token | |
| Line | line | OAuth2 | Client ID and secret | When the provider marks the email verified |
linkedin | OpenID Connect | Client ID and secret | Verified email in the ID token | |
| Microsoft | microsoft | OAuth2 | Client ID, secret, tenant (optional) | Tenant check |
reddit | OAuth2 | Client ID and secret | When the provider marks the email verified | |
| Shopify | shopify | OAuth2 | Client ID and secret | When the provider marks the email verified |
| Slack | slack | OAuth2 | Client ID and secret | When the provider marks the email verified |
| Twitch | twitch | OAuth2 | Client ID and secret | Email 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.
| Provider | Catalog ID | Protocol | Company settings | Links by email |
|---|---|---|---|---|
| Auth0 | auth0 | OAuth2 | Client ID, secret, AUTH0_URL | Never |
| Keycloak | keycloak | OpenID Connect | Client ID, secret, provider_id, server_url | Never |
| Okta | okta | OAuth2 | Client ID, secret, OKTA_BASE_URL | Never |
| OpenID Connect | openid_connect | OpenID Connect | Client ID, secret, server_url | Never |
| SAML | saml | SAML | idp_entity_id, see SAML | Trusted 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
- App registration:
- 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/emailsand 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: trueand 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: trueand 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 tokentidmust match it. Withcommonor no tenant, the ID token must carryxms_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_domainsand 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
emailonly for verified addresses, so its presence is the check. When Twitch omits it, sign-in stops withoauth_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.