This article will go a little beyond the usual, “do this, do that” of many knowledge base articles. It will instead attempt to explain the custom scope 6clicks uses to match a user with roles within 6clicks.
It will help explain the use of the checkbox within the SSO setup named, “Include "groups" scope in Authentication Request to Authorization“, and when it is required to be checked.
Note: If you are using the Okta Org Server - which would mean the Issuer URI you supplied is https://{yourOktaDomain} - then you should check the box and always send the ‘groups’ scope.
OpenID Connect (OIDC) is an authentication protocol built on top of OAuth 2.0, which allows clients to verify the identity of users based on the authentication performed by an Identity Provider (IdP). Some common IdPs are Okta, Azure AD (Entra ID), Ping, One Login, and ForgeRock but there are many others by providers including AWS, Google, and SAP.
In OIDC, a "scope" is a mechanism used to request specific pieces of information, known as "claims," about the authenticated user. An example of a few of the common OpenID Connect scopes is listed here. 6clicks uses each of these scopes:
-
openid: This is the essential scope that must be included in every OIDC request to indicate that the client is using OpenID Connect. The resulting ID token contains basic identity claims about the user.
-
profile: This scope requests access to the user's default profile claims, which may include information like name, preferred username, first and last name, and profile picture, amongst others.
-
email: This scope requests access to the user's email address.
In addition to these standard OIDC scopes, it is possible to define custom scopes to request additional claims specific to your application. 6clicks has a custom claim called ‘6clicksRoles’ which requires a value of ‘6clicks-roles-<rolename>’ as the variable. Each user can have many role values and these match roles set up in 6clicks.
An example of roles within 6clicks.
Unfortunately, as far as consistency is concerned, each IdP has a slightly different way of implementing how custom scopes and claims work. For example:
-
Okta’s Org Authorisation Server adds all custom claims to the ‘groups’ scope. This means you need to select the ‘Include "groups" scope in Authentication Request to Authorization’ checkbox to ensure the group's scope, with the included 6clicksRoles claim is included in the ID token.
-
Okta’s Custom Authorisation Server allows you to add a custom claim to an existing scope. This is the method we have shown in the KB article. However, it is also possible to create a custom scope, called ‘groups’ and attach the custom claim, 6clicksRoles, to this scope. If you choose to use this method, then it would be necessary to then include the ‘groups’ scope by checking the “Include "groups" scope in Authentication Request to Authorization” box.
In short, it does not matter how you choose to get the custom claim, 6clicksRoles, with the corresponding values into the ID token for each user, as long as it is present.