org.keycloak.adapters.saml

Class PropertiesBasedRoleMapper

java.lang.Object

org.keycloak.adapters.saml.PropertiesBasedRoleMapper

All Implemented Interfaces:

RoleMappingsProvider

public class PropertiesBasedRoleMapper
extends Object
implements RoleMappingsProvider

A 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=jeeRoleZ
 

If 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.

Author:

Stefan Guilhen

Field Summary

Fields

Modifier and Type	Field and Description
static String	PROVIDER_ID

Constructor Summary

Constructors

Constructor and Description
PropertiesBasedRoleMapper()

Method Summary

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.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

PROVIDER_ID

public static final String PROVIDER_ID

See Also:

Constant Field Values

Constructor Detail

PropertiesBasedRoleMapper

public PropertiesBasedRoleMapper()

Method Detail

getId

public String getId()

Description copied from interface: RoleMappingsProvider

Obtains the provider's identifier. This id is specified in keycloak-saml.xml to identify the provider implementation to be used.

Specified by:

getId in interface RoleMappingsProvider

Returns:

a String representing the provider's id.

init

public void init(SamlDeployment deployment,
                 ResourceLoader loader,
                 Properties config)

Description copied from interface: RoleMappingsProvider

Initializes the provider. This method is called by the adapter in deployment time after the contents of keycloak-saml.xml have been parsed and a provider whose id matches the one in the descriptor is successfully loaded.

Specified by:

init in interface RoleMappingsProvider

Parameters:

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

map

public Set<String> map(String principalName,
                       Set<String> roles)

Description copied from interface: RoleMappingsProvider

Produces the final set of roles that should be assigned to the specified principal. This method makes the principal and roles that were read from the SAML assertion available to implementations so they can apply their specific logic to produce the final set of roles for the principal. This method imposes no restrictions on the kind of mappings that can be performed. A simple implementation may, for example, just use a properties file to map some of the assertion roles into JEE roles while a more complex implementation may also connect to external databases or LDAP servers to retrieve extra roles and add those roles to the set of roles already extracted from the assertion.

Specified by:

map in interface RoleMappingsProvider

Parameters:

principalName - the principal name as extracted from the SAML assertion.

roles - the set of roles extracted from the SAML assertion.

Returns:

a Set containing the final set of roles that are to be assigned to the principal.