Skip to content
Documentation
Using
Resources
Protocol Mappers

Protocol Mappers

Use these resources when you need to control what Keycloak emits in OIDC tokens or SAML assertions. Use ProtocolMapper for custom claim mapping, RoleMapper to include roles from one client or client scope in another, and GroupMembershipProtocolMapper to expose group membership as a JWT claim.

API Reference

KindAPI GroupTerraform ResourceCRD Explorer
ProtocolMapperclient.keycloak.crossplane.io/v1alpha1keycloak_generic_protocol_mapperView CRD Schema
RoleMapperclient.keycloak.crossplane.io/v1alpha1keycloak_generic_role_mapperView CRD Schema
GroupMembershipProtocolMapperopenidgroup.keycloak.crossplane.io/v1alpha1keycloak_openid_group_membership_protocol_mapperView CRD Schema

Working YAML Examples

OIDC user attribute ProtocolMapper on a client 

apiVersion: client.keycloak.crossplane.io/v1alpha1
kind: ProtocolMapper
metadata:
  name: openid-client-protocol-mapper
spec:
  providerConfigRef:
    name: "keycloak-provider-config"
  deletionPolicy: Delete
  forProvider:
    name: "picture"
    protocol: "openid-connect"
    clientIdRef:
      name: "test"
      policy:
        resolve: Always
    realmIdRef:
      name: "dev"
      policy:
        resolve: Always
    protocolMapper: "oidc-usermodel-attribute-mapper"
    config:
      userinfo.token.claim: "true"
      user.attribute: "picture"
      id.token.claim: "true"
      access.token.claim: "true"
      claim.name: "picture"
      jsonType.label: "String"
      introspection.token.claim: "true"

OIDC client role ProtocolMapper on a client scope 

apiVersion: client.keycloak.crossplane.io/v1alpha1
kind: ProtocolMapper
metadata:
  name: openid-client-scope-protocol-mapper
spec:
  providerConfigRef:
    name: "keycloak-provider-config"
  deletionPolicy: Delete
  forProvider:
    name: "client roles"
    protocol: "openid-connect"
    clientScopeIdRef:
      name: "openid-client-scope"
      policy:
        resolve: Always
    realmIdRef:
      name: "dev"
      policy:
        resolve: Always
    protocolMapper: "oidc-usermodel-client-role-mapper"
    config:
      multivalued: "true"
      user.attribute: "foo"
      access.token.claim: "true"
      claim.name: "resource_access.${client_id}.roles"
      jsonType.label: "String"
      introspection.token.claim: "true"

SAML role list ProtocolMapper 

apiVersion: client.keycloak.crossplane.io/v1alpha1
kind: ProtocolMapper
metadata:
  name: saml-client-protocol-mapper
spec:
  providerConfigRef:
    name: "keycloak-provider-config"
  deletionPolicy: Delete
  forProvider:
    name: "user roles"
    protocol: "saml"
    samlClientIdRef:
      name: "saml-client"
      policy:
        resolve: Always
    realmIdRef:
      name: "dev"
      policy:
        resolve: Always
    protocolMapper: "saml-role-list-mapper"
    config:
      attribute.name: "Role"
      attribute.nameformat: "Basic"
      friendly.name: "test"
      single: "true"

RoleMapper on a client 

apiVersion: client.keycloak.crossplane.io/v1alpha1
kind: RoleMapper
metadata:
  name: openid-client-role-mapper
spec:
  providerConfigRef:
    name: "keycloak-provider-config"
  deletionPolicy: Delete
  forProvider:
    clientIdRef:
      name: "test"
      policy:
        resolve: Always
    realmIdRef:
      name: "dev"
      policy:
        resolve: Always
    roleIdRef:
      name: "test-client"
      policy:
        resolve: Always

RoleMapper on a client scope 

apiVersion: client.keycloak.crossplane.io/v1alpha1
kind: RoleMapper
metadata:
  name: openid-client-scope-role-mapper
spec:
  providerConfigRef:
    name: "keycloak-provider-config"
  deletionPolicy: Delete
  forProvider:
    clientScopeIdRef:
      name: "openid-client-scope"
      policy:
        resolve: Always
    realmIdRef:
      name: "dev"
      policy:
        resolve: Always
    roleIdRef:
      name: "test-client"
      policy:
        resolve: Always

GroupMembershipProtocolMapper on a client 

apiVersion: openidgroup.keycloak.crossplane.io/v1alpha1
kind: GroupMembershipProtocolMapper
metadata:
  name: openid-client-group-membership-protocol-mapper
spec:
  providerConfigRef:
    name: "keycloak-provider-config"
  deletionPolicy: Delete
  forProvider:
    name: "my-mapper"
    clientIdRef:
      name: "test"
      policy:
        resolve: Always
    realmIdRef:
      name: "dev"
      policy:
        resolve: Always
    claimName: "test"

GroupMembershipProtocolMapper on a client scope 

apiVersion: openidgroup.keycloak.crossplane.io/v1alpha1
kind: GroupMembershipProtocolMapper
metadata:
  name: openid-client-scope-group-membership-protocol-mapper
spec:
  providerConfigRef:
    name: "keycloak-provider-config"
  deletionPolicy: Delete
  forProvider:
    name: "my-mapper"
    clientScopeIdRef:
      name: "openid-client-scope"
      policy:
        resolve: Always
    realmIdRef:
      name: "dev"
      policy:
        resolve: Always
    claimName: "test"

Related Resources

OrganizationsRealm Settings