Mapping Keycloak default roles to specific client scopes

Question

Pulumi · Accepted Answer

To accomplish the task of mapping Keycloak default roles to specific client scopes, we'll be utilizing Pulumi's Keycloak provider. The process can be broken down into several steps, which we'll go through in detail.

First, we need to define the realm and the client within that realm for which we want to manage default roles and client scopes. Once the realm and client are set up, we will create the default roles for that realm. After that, we will create a client scope, and then we will map the default roles to this client scope using the Generic Role Mapper resource.

The resources we will use are as follows:

- `keycloak.DefaultRoles`: To handle the assignment of default roles for a Keycloak realm. This is useful to define roles that will be assigned by default to all users within a realm.
- `keycloak.openid.ClientScope`: This resource allows us to define a client scope. Client scopes allow you to define a common set of roles and other settings that can be applied to multiple clients.
- `keycloak.GenericRoleMapper`: The Generic Role Mapper resource enables us to map roles to client scopes. This is how we associate the default roles of the realm with the specific client scope.

Here's how you would write the program in TypeScript:

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

// Define the realm. Replace 'my-realm' with the actual realm name.
const realm = new keycloak.Realm('my-realm', {
    realm: 'my-realm',
    enabled: true,
});

// Define the client within the realm. Replace 'my-client' with the actual client ID.
const client = new keycloak.OpenIdClient('my-client', {
    realmId: realm.id,
    clientId: 'my-client',
    enabled: true,
    // Other client settings as needed.
});

// Define default roles for our realm.
const defaultRoles = new keycloak.DefaultRoles('default-roles', {
    realmId: realm.id,
    defaultRoles: [
        'role-1',
        'role-2',
        // Add other default roles as needed.
    ],
});

// Define a client scope to which we will map the default roles.
const clientScope = new keycloak.openid.ClientScope('my-client-scope', {
    realmId: realm.id,
    name: 'my-client-scope',
    description: 'A scope to consolidate default roles',
});

// Map the default roles to the client scope.
const roleMapper1 = new keycloak.GenericRoleMapper('role-mapper-1', {
    realmId: realm.id,
    clientScopeId: clientScope.id,
    roles: defaultRoles.defaultRoles,
});

// Export relevant URLs or IDs for the created resources.
export const realmUrl = realm.realm; // The URL of the realm.
export const clientUrl = client.clientId; // The ID of the client.
export const clientScopeName = clientScope.name; // The name of the client scope.
export const roleMapperUrl = roleMapper1.id; // The ID of the role mapper.
```

Explanation of what we did:

1. Imported the required modules from Pulumi and Keycloak.
2. Created a new `Realm` using `keycloak.Realm`. `my-realm` should be replaced with your desired realm name.
3. Created a new `OpenIdClient` within the realm, with client settings as needed.
4. Assigned default roles for our realm via `keycloak.DefaultRoles`.
5. Created a new `ClientScope` with the name `my-client-scope`. This will be used to consolidate roles for clients.
6. Mapped the default roles to this client scope using `keycloak.GenericRoleMapper`, ensuring that roles defined as defaults are associated with the scope we just created.
7. Finally, we exported some of the resource details, like URLs or IDs, to allow interaction or retrieval outside of Pulumi.

Remember to replace placeholders like 'my-realm', 'my-client', and 'role-1' with actual values that are relevant to your Keycloak setup. You will need to have the Keycloak provider configured with the necessary credentials and endpoint for this program to work.

This program can be used as a baseline and modified as necessary to fit the specific details of your Keycloak environment and the roles and scopes you need to handle.