Skip to content

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.

How-to guide6 min read

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.

1Start 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.

2Create 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.

3Finish the connection in Orbit

Back in the dialog, fill in:

Button name
What to enter
The name on your sign-in page, such as Okta. People see Continue with Okta.
Issuer URL
What to enter
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
What to enter
From your provider's app. The secret is stored encrypted and never shown again; only its last four characters are.
Groups claim
What to enter
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
What to enter
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.

4Choose 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.
  • 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.

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://.

Was this page helpful?

Read next