Add a Groups claim with a static allow list
On This Page
You can create a static allow list when you need to set group allow lists on a per-application basis. If you have a large number of Groups but only 20 Groups apply to your app, you don't want to run through all of your Groups every time a Groups claim is created.
This process optionally uses Okta's flexible app profile, which accepts any JSON-compliant content, to create an allow list of Groups that can then easily be referenced.
The following sections walk you through creating a Groups claim, assigning a group allow list to your client app, and configuring a Groups claim that references an allow list for the authorization server that you want to use.
For this example, we're configuring just one group (the IT group) for simplicity. This group has a group ID of: 00goeudyucv6CcaeV0h7
and the OpenID Connect client used has a client ID of: 0oaoesxtxmPf08QHk0h7
.
Get the group IDs
Send a request to https://${yourOktaDomain}/api/v1/groups
and collect the IDs for all of the Groups that you want in the allow list.
Request example
curl -X GET \
-H 'accept: application/json' \
-H 'authorization: SSWS ${api_token}' \
-H 'content-type: application/json' \
"https://${yourOktaDomain}/api/v1/groups"
Response example
{
"id": "00goeudyucv6CcaeV0h7",
"created": "2019-11-12T19:56:23.000Z",
"lastUpdated": "2019-11-12T19:56:23.000Z",
"lastMembershipUpdated": "2019-11-12T22:59:13.000Z",
"objectClass": [
"okta:user_group"
],
"type": "OKTA_GROUP",
"profile": {
"name": "IT",
"description": "Info Tech"
},
"_links": {
"logo": [
{
"name": "medium",
"href": "https://op1static.oktacdn.com/assets/img/logos/groups/okta-medium.d7fb831bc4e7e1a5d8bd35dfaf405d9e.png",
"type": "image/png"
},
{
"name": "large",
"href": "https://op1static.oktacdn.com/assets/img/logos/groups/okta-large.511fcb0de9da185b52589cb14d581c2c.png",
"type": "image/png"
}
],
"users": {
"href": "https://${yourOktaDomain}/api/v1/groups/00goeudyucv6CcaeV0h7/users"
},
"apps": {
"href": "https://${yourOktaDomain}/api/v1/groups/00goeudyucv6CcaeV0h7/apps"
}
}
}
Add a list of Groups to the client App profile
If your allow list has a lot of Groups, you can store the Group IDs as a string array property in the client App's profile. You can add App Groups, User Groups, or both to the Group allow list specified as an array of IDs. If you only have one or two Groups to specify, simply add the Group IDs to the first parameter of the getFilteredGroups
function described in the next step.
The following example names the group allow list groupallowlist
, but you can name it anything.
Tip: To build your request body, you can first perform a GET to the
/apps
endpoint (https://${yourOktaDomain}/api/v1/apps/${applicationId}
) using theapplicationId
for the app that you want to add the Groups list to. Then, copy the response JSON that you receive to help build your request JSON for this example.
The profile
property that contains the allow list is at the bottom of the request example.
Request example
{
"name": "oidc_client",
"label": "OIDC APP Name",
"status": "ACTIVE",
"signOnMode": "OPENID_CONNECT",
"credentials": {
"oauthClient": {
"autoKeyRotation": true,
"client_id": "0oaoesxtxmPf08QHk0h7",
"token_endpoint_auth_method": "client_secret_basic"
}
},
"settings": {
"oauthClient": {
"client_uri": null,
"logo_uri": null,
"redirect_uris": [
"http://yourredirecturihere.com/"
],
"response_types": [
"code",
"id_token",
"token"
],
"grant_types": [
"authorization_code",
"client_credentials",
"implicit"
],
"application_type": "web",
"consent_method": "REQUIRED",
"issuer_mode": "CUSTOM_URL"
}
},
"profile": {
"groupallowlist": [
"00goeudyucv6CcaeV0h7"
]
}
}
To use the group allow list for every client that gets this claim in a token, put the attribute name of the allow list in the first parameter of the getFilteredGroups
function described in the next step.
Note: The following Use group functions for static group allow lists section goes into more detail on using group functions with static group allow lists. To continue with creating a Groups claim with a static allow list, skip to the next section.
Use group functions for static group allow lists
This section discusses the getFilteredGroups
group function and how it helps you use a static group allow list.
getFilteredGroups
returns all Groups that are contained in a specified list, the allow list, of which the user is a member. The Groups are returned in a format specified by the group_expression
parameter. You must specify the maximum number of Groups to return in the expression.
The EL function format: getFilteredGroups(allow list, group_expression, limit)
You can use this function anywhere to get a list of Groups of which the current user is a member, including both User Groups and App Groups that originate from sources outside Okta, such as from Active Directory and Workday. Additionally, you can use this combined, custom-formatted list for customizable claims into access and ID tokens that drive authorization flows.
Important: When you use
Groups.startWith
,Groups.endsWith
, orGroups.contains
, thepattern
argument is matched and populated on thename
attribute rather than the group's email (for example, when using G Suite). If you are targeting groups that may have duplicate group names (such as Google Groups), thegetFilteredGroups
Group function is the best function for that use case.
This function takes Okta EL expressions for all parameters that evaluate to the correct data type. With these expressions you can create complex definitions for the allow list, for the group format, and for the number of Groups to return that can include if
logic and customized formatting.
Parameter | Description | Nullable |
---|---|---|
allowlist | Valid Okta EL expression that evaluates to a string array of group ids | FALSE |
group_expression | Valid Okta EL expression that evaluates to a string for use in evaluating the group. This string must also be a valid Okta EL expression. | FALSE |
limit | Valid Okta EL expression that evaluates to an integer between 1 and 100, inclusive, to indicate the maximum number of Groups to return | FALSE |
The string produced by the group_expression
parameter usually contains attributes and objects from the Groups API, although it isn't limited to those attributes and objects. Attributes and objects listed in the Group Attributes section of the Groups API can be any of the following: id
, status
, name
, description
, objectClass
, and the profile
object that contains the groupType
, samAccountName
, objectSid
, groupScope
, windowsDomainQualifiedName
, dn
, and externalID
attributes for Groups that come from apps such as Active Directory.
The allowlist parameter must evaluate to a list of group IDs that are returned from the Groups API. If the user isn't a member of a group in the allowlist, that group is ignored.
Parameter Examples
- allowlist
- Array:
{"00gn335BVurvavwEEL0g3", "00gnfg5BVurvavAAEL0g3"}
- Array variable:
app.profile.groupallowlist
- Array:
- group_expression
- Attribute name:
"group.id"
- Okta EL string that contains an
if
condition:"(group.objectClass[0] == 'okta:windows_security_principal') ? 'AD: ' + group.profile.windowsDomainQualifiedName : 'Okta: ' + group.name"
Ifokta:windows_security_principal
is true for a group, the function returns thewindowsDomainQualifiedName
prefixed withAD:
. Otherwise, the function returns the group name prefixed withOkta:
.
- Attribute name:
- limit
- Integer between 1 and 100, inclusive. For example:
50
- Okta EL expression that contains a condition that evaluates to an integer:
app.profile.maxLimit < 100 ? app.profile.maxLimit : 100
. If the maximum group limit in the profile is less than 100, return that number of Groups. Otherwise, return a maximum of 100 Groups. If there are more Groups returned than the specified limit, an error is returned.
- Integer between 1 and 100, inclusive. For example: