---
question: Which identity provider do people sign in with, and how do I add another one?
kind: task
via_web: na
via_cli: na
via_python: na
via_api: available
via_config: available
ref_api: PUT /api/organizations/{org_id}/domains/{domain_id}/provider
ref_config: identity
next:
  - /capabilities/get-started/sign-in
  - /capabilities/platform/authenticate-engine-api
  - /capabilities/get-started/configuration
---

# Choose an identity provider

Nexus has no login of its own. People sign in at an OpenID Connect identity provider that the engine trusts, listed under `identity` in the project's config. The engine checks the provider's tokens; the provider proves who the person is, and the engine's IAM decides what they may do.

- **The built-in provider** is the default. It ships with ABI (`naas-abi-idp`) and signs people in with a 6-digit code it mails them. `abi dev up` runs it, and so does the Docker stack.
- **Your own provider**: Okta, Microsoft Entra ID, Zitadel, Keycloak, or any provider that meets [what ABI expects](#what-abi-expects-of-a-provider). Use one for single sign-on, MFA or SAML, which the built-in provider does not do.

Providers are engine-wide: an organization is not a tenant of its own provider. The sign-in page sends an email to the provider its organization's verified domain names, or else to `default_provider`.

## Web UI

Not applicable. No Nexus screen adds a provider, and Organization settings › Domains is not built yet. Use Config to add a provider, and REST to route a domain.

## CLI

Not applicable. No `abi` command adds a provider: it is the `identity` block of the config. [`abi iam group bind`](/user-guide/reference/cli#abi-iam-group-bind) gives the members of a provider's group a role (see [Groups from the provider](#groups-from-the-provider)).

## Python

Not applicable. The engine reads the providers from its config.

## REST API

Send the logins of one email domain to a provider other than the default. An owner or admin of the organization does this, with a [personal API key](/capabilities/platform/create-a-personal-api-key).

### Add the domain

```bash
curl -X POST "$NEXUS_API_URL/api/organizations/$ORG_ID/domains" \
  -H "Authorization: Bearer $NEXUS_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com"}'
```

The answer is the domain, with its `id`.

### Verify it

```bash
curl -X POST "$NEXUS_API_URL/api/organizations/$ORG_ID/domains/$DOMAIN_ID/verify" \
  -H "Authorization: Bearer $NEXUS_ACCESS_TOKEN"
```

:::warning Verifying checks nothing
At this version, verify marks the domain verified without checking that the organization owns it: no DNS record or token is read. Any owner or admin of an organization can verify any domain, so only the platform's operators should route domains.
:::

Routing applies only to a verified domain.

### Route it to a provider

```bash
curl -X PUT "$NEXUS_API_URL/api/organizations/$ORG_ID/domains/$DOMAIN_ID/provider" \
  -H "Authorization: Bearer $NEXUS_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"provider": "corp"}'
```

`provider` is the `name` of a provider in `identity.providers`; an unknown one answers 400. Send `{"provider": null}` to send the domain back to the default provider.

## Config

### Register ABI at the provider

At the provider, create a confidential web client for ABI, with:

- the redirect URI `<Nexus API URL>/api/auth/oidc/callback`, such as `https://api.example.com/api/auth/oidc/callback`;
- the post-logout redirect URI `<Nexus web URL>/auth/login`;
- the authorization code grant, with PKCE (S256), and refresh tokens.

Keep its client ID, and put its secret in the [secret service](/capabilities/build/secrets/overview), such as `CORP_OIDC_SECRET` in `.env`.

### Add the provider

List it under `identity.providers`, next to the built-in one or in its place. Each block below is an example: the domains, IDs and secret names are placeholders.

#### Okta

Use a custom authorization server: Okta's org authorization server cannot carry a custom groups claim.

```yaml title="config.yaml"
identity:
  providers:
    - name: okta
      display_name: Okta
      issuer: https://example.okta.com/oauth2/default
      client_id: 0oa000000000example
      client_secret: "{{ secret.OKTA_CLIENT_SECRET }}"
      groups_claim: groups
      scopes: [openid, email, profile, offline_access]
```

#### Microsoft Entra ID

Use your tenant's issuer: the multi-tenant `common` and `organizations` endpoints are refused. Entra ID sends no `email_verified`, so set `trust_email: true` (its directory controls the addresses). Its groups claim holds group object IDs.

```yaml title="config.yaml"
identity:
  providers:
    - name: entra
      display_name: Microsoft
      issuer: https://login.microsoftonline.com/00000000-0000-0000-0000-000000000000/v2.0
      client_id: 11111111-1111-1111-1111-111111111111
      client_secret: "{{ secret.ENTRA_CLIENT_SECRET }}"
      groups_claim: groups
      trust_email: true
      scopes: [openid, email, profile, offline_access]
```

#### Zitadel

Zitadel puts a project's roles in the claim `urn:zitadel:iam:org:project:roles`: the role keys are the groups.

```yaml title="config.yaml"
identity:
  providers:
    - name: zitadel
      display_name: Zitadel
      issuer: https://auth.example.com
      client_id: "000000000000000001@abi"
      client_secret: "{{ secret.ZITADEL_CLIENT_SECRET }}"
      groups_claim: "urn:zitadel:iam:org:project:roles"
      scopes: [openid, email, profile, offline_access]
      provisioning: zitadel
      admin:
        token: "{{ secret.ZITADEL_PAT }}"
```

#### Keycloak

Add a groups mapper with "Full group path" off. For realm roles instead of groups, set `groups_claim: realm_access.roles`.

```yaml title="config.yaml"
identity:
  providers:
    - name: keycloak
      display_name: Keycloak
      issuer: https://keycloak.example.com/realms/example
      client_id: abi
      client_secret: "{{ secret.KEYCLOAK_CLIENT_SECRET }}"
      groups_claim: groups
      scopes: [openid, email, profile, offline_access]
      provisioning: keycloak
      admin:
        client_id: abi-provisioning
        client_secret: "{{ secret.KEYCLOAK_ADMIN_SECRET }}"
```

Every key is in the [Configuration Reference](/capabilities/get-started/configuration#identity).

### Choose the default

`default_provider` is where a sign-in goes when the email's domain routes to no provider, and where a bare `/login` goes. It is also a **Continue with ...** button on the sign-in page, as every provider is.

```yaml title="config.yaml"
identity:
  default_provider: okta
```

The default never captures a domain by itself: to send all of `example.com` to a provider, route the domain (REST tab).

### Restart

The config is checked when it loads, and the engine reads each provider's discovery document and keys when it starts. Restart it: `abi dev down` then `abi dev up`, or `docker compose restart abi`. A provider that is down is logged and does not stop the engine, but nobody signs in through it until it answers.

With an `identity` block that names no `provisioning: builtin` provider, `abi dev up` runs no built-in provider.

## What ABI expects of a provider

| | |
|---|---|
| Discovery | `<issuer>/.well-known/openid-configuration`, naming exactly the configured `issuer` |
| Client | A confidential web client (client ID and secret), authorization code grant, PKCE with S256. A public client has no secret: omit `client_secret`. |
| Redirect URIs | `<Nexus API URL>/api/auth/oidc/callback`; after logout, `<Nexus web URL>/auth/login` |
| Refresh tokens | Required: Nexus checks each person with the provider again at least every 10 minutes. Ask for `offline_access` where the provider needs it. |
| ID token | Signed with an asymmetric key (RS256, ES256, PS256 or EdDSA) published in the provider's JWKS. `aud` holds the client ID. |
| Email | `email` with `email_verified: true`, or `trust_email: true` for a directory that controls its addresses |
| Groups | Optional: a claim that lists the person's groups, named by `groups_claim` (a claim name, or a dotted path such as `realm_access.roles`) |
| Token lifetime | Ten minutes or less is recommended |

A person is the pair of the provider's issuer and its `sub`, never an email. The same person through two providers is two accounts, and nothing links them automatically.

## Provisioning

`provisioning` says what happens at the provider when an administrator invites someone who has no account yet:

| `provisioning` | What an invitation does at the provider | Needs |
|---|---|---|
| `builtin` | Creates the person at the built-in provider, which mails a code at each sign-in | Nothing more. Only one provider may have it. |
| `zitadel` | Creates the person through Zitadel's user API, with an unverified email, and Zitadel mails the verification code | `admin.token`: a machine user's personal access token, with `ORG_USER_MANAGER` |
| `keycloak` | Creates the person in the realm and asks Keycloak to mail its "verify email, update password" link | `admin.client_id` and `admin.client_secret`: a client with its service account on and the `realm-management` roles `manage-users` and `view-users` |
| `none` (default) | Nothing: the provider manages its own people | The person must exist at the provider before they can sign in |

With any setting, the invitation keeps the person's roles waiting. They attach at the person's first sign-in through that provider with the invited address verified. Choose `none` for a provider whose people come from elsewhere, such as an Entra ID tenant fed by your HR directory: invite them in Nexus to give them roles, and they sign in with the account they already have.

Platform settings › Users renames, deactivates and deletes people at the provider too, for `builtin`, `zitadel` and `keycloak`.

## Groups from the provider

When a provider sends a groups claim (`groups_claim`), give a group's members a role in an organization or a workspace, and each member holds it while their session lasts:

```bash
abi iam group bind okta engineering --role member --org org-...
```

The group's members get the role at their next sign-in, or within 10 minutes for a session already open. Someone removed from the group at the provider loses it the same way. A role held only through a group claim does not reach that person's [personal API keys](/capabilities/platform/create-a-personal-api-key), which carry no groups. Groups bound this way show in Roles & permissions › Groups, where the platform admin can also map a claim to a group by hand: see [Manage groups](/capabilities/platform/manage-groups#map-identity-provider-groups-platform).

## Emails and accounts

- Nexus stores an email only when the provider verified it. A verified email that another account already holds refuses the sign-in ("This email already belongs to another account") until an administrator links the two accounts.
- An account of Nexus's old login links at its first sign-in through the built-in provider, the only one that proves an address by mailing a code: see [Sign in to Nexus](/capabilities/get-started/sign-in#an-account-from-before-the-upgrade).
- Disabling someone at the provider ends their Nexus session within 10 minutes. Suspending them in ABI ends it within 5 seconds.
