Mapping custom user attributes to OpenID Connect tokens

Question

Pulumi · Accepted Answer

Mapping custom user attributes to OpenID Connect (OIDC) tokens often involves modifying configurations in an Identity Provider (IdP) such as Keycloak, Okta, or AWS Cognito. These platforms allow you to define custom attributes for users and then specify how these attributes are included in the tokens that the IdP issues.

Below, I will walk you through a Pulumi program using TypeScript that demonstrates how to create a custom user attribute and map it to an OIDC token using the Keycloak provider as an example. Keycloak is a widely-used open-source identity and access management solution that supports OIDC among other protocols.

### Step-by-Step Explanation

1. **Provider Setup**: First, ensure that you have set up the Keycloak provider in your Pulumi project. You will need to specify the URL of the Keycloak instance and have the credentials to authenticate requests.

2. **Realm Configuration**: In Keycloak, a Realm is an isolated environment. It contains the users, sessions, clients, and resources that you want to manage and protect. You will need to specify or create a realm for which you want to map custom user attributes.

3. **Custom User Attribute Creation**: Define a custom user attribute for Keycloak users. Custom user attributes can be any additional information you want to associate with a user.

4. **Token Mapping**: You will then create an OIDC `UserAttributeProtocolMapper` to map the custom user attributes into the token. This mapper will allow the custom attributes to be included as claims in the token.

5. **Output the Tokens**: Finally, you would typically configure a client or API to authenticate using Keycloak to retrieve OIDC tokens, which will now include the custom attributes. In the Pulumi program below, we focus on setting up the mapping.

### Pulumi Program

The following program sets up custom attributes on a user and maps them to OIDC tokens. Before you run this code, ensure that you have the `keycloak` provider configured in your Pulumi project.

```typescript
import * as pulumi from "@pulumi/pulumi";
import * as keycloak from "@pulumi/keycloak";

// Create or reference the realm under which the user and attribute mapping will be created
const realm = new keycloak.Realm("example-realm", {
    realm: "example",
    enabled: true,
});

// Create a custom attribute protocol mapper that maps the custom user attribute(s) to an OIDC claim
const customAttributeMapper = new keycloak.openid.UserAttributeProtocolMapper("custom-attribute-mapper", {
    realmId: realm.id,
    name: "custom-attribute-mapper",
    clientId: "<YOUR-CLIENT-ID>", // Please replace with your client ID
    userAttribute: "customAttributeName",
    claimName: "customClaimName",
    claimValueType: "String",
    addToIdToken: true,
    addToAccessToken: true,
    addToUserinfo: true,
    multivalued: false,
    aggregateAttributes: false,
});

// Output the name of the mapper for verification purposes
export const mapperName = customAttributeMapper.name;
```

In this program:

- We import Pulumi and the Keycloak package.
- A new realm is created or referenced using `keycloak.Realm`.
- A `UserAttributeProtocolMapper` is defined to map a custom user attribute to an OIDC claim named `customClaimName`.
- `clientId` should be replaced with the actual client ID of the Keycloak client you want to map the attribute to.
- We set `addToIdToken`, `addToAccessToken`, and `addToUserinfo` to `true`, indicating that this custom attribute should be included in all relevant tokens issued by Keycloak.
- The program then exports the name of the attribute mapper for verification purposes.

For more information, you can visit the [Keycloak Provider documentation](https://www.pulumi.com/registry/packages/keycloak/api-docs/openid/userattributeprotocolmapper/).

After you compile and run this Pulumi program, the described resources will be created in your Keycloak instance, linking custom user attributes to your OIDC tokens. You can then inspect your tokens upon authentication and see the custom claims embedded within.