Package org.keycloak.adapters.saml

Interface RoleMappingsProvider

All Known Implementing Classes:

PropertiesBasedRoleMapper

public interface RoleMappingsProvider

A simple SPI for mapping SAML roles into roles that exist in the SP application environment. The roles returned by an external IDP might not always correspond to the roles that were defined for the application so there is a need for a mechanism that allows mapping the SAML roles into different roles. It is used by the SAML adapter after it extracts the roles from the SAML assertion to set up the container's security context.

This SPI doesn't impose any restrictions on the mappings that can be performed. Implementations can not only map roles into other roles but also add or remove roles (and thus augmenting/reducing the number of roles assigned to the SAML principal) depending on the use case.

To install a custom role mappings provider, a META-INF/services/org.keycloak.adapters.saml.RoleMappingsProvider file containing the FQN of the custom implementation class must be added to the WAR that contains the provider implementation class (or the JAR that is attached to the WEB-INF/lib or as a jboss module if one wants to share the implementation among more WARs).

The role mappings provider implementation that will be selected for the SP application is identified in the keycloak-saml.xml by its id. The provider declaration can also contain one or more configuration properties that will be passed to the implementation in the {@link #init(SamlDeployment, ResourceLoader, Properties)} method. For example, if an LDAP-based implementation with id ldap-based-role-mapper is made available via META-INF/services, it can be selected in keycloak-saml.xml as follows:

     ...
     
         ...
     
     
         
         
         ...
     
 

NOTE: The SPI is not yet finished and method signatures are still subject to change in future versions.

Author:

Stefan Guilhen

Method Summary

Modifier and Type	Method	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.

Method Detail

getId

String getId()

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

Returns:

a String representing the provider's id.

init

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

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.

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

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

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.

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.