[id='role-mappers_{context}']
= Role Mappers
{brandname} includes a `PrincipalRoleMapper` API that maps security Principals in a Subject to authorization roles that you can assign to users.

== Cluster role mappers

`ClusterRoleMapper` uses a persistent replicated cache to dynamically store principal-to-role mappings for the default roles and permissions.

By default uses the Principal name as the role name and implements `org.infinispan.security.MutableRoleMapper` which exposes methods to change role mappings at runtime.

* Java class: `org.infinispan.security.mappers.ClusterRoleMapper`
* Declarative configuration: `<cluster-role-mapper />`

== Identity role mappers

`IdentityRoleMapper` uses the Principal name as the role name.

* Java class: `org.infinispan.security.mappers.IdentityRoleMapper`
* Declarative configuration: `<identity-role-mapper />`

== CommonName role mappers

`CommonNameRoleMapper` uses the Common Name (CN) as the role name if the
Principal name is a Distinguished Name (DN).

For example this DN, `cn=managers,ou=people,dc=example,dc=com`, maps to the `managers` role.

* Java class: `org.infinispan.security.mappers.CommonRoleMapper`
* Declarative configuration: `<common-name-role-mapper />`

== Custom role mappers

Custom role mappers are implementations of `org.infinispan.security.PrincipalRoleMapper`.

* Declarative configuration: `<custom-role-mapper class="my.custom.RoleMapper" />`

.Reference

* link:{javadocroot}/org/infinispan/security/package-summary.html[{brandname} Security API]
* link:{javadocroot}/org/infinispan/security/PrincipalRoleMapper.html[org.infinispan.security.PrincipalRoleMapper]
