Send Okta groups for role mapping

Workforce Intelligence grants abilities from the group names your identity provider sends at sign-in. This article shows how to make Okta send them. It assumes you have already added the domain as described in Set up single sign-on. You need the admin ability in Workforce Intelligence and an Okta administrator account.

What Workforce Intelligence reads:

• OIDC: the ID token's groups or roles claim, or the single claim you name in Claim name. If the ID token has no such claim, the provider's userinfo endpoint is checked.
• SAML: the groups or roles attribute, or the single attribute you name in Role attribute name.

When you set a name, only that exact name is read.

Workforce Intelligence asks for the openid, profile and email scopes only. It does not request a groups scope, so the claim has to be included without one.

OpenID Connect#

Use a custom authorization server (Okta's default one works) so you control the claim.

1. In the Okta Admin Console, create an OIDC - OpenID Connect app integration of type Web Application. Set the Sign-in redirect URI to the OIDC redirect URI shown on the Single sign-on page (it ends in /auth/callback), assign the people or groups who may sign in, and note the client ID and secret.

2. Open Security > API > Authorization Servers, and select the server you use. Note its Issuer URI, for example https://company.okta.com/oauth2/default.

3. On the Claims tab, select Add Claim and enter:

   Field	Value
   Name	groups
   Include in token type	ID Token, Always
   Value type	Groups
   Filter	Matches regex .*, or narrow it, for example Starts with wi-
   Include in	Any scope

4. Save the claim. Use Token Preview on the server's page to check that a test user's ID token includes groups.

5. In Workforce Intelligence, add the domain as OpenID Connect (OIDC) with the Issuer from step 2, and the Client ID and Client secret from step 1. Leave Claim name blank, because groups is read by default. If you named the claim something else, enter that name.

6. Select Edit mapping, add a row for each group, and pick its ability. The value is the group's name exactly as Okta shows it.

Okta's own filter limits which groups are sent, so a group that does not match the filter is never seen by Workforce Intelligence.

SAML 2.0#

1. In Workforce Intelligence, add the domain as SAML 2.0 and copy its service provider details as described in Set up SAML 2.0.

2. In Okta, create a SAML 2.0 app integration. Enter the Assertion consumer service (ACS) URL as the Single sign-on URL and the Service provider entity ID as the Audience URI (SP Entity ID). Set Name ID format to EmailAddress and Application username to Email.

3. Under Group Attribute Statements, add one statement:

   Field	Value
   Name	groups
   Filter	Matches regex .*, or narrow it to the groups you want

4. Assign the people or groups to the application, finish creating it, and copy the application's metadata URL from the Sign On tab.

5. In Workforce Intelligence, select Add identity provider details and paste the metadata URL, then select Save. Leave Role attribute name blank when the attribute is named groups.

6. Use Edit mapping as in the OIDC steps, with the group names as values.

Check that it works#

Sign in as a test user who is in one of the mapped groups. Mapped abilities apply from that sign-in. If nothing changed:

• Sign out and back in. Mappings are read at each sign-in.
• Confirm the mapping value matches the group name character for character.
• For OIDC, confirm the claim reaches the ID token for Any scope, and that Claim name matches the claim you created.
• For SAML, confirm Role attribute name matches the Name of the group attribute statement.

The audit log records the abilities each sign-in granted. See Map provider roles to abilities for how mapped abilities behave, and Set up SCIM provisioning to also push people and groups from Okta.