# Connect an OpenID Connect provider

> Let your people sign in with Okta, Auth0, OneLogin, JumpCloud, Keycloak or any other OpenID Connect provider, and give access from their groups.

Source: https://docs.bifrostorbit.com/orbit/admins/connect-oidc-sso/

## Before you start

OpenID Connect (OIDC) is the sign-in standard most identity providers speak, including Okta, Auth0, OneLogin, JumpCloud, Keycloak, Ping Identity and Microsoft Entra ID. You create a web app in your provider, and Orbit signs people in through it. Your provider's own rules, such as multi-factor authentication, apply as usual.

You need:

- an administrator account in your identity provider,
- the email domains your people use, such as `northwilds.com`. Orbit only lets in addresses on these domains through the connection, whatever your provider says.

Keep Orbit open on your organisation's **Sign-in** tab in another window, because you copy values back and forth.

## 1. Start the connection in Orbit

1. In Orbit, open **Organisations**, choose your organisation, then the **Sign-in** tab.
2. Under **Ways to sign in**, switch on **Other provider (OpenID Connect)**, then choose **Save changes**.
3. In the **OpenID Connect** section, choose **Add OpenID Connect provider**.
4. Copy the **Redirect URI**. It ends in the connection's own ID, such as `https://app.bifrostorbit.com/api/auth/callback/oidc-…`.

Keep the dialog open while you set up your provider.

## 2. Create the app in your provider

Create a web application that uses the authorisation code flow, with the redirect URI from step 1. Then note the **issuer URL**, **client ID** and **client secret**.

**Okta:**

1. In the Okta Admin Console, go to **Applications** > **Applications** and choose **Create App Integration**.
2. Choose **OIDC - OpenID Connect** and **Web Application**, then **Next**.
3. Name it *Bifröst Orbit*, paste the redirect URI under **Sign-in redirect URIs** and remove the sample sign-out URI.
4. Under **Assignments**, choose who may sign in, then **Save**.
5. Copy the **Client ID** and **Client secret** from the app's **General** tab. The issuer URL is your Okta address, such as `https://northwilds.okta.com`.
6. To map groups, open the **Sign On** tab, edit **OpenID Connect ID Token**, set **Groups claim type** to *Filter*, the name to `groups` and a filter such as *Starts with* `northwilds-`.

**Auth0:**

1. In the Auth0 Dashboard, go to **Applications** > **Applications** and choose **Create Application** > **Regular Web Applications**.
2. On **Settings**, paste the redirect URI into **Allowed Callback URLs** and save.
3. Copy the **Client ID** and **Client Secret**. The issuer URL is your Auth0 domain with `https://` in front and a slash at the end, such as `https://northwilds.eu.auth0.com/`.
4. Auth0 sends no groups by default. Add them to the ID token with a post-login Action if you want to map groups.

**OneLogin:**

1. In OneLogin, go to **Applications** > **Add App**, search for *OpenID Connect* and add **OpenId Connect (OIDC)**.
2. On **Configuration**, paste the redirect URI into **Redirect URIs**.
3. On **SSO**, set **Token Endpoint** to *POST*, and copy the **Client ID**, **Client Secret** and **Issuer URL**.
4. To map groups, set **Groups** on the **Parameters** tab to send the roles you want in the ID token.

**JumpCloud:**

1. In the JumpCloud Admin Portal, go to **SSO Applications** > **Add New Application** > **Custom Application**, and choose **Manage Single Sign-On (SSO)** with **OIDC**.
2. Paste the redirect URI into **Redirect URIs**, set **Login URL** to your Orbit sign-in address, and under **Attribute Mapping** include the email and, for groups, the `groups` claim.
3. Save, then copy the **Client ID** and **Client Secret** shown once. The issuer URL is `https://oauth.id.jumpcloud.com/`.

Other providers, such as Keycloak or Ping Identity, follow the same pattern: a confidential web client with the redirect URI, the authorisation code flow and the `openid`, `email` and `profile` scopes.

## 3. Finish the connection in Orbit

Back in the dialog, fill in:

| Field | What to enter |
| --- | --- |
| **Button name** | The name on your sign-in page, such as *Okta*. People see **Continue with Okta**. |
| **Issuer URL** | Your provider's issuer. Orbit reads its settings from `/.well-known/openid-configuration` when you save, and checks the provider calls itself by exactly this address. |
| **Client ID** and **Client secret** | From your provider's app. The secret is stored encrypted and never shown again; only its last four characters are. |
| **Groups claim** | The claim in the ID token that lists the person's groups, usually `groups`. Leave it blank if you don't map groups. |
| **Work email domains** | The domains your people's addresses use, such as `northwilds.com`, verified first under **Domains**. |

Choose **Save connection**. Each domain can belong to only one organisation, and to one of your connections.

## 4. Choose who gets in

Under **Who gets in**:

- **Everyone the provider lets in** lets in everyone your provider lets sign in to the app, with an address on your domains, with the role and satellites under **Everyone gets**. Choose who that is in your provider, with assignments.
- **Only people matching a rule** lets in only people in a group below.

Under **Role mapping**, choose **Add group rule** and type a group name exactly as your provider sends it, such as `northwilds-editors`. Then choose the role and satellites it gives. Someone in several matching groups gets the highest role and every satellite those groups give.

## What happens next

- People type their work email on the main sign-in page and go straight to your provider, or choose **Continue with Okta** on your sign-in address.
- They join your organisation with the mapped access. Taking someone out of a group takes the access away at their next sign-in.
- To add and remove people before they sign in, and remove leavers at once, set up [SCIM provisioning](https://docs.bifrostorbit.com/orbit/admins/set-up-scim/).
- To make everyone on your domain use this connection, add the domain under **Require SSO for your domains** and choose the connection. See [Choose how your people sign in](https://docs.bifrostorbit.com/orbit/admins/set-up-sign-in/).

Switching the connection off keeps its settings but lets nobody in through it until it is on again.

## If something goes wrong

**Orbit could not read the issuer:** check the issuer URL opens `/.well-known/openid-configuration` in a browser, and that it is public. Orbit cannot reach addresses on a private network.

**The provider calls itself by another address:** copy the address Orbit shows into **Issuer URL** exactly, including any slash at the end.

**Your company's sign-in vouched for an email address this organisation does not use:** the person's email is not on the connection's domains. Add the domain, or check the email your provider sends.

**This email address already has an account that signs in another way:** the address already belongs to someone in another organisation, or to a platform admin. Orbit never lets a provider take over such an account. Ask the person to sign in the way they did before.

**Redirect URI mismatch:** the redirect URI in your provider must match the one in Orbit exactly, including `https://`.
