Okta SAML SSO Setup
Hgraph supports SAML 2.0 single sign-on, so your team signs in to the Hgraph App with your Okta credentials. Once connected, anyone who enters an email address on your company domain is routed to your Okta sign-in page automatically, and accounts are created and added to your Hgraph organization on first sign-in — there are no invitations to manage.
SSO is available on enterprise plans and is enabled per organization by the Hgraph team. Contact us or email support@hgraph.io to get started before configuring Okta.
How it works
- SP-initiated SAML 2.0. Your team starts at app.hgraph.com — either by typing their work email or clicking Continue with SSO — and is redirected to Okta to authenticate.
- Just-in-time provisioning. The first Okta sign-in creates the user's Hgraph account and adds it to your organization as a member. Roles can then be 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 in your organization carry over, and the old sign-in method stops working.
- Optional SSO enforcement. We can restrict your organization so its data is only accessible to sessions authenticated through your Okta — ask us to enable this once your team has moved over.
Step 1: Create the SAML app in Okta
In the Okta Admin Console, go to Applications → Applications → Create App Integration, choose SAML 2.0, and name it (e.g. "Hgraph").
On the Configure SAML step, enter:
| Okta field | Value |
|---|---|
| Single sign-on URL (ACS) | https://api-v2.hgraph.com/sso/saml/acs |
| Audience URI (SP Entity ID) | https://api-v2.hgraph.com/sso/saml/metadata |
| Name ID format | EmailAddress |
| Application username |
Okta defaults the Name ID format to "Unspecified", which fails against Hgraph. Set it to EmailAddress.
Then add three Attribute Statements (leave the name format as Unspecified):
| Name | Value |
|---|---|
email | user.email |
firstName | user.firstName |
lastName | user.lastName |
Hgraph's SP metadata is public at https://api-v2.hgraph.com/sso/saml/metadata if your tooling prefers to import it.
Step 2: Assign your people
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.
Step 3: Send us your details
From the app's Sign On tab, copy the Metadata URL (it looks like https://<your-org>.okta.com/app/<app-id>/sso/saml/metadata) and send it to support@hgraph.io along with:
- The email domain(s) your team signs in with (e.g.
yourcompany.com). A domain can be connected to only one identity provider. - The name of your Hgraph organization.
We register your Okta app by its metadata URL, so certificate rotations on your side are picked up automatically — no maintenance required.
Step 4: Confirm sign-in
Once we confirm registration, have one person test the round trip: go to app.hgraph.com/login, enter their work email, and click Send magic link. Instead of an email, they'll see "Taking you to your organization's sign-in page" and land on Okta. After authenticating, they arrive back in the Hgraph App inside your organization.
From then on, everyone on your domain is routed to Okta automatically, whichever sign-in option they pick.
Okta dashboard tile
The integration is SP-initiated. If you want an Hgraph tile on your team's Okta dashboard, create an Okta Bookmark App pointing at https://app.hgraph.com/login — signing in from there flows through SSO as usual.
Limitations
- SAML 2.0 only — OIDC enterprise connections aren't supported.
- No SCIM provisioning. Accounts are created on first sign-in, not synced from your directory. Removing someone from the Okta app blocks their next sign-in, but sessions already issued remain valid until they expire — contact us if you need a session revoked immediately.
- No Single Logout. Signing out of Okta doesn't end active Hgraph sessions.
Troubleshooting
| Symptom | Likely cause |
|---|---|
| Okta shows a 403 / "app not assigned" page | The user isn't assigned to the Hgraph app in Okta (Step 2). |
| SAML assertion error after Okta sign-in | Name ID format is not EmailAddress, or the attribute statements are missing (Step 1). |
| Sign-in returns to the login page with an expired-link message | The 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" | We haven't registered your domain yet (Step 3), or the user typed a personal email. |
| "This account can't sign in this way" after clicking Google/GitHub | The account has moved to SSO. Enter the work email in the form shown to continue through Okta. |
Still stuck? Email support@hgraph.io with the time of the attempt and the email address used.