Okta OIDC Provider

This guide walks through configuring Okta as an OpenID Connect (OIDC) provider for Synadia Control Plane, including setting up group claims for automatic role mapping.

Overview

The integration between Okta and Control Plane follows this flow:

1. Okta: Create groups and assign users
2. Okta: Configure your OIDC application to include a groups claim
3. Control Plane: Add the OIDC provider with the correct scope and claims mapping
4. Control Plane: Create group mappings that link Okta groups to Control Plane roles

Step 1: Create groups in Okta

Groups in Okta are used to organize users. These group names become the identifiers that Control Plane uses for role mapping.

In the Okta Admin Console:

1. Navigate to Directory → Groups
2. Click Add Group
3. Enter a Name (e.g., engineering) and optional description
4. Click Save

Assign users to the group

1. Click on the group name to open its detail page
2. Click Assign people
3. Select users to add to the group

Step 2: Configure the groups claim in Okta

Okta must be configured to include group membership in the OIDC token. This is done on the application's Sign On tab under Token Claims.

1. In the Okta Admin Console, navigate to Applications → Applications
2. Select your OIDC application
3. Go to the Sign On tab
4. Scroll down to the Token Claims section
5. Expand Show legacy configuration to view the Group Claims settings
6. Click Edit and configure the groups claim filter to groups with Matches regex .*

This ensures that when a user authenticates, all their group memberships are included as a groups claim in the id_token.

Step 3: Configure the OIDC provider in Control Plane

When adding or editing the Okta OIDC provider in Control Plane, two fields require the groups value to enable group mapping.

Scope

The Scope field must include groups alongside the standard OIDC scopes:

email, openid, profile, groups

Claims

The Claims Mapping field in the Advanced Configuration section must also include groups:

"email,name,groups"

Jsonnet mapper

If using Jsonnet is required to extract the groups claim from the token and pass it to Control Plane as a trait. Add the following to the provider's mapper_schema:

local claims = std.extVar('claims');
{
  identity: {
    traits: {
      username: claims.preferred_username,
      name: claims.name,
      [if 'groups' in claims.raw_claims then 'groups' else null]: claims.raw_claims.groups,
    },
  },
}

Step 4: Create group mappings in Control Plane

With the Okta groups claim flowing into Control Plane, you can now map Okta groups to Control Plane roles.

1. Navigate to the OIDC provider detail page
2. Scroll to the Group Mappings section
3. Click Manage Group Mappings
4. Click Add Group Mapping
5. Enter the Group ID — this must exactly match the Okta group name (e.g., engineering)
6. Assign teams, systems, and accounts with their respective roles

For full details on configuring group mappings and the available roles, see the OIDC Group Mapping section of the main OIDC guide.

Demo

The following video demonstrates the end-to-end setup of Okta OIDC with group mapping in Control Plane.

Best viewed in full-screen or a pop-out window.

Troubleshooting