Assigning Security Roles in the Identity Provider

With SAML, OIDC and OAuth 2.0, users and API clients receive their Data Foundation security roles from the identity provider (IdP). The IdP sends a list of group or role names in a claim or attribute, and Data Foundation keeps the names that are listed in the setup file. The global privileges Administrator, Power User, Manager and Explorer User follow from the setup fields adminSecurityRoles, powerUserSecurityRoles, managerSecurityRoles and explorerSecurityRoles.

This page describes how to make popular IdPs send role names that Data Foundation can match.

General recommendations

  • Create dedicated groups or roles in the IdP for Data Foundation, with names that identify them, such as tq-admin, tq-poweruser, tq-manager and tq-user. Assign users to them in the IdP.

  • List the same names in the setup file. Names must match exactly:

    adminSecurityRoles = tq-admin
powerUserSecurityRoles = tq-poweruser
managerSecurityRoles = tq-manager
securityRoles = tq-user

  • Configure the IdP to send only the Data Foundation groups or roles, where it supports filtering. This keeps tokens small and avoids the group limits some IdPs apply.

  • For OIDC and OAuth 2.0, the mapping can name a top-level claim or a dotted path to a nested claim, such as realm_access.roles. A claim name that itself contains dots, such as https://example.com/roles, is matched as a whole first. For SAML, the mapping names an attribute.

  • Every user needs at least one recognized role. If security roles are defined in the setup file and none of a user’s values match them, Data Foundation rejects the login with HTTP status 403.

Note

With SAML and OIDC, Data Foundation reads roles when the user signs in. A change to a user’s groups or roles in the IdP takes effect at their next sign-in, after they sign out or their session expires. With OAuth 2.0, roles are read from each access token, so a change takes effect once the client gets a new token.

Microsoft Entra ID

Use app roles rather than groups. Entra sends groups as object IDs, such as a1b2c3d4-..., rather than names, and can drop the whole groups claim when a user belongs to many groups. App roles are sent by name and are not subject to that limit.

  1. In the Data Foundation app registration, open App roles and create one role per Data Foundation security role. Set Allowed member types to Users/Groups, and use the Data Foundation role name as the Value.

  2. In Enterprise applications, open the Data Foundation application, then Users and groups, and assign users or groups to the app roles.

  3. Map the claim in Data Foundation:

    • OIDC: roles: roles

    • SAML: role: http://schemas.microsoft.com/ws/2008/06/identity/claims/role

For OAuth 2.0 Client Credentials, create the app role with Allowed member types set to Applications, grant it to the client application under API permissions, and grant admin consent. Entra then includes the role in the client’s access tokens, and role: roles can be used in oauth2.yaml.

If you use groups instead, list the group object IDs in the setup file, and select Groups assigned to the application in the groups claim configuration to stay below the group limit.

Okta

Okta sends group names in a groups claim when one is configured. Use a filter to send only the Data Foundation groups.

  • OIDC with the Okta org authorization server: in the Data Foundation app, open Sign On, edit OpenID Connect ID Token, and set the Group claim type to Filter, with claim name groups and a filter such as Starts with tq-.

  • OIDC or OAuth 2.0 with a custom authorization server, such as /oauth2/default: open Security, API, Authorization Servers, select the server, and add a claim named groups on the Claims tab. Set Value type to Groups and add a filter such as Starts with tq-. Include it in the ID Token for OIDC, and in the Access Token for OAuth 2.0 user tokens.

  • SAML: on the Data Foundation app’s Sign On tab, add a custom claim for groups named group, with a filter such as Starts with tq-. Apps that use the legacy configuration have a Group Attribute Statement instead, which takes the same name and filter.

Map the claim in Data Foundation with roles: groups for OIDC, role: groups for OAuth 2.0, and role: group for SAML. For Client Credentials tokens, which carry no groups, map role: cid and list the client IDs as security roles. Client Credentials tokens for Data Foundation require a custom authorization server.

Google Workspace

Google’s OpenID Connect ID tokens do not include group membership. To assign security roles from Google Workspace groups, use SAML:

  1. In the Google Admin console, open the custom SAML app for Data Foundation, then Attribute mapping.

  2. Under Group membership, select the groups to send, and enter an app attribute name such as groups.

  3. Map the attribute in Data Foundation with role: groups.

Google sends only the selected groups, by group name. Check a real assertion to confirm the exact attribute name and values before listing them in the setup file.

Keycloak

Use realm roles. Create a realm role per Data Foundation security role, and assign it to users directly or to groups. A user receives the realm roles of all their groups.

Keycloak sends realm roles in the nested realm_access.roles claim. Map it in Data Foundation with roles: realm_access.roles for OIDC and role: realm_access.roles for OAuth 2.0.

Access tokens contain the claim by default, which covers OAuth 2.0. For OIDC, Data Foundation reads roles from the ID token, which does not contain the claim by default. To add it, open Client scopes, select the roles scope, open its Mappers tab, select realm roles, and turn Add to ID token on.

For OAuth 2.0 Client Credentials, enable Service accounts roles on the API client, and assign realm roles on its Service account roles tab. Keycloak sends them in the same claim.

To use groups instead of roles, add a Group Membership mapper with Token Claim Name groups and Full group path off, and map roles: groups or role: groups. With the full path, Keycloak sends /tq-admin instead of tq-admin, which does not match the setup file.

When Keycloak brokers logins to another identity provider and copies its groups onto a user attribute, choose the User Attribute mapper type instead, with that attribute as User Attribute and Multivalued on. This only covers users who sign in through the broker, not Client Credentials service accounts.

For SAML, Keycloak’s default role_list client scope already sends the user’s roles in a Role attribute. Map it with role: Role.