Okta Integration — Bring Your Own IAM

Step 1 — Create Okta API Application

Create Application in Okta Admin

In your Okta org, go to Applications → Create App Integration. Select API Services (for service-to-service) or OIDC - Web Application (for user-facing flows).

Configure Application Settings

App name:      BizFirstGO Integration
Sign-in method: OIDC
Application type: Web Application
Grant types: Authorization Code, Refresh Token
Redirect URIs: https://passport.bizfirst.ai/federation/okta/callback

Create Custom Authorization Server

Go to Security → API → Authorization Servers → Add Authorization Server. Set the audience to api://bizfirstgo.

Add Groups Claim

In the Authorization Server, go to Claims → Add Claim:

Name:          groups
Include in:    Access Token
Value type:    Groups
Filter:        Starts with: BizFirst-
Always include in token: Yes

Add BizFirstGO Tenant Claim

Add another claim for the BizFirstGO tenant ID:

Name:          tenant_id
Include in:    Access Token
Value type:    Expression
Value:         user.bizfirstTenantId  (custom Okta user attribute)

Okta Token Example

// Decoded Okta access token (after configuration above)
{
  "iss": "https://company.okta.com/oauth2/default",
  "sub": "00u1ab2cd3ef456GH78",
  "aud": "api://bizfirstgo",
  "exp": 1748120400,
  "iat": 1748119500,
  "email": "jane.smith@company.com",
  "name": "Jane Smith",
  "groups": ["BizFirst-Admins", "Finance-Users"],
  "tenant_id": "tenant-abc"
}

BizFirstGO Federation Configuration

POST /passport/admin/tenants/{tenantId}/federation
{
  "providerId":    "okta-main",
  "displayName":   "Okta (Company Directory)",
  "issuer":        "https://company.okta.com/oauth2/default",
  "jwksUri":       "https://company.okta.com/oauth2/default/v1/keys",
  "audience":      "api://bizfirstgo",
  "tenantIdClaim": "tenant_id",
  "userIdClaim":   "sub",
  "emailClaim":    "email",
  "groupsClaim":   "groups",
  "groupMapping": {
    "BizFirst-Admins":    "admin",
    "BizFirst-Managers":  "manager",
    "Finance-Users":      "finance-user",
    "BizFirst-Viewers":   "viewer"
  }
}

Claims After Mapping

Okta Claim	Value	BizFirstGO IDInfo
`sub`	`00u1ab2cd3ef456GH78`	`UserId`
`email`	`jane.smith@company.com`	`Email`
`name`	`Jane Smith`	`DisplayName`
`groups[0]`	`BizFirst-Admins`	`Roles → admin`
`groups[1]`	`Finance-Users`	`Roles → finance-user`
`tenant_id`	`tenant-abc`	`TenantId`

Okta Groups Filter

Use the Okta groups claim filter (Starts with: BizFirst-) to only include BizFirstGO-relevant groups in the token. Including all Okta groups would bloat the JWT and expose group memberships not relevant to BizFirstGO. Only mapped groups translate to BizFirstGO roles — unmapped groups are silently ignored.

← External Token Validation Next: Azure AD Integration →