# Okta and other OpenID Connect providers

> Register OneiD at Okta or another OpenID Connect provider so users sign in there, and map the provider's groups to roles.

Source: https://oltinid.com/docs/sign-in-sources/openid-connect-provider/ · Section: Sign-in sources · All OneiD documentation: https://oltinid.com/llms.txt

With an OpenID Connect provider as the sign-in source, OneiD sends users to your provider to sign in, for example Okta. The provider checks the password and runs its own MFA. OneiD then issues its own tokens to your applications, so applications connect only to OneiD.

## How sign-in works

1. An application sends the user to OneiD.
2. OneiD sends the user straight on to the provider's sign-in page. OneiD uses the authorization code flow with PKCE towards the provider; this is fixed.
3. The user signs in at the provider, including any MFA the provider requires.
4. The provider returns the user to OneiD at `https://YOUR_ONEID/signin-oidc-external`.
5. OneiD reads the user's claims and groups, turns the groups into roles and issues tokens to the application.

Applications receive the same tokens as with any other source, with `idp` set to `oidc`, `amr` set to `["external"]` and `acr` set to `urn:oltin:ac:external`. The `sub` is the provider's `sub`, unchanged.

### MFA

MFA happens at the provider. OneiD does not add its own code on top. If your applications need MFA, require it in the provider's sign-in policy.

### Sign-out

When a user signs out of an application through OneiD, OneiD ends its own session and then sends the user on to the provider's sign-out, so the user is signed out there as well.

## Register OneiD at the provider

At your provider, OneiD is an ordinary web application. Create it with these settings:

| Setting | Value |
|---|---|
| Application type | Web application (server-side, with a client secret) |
| Grant type | Authorization code |
| PKCE | Required, if the provider offers the option |
| Sign-in redirect URI | `https://YOUR_ONEID/signin-oidc-external` |
| Sign-out redirect URI | `https://YOUR_ONEID/signout-callback-oidc` |
| Scopes | `openid`, `profile`, `email`, and whatever scope your provider needs to release groups |
| Groups | Send a `groups` claim with the groups OneiD should map to roles |

`/signin-oidc-external` and `/signout-callback-oidc` are the default paths. Ask your OneiD operator to confirm them for your deployment before you register.

## What to give your OneiD operator

Your OneiD operator configures the connection. For a deployment hosted by OneiD, the operator is the OneiD team. Send the client secret over a secure channel, never by plain email.

- [ ] **Authority.** The provider's issuer address, from which OneiD reads the provider's discovery document. For Okta, for example `https://YOUR_OKTA_DOMAIN` or `https://YOUR_OKTA_DOMAIN/oauth2/default`, depending on which authorisation server you use.
- [ ] **Client ID** of the application you registered.
- [ ] **Client secret** of that application. Supplied as a secret.
- [ ] **Scopes** OneiD should request, for example `openid profile email groups`.
- [ ] **Group rules.** The required group, the administrators group, the group-to-role mappings and, if wanted, a prefix for unmapped groups.

## Map provider groups to roles

OneiD reads the `groups` and `role` claims the provider sends and turns them into roles at each sign-in. The rules are described in [Where users come from](https://oltinid.com/docs/sign-in-sources/overview/#from-groups-to-roles). An example plan:

| Rule | Provider group | Result |
|---|---|---|
| Required group | `App-Users` | Only members can sign in. |
| Administrators group | `OneiD-Admins` | Members get OneiD's `All` administrator role. |
| Mapping | `Order-Viewers` | Role `OrderViewer` |
| Mapping | `Order-Managers` | Role `OrderManager` |

> **Warning:** Members of the administrators group can change every setting in OneiD. Use a small group that exists only for this purpose.

If the provider sends no groups, users get no roles from it. If you set a required group and the provider sends no groups, nobody can sign in. Check the groups claim first.

## Step by step for Okta

Okta's admin console changes over time, so the names below can differ by version. The settings in the table above are what matters.

1. In the Okta admin console, open **Applications** and choose **Create App Integration**.
2. Choose **OIDC - OpenID Connect** as the sign-in method and **Web Application** as the application type.
3. Give the integration a name, for example `OneiD`.
4. Under grant types, keep **Authorization Code**. Turn on the option to require PKCE if your Okta version shows it.
5. Set the sign-in redirect URI to `https://YOUR_ONEID/signin-oidc-external`.
6. Set the sign-out redirect URI to `https://YOUR_ONEID/signout-callback-oidc`.
7. Under assignments, choose who may use the integration, for example the `App-Users` group.
8. Save. Copy the **Client ID** and the **Client secret**.
9. Add a groups claim. In the integration's sign-on settings, find the OpenID Connect ID token section and set a **Groups claim** named `groups` with a filter, for example **Starts with** `App-` or **Matches regex** `.*`. If you use a custom authorisation server, add the `groups` claim there instead.
10. Note the authority. With the org authorisation server it is your Okta domain, for example `https://YOUR_OKTA_DOMAIN`. With a custom authorisation server it is the server's issuer, for example `https://YOUR_OKTA_DOMAIN/oauth2/default`.
11. Send the authority, client ID, client secret, scopes and group plan to your OneiD operator.

> **Tip:** Use a filter that releases only the groups OneiD needs. Users in many groups otherwise get large tokens and many roles.

> **Checkpoint:** After your operator has configured OneiD, open an application that signs in through OneiD. You land on Okta's sign-in page, and after sign-in you return to the application. With the `roles` scope, the ID token shows the mapped roles in `role`.

## Other providers

Other OpenID Connect providers that support the authorization code flow with PKCE and publish a discovery document are set up the same way. Register OneiD with the settings in [Register OneiD at the provider](#register-oneid-at-the-provider) and give your operator the same details.

Microsoft Entra ID is not available as a sign-in source. [Contact us](https://oltinid.com/contact/?topic=organisation) if you need Entra ID.

## Learn more

- [Where users come from](https://oltinid.com/docs/sign-in-sources/overview/)
- [Scopes, claims and roles](https://oltinid.com/docs/guides/scopes-claims-roles/)
- [Sign-out](https://oltinid.com/docs/guides/logout/)