keycloak(feat): add recipes for client management

keycloak/justfile

@@ -191,6 +191,16 @@ delete-realm realm:
     export KEYCLOAK_REALM_TO_DELETE={{ realm }}
     dotenvx run -q -f ../.env.local -- tsx ./scripts/delete-realm.ts
 
+# Check if Keycloak client exists
+client-exists realm client_id:
+    #!/bin/bash
+    set -euo pipefail
+    export KEYCLOAK_ADMIN_USER=$(just admin-username)
+    export KEYCLOAK_ADMIN_PASSWORD=$(just admin-password)
+    export KEYCLOAK_REALM={{ realm }}
+    export KEYCLOAK_CLIENT_ID={{ client_id }}
+    dotenvx run -q -f ../.env.local -- tsx ./scripts/client-exists.ts
+
 # Create Keycloak client
 create-client realm client_id redirect_url client_secret='' session_idle='' session_max='':
     #!/bin/bash
@@ -243,6 +253,30 @@ add-attribute-mapper client_id attribute_name display_name='' claim_name='' opti
     export ATTRIBUTE_EDIT_PERMISSIONS="{{ edit_perms }}"
     dotenvx run -q -f ../.env.local -- tsx ./scripts/add-attribute-mapper.ts
 
+# Add client roles mapper for Keycloak client
+add-client-roles-mapper client_id claim_name='client_roles' mapper_name='':
+    #!/bin/bash
+    set -euo pipefail
+    export KEYCLOAK_ADMIN_USER=$(just keycloak::admin-username)
+    export KEYCLOAK_ADMIN_PASSWORD=$(just keycloak::admin-password)
+    export KEYCLOAK_REALM=${KEYCLOAK_REALM}
+    export CLIENT_ID={{ client_id }}
+    export CLAIM_NAME="{{ claim_name }}"
+    export MAPPER_NAME="{{ mapper_name }}"
+    dotenvx run -q -f ../.env.local -- tsx ./scripts/add-client-roles-mapper.ts
+
+# Update client roles mapper for Keycloak client (force recreation)
+update-client-roles-mapper client_id claim_name='client_roles' mapper_name='':
+    #!/bin/bash
+    set -euo pipefail
+    export KEYCLOAK_ADMIN_USER=$(just keycloak::admin-username)
+    export KEYCLOAK_ADMIN_PASSWORD=$(just keycloak::admin-password)
+    export KEYCLOAK_REALM=${KEYCLOAK_REALM}
+    export CLIENT_ID={{ client_id }}
+    export CLAIM_NAME="{{ claim_name }}"
+    export MAPPER_NAME="{{ mapper_name }}"
+    dotenvx run -q -f ../.env.local -- tsx ./scripts/update-client-roles-mapper.ts
+
 # Add Keycloak client groups mapper
 add-groups-mapper client_id:
     #!/bin/bash
@@ -495,6 +529,59 @@ add-user-to-client-role realm username client_id role_name:
     export KEYCLOAK_ROLE_NAME={{ role_name }}
     dotenvx run -q -f ../.env.local -- tsx ./scripts/add-user-to-client-role.ts
 
+# List user's client roles
+list-user-client-roles realm username client_id:
+    #!/bin/bash
+    set -euo pipefail
+    export KEYCLOAK_ADMIN_USER=$(just admin-username)
+    export KEYCLOAK_ADMIN_PASSWORD=$(just admin-password)
+    export KEYCLOAK_REALM={{ realm }}
+    export USERNAME={{ username }}
+    export KEYCLOAK_CLIENT_ID={{ client_id }}
+    dotenvx run -q -f ../.env.local -- tsx ./scripts/list-user-client-roles.ts
+
+# Get user token information and client configuration
+get-user-token-info realm username client_id:
+    #!/bin/bash
+    set -euo pipefail
+    export KEYCLOAK_ADMIN_USER=$(just admin-username)
+    export KEYCLOAK_ADMIN_PASSWORD=$(just admin-password)
+    export KEYCLOAK_REALM={{ realm }}
+    export USERNAME={{ username }}
+    export KEYCLOAK_CLIENT_ID={{ client_id }}
+    dotenvx run -q -f ../.env.local -- tsx ./scripts/get-user-token.ts
+
+# Get client secret from Keycloak
+get-client-secret realm client_id:
+    #!/bin/bash
+    set -euo pipefail
+    export KEYCLOAK_ADMIN_USER=$(just admin-username)
+    export KEYCLOAK_ADMIN_PASSWORD=$(just admin-password)
+    export KEYCLOAK_REALM={{ realm }}
+    export KEYCLOAK_CLIENT_ID={{ client_id }}
+    dotenvx run -q -f ../.env.local -- tsx ./scripts/get-client-secret.ts
+
+# Check detailed mapper configuration
+check-mapper-details realm client_id:
+    #!/bin/bash
+    set -euo pipefail
+    export KEYCLOAK_ADMIN_USER=$(just admin-username)
+    export KEYCLOAK_ADMIN_PASSWORD=$(just admin-password)
+    export KEYCLOAK_REALM={{ realm }}
+    export KEYCLOAK_CLIENT_ID={{ client_id }}
+    dotenvx run -q -f ../.env.local -- tsx ./scripts/check-mapper-details.ts
+
+# Add client roles mapper to profile scope (generic)
+add-client-roles-to-profile-scope realm client_id claim_name='client_roles':
+    #!/bin/bash
+    set -euo pipefail
+    export KEYCLOAK_ADMIN_USER=$(just admin-username)
+    export KEYCLOAK_ADMIN_PASSWORD=$(just admin-password)
+    export KEYCLOAK_REALM={{ realm }}
+    export KEYCLOAK_CLIENT_ID={{ client_id }}
+    export CLAIM_NAME="{{ claim_name }}"
+    dotenvx run -q -f ../.env.local -- tsx ./scripts/add-client-roles-to-profile-scope.ts
+
 # Remove user from client role
 remove-user-from-client-role realm username client_id role_name:
     #!/bin/bash

keycloak/scripts/add-client-roles-mapper.ts

@@ -0,0 +1,89 @@
+#!/usr/bin/env tsx
+
+import KcAdminClient from "@keycloak/keycloak-admin-client";
+import invariant from "tiny-invariant";
+
+async function main() {
+  const keycloakHost = process.env.KEYCLOAK_HOST;
+  invariant(keycloakHost, "KEYCLOAK_HOST environment variable is required.");
+
+  const adminUsername = process.env.KEYCLOAK_ADMIN_USER;
+  invariant(adminUsername, "KEYCLOAK_ADMIN_USER environment variable is required.");
+
+  const adminPassword = process.env.KEYCLOAK_ADMIN_PASSWORD;
+  invariant(adminPassword, "KEYCLOAK_ADMIN_PASSWORD environment variable is required");
+
+  const realmName = process.env.KEYCLOAK_REALM;
+  invariant(realmName, "KEYCLOAK_REALM environment variable is required");
+
+  const clientId = process.env.CLIENT_ID;
+  invariant(clientId, "CLIENT_ID environment variable is required");
+
+  const mapperName = process.env.MAPPER_NAME || `${clientId} client roles`;
+  const claimName = process.env.CLAIM_NAME || "client_roles";
+
+  const kcAdminClient = new KcAdminClient({
+    baseUrl: `https://${keycloakHost}`,
+    realmName: "master",
+  });
+
+  try {
+    await kcAdminClient.auth({
+      username: adminUsername,
+      password: adminPassword,
+      grantType: "password",
+      clientId: "admin-cli",
+    });
+
+    // Set realm to work with
+    kcAdminClient.setConfig({
+      realmName,
+    });
+
+    // Find the client
+    const clients = await kcAdminClient.clients.find({ clientId });
+    if (clients.length === 0) {
+      throw new Error(`Client '${clientId}' not found in realm '${realmName}'`);
+    }
+
+    const client = clients[0];
+    const clientInternalId = client.id!;
+
+    // Check if the mapper already exists
+    const mappers = await kcAdminClient.clients.listProtocolMappers({ id: clientInternalId });
+    const existingMapper = mappers.find((mapper) => mapper.name === mapperName);
+
+    if (existingMapper) {
+      console.log(`Client roles mapper '${mapperName}' already exists for client '${clientId}'`);
+      return;
+    }
+
+    // Create the client roles protocol mapper
+    await kcAdminClient.clients.addProtocolMapper(
+      { id: clientInternalId },
+      {
+        name: mapperName,
+        protocol: "openid-connect",
+        protocolMapper: "oidc-usermodel-client-role-mapper",
+        config: {
+          "userinfo.token.claim": "true",
+          "id.token.claim": "true",
+          "access.token.claim": "true",
+          "claim.name": claimName,
+          "jsonType.label": "String",
+          "multivalued": "true",
+          "usermodel.clientRoleMapping.clientId": clientId,
+        },
+      }
+    );
+
+    console.log(`✓ Client roles mapper '${mapperName}' created for client '${clientId}' in realm '${realmName}'`);
+    console.log(`  Claim name: ${claimName}`);
+    console.log(`  Maps client roles from '${clientId}' to JWT token`);
+  } catch (error) {
+    console.error("An error occurred:", error);
+    process.exit(1);
+  }
+}
+
+main().catch(console.error);

keycloak/scripts/add-client-roles-to-profile-scope.ts

@@ -0,0 +1,88 @@
+#!/usr/bin/env tsx
+
+import KcAdminClient from "@keycloak/keycloak-admin-client";
+import invariant from "tiny-invariant";
+
+async function main() {
+  const kcAdminClient = new KcAdminClient({
+    baseUrl: `https://${process.env.KEYCLOAK_HOST}`,
+    realmName: "master",
+  });
+
+  await kcAdminClient.auth({
+    username: process.env.KEYCLOAK_ADMIN_USER!,
+    password: process.env.KEYCLOAK_ADMIN_PASSWORD!,
+    grantType: "password",
+    clientId: "admin-cli",
+  });
+
+  const realm = process.env.KEYCLOAK_REALM!;
+  const clientId = process.env.KEYCLOAK_CLIENT_ID!;
+  const claimName = process.env.CLAIM_NAME || "client_roles";
+
+  invariant(realm, "KEYCLOAK_REALM is required");
+  invariant(clientId, "KEYCLOAK_CLIENT_ID is required");
+
+  kcAdminClient.setConfig({ realmName: realm });
+
+  try {
+    // Find the profile client scope
+    const clientScopes = await kcAdminClient.clientScopes.find({ realm });
+    const profileScope = clientScopes.find(scope => scope.name === 'profile');
+
+    if (!profileScope) {
+      throw new Error("Profile client scope not found");
+    }
+
+    console.log(`Found profile scope: ${profileScope.id}`);
+
+    // Check existing mappers in profile scope
+    const existingMappers = await kcAdminClient.clientScopes.listProtocolMappers({
+      realm,
+      id: profileScope.id!,
+    });
+
+    console.log("Existing mappers in profile scope:");
+    existingMappers.forEach(mapper => {
+      console.log(`- ${mapper.name} (${mapper.protocolMapper})`);
+    });
+
+    // Check if our client roles mapper already exists in profile scope
+    const clientRolesMapper = existingMappers.find(m =>
+      m.config?.['usermodel.clientRoleMapping.clientId'] === clientId
+    );
+
+    if (clientRolesMapper) {
+      console.log(`Client roles mapper already exists in profile scope: ${clientRolesMapper.name}`);
+    } else {
+      console.log(`Adding ${clientId} client roles mapper to profile scope...`);
+
+      // Add client roles mapper to profile scope
+      await kcAdminClient.clientScopes.addProtocolMapper(
+        { realm, id: profileScope.id! },
+        {
+          name: `${clientId} Client Roles`,
+          protocol: "openid-connect",
+          protocolMapper: "oidc-usermodel-client-role-mapper",
+          config: {
+            "userinfo.token.claim": "true",
+            "id.token.claim": "true",
+            "access.token.claim": "true",
+            "claim.name": claimName,
+            "jsonType.label": "String",
+            "multivalued": "true",
+            "usermodel.clientRoleMapping.clientId": clientId,
+          },
+        }
+      );
+
+      console.log(`✓ Added ${clientId} client roles mapper to profile scope`);
+    }
+
+  } catch (error) {
+    console.error(`Error: ${error}`);
+    process.exit(1);
+  }
+}
+
+main().catch(console.error);

keycloak/scripts/check-mapper-details.ts

@@ -0,0 +1,78 @@
+#!/usr/bin/env tsx
+
+import KcAdminClient from "@keycloak/keycloak-admin-client";
+import invariant from "tiny-invariant";
+
+async function main() {
+  const kcAdminClient = new KcAdminClient({
+    baseUrl: `https://${process.env.KEYCLOAK_HOST}`,
+    realmName: "master",
+  });
+
+  await kcAdminClient.auth({
+    username: process.env.KEYCLOAK_ADMIN_USER!,
+    password: process.env.KEYCLOAK_ADMIN_PASSWORD!,
+    grantType: "password",
+    clientId: "admin-cli",
+  });
+
+  const realm = process.env.KEYCLOAK_REALM!;
+  const clientId = process.env.KEYCLOAK_CLIENT_ID!;
+
+  invariant(realm, "KEYCLOAK_REALM is required");
+  invariant(clientId, "KEYCLOAK_CLIENT_ID is required");
+
+  try {
+    // Find the client
+    const clients = await kcAdminClient.clients.find({ realm, clientId });
+    if (clients.length === 0) {
+      throw new Error(`Client '${clientId}' not found in realm '${realm}'`);
+    }
+
+    const client = clients[0];
+
+    // Get all protocol mappers with full details
+    const mappers = await kcAdminClient.clients.listProtocolMappers({
+      realm,
+      id: client.id!,
+    });
+
+    console.log(`=== All Protocol Mappers for client '${clientId}' ===`);
+    mappers.forEach((mapper, index) => {
+      console.log(`\n${index + 1}. ${mapper.name}`);
+      console.log(`   Protocol: ${mapper.protocol}`);
+      console.log(`   Type: ${mapper.protocolMapper}`);
+      console.log(`   Config:`);
+      if (mapper.config) {
+        Object.entries(mapper.config).forEach(([key, value]) => {
+          console.log(`     ${key}: ${value}`);
+        });
+      }
+    });
+
+    // Check client scope assignments
+    console.log(`\n=== Client Scope Assignments ===`);
+
+    // Get default client scopes
+    const defaultScopes = await kcAdminClient.clients.listDefaultClientScopes({
+      realm,
+      id: client.id!,
+    });
+
+    console.log(`Default scopes: ${defaultScopes.map(s => s.name).join(', ')}`);
+
+    // Get optional client scopes
+    const optionalScopes = await kcAdminClient.clients.listOptionalClientScopes({
+      realm,
+      id: client.id!,
+    });
+
+    console.log(`Optional scopes: ${optionalScopes.map(s => s.name).join(', ')}`);
+
+  } catch (error) {
+    console.error(`Error: ${error}`);
+    process.exit(1);
+  }
+}
+
+main().catch(console.error);

keycloak/scripts/client-exists.ts

@@ -0,0 +1,42 @@
+#!/usr/bin/env tsx
+
+import KcAdminClient from "@keycloak/keycloak-admin-client";
+import invariant from "tiny-invariant";
+
+async function main() {
+  const kcAdminClient = new KcAdminClient({
+    baseUrl: `https://${process.env.KEYCLOAK_HOST}`,
+    realmName: "master",
+  });
+
+  await kcAdminClient.auth({
+    username: process.env.KEYCLOAK_ADMIN_USER!,
+    password: process.env.KEYCLOAK_ADMIN_PASSWORD!,
+    grantType: "password",
+    clientId: "admin-cli",
+  });
+
+  const realm = process.env.KEYCLOAK_REALM!;
+  const clientId = process.env.KEYCLOAK_CLIENT_ID!;
+
+  invariant(realm, "KEYCLOAK_REALM is required");
+  invariant(clientId, "KEYCLOAK_CLIENT_ID is required");
+
+  try {
+    // Find the client by clientId
+    const clients = await kcAdminClient.clients.find({ realm, clientId });
+
+    if (clients.length > 0) {
+      console.log(`Client '${clientId}' exists in realm '${realm}'`);
+      process.exit(0); // Success - client exists
+    } else {
+      console.log(`Client '${clientId}' does not exist in realm '${realm}'`);
+      process.exit(1); // Client doesn't exist
+    }
+  } catch (error) {
+    console.error(`Error checking client existence: ${error}`);
+    process.exit(1);
+  }
+}
+
+main().catch(console.error);

keycloak/scripts/get-client-secret.ts

@@ -0,0 +1,48 @@
+#!/usr/bin/env tsx
+
+import KcAdminClient from "@keycloak/keycloak-admin-client";
+import invariant from "tiny-invariant";
+
+async function main() {
+  const kcAdminClient = new KcAdminClient({
+    baseUrl: `https://${process.env.KEYCLOAK_HOST}`,
+    realmName: "master",
+  });
+
+  await kcAdminClient.auth({
+    username: process.env.KEYCLOAK_ADMIN_USER!,
+    password: process.env.KEYCLOAK_ADMIN_PASSWORD!,
+    grantType: "password",
+    clientId: "admin-cli",
+  });
+
+  const realm = process.env.KEYCLOAK_REALM!;
+  const clientId = process.env.KEYCLOAK_CLIENT_ID!;
+
+  invariant(realm, "KEYCLOAK_REALM is required");
+  invariant(clientId, "KEYCLOAK_CLIENT_ID is required");
+
+  try {
+    // Find the client
+    const clients = await kcAdminClient.clients.find({ realm, clientId });
+    if (clients.length === 0) {
+      throw new Error(`Client '${clientId}' not found in realm '${realm}'`);
+    }
+
+    const client = clients[0];
+
+    // Get client secret
+    const clientSecret = await kcAdminClient.clients.getClientSecret({
+      realm,
+      id: client.id!,
+    });
+
+    console.log(`Client '${clientId}' secret: ${clientSecret.value}`);
+
+  } catch (error) {
+    console.error(`Error retrieving client secret: ${error}`);
+    process.exit(1);
+  }
+}
+
+main().catch(console.error);

keycloak/scripts/get-user-token.ts

@@ -0,0 +1,112 @@
+#!/usr/bin/env tsx
+
+import KcAdminClient from "@keycloak/keycloak-admin-client";
+import invariant from "tiny-invariant";
+
+async function main() {
+  const kcAdminClient = new KcAdminClient({
+    baseUrl: `https://${process.env.KEYCLOAK_HOST}`,
+    realmName: "master",
+  });
+
+  await kcAdminClient.auth({
+    username: process.env.KEYCLOAK_ADMIN_USER!,
+    password: process.env.KEYCLOAK_ADMIN_PASSWORD!,
+    grantType: "password",
+    clientId: "admin-cli",
+  });
+
+  const realm = process.env.KEYCLOAK_REALM!;
+  const username = process.env.USERNAME!;
+  const clientId = process.env.KEYCLOAK_CLIENT_ID!;
+
+  invariant(realm, "KEYCLOAK_REALM is required");
+  invariant(username, "USERNAME is required");
+  invariant(clientId, "KEYCLOAK_CLIENT_ID is required");
+
+  // Find the user
+  const users = await kcAdminClient.users.find({ realm, username });
+  if (users.length === 0) {
+    throw new Error(`User '${username}' not found in realm '${realm}'`);
+  }
+  const user = users[0];
+
+  // Find the client
+  const clients = await kcAdminClient.clients.find({ realm, clientId });
+  if (clients.length === 0) {
+    throw new Error(`Client '${clientId}' not found in realm '${realm}'`);
+  }
+  const client = clients[0];
+
+  try {
+    // Get a token for this user (impersonation)
+    console.log(`Getting token for user '${username}' with client '${clientId}'...`);
+
+    // Get client secret
+    const clientSecret = await kcAdminClient.clients.getClientSecret({
+      realm,
+      id: client.id!,
+    });
+
+    // Create a new client instance for the specific realm/client
+    const userClient = new KcAdminClient({
+      baseUrl: `https://${process.env.KEYCLOAK_HOST}`,
+      realmName: realm,
+    });
+
+    // Note: This requires the user's actual password or impersonation capability
+    console.log("To get actual user token, you need:");
+    console.log("1. User's password, or");
+    console.log("2. Impersonation permissions");
+    console.log("\nAlternatively, check the browser's Network tab:");
+    console.log("1. Open DevTools -> Network tab");
+    console.log("2. Try to trigger a DAG in Airflow");
+    console.log("3. Look for the request with 403 error");
+    console.log("4. Check Authorization header: 'Bearer <token>'");
+    console.log("5. Decode at https://jwt.io");
+
+    // Show client configuration that affects tokens
+    console.log("\n=== Client Configuration ===");
+    console.log(`Client ID: ${client.clientId}`);
+    console.log(`Client Name: ${client.name}`);
+    console.log(`Protocol: ${client.protocol}`);
+    console.log(`Public Client: ${client.publicClient}`);
+
+    // Get protocol mappers
+    const mappers = await kcAdminClient.clients.listProtocolMappers({
+      realm,
+      id: client.id!,
+    });
+
+    console.log("\n=== Protocol Mappers ===");
+    mappers.forEach(mapper => {
+      console.log(`- ${mapper.name} (${mapper.protocolMapper})`);
+      if (mapper.config) {
+        console.log(`  Claim: ${mapper.config['claim.name'] || 'N/A'}`);
+        console.log(`  Access Token: ${mapper.config['access.token.claim'] || 'false'}`);
+        console.log(`  ID Token: ${mapper.config['id.token.claim'] || 'false'}`);
+      }
+    });
+
+    // Show user's client roles
+    const clientRoles = await kcAdminClient.users.listClientRoleMappings({
+      realm,
+      id: user.id!,
+      clientUniqueId: client.id!,
+    });
+
+    console.log("\n=== User's Client Roles ===");
+    if (clientRoles.length === 0) {
+      console.log("No client roles assigned");
+    } else {
+      clientRoles.forEach(role => {
+        console.log(`- ${role.name} (${role.id})`);
+      });
+    }
+
+  } catch (error) {
+    console.error(`Error: ${error}`);
+  }
+}
+
+main().catch(console.error);

keycloak/scripts/list-user-client-roles.ts

@@ -0,0 +1,85 @@
+#!/usr/bin/env tsx
+
+import KcAdminClient from "@keycloak/keycloak-admin-client";
+import invariant from "tiny-invariant";
+
+async function main() {
+  const kcAdminClient = new KcAdminClient({
+    baseUrl: `https://${process.env.KEYCLOAK_HOST}`,
+    realmName: "master",
+  });
+
+  await kcAdminClient.auth({
+    username: process.env.KEYCLOAK_ADMIN_USER!,
+    password: process.env.KEYCLOAK_ADMIN_PASSWORD!,
+    grantType: "password",
+    clientId: "admin-cli",
+  });
+
+  const realm = process.env.KEYCLOAK_REALM!;
+  const username = process.env.USERNAME!;
+  const clientId = process.env.KEYCLOAK_CLIENT_ID!;
+
+  invariant(realm, "KEYCLOAK_REALM is required");
+  invariant(username, "USERNAME is required");
+  invariant(clientId, "KEYCLOAK_CLIENT_ID is required");
+
+  // Find the user
+  const users = await kcAdminClient.users.find({ realm, username });
+
+  if (users.length === 0) {
+    throw new Error(`User '${username}' not found in realm '${realm}'`);
+  }
+
+  const user = users[0];
+
+  // Find the client
+  const clients = await kcAdminClient.clients.find({ realm, clientId });
+
+  if (clients.length === 0) {
+    throw new Error(`Client '${clientId}' not found in realm '${realm}'`);
+  }
+
+  const client = clients[0];
+
+  try {
+    // Get user's client role mappings
+    const clientRoles = await kcAdminClient.users.listClientRoleMappings({
+      realm,
+      id: user.id!,
+      clientUniqueId: client.id!,
+    });
+
+    console.log(`Client roles for user '${username}' in client '${clientId}':`);
+
+    if (clientRoles.length === 0) {
+      console.log("  No client roles assigned");
+    } else {
+      clientRoles.forEach((role) => {
+        console.log(`  - ${role.name}`);
+        if (role.description) {
+          console.log(`    Description: ${role.description}`);
+        }
+      });
+    }
+
+    // Also show available roles for reference
+    const availableRoles = await kcAdminClient.clients.listRoles({
+      realm,
+      id: client.id!,
+    });
+
+    console.log(`\nAvailable client roles in '${clientId}':`);
+    availableRoles.forEach((role) => {
+      const isAssigned = clientRoles.some((assigned) => assigned.id === role.id);
+      const status = isAssigned ? "✓ assigned" : "  available";
+      console.log(`  ${status}: ${role.name}`);
+    });
+
+  } catch (error) {
+    console.error(`Error retrieving client roles: ${error}`);
+    process.exit(1);
+  }
+}
+
+main().catch(console.error);

keycloak/scripts/update-client-roles-mapper.ts

@@ -0,0 +1,94 @@
+#!/usr/bin/env tsx
+
+import KcAdminClient from "@keycloak/keycloak-admin-client";
+import invariant from "tiny-invariant";
+
+async function main() {
+  const keycloakHost = process.env.KEYCLOAK_HOST;
+  invariant(keycloakHost, "KEYCLOAK_HOST environment variable is required.");
+
+  const adminUsername = process.env.KEYCLOAK_ADMIN_USER;
+  invariant(adminUsername, "KEYCLOAK_ADMIN_USER environment variable is required.");
+
+  const adminPassword = process.env.KEYCLOAK_ADMIN_PASSWORD;
+  invariant(adminPassword, "KEYCLOAK_ADMIN_PASSWORD environment variable is required");
+
+  const realmName = process.env.KEYCLOAK_REALM;
+  invariant(realmName, "KEYCLOAK_REALM environment variable is required");
+
+  const clientId = process.env.CLIENT_ID;
+  invariant(clientId, "CLIENT_ID environment variable is required");
+
+  const mapperName = process.env.MAPPER_NAME || `${clientId} client roles`;
+  const claimName = process.env.CLAIM_NAME || "client_roles";
+
+  const kcAdminClient = new KcAdminClient({
+    baseUrl: `https://${keycloakHost}`,
+    realmName: "master",
+  });
+
+  try {
+    await kcAdminClient.auth({
+      username: adminUsername,
+      password: adminPassword,
+      grantType: "password",
+      clientId: "admin-cli",
+    });
+
+    // Set realm to work with
+    kcAdminClient.setConfig({
+      realmName,
+    });
+
+    // Find the client
+    const clients = await kcAdminClient.clients.find({ clientId });
+    if (clients.length === 0) {
+      throw new Error(`Client '${clientId}' not found in realm '${realmName}'`);
+    }
+
+    const client = clients[0];
+    const clientInternalId = client.id!;
+
+    // Find existing mapper
+    const mappers = await kcAdminClient.clients.listProtocolMappers({ id: clientInternalId });
+    const existingMapper = mappers.find((mapper) => mapper.name === mapperName);
+
+    if (existingMapper) {
+      console.log(`Deleting existing mapper '${mapperName}'...`);
+      await kcAdminClient.clients.delProtocolMapper({
+        id: clientInternalId,
+        mapperId: existingMapper.id!,
+      });
+    }
+
+    // Create updated client roles protocol mapper
+    await kcAdminClient.clients.addProtocolMapper(
+      { id: clientInternalId },
+      {
+        name: mapperName,
+        protocol: "openid-connect",
+        protocolMapper: "oidc-usermodel-client-role-mapper",
+        config: {
+          "userinfo.token.claim": "true",
+          "id.token.claim": "true",
+          "access.token.claim": "true",
+          "claim.name": claimName,
+          "jsonType.label": "String",
+          "multivalued": "true",
+          "usermodel.clientRoleMapping.clientId": clientId,
+        },
+      }
+    );
+
+    console.log(`✓ Client roles mapper '${mapperName}' updated for client '${clientId}' in realm '${realmName}'`);
+    console.log(`  Claim name: ${claimName}`);
+    console.log(`  User Info: enabled`);
+    console.log(`  Access Token: enabled`);
+    console.log(`  ID Token: enabled`);
+  } catch (error) {
+    console.error("An error occurred:", error);
+    process.exit(1);
+  }
+}
+
+main().catch(console.error);