public class PropertiesBasedRoleMapper extends Object implements RoleMappingsProvider
RoleMappingsProvider
implementation that uses a properties
file to determine the mappings that should be applied
to the SAML principal and roles. It is always identified by the id properties-based-role-mapper
in keycloak-saml.xml
.
This provider relies on two configuration properties that can be used to specify the location of the properties
file
that will be used. First, it checks if the properties.file.location
property has been specified, using the configured
value to locate the properties
file in the filesystem. If the configured file is not located, the provider throws a
RuntimeException
. The following snippet shows an example of provider using the properties.file.configuration
option to load the roles.properties
file from the /opt/mappers/
directory in the filesystem:
If the
properties.file.location
configuration property is not present, the provider checks the properties.resource.location
property, using the configured value to load the properties
file from the WAR resource. If no value is found, it
finally attempts to load a file named role-mappings.properties
from the WEB-INF
directory of the application.
Failure to load the file from the resource will result in the provider throwing a RuntimeException
. The following
snippet shows an example of provider using the properties.resource.location
to load the roles.properties
file from the application's /WEB-INF/conf/
directory:
The
properties
file can contain both roles and principals as keys, and a list of zero or more roles separated by comma
as values. When the {@link #map(String, Set)}
method is called, the implementation iterates through the set of roles
that were extracted from the assertion and checks, for eache role, if a mapping exists. If the role maps to an empty role,
it is discarded. If it maps to a set of one ore more different roles, then these roles are set in the result set. If no
mapping is found for the role then it is included as is in the result set.
Once the roles have been processed, the implementation checks if the principal extracted from the assertion contains an entry
in the properties
file. If a mapping for the principal exists, any roles listed as value are added to the result set. This
allows the assignment of extra roles to a principal.
For example, consider the following properties
file:
# role to roles mappings samlRoleA=jeeRoleX,jeeRoleY samlRoleB= # principal to roles mappings kc-user=jeeRoleZIf the
{@link #map(String, Set)}
method is called with kc-user
as principal and a set containing roles
samlRoleA,samlRoleB,samlRoleC
, the result set will be formed by the roles jeeRoleX,jeeRoleY,samlRoleC,jeeRoleZ
.
In this case, samlRoleA
is mapped to two roles (jeeRoleX,jeeRoleY
), samlRoleB
is discarded as it is
mapped to an empty role, samlRoleC
is used as is and the principal is also assigned jeeRoleZ
.Modifier and Type | Field and Description |
---|---|
static String |
PROVIDER_ID |
Constructor and Description |
---|
PropertiesBasedRoleMapper() |
Modifier and Type | Method and Description |
---|---|
String |
getId()
Obtains the provider's identifier.
|
void |
init(SamlDeployment deployment,
ResourceLoader loader,
Properties config)
Initializes the provider.
|
Set<String> |
map(String principalName,
Set<String> roles)
Produces the final set of roles that should be assigned to the specified principal.
|
public static final String PROVIDER_ID
public String getId()
RoleMappingsProvider
keycloak-saml.xml
to identify the provider implementation
to be used.getId
in interface RoleMappingsProvider
String
representing the provider's id.public void init(SamlDeployment deployment, ResourceLoader loader, Properties config)
RoleMappingsProvider
keycloak-saml.xml
have been parsed and a provider whose id matches the one in the descriptor is successfully loaded.init
in interface RoleMappingsProvider
deployment
- a reference to the constructed SamlDeployment
.loader
- a reference to a ResourceLoader
that can be used to load additional resources from the WAR.config
- a Properties
object containing the provider config as read from keycloak-saml.xml
public Set<String> map(String principalName, Set<String> roles)
RoleMappingsProvider
map
in interface RoleMappingsProvider
principalName
- the principal name as extracted from the SAML assertion.roles
- the set of roles extracted from the SAML assertion.Set
containing the final set of roles that are to be assigned to the principal.Copyright © 2021 JBoss by Red Hat. All rights reserved.