Skip to main content

Set up Okta SSO

This guide walks an Okta administrator through creating an application for Oho so your team can sign in with Okta. It's the provider-specific companion to Set up SSO — read that first for how SSO configuration works in Oho and what changes for your team.

Who this is for

You'll need administrator access to your Okta org (the Admin console at https://<your-org>-admin.okta.com). Oho supports both OIDC and SAML with Okta; this guide leads with OIDC, which is the simpler of the two, and calls out the SAML differences where they matter.

Step 1: Create the app in Okta​

  1. In the Okta Admin console, go to Applications → Applications and click Create App Integration.
  2. Choose OIDC - OpenID Connect as the sign-in method, and Web Application as the application type. Click Next.
  3. Name it something your team will recognise, for example Oho.
Technical detail: doing this with SAML instead

Choose SAML 2.0 as the sign-in method at step 2 instead. You'll be asked for a Single sign-on URL (this is the ACS URL shown on Oho's SSO screen, your Oho URL followed by /callback/saml) and an Audience URI (SP Entity ID) (also shown there — it defaults to urn:oho:datahub). Set the Name ID format to EmailAddress and map email as the primary attribute. The rest of this guide's group and entry steps apply the same way — in Oho you'll pick SAML 2.0 and enter your Identity Provider metadata URL rather than a client ID and secret.

Expected outcome: an Oho app integration exists in Okta, ready to configure.

Step 2: Set the sign-in redirect URL​

Oho shows you the callback URL to use on its SSO settings screen (Settings → Developer → Single Sign-On). It's your Oho URL followed by /callback/oidc.

  1. In the app's General settings, under Sign-in redirect URIs, add the callback URL shown on Oho's SSO screen.
  2. Set the Sign-out redirect URI to your Oho sign-in page if you want people returned there after logging out.
  3. Save.
Register the exact URL Oho shows you

If the redirect URI in Okta doesn't match the one on Oho's SSO screen, sign-in fails with a redirect-mismatch error. Copy the value from Oho rather than typing the pattern from memory.

Expected outcome: the redirect URI in Okta matches the callback URL on Oho's SSO screen.

Step 3: Assign people and (optionally) map groups​

  1. On the app's Assignments tab, assign the people or groups who should be able to sign in to Oho. Anyone not assigned here can't reach Oho through Okta.
  2. If you want Oho to place people into roles automatically based on their Okta groups, add a groups claim to the app: on the Sign On tab, edit the OpenID Connect ID Token settings and set Groups claim type to Filter, with a claim name of groups and a filter that matches the groups you'll map (for example, starts with oho-).

In Oho's SSO screen, turn on Sync group membership and set the Groups Claim to groups to use this — see Mapping groups to roles for what it does. If you skip it, an Oho Admin assigns each person's role instead.

Expected outcome: the right people are assigned, and — if you're using it — a groups claim is configured.

Step 4: Enter the details in Oho​

From the app's General tab, gather:

  • Client ID
  • Client secret
  • Discovery URI — your Okta org's OIDC discovery document, https://<your-org>.okta.com/.well-known/openid-configuration (or the authorisation-server-specific URL if you use a custom Okta authorisation server)

In Oho, go to Settings → Developer → Single Sign-On, turn on Enable Single Sign-On, choose OpenID Connect, and paste in the client ID, client secret, and discovery URI. For a SAML setup, choose SAML 2.0 and enter your IdP metadata URL instead of the client ID and secret. Click Test connection, then Save.

The client secret is a credential

Anyone with the client secret can impersonate the Oho app against your Okta org. Paste it straight into Oho's SSO screen rather than emailing or ticketing it, and rotate it in Okta if it's ever exposed. Oho stores it securely and never shows it again.

Expected outcome: SSO is enabled in Oho with your Okta details, and the connection test passes.

Step 5: Test the first sign-in​

After the connection test passes and you've saved:

  1. Go to your Oho URL in a private/incognito window.
  2. You're redirected to Okta — sign in as an assigned user.
  3. You're returned to Oho, signed in.

If you're testing a brand-new account and Oho is set to create accounts automatically, you'll land in Oho with a baseline role; an Admin then sets your role and scope (unless group mapping does it for you).

Expected outcome: an assigned Okta user can sign in to Oho end to end.

Common questions​

Someone sees "you're not assigned to this app." They aren't on the app's Assignments tab in Okta — assign them (or their group) and try again.

Sign-in fails with a redirect error. The Sign-in redirect URI in Okta doesn't exactly match the callback URL on Oho's SSO screen. Re-check it against the value shown there.

A new person can't get in at all. If Automatically create users on first login is turned off in Oho's SSO settings, the person must be added in Oho first. Either invite them, or turn that toggle on.