JWT profiles support

Starting with version 1.6.0, IAM introduces support for JWT profiles.

A JWT profile is a named set of rules that defines which information is included in access tokens, id tokens, userinfo and introspection responses issued by IAM in an OAuth/OIDC message exchanges.

IAM allows to define a default profile that is used for all clients that are not explicitly bound to one. This allows to use the same profile across all clients in an organization.

It’s also possible to define the profile to be used at client level, using scopes, i.e. adding among the scope allowed for the client the name of the profile the client should use. The scope, in this context, does not identify a set of permissions but an encoding of authentication/authorization informations in tokens and responses issued by IAM.

This mechanism enables integration of the same IAM instance with resources relying on different profiles.

IAM currently supports three JWT profiles:

• the iam profile
• the wlcg WLCG profile
• the aarc profile

Setting the default profile

The IAM JWT default profile is set using the IAM_JWT_DEFAULT_PROFILE environment variable, e.g.:

IAM_JWT_DEFAULT_PROFILE=iam

The default profile will be used for all clients that do not explicitly and correctly request the use of a profile using scopes.

Using scopes to select the JWT profile for a client

To select the profile used by a client, include one of the following scopes in the list of scopes authorized for a client:

• iam, for the IAM profile
• wlcg, for the WLCG profile
• aarc profile, for the AARC profile

Clients should only link to one profile. When multiple profiles are linked to a client, IAM falls back to the default profile configured for the IAM instance.

Using system scopes to control profile selection

MitreID System Scopes can be used to control access to profile selection.

The scopes iam, wlcg and aarc used to select the JWT profile are not available in IAM by default; an administrator has to add all of them manually, as described in the in System Scopes documentation.

Supported JWT profiles

The IAM profile

This is the default profile for IAM.

With this profile:

• groups are enconded in the groups claim; all the groups the user is member of are included in the groups claim;

• authentication information (username, email, groups) is not by default included in access tokens; this behaviour can be changed by setting the IAM_ACCESS_TOKEN_INCLUDE_AUTHN_INFO=true environment variable;

• scope information is not by default included in access tokens; this behaviour can be changed by setting the IAM_ACCESS_TOKEN_INCLUDE_SCOPE=true environment variable;

• the nbf (not before) claim is not set in access tokens; this behaviour can be changed by setting the IAM_ACCESS_TOKEN_INCLUDE_NBF=true environment variable;

This profile is assigned to clients using the iam scope.

The WLCG profile

This profile implements the Common JWT Token profile.

In particular:

• the scope claim is always included in access tokens;
• groups are not included by default in access and ID tokens;

This profile is assigned to clients using the wlcg scope.

Requesting groups with the WLCG profile

When the WLCG profile is used, groups are not automatically included in access tokens and ID tokens, but can be requested using the wlcg.groups scope (which has to be added among the System Scopes), following the rules described in the WLCG profile.

Optional groups

Optional groups are groups whose membership is only asserted in tokens on explicit request coming from a user.

In order to configure a IAM group as an optional group, add the wlcg.optional-group label to the group.

The AARC profile

This profile encodes group membership information following the rules defined by the AARC G002 profile document.

In particular:

• groups and organisation name are not included by default in access and ID tokens;
• organisation name can be requested using the eduperson_scoped_affiliation scope and it’s encoded in the eduperson_scoped_affiliation claim;
• groups can be requested using the eduperson_entitlement scope and they’re encoded as URN in the eduperson_entitlement claim;

All the mapping rules are described in the White Paper for implementation mappings between SAML 2.0 and OpenID Connect in Research and Education.

This profile is assigned to clients using the aarc scope.