Portal Community
Passport

Keycloak Integration

Configure a Keycloak realm as the identity source for BizFirstGO — create an OIDC client, expose realm roles in tokens, and map Keycloak roles to BizFirstGO roles.

Keycloak Configuration Steps

1

Create OIDC Client

In Keycloak Admin → Your Realm → Clients → Create Client.
Client type: OpenID Connect, Client ID: bizfirstgo-api, Client authentication: On.

2

Configure Client Settings

Valid Redirect URIs:  https://passport.bizfirst.ai/federation/keycloak/callback
Web Origins:          https://passport.bizfirst.ai
Access Type:          confidential
3

Create Realm Roles

In Realm Roles, create: bizfirst-admin, bizfirst-manager, bizfirst-user, bizfirst-viewer. Assign users to roles as appropriate.

4

Add Realm Roles to Token

In Clients → bizfirstgo-api → Client Scopes → Add Mapper → User Realm Role.
Token claim name: realm_roles, Add to access token: On.

5

Add Tenant ID Claim

In Client Scopes → Add Mapper → User Attribute.
User attribute: bizfirst_tenant_id, Token claim name: tenant_id.

Keycloak Token Structure

// Decoded Keycloak access token
{
  "iss":        "https://keycloak.company.com/realms/company",
  "sub":        "3b5f8797-...-kc-user-guid",
  "aud":        "bizfirstgo-api",
  "exp":        1748120400,
  "iat":        1748119500,
  "email":      "jane.smith@company.com",
  "name":       "Jane Smith",
  "realm_roles": ["bizfirst-admin", "bizfirst-manager", "offline_access"],
  "tenant_id":  "tenant-abc"
}

BizFirstGO Federation Configuration

POST /passport/admin/tenants/{tenantId}/federation
{
  "providerId":    "keycloak-main",
  "displayName":   "Keycloak (Company Realm)",
  "issuer":        "https://keycloak.company.com/realms/company",
  "jwksUri":       "https://keycloak.company.com/realms/company/protocol/openid-connect/certs",
  "audience":      "bizfirstgo-api",
  "tenantIdClaim": "tenant_id",
  "userIdClaim":   "sub",
  "emailClaim":    "email",
  "rolesClaim":    "realm_roles",
  "roleMapping": {
    "bizfirst-admin":   "admin",
    "bizfirst-manager": "manager",
    "bizfirst-user":    "user",
    "bizfirst-viewer":  "viewer"
  }
}

Keycloak Realm Discovery

// Keycloak OIDC discovery endpoint (auto-configure)
GET https://keycloak.company.com/realms/company/.well-known/openid-configuration

// Returns the standard discovery document with:
// - issuer: "https://keycloak.company.com/realms/company"
// - jwks_uri: "https://keycloak.company.com/realms/company/protocol/openid-connect/certs"
// - token_endpoint, authorization_endpoint, etc.
← Auth0 Integration Next: Claims Mapping →