Multi-Provider Platform Authentication & Setup
Sign in to GraphnAI through Microsoft Entra ID, Okta, AWS (Amazon Cognito), or any other standards-compliant OpenID Connect (OIDC) identity provider.
Requires role: Admin, to manage providers and users after setup. The setup wizard runs before any account exists, so it needs no sign-in.
Related: Entra ID (Azure AD) OIDC Configuration Guide, Automated Entra ID Setup Walkthrough, On-Premises Directory Sign-In (Active Directory / LDAP), Managing Sign-In Methods After Setup, User Management & RBAC
Overview
GraphnAI can sign people in through any identity provider that supports standard OpenID Connect (OIDC). After the license step, the setup wizard shows Choose how your team signs in with these cards:
| Card | What it sets up |
|---|---|
| Microsoft Entra ID | A Sign in with Microsoft pop-up: GraphnAI registers the app in your tenant through Microsoft Graph and checks the setup administrator email. |
| Okta | A guided form for an Okta org's authorization server. |
| AWS (Amazon Cognito) | A guided form for an Amazon Cognito user pool, with steps for putting IAM Identity Center behind it. |
| Generic OIDC provider | An issuer and client form for any other standards-compliant provider, such as Google Workspace. |
| Active Directory (LDAPS) | Directory sign-in with on-premises AD accounts. See On-Premises Directory Sign-In. |
People sign in to GraphnAI through the provider you choose. It confirms each person's identity, and GraphnAI gives them a role: Viewer, Operator or Admin.
IMPORTANT
This guide covers signing in to GraphnAI. The Identity Bridge is separate: it collects Active Directory or Entra ID identities into the graph for analysis. A domain the bridge collects doesn't have to be the one your team signs in with, and the reverse is also true.
Choosing a Provider
| Provider | What you need | Notes |
|---|---|---|
| Microsoft Entra ID | An Entra ID tenant, and an account with Global Administrator or Application Administrator rights | Follow the Automated Entra ID Setup Walkthrough, or the Entra ID Setup Guide for manual setup. |
| Okta | An Okta org, and admin access to it | The form starts from your org's built-in authorization server (https://{org}.okta.com). With a custom authorization server or custom domain, paste its full issuer URL. A custom authorization server needs extra setup at Okta to send group claims. |
| AWS (Amazon Cognito) | A Cognito user pool with a hosted UI domain | IAM Identity Center doesn't offer OIDC sign-in for third-party applications. Use Cognito as the OIDC provider. To keep Identity Center as the credential store, add it to the pool as a SAML identity provider. A pool with no hosted domain fails the check at once, because browser sign-in needs one. |
| Generic OIDC | Any standards-compliant OIDC issuer, and a confidential (server-side) client with a client secret | Works with providers such as Google Workspace. Certificate-based client authentication isn't available here. Use a client secret. |
For a Cognito pool that federates another identity provider, IAM Identity Center included: map the email_verified attribute from that provider, or set it with a post-authentication Lambda function. GraphnAI refuses a sign-in whose email the provider marks unverified. Until you map the attribute, or turn on the unverified-email override, every sign-in from that pool is refused.
Prerequisites
- First-time setup: no sign-in method exists yet. The setup wizard starts when you open the setup link the server printed at first start.
- Adding or changing a provider later: you're signed in as an Admin. See Managing Sign-In Methods After Setup.
- The address your team uses to reach GraphnAI. The wizard builds the callback URL from it.
- Admin access at the identity provider, to register an application and get a client ID and client secret.
- For Okta: permission to create an OIDC web application integration in the Okta Admin Console.
- For AWS: a Cognito user pool with an app client. If you federate, set up the SAML federation before or during setup.
Set Up Sign-In with Okta, AWS, or a Generic Provider
These steps cover the three non-Entra providers. For Entra ID, follow the Automated Entra ID Setup Walkthrough.
- Open the setup link the server printed at first start (see Quick Start). The setup wizard starts.
- Import your license, or select Continue without a license.
- On Choose how your team signs in, select Okta, AWS (Amazon Cognito) or Generic OIDC provider.
- Fill in the provider form:
- Display name: the name on the sign-in button, for example "Acme Okta".
- Okta org URL, User pool issuer URL or Issuer URL: for Okta, the field starts as
https://{org}.okta.com, so replace{org}with your Okta subdomain. For the others, paste the issuer exactly as your provider's console shows it. - Client ID and Client secret: from the application you registered at the identity provider.
- Setup administrator email: the email of the person who completes verification and becomes the first Admin.
- Auto-create accounts on first sign-in: on by default. Read Managing Users Without Directory Search before you keep it on.
- Copy the Redirect URI (callback URL) and register that exact value at your identity provider.
- Expand the sections under Set up GraphnAI in your provider for step-by-step instructions. They cover creating the app, assigning users, and mapping verified email for Cognito.
- Select Check and continue. GraphnAI fetches the issuer's discovery document before it saves anything. A wrong or unreachable issuer fails here, with the reason, and not at the first sign-in.
- On Review discovered configuration, check the endpoints, the requested scopes and any warnings. Then select Save and continue.
- On Verify sign-in, check the provider, the setup administrator and the verification expiry. Select Sign in to verify.
- Sign in at your identity provider as the setup administrator.
When the account matches, the provider becomes the sign-in method, your account becomes an Admin, and the dashboard opens. When it doesn't, the wizard says so, and nobody is signed in. Sign in again with the right account.
NOTE
The verification window lasts 24 hours from the save. If it expires, select Restart provider setup. The form comes back with the name and issuer filled in, and you enter the client secret again. You can restart as often as you need before setup finishes. If you started setup in another browser, the wizard asks whether to start setup over in this one. Confirm to continue here.
From then on, the sign-in page shows your provider's name, as in "Sign in with Acme Okta". The setup wizard is closed, and you manage providers and users from the Admin pages.
Managing Users Without Directory Search
Okta, AWS and generic providers give GraphnAI no directory to search. Use auto-created accounts and email invites to give people access.
Auto-Created Accounts
Auto-create accounts on first sign-in is on by default for these three providers. With it on, anyone who can sign in through your identity provider gets an account with the default role. A Viewer can browse the whole identity graph and search it. There is no invite step, so the identity provider decides who gets in.
With no directory to search, this is the only way for people to get access without an invite. To allow only people you invite, turn the setting off, during setup or later under Managing Providers. An uninvited person is then refused.
Choose the default role for auto-created accounts: Viewer or Operator. GraphnAI never grants Admin automatically.
Inviting People by Email
Requires role: Admin
- Select Admin > Users in the sidebar, then select Add user.
- In Find a platform user, type the person's name or email. The results show existing users as Active and open invites as Invited.
- If the person isn't listed, select Create invite, or select the "No platform user found. Invite …" line.
- Enter the Email, an optional Name, and a Role. Select Create invite.
The invite lasts 14 days. When the person signs in through your identity provider with the same email, verified, the invite is used: their account is created with the invited role.
On deployments that sign in through Okta, AWS or a generic provider, Admin > Users has an Invites tab. It lists each invite's email, name, role, who invited them, when it expires, and its status: Pending, Expiring soon (within 3 days) or Accepted.
To cancel an invite that hasn't been used, select Revoke on its row, then confirm. An accepted invite can't be revoked. Manage that person on the Users tab instead.
Changing an Auto-Created User's Role
On the Users tab, the Created by column shows "Auto-created at first sign-in" for these accounts. To change a role, select the pencil icon on the row. See User Management & RBAC.
Managing Providers
Requires role: Admin
Select Admin > Identity Providers in the sidebar to change a provider's settings.
- Pick the provider from the menu at the top, then select Edit.
- Change Display name to rename the sign-in button.
- Turn Auto-create accounts on first sign-in on or off, and choose its Default role.
- To replace the client secret, paste the new one in Rotate client secret. Leave it blank to keep the current one.
- Select Save.
The stored secret is never shown again. If you lose track of it, rotate it. Every change you save here is recorded in the audit log.
The Unverified-Email Override
The edit dialog also has Allow sign-in with unverified email, in a red panel. Leave it off unless your provider can't mark emails as verified.
By default, GraphnAI refuses a sign-in when the identity provider marks the email unverified. Invites and the setup administrator check both trust the email address.
Some federated Amazon Cognito pools, including ones that federate IAM Identity Center, can't send a verified email. The override exists for them. With it on, someone with an unverified address could match an invite. Map the email_verified attribute at your identity provider first. Use the override only when you can't.
What You Can't Do
- Delete the first-run provider. The provider set up in the setup wizard carries a First-run provider badge and has no Delete button.
- Remove your last sign-in method. Deactivate and Delete are disabled on the active provider when no other sign-in method is active.
- Use two OIDC providers at once. Only one OIDC provider signs people in at a time. An Okta, AWS or generic provider you add with Add provider starts turned off. Test sign-in and activate makes it the sign-in method and turns the previous one off in the same step. See Managing Sign-In Methods After Setup.
Directory sign-in with Active Directory runs alongside the active OIDC provider. See On-Premises Directory Sign-In.
Security Notes
- A verified email is required. A sign-in is refused when the identity provider marks its email unverified, unless you turn on the override for that provider. For Okta, AWS and generic providers, an invite or the setup administrator check also refuses an email the provider doesn't mark as verified at all.
- Issuer checks can't reach your internal network. The discovery check connects only over HTTPS. It refuses private, loopback and link-local addresses, cloud metadata endpoints included. An internal address fails with the same message as an unreachable one, so the check can't be used to map your network.
- Entra ID sign-in is unchanged. The browser sign-in setup, the seed Admin and Entra sync work as described in the Entra ID guides.
Troubleshooting
| Message or symptom | What to do |
|---|---|
| "Couldn't reach the discovery document at … Check the issuer URL." | Check the issuer you copied from your provider's console. The provider must be reachable from the server over HTTPS at a public address. |
| "This user pool has no hosted UI domain. Add one under App integration in the Cognito console, then try again." | Add a Cognito domain, or your own custom domain, under App integration. Browser sign-in can't work without one. |
| "The provider's discovery document is missing its authorization, token, or keys endpoint." | Check that the URL is the provider's issuer. |
| "Your identity provider didn't send a verified email address." | Map the email_verified attribute at the identity provider, which federated Cognito pools often need. Or have an Admin turn on the unverified-email override for that provider. |
| "That account doesn't match the setup administrator email." | Sign in again with the account you entered as the setup administrator. |
| "The setup verification window expired. Set up the provider again." | Select Restart provider setup, enter the client secret again, and save. |
| An invite still shows Pending after the person tried to sign in | Their email at the identity provider must match the invite exactly and be verified. Check the invite for typos, and ask which email their account uses. |
| An unexpected user appears in Users with no invite | Auto-created accounts are on for this provider. Turn off Auto-create accounts on first sign-in under Admin > Identity Providers to allow only invited people. |
| "Setup is already complete. Sign in instead." | Sign-in is already set up. Manage providers and users from Admin > Identity Providers and Admin > Users. |