Skip to main content

Okta SSO Setup

Hgraph is available in the Okta Integration Network (OIN) as a pre-configured SAML 2.0 integration. This guide walks Okta administrators through adding Hgraph from the OIN catalog and connecting it to your Hgraph organization. Once connected, anyone who enters an email address on your company domain at app.hgraph.com is routed to your Okta sign-in page automatically, and accounts are created and added to your Hgraph organization on first sign-in.

Prerequisites​

  • An Hgraph organization with SSO enabled by the Hgraph team. SSO is an enterprise feature offered through our custom solutions rather than a self-serve plan — contact us or email support@hgraph.com to get started.
  • Administrator access to your Okta org.
  • The email domain(s) your team signs in with (e.g. yourcompany.com). A domain can be connected to only one identity provider.

Supported features​

The Okta/Hgraph SAML integration supports the following features:

  • SP-initiated SSO — sign-in starts from the Hgraph login page (see SP-initiated SSO).
  • IdP-initiated SSO — sign-in starts from the Hgraph tile on the Okta End-User Dashboard (see IdP-initiated SSO).
  • Just-in-time (JIT) provisioning — the first Okta sign-in creates the user's Hgraph account and adds it to your organization as a member. Roles are then managed in the Hgraph App.
  • Automatic account migration — if someone on your domain already has an Hgraph account (from GitHub, Google, or email sign-in), their first SSO sign-in migrates it automatically: projects, teams, and roles carry over, and the old sign-in method stops working.
  • Optional SSO enforcement — the Hgraph team can restrict your organization so its data is only accessible to sessions authenticated through your Okta.

For more information on the listed features, visit the Okta Glossary.

The following features are not supported:

  • SCIM provisioning — accounts are created on first sign-in, not synced from your directory. Unassigning someone from the app blocks their next sign-in, but sessions already issued remain valid until they expire; contact us if you need a session revoked immediately.
  • Single Logout (SLO) — signing out of Okta doesn't end active Hgraph sessions.
  • OIDC — the integration is SAML 2.0 only.

Configuration steps​

  1. Sign in to the Okta Admin Console and go to Applications → Applications → Browse App Catalog.
  2. Search for Hgraph, open the integration, and click Add Integration.
  3. Keep or adjust the Application label, then click Done. All SAML settings (ACS URL, audience, Name ID format, attribute mappings) are pre-configured — there is nothing to enter.
  4. On the app's Assignments tab, assign the people or groups who should have access to Hgraph. Anyone not assigned will be stopped by Okta when they try to sign in.
  5. On the app's Sign On tab, copy the Metadata URL (it looks like https://<your-org>.okta.com/app/<app-id>/sso/saml/metadata).
  6. Email support@hgraph.com with:
    • the Metadata URL from step 5,
    • the email domain(s) your team signs in with,
    • the name of your Hgraph organization. If you have more than one organization, tell us which one SSO sign-ins should join — a domain connects to a single organization.
  7. The Hgraph team registers your Okta app and confirms by email. Registration uses your metadata URL, so certificate rotations on your side are picked up automatically — no maintenance required.
  8. Verify the connection by signing in as described below in SP-initiated SSO.
SAML attributes

The integration sends the following attributes to Hgraph, mapped from the Okta user profile: email (also the Name ID, format EmailAddress), firstName, and lastName.

SP-initiated SSO​

  1. Go to app.hgraph.com/login.
  2. Enter your work email address (or click Continue with SSO and enter it there).
  3. Hgraph detects that your email domain is SSO-enabled, shows "Taking you to your organization's sign-in page", and redirects you to Okta.
  4. Authenticate with Okta. You land back in the Hgraph App inside your organization with an active session. On first sign-in your account is created just-in-time.

From then on, everyone on your registered domain is routed to Okta automatically, whichever sign-in option they pick.

IdP-initiated SSO​

  1. Sign in to your Okta End-User Dashboard.
  2. Open the Hgraph tile.
  3. You land in the Hgraph App inside your organization with an active session — no Hgraph login page involved. As with the SP-initiated flow, a first sign-in creates the account just-in-time.

Troubleshoot​

SymptomLikely cause
Okta shows a 403 / "app not assigned" pageThe user isn't assigned to the Hgraph app in Okta (configuration step 4).
Sign-in returns to the login page with an expired-link messageThe Okta sign-in took longer than the SAML relay window (about 2 minutes). Start again from app.hgraph.com/login.
"This email's domain isn't set up for single sign-on"Hgraph hasn't registered your domain yet (configuration step 6), or the user typed a personal email.
"This account can't sign in this way" after clicking Google/GitHubThe account has moved to SSO. Enter the work email in the form shown to continue through Okta.

Still stuck? Email support@hgraph.com with the time of the attempt and the email address used.