Okta Integration

This guide walks through everything you need to do to enable Okta SSO for your organization’s Biometry dashboard access. You will need:

• An Okta account with admin access (a free Okta developer account works)
• Your tenant slug — a short identifier for your organization (e.g. acme-corp). Choose one now; you will use it throughout this guide.

---

1. Create an OIDC App Integration in Okta

   In the Okta Admin Console, go to Applications → Applications → Create App Integration.

   Select:

   • Sign-in method: OIDC — OpenID Connect
   • Application type: Web Application

   Click Next, then configure the app:

   Field	Value
   App integration name	Biometry (or any descriptive name)
   Grant type	Authorization Code (checked by default)
   Sign-in redirect URIs	https://auth.biometrysolutions.com/okta-login/{your-tenant-slug}
   Sign-out redirect URIs	Leave empty
   Controlled access	Allow everyone in your organization

   Replace {your-tenant-slug} with the slug you chose (e.g. https://auth.biometrysolutions.com/okta-login/acme-corp).

   Redirect URI must match exactly

   The redirect URI Biometry constructs is https://auth.biometrysolutions.com/okta-login/{tenant_slug}. If the URI in Okta does not match character-for-character (including trailing slashes), Okta will reject the login with a redirect_uri mismatch error.

   Click Save. On the app detail page, copy:

   • Client ID
   • Client Secret (click the eye icon to reveal it)

   You will need both of these in Step 3.

2. Note Your Okta Domain

   Your Okta domain is visible in the top-right corner of the Okta Admin Console. It looks like:

   dev-12345678.okta.com

   Save this alongside your Client ID and Client Secret.

3. Configure the Authorization Server Policy

   Okta requires an explicit access policy for the Authorization Code flow to succeed. Without this, Okta returns a 400 error: Policy evaluation failed for this request.

   1. Go to Security → API → Authorization Servers
   2. Open the default Authorization Server
   3. Go to the Access Policies tab
   4. Click Add Policy, give it a name (e.g. Biometry SSO Policy), and set it to apply to All clients
   5. Inside the new policy, click Add Rule and configure:

   Setting	Value
   Grant type	Authorization Code
   User is	Any user assigned to the app
   Scopes requested	Any scopes

   Save the rule.

4. Submit Your Tenant Registration to Biometry

   Self-service registration is coming

   Tenant registration is currently handled by the Biometry team. A self-service registration portal is planned for a future release.

   Contact Biometry support or your account manager and provide the following details:

   Field	Description
   Tenant slug	The slug you chose (e.g. acme-corp) — must match the redirect URI
   Company name	Your organization’s full name
   Okta domain	e.g. dev-12345678.okta.com
   Client ID	From Step 1
   Client Secret	From Step 1

   Once registered, Biometry will confirm your tenant is active and provide the dashboard URL to share with your users.

5. Test the Login Flow

   1. Open the Biometry dashboard: https://console.biometrysolutions.com
   2. On the sign-in page, click Sign in with SSO
   3. Enter your tenant slug (e.g. acme-corp) in the organization field
   4. Click Continue with SSO
   5. You are redirected to your Okta login page
   6. Sign in with your Okta credentials
   7. Okta redirects back to Biometry and you land on the dashboard

   On the first login for a new tenant, Biometry automatically creates a project and an advanced subscription for your organization. Subsequent logins reuse the existing project.

---

Troubleshooting

Error	Likely Cause	Fix
redirect_uri mismatch (Okta)	The redirect URI in your Okta app settings does not match what Biometry sends	Verify the URI in Okta exactly matches https://auth.biometrysolutions.com/okta-login/{tenant_slug}
Policy evaluation failed for this request (Okta 400)	No access policy/rule configured for Authorization Code flow	Follow Step 3 to create the policy and rule
SSO config not found (404)	The tenant slug entered on the sign-in page does not match a registered tenant	Confirm with Biometry support that your tenant is registered and the slug matches
invalid or expired sso state (401)	The login flow took longer than 10 minutes	Start the login flow again from the beginning
Dashboard loads but project_id is empty	Biometry’s provisioning services were unreachable at first login	Contact Biometry support — they can trigger re-provisioning for your tenant
CORS errors in browser console	Your frontend domain is not in Biometry’s allowed origins	Contact Biometry support with your domain

---

What Gets Provisioned on First Login

When the first user from your organization logs in via SSO, Biometry automatically provisions:

• A project associated with your tenant
• An advanced subscription for that project
• Your user account with the partner role and owner project role

All subsequent SSO users from the same tenant join the existing project — no duplicate provisioning occurs.

---

Related

• SSO Overview — conceptual background and comparison with API token auth
• API Token — for service-to-service API authentication (not SSO)