Federated Providers¶

Overview¶

Federated providers let users log in with an external identity provider (e.g., Google, GitHub) instead of a local password. On first login, JustIAM either creates a new local account or links to an existing one if the email matches.

Supported provider types¶

Type	`provider_type`	Notes
Google OAuth2	`google`	Standard OAuth2 + userinfo
GitHub	`github`	OAuth2, fetches `/user` and `/user/emails`
Microsoft / Entra ID	`microsoft`	OIDC with per-tenant issuer URL
Apple Sign In	`apple`	OAuth2 with JWT client secret + `form_post`
Generic OIDC	`oidc`	Any standards-compliant OIDC provider
SAML 2.0	`saml`	SP-initiated SSO via HTTP POST binding
LDAP / Active Directory	`ldap`	Credential-based login via LDAP bind+search

Callback URL¶

Regardless of provider type, the OAuth2/OIDC redirect URI to register with the provider is:

https://justiam.example.com/federated/callback

Apple Sign In uses response_mode=form_post, so JustIAM also accepts POST /federated/callback.

Provider fields¶

Field	Description
`name`	Display name shown on the login page button
`provider_type`	One of `google`, `github`, `microsoft`, `apple`, `oidc`, `saml`, `ldap`
`client_id`	OAuth2 / App ID from the provider's developer console
`client_secret`	OAuth2 client secret. For Apple, the contents of the `.p8` private key file. For SAML, the IdP signing certificate in PEM format. Not used for LDAP (anonymous bind) or use it for the service-account bind password
`issuer_url`	Required for `microsoft` and `oidc`. OIDC discovery base URL
`scopes`	Space-separated scopes. Defaults to `openid profile email`. Not used for `github`, `apple`, `saml`, or `ldap`
`metadata`	Provider-specific key-value pairs. Required for `apple`: `team_id`, `key_id`. Required for `saml`: `idp_entity_id`, `idp_sso_url`. Required for `ldap`: `ldap_url`, `base_dn`, `user_filter`. Optional for `saml`/`ldap`: `attr_email`, `attr_first_name`, `attr_last_name`
`enabled`	Set `false` to hide from login page without deleting
`allowed_domains`	If non-empty, only email addresses from these domains are accepted
`allowed_emails`	If non-empty, only these specific email addresses are accepted

allowed_domains and allowed_emails work as separate whitelists — a login is permitted if the email matches either list. Leave both empty to allow any account from the provider.

Setting up Google OAuth2¶

Go to Google Cloud Console → APIs & Services → Credentials.
Create an OAuth 2.0 Client ID of type Web application.

Add the callback URL to Authorized redirect URIs:

https://justiam.example.com/federated/callback

Copy the Client ID and Client Secret into the provider configuration.

{
  "name": "Google",
  "provider_type": "google",
  "client_id": "1234567890-abc.apps.googleusercontent.com",
  "client_secret": "GOCSPX-...",
  "enabled": true
}

Setting up GitHub¶

Go to GitHub Developer Settings → OAuth Apps → New OAuth App.

Set Authorization callback URL:

https://justiam.example.com/federated/callback

Copy the Client ID and generate a Client Secret.
GitHub users must have a verified primary email address on their account.

{
  "name": "GitHub",
  "provider_type": "github",
  "client_id": "Ov23li...",
  "client_secret": "...",
  "enabled": true
}

Setting up Microsoft / Entra ID¶

Go to Azure Portal → Microsoft Entra ID → App registrations → New registration.

Set Redirect URI (Web):

https://justiam.example.com/federated/callback

Under Certificates & secrets, create a Client secret.
Copy the Application (client) ID and the Directory (tenant) ID.
Set issuer_url to https://login.microsoftonline.com/{tenant-id}/v2.0.

{
  "name": "Microsoft",
  "provider_type": "microsoft",
  "client_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "client_secret": "...",
  "issuer_url": "https://login.microsoftonline.com/YOUR_TENANT_ID/v2.0",
  "enabled": true
}

To restrict access to a single organisation, add allowed_domains with your organisation's email domain.

Apple Sign In requires additional configuration compared to other providers because the client secret is a short-lived JWT signed with a private key.

Prerequisites¶

An Apple Developer account with the Sign in with Apple capability enabled.
An App ID with the Sign in with Apple service activated.
A Services ID (this is the client_id).
A private key downloaded as a .p8 file.
Your Team ID (10-character string shown in the top-right of the Developer portal).
The Key ID of the private key.

Steps¶

In Apple Developer, create a Services ID under Certificates, Identifiers & Profiles → Identifiers.
Enable Sign in with Apple and configure the domain and return URL:
```
Return URL: https://justiam.example.com/federated/callback
```
Create a Sign in with Apple key and download the .p8 file.
Create the provider with metadata.team_id and metadata.key_id:

{
  "name": "Apple",
  "provider_type": "apple",
  "client_id": "com.example.justiam.signin",
  "client_secret": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----",
  "metadata": {
    "team_id": "XXXXXXXXXX",
    "key_id": "XXXXXXXXXX"
  },
  "enabled": true
}

The client_secret field holds the full PEM content of the .p8 private key file. JustIAM generates the required JWT client secret on each login request.

Note: Apple only sends the user's name on the first login. Subsequent logins only provide the sub identifier and email.

Setting up a generic OIDC provider¶

Any standards-compliant OpenID Connect provider is supported via the oidc type.

Register a web application in the provider's admin console.
Set the redirect URI to https://justiam.example.com/federated/callback.
Obtain the Client ID, Client Secret, and the Issuer URL (the OIDC discovery base URL).

{
  "name": "My OIDC Provider",
  "provider_type": "oidc",
  "client_id": "...",
  "client_secret": "...",
  "issuer_url": "https://sso.example.com",
  "scopes": "openid profile email",
  "enabled": true
}

JustIAM fetches {issuer_url}/.well-known/openid-configuration to discover the authorization and token endpoints.

Setting up a SAML 2.0 provider¶

JustIAM acts as a Service Provider (SP) and initiates SP-initiated SSO. The IdP must support the HTTP POST binding for the assertion consumer service (ACS).

Prerequisites¶

The IdP's SSO URL (the endpoint that JustIAM redirects/posts to).
The IdP's Entity ID (a URI that uniquely identifies the IdP in SAML metadata).
The IdP's signing certificate in PEM format (used to validate SAMLResponse signatures).
A SP Entity ID — an arbitrary URI you choose to identify JustIAM (e.g. https://justiam.example.com).

ACS URL¶

Register the following as the SAML Assertion Consumer Service (ACS) URL with HTTP POST binding in the IdP:

https://justiam.example.com/federated/saml-callback

Configuration¶

{
  "name": "Corporate SSO",
  "provider_type": "saml",
  "client_id": "https://justiam.example.com",
  "client_secret": "-----BEGIN CERTIFICATE-----\nMIIC...==\n-----END CERTIFICATE-----",
  "metadata": {
    "idp_entity_id": "https://idp.example.com/saml",
    "idp_sso_url": "https://idp.example.com/saml/sso"
  },
  "enabled": true
}

Field	Description
`client_id`	SP Entity ID — the URI you registered with the IdP
`client_secret`	IdP signing certificate PEM (the X.509 certificate, not a private key)
`metadata.idp_entity_id`	IdP entity ID (from the IdP's SAML metadata)
`metadata.idp_sso_url`	IdP SSO endpoint URL with HTTP Redirect or POST binding
`metadata.attr_email`	Optional: SAML attribute name for email. Auto-detected if not set
`metadata.attr_first_name`	Optional: SAML attribute name for first name. Auto-detected if not set
`metadata.attr_last_name`	Optional: SAML attribute name for last name. Auto-detected if not set

Attribute auto-detection¶

JustIAM recognises the following attribute names automatically:

Email: email, emailAddress, mail, urn:oid:0.9.2342.19200300.100.1.3, http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
First name: givenname, givenName, firstName, urn:oid:2.5.4.42, http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
Last name: sn, surname, lastName, urn:oid:2.5.4.4, http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname

Setting up an LDAP / Active Directory provider¶

LDAP is a credential-based provider. Unlike OAuth2/OIDC/SAML, there is no browser redirect — the user enters their LDAP username and password directly in the JustIAM login page. JustIAM binds to the LDAP server, searches for the user entry, re-binds as that user to verify the password, and then finds or creates a local account.

Configuration¶

{
  "name": "Corporate LDAP",
  "provider_type": "ldap",
  "client_id": "cn=service,dc=example,dc=com",
  "client_secret": "service-account-password",
  "metadata": {
    "ldap_url":    "ldap://ldap.example.com:389",
    "base_dn":     "dc=example,dc=com",
    "user_filter": "(uid={username})"
  },
  "enabled": true
}

Field	Description
`client_id`	Bind DN of the service account used to search for users. Leave empty for anonymous bind
`client_secret`	Password for the service account. Leave empty for anonymous bind
`metadata.ldap_url`	LDAP server URL. Use `ldap://` for plain or `ldaps://` for LDAP over TLS
`metadata.base_dn`	Base DN to search for user entries
`metadata.user_filter`	LDAP search filter. Use `{username}` as a placeholder for the entered username
`metadata.start_tls`	Set to `"true"` to upgrade a plain `ldap://` connection to TLS via StartTLS
`metadata.attr_email`	LDAP attribute for email address. Default: `mail`
`metadata.attr_first_name`	LDAP attribute for given name. Default: `givenname`
`metadata.attr_last_name`	LDAP attribute for surname. Default: `sn`

Common user filters¶

Scenario	Filter
OpenLDAP / by username	`(uid={username})`
Active Directory / by username	`(sAMAccountName={username})`
Login by email	`(mail={username})`
AD search by UPN	`(userPrincipalName={username})`

TLS options¶

ldaps:// — connects via TLS from the start (default port 636).
ldap:// + start_tls: "true" — connects in plain text then upgrades to TLS via StartTLS (default port 389).
ldap:// without StartTLS — plain-text LDAP. Only use in trusted internal networks.

The login page shows a Sign in with {name} button for each enabled provider.
Clicking redirects the user to the provider's consent/login screen.
For OAuth2/OIDC providers: redirected to GET {authorizationEndpoint}?...
For SAML providers: redirected to the IdP's SSO URL via a SAML AuthnRequest
After authentication:
OAuth2/OIDC: provider redirects back to /federated/callback.
SAML: IdP posts SAMLResponse to /federated/saml-callback.
LDAP: user submits credentials in an inline form; JustIAM posts to /federated/ldap-auth/:id.
JustIAM validates the response and extracts the user profile.
The user is linked or created, then:
Portal login: a short-lived exchange code is issued; the frontend exchanges it for a JWT.
OIDC flow: JustIAM continues the OIDC authorization flow and issues an authorization code.

Account linking¶

If a user with the same email already exists locally, the federated identity is linked automatically.
On subsequent federated logins, the user logs into the same account.
auth_source on the user record is updated to reflect the provider name.

Public provider list¶

The list of enabled providers (name, ID, and type — no secrets) is available without authentication:

GET /api/v1/federated/providers/public

This is used by the frontend to render the login buttons.

Federated Providers¶

Overview¶

Supported provider types¶

Callback URL¶

Provider fields¶

Setting up Google OAuth2¶

Setting up GitHub¶

Setting up Microsoft / Entra ID¶

Setting up Apple Sign In¶

Prerequisites¶

Steps¶

Setting up a generic OIDC provider¶

Setting up a SAML 2.0 provider¶

Prerequisites¶

ACS URL¶

Configuration¶

Attribute auto-detection¶

Setting up an LDAP / Active Directory provider¶

Configuration¶

Common user filters¶

TLS options¶

Login flow¶

Account linking¶

Public provider list¶