SAML 2.0 Federation

security.manager can be integrated into a SAML2-based identity federation where it acts as a central point for authentication (identity provider, IdP) or as a service provider (SP). security.manager supports the SAML2 web browser SSO profile (except artifact binding) as well as the Enhanced Client and Proxy (ECP) profile.

If security.manager is registered as an IdP within a federation the users stored in the user database can be authenticated through the SSO service interface and security.manager can issue the required SAML2 assertions. These assertions can contain selected user attributes, such as username and user roles to identify the user to other service providers of the federation and to establish "federated" identities.

When security.manager is configured to act as a service provider it can make secured services and all kinds of Java web applications available to other participants in the federation.

security.manager as Identity Provider (IdP)

security.manager can be used as an identity provider in a SAML2 federation. Users whose accounts are managed by security.manager can use it as a central point for authentication and connect to services that are offered by external service providers of the same federation. It is also possible to "federate" local user accounts (for example user accounts that are registered locally in security.manager) with the central user account (depending on the capabilities offered by the service provider).

If a user is directed to the security.manager IdP (either straight from a client application or by being redirected from the service provider) the following situations can arise:

The user is already logged in and holds a security context with the IdP (an SSO session).
The user is not yet logged in.

In the first case a SAML assertion is issued and sent to the SP.

In the second case the user is redirected to the login page of security.manager to sign in. If the user signed in successfully she is returned the SAML assertion with the agreed-on user attributes and gets redirected to the service provider. Here, the SAML assertion is validated and a new SSO session is established. The user is logged in for as long as the SSO session is valid.

IdP Metadata

To integrate security.manager as an identity provider into a federation the following steps concerning the local IdP metadata have to be taken:

Adjust local IdP metadata
1. Adjust the SAML2 endpoint URLs to the installation.
2. Specify the certificate that is used in the security.manager installation
Register IdP and SP metadata locally
Register IdP metadata at the federation members

In the section Metadata Configuration these steps are described in more detail.

security.manager as Service Provider (SP)

If security.manager is used as a service provider the security context shared with the client (usually a browser application or an ECP-ready component) is established via the SSO domain cookie mechanism (SSO session). There are two possible starting situations if a client tries to access a security.manager resource that is protected through an SSO session:

The client already owns a valid SSO session, for example, through a previously made login to one of the security.manager components (for example the administration interface).
The client does not own a valid SSO session.

In the first case no further SAML2-based communication is made, because the client already has a valid security context with security.manager.

In the second case, depending on the client type (browser or ECP client), the corresponding SAML2 workflow is initiated and the user is redirected to the security.manager login page. Here, the user can either sign in locally, or select from a list of IdPs that are available in the federation to perform a central authentication. Using the returned assertion a security context (the SSO session) is established. If this was successful the user is redirected to the resource that was initially requested.

User attribute translation

If the user logged in to a central IdP her user attributes have to be translated so that security.manager can understand them. Therefore, while creating the security context, security.manager reads the user attributes from the SAML assertion issued by the IdP and translates it with the help of a preconfigured mapping table to its own user model. The user object that is created during this process, is stored in the user database using a pseudonym that was assigned to this user by the IdP.

The pseudonym is taken from the NameID of the assertion. security.manager does not request a specific NameID format, so the IdP must be configured to send a stable, persistent NameID (urn:oasis:names:tc:SAML:2.0:nameid-format:persistent) for security.manager. With a transient NameID, the user would be created as a new user on each login.

SP metadata

To integrate security.manager as an identity provider into a federation the following steps concerning the local SP metadata have to be taken:

Adjust local SP metadata
1. Adjust the SAML2 endpoint URLs to the installation.
2. Specify the certificate that is used in the security.manager installation
Register SP and IdP metadata locally
Register SP metadata at the federation members

In the section Metadata Configuration these steps are described in more detail.

User attribute mapping

Information about a user that is logged in at a central IdP is transferred as part of the SAML2 assertion as so-called attribute statements to the service provider. These attribute statements have to be translated to the user data model of security.manager. Therefore, an attribute mapping is defined in [SECMAN_INSTALL]/webapp/administration/WEB-INF/classes/saml2/spring-saml2-config.xml that can be adapted to the attributes that are actually returned by the IdP (or the IdPs).

The property named sourceNameToTargetName determines which attributes from the attribute statements contain the basic user information. In the following example the attribute sn of an assertion is mapped to the user attribute familyname. Accordingly, the user is shown in the user administration of security.manager with a family name equal to the value of the sn attribute in the assertion.

The keys of sourceNameToTargetName must exactly match the attribute names (the Name of the Attribute element) that the IdP sends. Depending on the IdP product, these are often not short names like sn, but OIDs (for example urn:oid:2.5.4.4 for the family name) or claim URIs (for example http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname). Check the attribute names in an assertion of your IdP and adjust the mapping accordingly. If several IdPs with different attribute names are used, add one entry per attribute name.

The roleMapper property specifies the attributes that are to be interpreted as roles in the sense of security.manager. In the following example all attributes with the name isMemberOf are interpreted as role definitions. The role name is extracted from the attribute value using a regular expression which is defined in the valueFilterPattern property.

The value of roleAttributeName must exactly match the name of the attribute as it is sent by the IdP (for URI-style attribute names including the complete URI). The attribute names configured in the delivered spring-saml2-config.xml may differ from the example below, so check and adjust them to your IdP.

Only such roles can be assigned to a user that have previously been created by the administrator in security.manager.

Using a special role mapper allows to map the value of a single attribute to multiple roles inside security.manager. For example, if the attribute multirole has the value Administrator both the roles sM_Administrator and tc_Administrator are assigned to the user. To activate this attribute mapping the corresponding section in the XML file has to be uncommented.

Example of an attribute mapping

<bean id="saml2AssertionAttributeMapper" class="org.n52.security.authentication.saml2.ConfigurableAssertionAttributeMapper">
    <property name="sourceNameToTargetName">
        <map>
            <entry key="sn" value="familyname" />
            <entry key="givenName" value="givenname" />
            <entry key="mail" value="mail" />
            <entry key="gender" value="gender" />
            <entry key="phonenumber" value="phonenumber" />
            <entry key="city" value="city" />
            <entry key="street" value="street" />
            <entry key="country" value="country" />
        </map>
    </property>
    <property name="roleMapper">
        <list>
            <bean class="org.n52.security.authentication.saml2.ConfigurableAssertionAttributeMapper.NameRoleAttributeMapper">
                <property name="roleAttributeName" value="isMemberOf" />
                <!--
                    value pattern filters a value like 'cn=Users,ou=groups,dc=opensso,dc=java,dc=net' to 'Users'
                -->
                <property name="valueFilterPattern" value="^cn=([^,]+),.*" />
            </bean>
            <!-- <bean class="org.n52.security.authentication.saml2.ConfigurableAssertionAttributeMapper.NameValueRoleAttributeMapper">
                    <property name="roleAttributeName" value="multirole" />
                    <property name="sourceValueToRoles">
                        <map>
                            <entry key="Administrator">
                                <list>
                                    <value>sM_Administrator</value>
                                    <value>tc_Administrator</value>
                                </list>
                            </entry>
                        </map>
                    </property>
                </bean>
             -->
         </list>
     </property>
     <!--<property name="userIdMapper"></property> -->
 </bean>

All users that have been authenticated by a central IdP are automatically mapped to a group. The group’s name matches the issuerId of the SAML assertion. The group is created if it does not yet exist in security.manager.

Protected Resources

To access resources that are protected by security.manager it is essential that there exists a security context between the client and the security.manager component, for example a protected service. A security context can be established, for example, when an SSO session is created after logging in locally. Another way to establish a security context is to perform a SAML2-based login at a central IdP which again causes an SSO session to be created. This means that the SSO endpoints of protected resources have to be accessed to utilize such a security context.

In most cases this SSO endpoint ends with /sso, for example:

http://maps.example.org/wss/services/MyWMS/sso?SERVICE=WMS&REQUEST=GetCapabilities

In common web applications that are protected by the security.manager domain cookie mechanism the endpoint is determined by the configuration of the protected application paths.

Immediate Redirection to an IdP

When a users attempts to access a protected resource for the first time it is sometimes desirable to redirect to a certain IdP instance immediately instead of redirecting to the security.manager login page first. This suppresses the security.manager login page and the extra step of selecting an IdP.

To enable an immediate redirect, set the parameter security.login.service.url in the file [DATA_FOLDER]/application.properties. The value must have this form: <your host>/administration/saml2/init?idpEntityId=<entity Id of the external idp>.

Example: Immediate redirect to the IdP with entity ID 'testIdp'

# direct redirect to external IdP 'testIdp'
security.login.service.url=http://host.example.com/administration/saml2/init?idpEntityId=testIdp

# show the security.manager login page (default)
#security.login.service.url=http://host.example.com/administration/account/login

The protected components automatically append the parameter returnURL with the originally requested resource. If you use the URL <your host>/administration/saml2/init directly, for example as a link in a portal, you have to append the parameter returnURL yourself, otherwise the request fails:

http://host.example.com/administration/saml2/init?idpEntityId=testIdp&returnURL=<URL-encoded target URL>

Metadata Configuration

Adjust Local Metadata

The local SP and IdP metadata are configured in the corresponding template under [SECMAN_INSTALL]/webapp/administration/WEB-INF/classes/saml2/metadata/local-[sp|idp]-metadata.xml. It is recommended to create a backup copy of the file before manipulating it.

Service URLs

By default the templates contain references to the URL http://localhost:8080/administration/…. According to the local installation these references have to be replaced by the correct hostname, port, and path, usually something like https://[myhost]/administration/….

EntityID

The entityID attribute in the first line of the metadata file denotes the name of the organization that acts as SP/IdP. This name must be unique within the entire federation and the attribute value must be equal to the value of the saml2.local.entityid property. Set this property in the file [DATA_FOLDER]/application.properties:

saml2.local.entityid=example.org

Certificate

The certificate that is used by the security.manager installation also has to be inserted into the metadata file. This enables other participants of the federations to validate content that has been signed by this instance. The certificate is located in the .keystore file in the "data home" folder, which is created during installation. By default [SECMAN_INSTALL]/data is used as "data home" folder. The keytool command of the JDK can be utilized to export the certificate from the keystore to the required PEM format:

[SECMAN_DATA_DIR]> [JAVA_HOME]/bin/keytool -export -alias ct-security -keystore .keystore -storepass changeit -rfc

The text printed out between -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- has to be copied into the ds:x509Certificate element within the meta data file.

Adjusted local-sp-metadata.xml

<EntityDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata" entityID="example.org">
    <SPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol" WantAssertionsSigned="true">
        <KeyDescriptor>
            <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
                <ds:X509Data>
                    <ds:X509Certificate>MIICLjCCAZcCBEirSywwDQYJKoZIhvcNAQEEBQAwXjELMAkGA1UEBhMCREUxETAPBgNVBAcTCE11ZW5zdGVyMRcwFQYDVQQKEw5jb24gdGVycmEgR21iSDEPMA0GA1UECxMGc2VydmVyMRIwEAYDVQQDEwljb24tdGVycmEwHhcNMDgwODE5MjIzNzMyWhcNMTMwNzI0MjIzNzMyWjBeMQswCQYDVQQGEwJERTERMA8GA1UEBxMITXVlbnN0ZXIxFzAVBgNVBAoTDmNvbiB0ZXJyYSBHbWJIMQ8wDQYDVQQLEwZzZXJ2ZXIxEjAQBgNVBAMTCWNvbi10ZXJyYTCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEAj0qvXMZmogeZgcvpysZxAOieFHuCknOsJ1iSe/n+leuoVqmgvfwfI0BEocT3TrGK1189nAaMRdZFq2Dy0hdmsnKsKR0dDtArMpmzhHHsFOTKzupbdixa2RmJq845b8BxVUC92h455rnV2QMIYqAh88ArBLe4HeyjyKMM7VgicCAwEAATANBgkqhkiG9w0BAQQFAAOBgQBLM9auhRWmfTCfYEuQLXs40OCi/byYzWJ4Dz7ZUZPxMfSraGy+vyVkCbxw2JL+194wEGpAY7giI08NwvKRAQkH+qV/XeklUs9a9Qx3WKw7ZtUcoTCodpfA61YlmWTDZ24m6MJtdVIBccBzFyfeA1LfAFdaouGXLLgHIN/+rr3nw==</ds:X509Certificate>
                </ds:X509Data>
            </ds:KeyInfo>
        </KeyDescriptor>
        <NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:persistent</NameIDFormat>
        <!--<NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</NameIDFormat>
        <NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:transient</NameIDFormat>
        <NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</NameIDFormat>-->
        <!-- <AssertionConsumerService
        Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact"
        Location="https://www.example.org/administration/saml2/acs/Artifact"
        index="1" /> -->
        <AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://www.example.org/administration/saml2/acs/POST" index="2"/>
        <AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://www.example.org/administration/saml2/acs/Redirect" index="9"/>
        <AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:PAOS" Location="https://www.example.org/administration/saml2/acs/ECP" index="10"/>
    </SPSSODescriptor>
</EntityDescriptor>

Adjusted local-idp-metadata.xml

<EntityDescriptor entityID="example.org" xmlns="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" xmlns:xsi="http://www.w3.org /2001/XMLSchema-instance">
    <IDPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
        <KeyDescriptor>
            <ds:KeyInfo>
                <ds:X509Data>
                    <ds:X509Certificate>MIICLjCCAZcCBEirSywwDQYJKoZIhvcNAQEEBQAwXjELMAkGA1UEBhMCREUxETAPBgNVBAcTCE11ZW5zdGVyMRcwFQYDVQQKEw5jb24gdGVycmEgR21iSDEPMA0GA1UECxMGc2VydmVyMRIwEAYDVQQDEwljb24tdGVycmEwHhcNMDgwODE5MjIzNzMyWhcNMTMwNzI0MjIzNzMyWjBeMQswCQYDVQQGEwJERTERMA8GA1UEBxMITXVlbnN0ZXIxFzAVBgNVBAoTDmNvbiB0ZXJyYSBHbWJIMQ8wDQYDVQQLEwZzZXJ2ZXIxEjAQBgNVBAMTCWNvbi10ZXJyYTCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEAj0/qvXMZmogeZgcvpysZxAOieFHuCknOsJ1iSe/n+leuoVqmgvfwfI0BEocT3TrGK1189nAaMRdZFq2Dy0hdmsnKsKR0dDtArMpmzhHHsFOTKzupbdixa2RmJq845b8BxVUC92h455rnV2QMIYqAh/88ArBLe4HeyjyKMM7VgicCAwEAATANBgkqhkiG9w0BAQQFAAOBgQBLM9auhRWmfTCfYEuQLXs40OC/i/byYzWJ4Dz7ZUZPxMfSraGy+vyVkCbxw2JL+194wEGpAY7giI08NwvKRAQkH+qV/XeklUs9a9Qx3WKw7ZtUcoTCodpfA61YlmWTDZ24m6MJtdVIBccBzFyfeA1LfAFdaouGXLLgHIN/+rr3nw==</ds:X509Certificate>
                </ds:X509Data>
            </ds:KeyInfo>
        </KeyDescriptor>
        <NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:persistent</NameIDFormat>
        <!--<NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</NameIDFormat>
        <NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:transient</NameIDFormat>
        <NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</NameIDFormat>-->
        <SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://www.example.org/administration/saml2/idp/profile/SAML2/POST/SSO"/>
        <SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://www.example.org/administration/saml2/idp/profile/SAML2/Redirect/SSO"/>
        <!-- <SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP" Location="https://www.example.org/administration/saml2/idp/profile/SAML2/SOAP/ECP" />-->
    </IDPSSODescriptor>
</EntityDescriptor>

Local Metadata Registration

All metadata of the members of the federation that security.manager is a part of, have to be placed in the [DATA_DIR]/saml2metadata folder. This folder is not created during installation; create it if it does not exist. To make the local SP/IdP configuration come to effect the adjusted meta data file also has to be copied into this folder. Furthermore, all metadata files of accepted, trustworthy IdPs and SPs have to be placed there.

It needs to be guaranteed that only one file exists per specific entityId inside the [DATA_DIR]/saml2metadata folder. If security.manager is supposed to work as both Identity Provider and Service Provider, the content of both metadata template files needs to be merged into a single XML file like this:

local-sp-and-idp-metadata.xml

<EntityDescriptor entityID="example.org" xmlns="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" xmlns:xsi="http://www.w3.org /2001/XMLSchema-instance">
    <IDPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
        ...
    </IDPSSODescriptor>
    <SPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
        ...
    </SPSSODescriptor>
</EntityDescriptor>

After changing application.properties, spring-saml2-config.xml, or the metadata files, restart the web applications (alternatively, restart the entire Tomcat server).

Metadata Registration in the Federation

When integrating security.manager into a federation as an SP or IdP all local metadata has to be registered at the other participating SPs and IdPs. The concrete procedure that is required to register security.manager in third-party IdPs/SPs depends on the different products. Consult the applicable product documentation.