Okta SSO Configuration Guide | Confidential Client Setup

Comprehensive guide to setting up Okta SSO for confidential clients using OIDC. Includes client secret configuration, secure token handling, and advanced security options.

Okta SSO Configuration (Confidential Client)

• Troubleshooting

Okta Single Sign-On (SSO) enables users to log in to Collate with their Okta credentials using OAuth 2.0 and OpenID Connect (OIDC) protocols.

This guide covers the Confidential Client configuration, intended for web applications and backend services that can securely store secrets.

Overview

Collate supports Single Sign-On (SSO) integration with various identity providers, enabling secure, centralized user authentication.

1. Navigate to Settings > SSO.

   

2. Select the service provider.

   

3. Click Configure to set up Single Sign-On (SSO). See Confidential Configuration Fields.

   

4. Click Save to finish the SSO configuration.

Confidential Configuration Fields

This section lists all fields in the order they appear in the Collate SSO configuration form.

Authentication Configuration

Configure the identity provider connection and basic authentication behavior.

Provider Name

• Definition: A human-readable name for this Okta SSO configuration instance.
• Example: Okta SSO, Company Okta, Corporate Identity
• Why it matters: Helps identify this specific SSO configuration in logs and user interfaces.
• Note: This is a display name and doesn’t affect authentication functionality.

Client Type

• Definition: Defines whether the application is public (no client secret) or confidential (requires client secret).
• Options: Public | Confidential
• Example: Confidential
• Why it matters: Determines security level and authentication flow. Confidential clients can securely store secrets.
• Note:
  • Use Confidential for backend services and web applications.
  • Use Public for SPAs and mobile apps.
  • Okta typically uses Confidential client type.

Enable Self Signup

• Definition: Allows users to automatically create Collate accounts on their first SSO login.
• Options: Enabled | Disabled
• Example: Enabled
• Why it matters: Controls whether new users join automatically or need manual provisioning.
• Note: Disable for stricter control over user access.

Authority

• Definition: Okta domain that issues tokens for your organization.
• Example: https://dev-123456.okta.com or https://company.okta.com
• Why it matters: Tells Collate which Okta org to authenticate against.
• Note: Use your full Okta domain URL.

OIDC Configuration

Configure the OIDC client credentials and token handling; these fields appear when Client Type is set to Confidential.

OIDC Client ID

• Definition: Client ID for OIDC authentication with Okta.
• Example: 0oabc123def456ghi789
• Why it matters: Identifies your application to Okta in OIDC flows.
• Note: Found in Okta Admin Console → Applications → Your app → General → Client ID.

OIDC Client Secret

• Definition: Secret key for confidential client authentication with Okta.
• Example: abc123def456ghi789jkl012mno345pqr678st
• Why it matters: Required for confidential clients to securely authenticate with Okta.
• Note:
  • Generate in Okta → Applications → Your app → General → Client secret.
  • Store securely and rotate regularly.

Scope

• Definition: Permissions requested from Okta during authentication.
• Default: openid email profile
• Example: openid email profile groups
• Why it matters: Determines what user information Collate can access.
• Note:
  • Add groups scope if you need group information for authorization.
  • Add offline_access if using the Authorization Code flow to obtain refresh tokens. Okta requires this scope to issue refresh tokens.

OIDC Discovery URI

• Definition: Okta’s OpenID Connect metadata endpoint.
• Example: https://dev-123456.okta.com/.well-known/openid-configuration
• Why it matters: Allows Collate to automatically discover Okta’s OIDC endpoints.
• Note: Replace with your actual Okta domain.

OIDC Client Authentication Method

• Definition: Method used to authenticate the client with Okta.
• Default: client_secret_post
• Options: client_secret_basic | client_secret_post | client_secret_jwt | private_key_jwt
• Example: client_secret_post
• Why it matters: Must match the client authentication method configured in your Okta app.

OIDC Callback URL

• Definition: URL where Okta redirects after authentication.
• Example: https://openmetadata.company.com/callback
• Why it matters: Must be registered in your Okta configuration.
• Note:
  • This field is read-only — it is auto-populated as {your-domain}/callback.
  • Copy this URL and add it to Okta → Applications → Your app → Sign-in redirect URIs.

OIDC Prompt

• Definition: Controls Okta’s authentication prompt behavior.
• Options: none, login, consent, select_account
• Example: login
• Why it matters: Defines how the login experience behaves for users.
• Note:
  • login: Always prompt for credentials.
  • consent: Prompt for permissions.
  • none: Use existing session silently (SSO).

OIDC Custom Parameters

• Definition: Additional parameters to include in OIDC authentication requests.
• Example: {"prompt": "login", "max_age": "3600"}
• Why it matters: Allows customization of Okta authentication behavior.
• Note: Common parameters include prompt, max_age, login_hint.

Advanced Configuration

The following fields are grouped under Advanced Config in the UI (collapsed by default):

OIDC Use Nonce

• Definition: Security feature to prevent replay attacks in OIDC flows.
• Default: false
• Why it matters: Enhances security by ensuring each authentication request is unique.

OIDC Disable PKCE

• Definition: Whether to disable Proof Key for Code Exchange.
• Default: false
• Why it matters: PKCE adds security to the authorization code flow.
• Note: Should remain false (enabled) in most cases.

OIDC Max Clock Skew

• Definition: Maximum allowed time difference in seconds between systems when validating tokens.
• Example: 0
• Why it matters: Prevents token validation failures due to minor clock differences between servers.

OIDC Token Validity

• Definition: Duration in seconds that tokens remain valid.
• Default: 3600
• Example: 3600
• Why it matters: Balances token lifetime against security requirements.

OIDC Max Age

• Definition: Maximum authentication age in seconds before re-authentication is required.
• Example: 3600
• Why it matters: Controls how frequently users must re-authenticate.

OIDC Session Expiry

• Definition: How long user sessions remain valid in seconds.
• Default: 604800 (7 days)
• Why it matters: Controls session timeout for confidential clients.

JWT Claims

Map identity token claims to Collate user identities and team assignments.

JWT Principal Claims

• Definition: JWT fields used to identify users in Collate. The first claim that returns a value is used.
• Default: ["email", "preferred_username", "sub"]
• Example: ["preferred_username", "email", "sub"]
• Why it matters: Determines how users are matched to their Collate accounts.
• Note:
  • At least one claim must correspond to the user’s email address.
  • Common Okta claims: email, preferred_username, sub, login.
  • Order matters — the first matching claim is used.

Important: Incorrect claims will lock out all users including admins. The default values (email, preferred_username, sub) work for most Okta configurations. Only change if you have custom claim requirements.

JWT Principal Claims Mapping

Definition: Maps JSON Web Token (JWT) claims to Collate user profile fields.

Supported keys: Only email and username are valid mapping targets in jwtPrincipalClaimsMapping.

Example:

["email:email", "username:preferred_username"]

Why it matters: Controls how SSO login data maps to user profiles in Collate.

Format: collate_field:jwt_claim (for example, "email:email").

Note: The display name is derived automatically from standard OIDC/JWT claims — you don’t need to configure it using jwtPrincipalClaimsMapping. If you need richer name handling, make sure Okta includes given_name and family_name as claims in the ID token — Collate will pick them up automatically.

Important: Using any other key (for example, name or firstName) will cause the service to fail on startup with a validation error. JWT Principal Claims Mapping is rarely needed — the default JWT Principal Claims handle user identification correctly for most Okta configurations.

JWT Team Claim Mapping

• Definition: Okta claim containing team or department information for automatic team assignment in Collate.
• Example: department, groups, division
• Why it matters: Automatically assigns users to existing Collate teams based on their Okta user profile at login.
• Note:
  • Common Okta user profile attributes: department, division, organization.
  • For group-based teams, use the groups claim (requires group membership in scope).
  • Configure claim mappings in Okta → Directory → Profile Editor to include the attribute in the ID token.
  • The team must already exist in Collate for assignment to work.
  • Only teams of type Group can be auto-assigned. Team names are case-sensitive.

Authorizer Configuration

Control which users and domains are permitted to access Collate.

Admin Principals

• Definition: Users granted admin access in Collate.
• Example: ["admin", "superuser"]
• Why it matters: Grants full admin privileges in Collate.
• Note: Enter usernames only — not email addresses. Use the part of the email before @ (for example, for [e-mail], enter admin). The value must match what Okta returns for the claim configured in JWT Principal Claims.

Principal Domain

• Definition: Default domain for user principals.
• Example: company.com
• Why it matters: Used to construct full user identifiers when only a username is provided.

Enforce Principal Domain

• Definition: Restricts login to users belonging to the configured Principal Domain.
• Default: false
• Example: true
• Why it matters: Adds an extra layer of security by limiting access to a specific domain.

Enable Secure Socket Connection

• Definition: Enables SSL/TLS for all SSO communication.
• Default: false
• Example: true
• Why it matters: Ensures encrypted communication between Collate and Okta.
• Note: Recommended in production environments.

Allowed Domains

• Definition: List of email domains permitted to authenticate with Collate.
• Example: ["company.com", "partner.com"]
• Why it matters: Provides fine-grained control over which email domains can log in via Okta.
• Note:
  • Works in conjunction with Enforce Principal Domain.
  • Leave empty if you only use a single domain configured in Principal Domain.

Use Roles From Provider

• Definition: Use roles returned by Okta in the token to assign Collate roles.
• Default: false
• Why it matters: Enables role-based access control driven by your Okta role assignments.
• Note: Roles must be included in the Okta token and must match existing Collate role names.

Default OAuth Role

• Definition: Default role assigned to new users when they first sign in via SSO self-signup.
• Example: DataConsumer
• Why it matters: Controls the starting permission level for new users who join through self-signup.
• Note: Leave empty to create users without any role. Requires Enable Self Signup to be active. The role must already exist in Collate.

Summary

Quick reference of all configuration fields and their example values.

Field	Example / Default
Provider Name	Okta SSO
Client Type	Confidential
Enable Self Signup	Enabled
Authority	https://dev-123456.okta.com
OIDC Client ID	0oabc123def456ghi789
OIDC Client Secret	abc123def456…
OIDC Request Scopes	openid email profile
OIDC Discovery URI	https://dev-123456.okta.com/.well-known/openid-configuration
OIDC Client Authentication Method	client_secret_post
OIDC Callback URL	https://openmetadata.company.com/callback (read-only)
OIDC Prompt	login
OIDC Custom Parameters	{"prompt": "login"}
OIDC Use Nonce	false
OIDC Disable PKCE	false
OIDC Max Clock Skew	0
OIDC Token Validity	3600
OIDC Max Age	3600
OIDC Session Expiry	604800
JWT Principal Claims	["email", "preferred_username", "sub"]
JWT Principal Claims Mapping	["email:email"]
JWT Team Claim Mapping	department
Admin Principals	["admin", "superuser"]
Principal Domain	company.com
Enforce Principal Domain	false
Enable Secure Socket Connection	true
Allowed Domains	["company.com"]
Use Roles From Provider	false
Default OAuth Role	DataConsumer

Troubleshooting

If users are automatically logged out and unable to log in again due to a bad authentication configuration, you can reset the security setup using the following command:

./bootstrap/openmetadata-ops.sh remove-security-config --force

After executing the command, restart the server. The authentication values from your YAML or Helm chart will then be reapplied on startup. The following tiles detail how to apply this configuration:

Docker Security

Configure Auth0 SSO to access the UI and APIs.

Bare Metal Security

Configure Azure SSO to access the UI and APIs.

Kubernetes Security

Configure a custom OIDC SSO to access the UI and APIs.

Google SSO

Configure Google SSO to access the UI and APIs.

Okta SSO

Configure Okta SSO to access the UI and APIs.

Amazon Cognito SSO

Configure Amazon Cognito SSO to access the UI and APIs.

SAML

Configure SAML SSO to access the UI and APIs.

LDAP

Configure LDAP SSO to access the UI and APIs.