SAML SP configuration for the Loginapp REST API

This article explains how to configure the SAML SP.

• The SAML directory and the key store information as explained in Prerequisites to setup IAM as SAML SP.

The SP configuration consists of the following parts:

The SP metadata file (usually sp.xml) contains all standardized information about the SP. It contains public keys, SAML endpoints (URLs), supported SAML bindings, and encryption/signing preferences.

It may be given to any trusted identity provider that wants to integrate with the SP.

The transfer of the sp.xml to the IDP must be authentic, i.e., the IDP must be sure the file belongs to the actual and trusted SP.

The following XML template file may be used as starting point.

The SAML SP endpoint URLs are new for IAM 7.7

The old endpoints are still supported so that SSO and SLO integrations with existing IDPs will continue to work without reconfiguration when migrating the IDP from the JSP-Loginapp to the Loginapp REST UI.

Show moreShow lesscopy

<EntityDescriptor entityID="https://iam.host.com/auth/saml/sp" xmlns="urn:oasis:names:tc:SAML:2.0:metadata">
	<SPSSODescriptor AuthnRequestsSigned="true" WantAssertionsSigned="true"
		protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">

		<KeyDescriptor use="signing">
			<ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
				<ds:X509Data>
					<ds:X509Certificate>
MIICujCCAaKgAwIBAgIEULjYKTANBgkqhkiG9w0BAQUFADAeMRwwGgYDVQQDDBNT
						...
						
2VBiRYWRWo9FKGAOkNf03tRAEvvkDONwPurUaXZz
					</ds:X509Certificate>
				</ds:X509Data>
			</ds:KeyInfo>
		</KeyDescriptor>

		<KeyDescriptor use="encryption">
			<ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
				<ds:X509Data>
					<ds:X509Certificate>
MIICujCCAaKgAwIBAgIEULjYKTANBgkqhkiG9w0BAQUFADAeMRwwGgYDVQQDDBNT
						...
						
2VBiRYWRWo9FKGAOkNf03tRAEvvkDONwPurUaXZz
					</ds:X509Certificate>
				</ds:X509Data>
			</ds:KeyInfo>
			<EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes128-cbc">
				<KeySize xmlns="http://www.w3.org/2001/04/xmlenc#">128</KeySize>
			</EncryptionMethod>
		</KeyDescriptor>

		<SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
			Location="https://iam.host.com/auth/saml2/sp/slo/metaAlias/iamSp"
			ResponseLocation="https://iam.host.com/auth/saml2/sp/slo/metaAlias/iamSp" />

		<SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
			Location="https://iam.host.com/auth/saml2/sp/slo/metaAlias/iamSp"
			ResponseLocation="https://iam.host.com/auth/saml2/sp/slo/metaAlias/iamSp" />

<!--
		<NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:unspecified</NameIDFormat>
		<NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:transient</NameIDFormat>
		<NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</NameIDFormat>
-->
		<NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:persistent</NameIDFormat>

		<AssertionConsumerService index="0" isDefault="1"
			Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
			Location="https://iam.host.com/auth/saml2/sp/sso/metaAlias/iamSp" />


	</SPSSODescriptor>
</EntityDescriptor>

0. Configuring the sp.xml
1. Copy the SP metadata template file to the SAML directory.
copy



cp sp.xml instances/auth/saml/ 

2. entityID (XML attribute)
   The EntityDescriptor's attribute entityID can be chosen freely but it must be unique among all parties taking part in the single sign-on (IDP and all SPs). Often, the public URL of the SP is used as its entityID. In our examples, we use the entity ID https://iam.host.com/auth/saml/sp.
   The entityID must be identical in the SP metadata file, the SP extended metadata file, and the Airlock IAM configuration.
3. ds:X509Certificate (XML tags)
   Replace the certificate data  (the chunk of base-64 data MIICujCC ... PurUaXZz) with the certificate of the configured key store. The same certificate may be used for both signing and encryption though for production environments it is recommended to use two different certificates.
4. URLs (various XML attributes)
   Replace all URLs in the files starting with https://iam.host.com/auth/ with the URL of your Loginapp as seen from the browser. This is usually the entry path of the IAM mapping on the Airlock Gateway.
   Example: https://my.host.com/auth/
5. The SP metadata template assumes that your SP supports both POST- and Artifact-Binding. To disable either of the bindings (and thus enforce the other), remove or comment out the corresponding SingleSignOnService-Tag at the bottom of the file. The Artifact-Binding is denoted by HTTP-Redirect.

Note that the sp.xml file must comply with the XML schema as specified in http://docs.oasis-open.org/security/saml/v2.0/saml-metadata-2.0-os.pdf.

The SP extended metadata file (usually sp-extended.xml) contains IAM-specific information and must not be given to the identity provider unless the identity provider is an Airlock IAM as well.

The following XML template file may be used as starting point.

Show moreShow lesscopy

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<EntityConfig xmlns="urn:sun:fm:SAML:2.0:entityconfig" xmlns:fm="urn:sun:fm:SAML:2.0:entityconfig"
	hosted="true" entityID="sp1">

	<SPSSOConfig metaAlias="/iamSp">
		<Attribute name="signingCertAlias">
			<Value>sp</Value>
		</Attribute>
		<Attribute name="encryptionCertAlias">
			<Value>sp</Value>
		</Attribute>
		<Attribute name="spAuthncontextClassrefMapping">
			<Value>urn:oasis:names:tc:SAML:2.0:ac:classes:Password|0|default</Value>
		</Attribute>
		<Attribute name="spAuthncontextComparisonType">
			<Value>exact</Value>
		</Attribute>
		<Attribute name="wantAssertionEncrypted">
			<Value>false</Value>
		</Attribute>
		<Attribute name="wantPOSTResponseSigned">
			<Value>true</Value>
		</Attribute>
		<Attribute name="wantArtifactResponseSigned">
			<Value>true</Value>
		</Attribute>
		<Attribute name="wantLogoutRequestSigned">
			<Value>true</Value>
		</Attribute>
		<Attribute name="wantLogoutResponseSigned">
			<Value>true</Value>
		</Attribute>
		<Attribute name="cotlist">
			<Value>iam</Value>
		</Attribute>
		<Attribute name="useNameIDAsSPUserID">
			<Value>true</Value>
		</Attribute>
	</SPSSOConfig>
</EntityConfig>

0. Configuring the sp-extended.xml
1. Copy the sp extended metadata template file to the SAML directory.
copy



cp sp-extended.xml instances/auth/saml/  

2. entityID (XML attribute)
   The entityID must be exactly the same as in the SP metadata file.
3. Set the signingCertAlias and encryptionCertAlias to the respective aliases in the certificate key store.
• If you don’t use encryption, you can leave the latter empty.
• To check whether the alias is the right one, you may use the following command (using the Java key tool utility):
copy



keytool -exportcert -keystore saml-keystore.jks -alias your-alias -rfc

4. Set the cotlist attribute to exactly the same value as in idp-extended.xml (e.g. "iam")
5. want*Signed/Encrypted attributes: If you want the IDP to sign and/or encrypt certain specific elements in the Assertion, specify it here to enforce it but don’t forget to also configure it on the IDP so that the Assertions are really issued that way.
6. Leave all other attributes unchanged as they configure various important plugin classes.

0. To complete the SP configuration, open the IAM Config Editor and perform the following steps:
1. Go to:
   Loginapp >> SAML Settings >> Service Provider Settings (Flow Auth)
2. Create end edit a new SAML 2.0 Flow SP plugin in the SAML 2.0 Service Providers list
3. Add or fill in the SP Entity Config:
• Create or edit the SAML 2.0 Service Provider Entity plugin:
• SP Entity ID: Use the same value as used in the metadata files above. In our example, we used the value https://iam.host.com/auth/saml/sp.
• Metadata File: point to the IDP metadata file. Example: instances/auth/saml/sp.xml
• Extended Metadata File: point to the extended IDP metadata file. Example: instances/auth/saml/sp-extended.xml
• To fill in the IdP Entity Settings see Adding SAML IDP to the SP configuration for the Loginapp REST API
• Optionally configure the Username Transformation property. This username transformation will be executed before the username transformations configured in the authentication flow and it can be configured to interrupt the transformation chain. This may be useful to support both local login and SAML SSO with the same authentication flow.
• Optionally configure SP-initiated SSO Settings to select a particular binding or to add additional extension to the authentication request.
• Optionally configure IdP-initiated SSO Settings to explicitly select a target application of the IdP-initiated SSO use case.
4. Optionally configure Use Single-Logout (SLO) Behaviour. If this option is set (Default) the SP will inform the IDP when its logout URL is called. If this option is not set, the logout is only processed locally.

This is sufficient for the SAML SP to work. As the next step, a SAML IDP must be configured for this SP.

All advanced configuration options are covered in separate articles or described in the Config Editor.

0. The federation settings affect both the IDP and the SPs and are configured in a separate plugin:
1. Go to:
   Loginapp >> SAML Settings >> SAML Federation Settings (create plugin if required)
2. Set the plugin SAML XML Signature Provider in property XML Signature Keystore Provider and configure it as follows:
• Keystore: refer to the key store created earlier.
  In our example above, it is instances/auth/saml/saml-keystore.jks
• Keystore Type: The type of the key store.
  In our example, choose the jks option.
• Keystore Password File: The file containing the key store password.
  In our example, this is instances/auth/saml/.keystorepass
• Keystore Private Key Password File: The file containing the private key password.
  In our example, this is instances/auth/saml/.privatekeypass
3. Set the Error Page URL to ui/app/error/message.

In this step, a target application is configured for the application accessed on the remote SP. It tells Airlock IAM how to use the remote IDP for authentication.

• For general (not SAML-specific) information on target applications, see also:
• Flow-based authentication

0. To configure the target application for the SAML SP, do the following:
1. Go to:
   Loginapp >> Authentication Flows
2. Add a new Target Application to the list of Applications and configure it as follows:
3. Create a new Application ID.
4. If suitable, configure an Application Selector (see also Flow-based authentication). This is not necessary if the SAML flow is started on the IDP (IDP-initiated SSO).
5. Connect or create an Authentication Flow. To access the remote IDP's authentication flow.
• Add the SAML 2.0 User Identifying Step as the only step in the list of Steps.
• Optionally the authentication flow for SAML may be configured Persistency-less.
• Optionally futher steps may be added to the authentication flow. If the SP persists users, it is possible to add steps that require a persisted user (e.g. 2nd factor authentication).
6. Optionally configure Identity Propagation. To use the attributes from the SAML assertion issued by the IDP you may configure a SAML 2.0 Identity Propagator.

If using Airlock IAM's SP initiated login, do not forget to add a UI configuration for the target application. This is required so that the SAML SP will support the SAML protocols correctly.

See Using the Loginapp REST UI with SAML.

Note that the configured Target URI Resolver is ignored for SAML. The SAML implementation determines the target URI itself. In the case of IDP-initiated SSO, the URI defined in property Relay State URI (IdP-Initiated SSO) (in the SP configuration, see above) is used.

• Activate the configuration to make the changes effective.
• Make sure to use an up-to-date Airlock Gateway mapping template file and activate the SAML allow rule.

If any of the SAML metadata files are changed, a restart of the IAM instance may be necessary.

• Adding SAML IDP to the SP configuration for the Loginapp REST API
• SAML SP Advanced Configuration Topics