Adding SAML SPs to the IDP configuration for the Loginapp REST API

Structure of the configuration

Adding an SP to the IDP configuration involves the following configuration parts:

Part

Purpose

Metadata file
(sp.xml)

The SAML metadata file contains information about the SP in a standardized XML format. It is usually provided by the service provider.

Extended metadata file
(sp-extended.xml)

The extended SAML metadata file contains additional information about the remote SP in an XML file. It is not provided by the service provider (unless the SP is an Airlock IAM).

SAML settings

The SP configuration within the IDP configuration in the IAM configuration (Config editor).

Target application

A target application configuration for remote SP. This involves an authentication flow and an identity propagator suitable for SAML.

SP metadata file

 
Info

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

The file should be provided by the service provider.

 
Risk

The transfer of the SP metadata file to the IDP must be authentic, i.e., before using it, you must make sure it really belongs to the remote SP. Failing to do so, may result in severe security flaws.

If the remote SP does not provide you with a ready-to-use metadata file but only the relevant data (URLs, public keys, etc.) you may use the following template file to create a valid metadata file.

 
Example
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<EntityDescriptor entityID="https://remote-sp1.com/auth/saml/" 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>
MIIC.... (remote SP's signing certificate)

					</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>
MIIC... (remote SP's encryption certificate)
					</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://remote-sp1.com/auth/slo-responder-endpoint"
			ResponseLocation="https://remote-sp1.com/auth/slo-responder-response-location" />

		<SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
			Location="https://remote-sp1.com/auth/slo-responder-endpoint"
			ResponseLocation="https://remote-sp1.com/auth/slo-responder-response-location" />

<!--
		<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:1.1:nameid-format:transient</NameIDFormat>

		<AssertionConsumerService index="0" isDefault="1"
			Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
			Location="https://remote-sp1.com/auth/assertion-consumer-endpoint" />

		<AssertionConsumerService index="1" isDefault="0"
			Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact"
			Location="https://remote-sp1.com/auth/assertion-consumer-endpoint" />
			
	
	</SPSSODescriptor>
</EntityDescriptor>

Configuration instructions

  1. Copy the remote SP metadata template file to the SAML directory.
  2.  
    Example
    cp remote-sp1.xml instances/auth/saml/
  3. Remember the entityID of the remote SP. It is required for the next two steps.
    In this example, we use https://remote-sp1.com/auth/saml/ as entity ID.

SP extended metadata file

 
Info

The extended metadata file contains IAM-specific information and is not provided by the service provider unless the service provider is an Airlock IAM as well.

To create the extended SP metadata file, the following XML template file may be used as starting point.

 
Example
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<!--
	Extended SP Metadata when IAM is used as IDP to communicate with a remote (Non-IAM) SP.
-->
<EntityConfig entityID="https://remote-sp1.com/auth/saml/" hosted="false" xmlns="urn:sun:fm:SAML:2.0:entityconfig">
	<SPSSOConfig>

		<Attribute name="cotlist">
			<!-- Name(s) of the 'circle of trust' this IdP belongs to. Entities within the same COT trust each other. -->
			<Value>iam</Value>
		</Attribute>
		<Attribute name="wantArtifactResponseSigned">
			<!-- If true, the identity provider must sign the ArtifactResponse element
			     (signing of the Assertion element is however configured by WantAssertionsSigned in the standard metadata). -->
			<Value>false</Value>
		</Attribute>
		<Attribute name="wantPOSTResponseSigned">
			<!-- If true, the identity provider must sign the Response element sent via POST binding instead of the
			     Assertion itself (overrides WantAssertionsSigned in the standard metadata for POSTs if set to true). -->
			<Value>false</Value>
		</Attribute>
		<Attribute name="wantLogoutResponseSigned">
			<!-- If true, the identity provider must sign the LogoutResponse element. -->
			<Value>true</Value>
		</Attribute>
		<Attribute name="wantLogoutRequestSigned">
			<!-- If true, the identity provider must sign the LogoutRequest element. -->
			<Value>true</Value>
		</Attribute>

	</SPSSOConfig>
</EntityConfig>

Configuring the SP extended metadata file (remote-sp1-extended.xml)

  1. Copy the SP extended metadata template file to the SAML directory and name it such that it is clearly associated with the remote SP's metadata file from the previous step.
    cp sp-extended-template.xml instances/auth/saml/remote-sp1-extended.xml
  2. entityID (XML attribute)
    The entityID must be exactly the same as in the SP metadata file.
    In our example: https://remote-sp1.com/auth/saml/
  3. hosted (XML attribute)
    The hosted attribute in the element  EntityConfig must be 0 or false.
  4. cotlist (XML attribute)
    The cotlist attribute defines the name of the circle of trust to be used. All parties participating in the single sign-on must use the same circle of trust. Use the same value as in the idp-extended.xml.
  5. Signing and encryption preferences (various XML attributes)
    There are various attributes defining the requirements of the remote SP regarding signing and encrypting SAML messages. The remote SP should provide this information. If the information is not available, try using the values of the above template.

Adding the SP to the IDP settings (Config Editor)

To add the remote SP to the IDP settings, open the IAM Config Editor and perform the following steps.

  1. Go to:
    Loginapp >> SAML Settings >> SAML 2.0 Identity Provider
  2. Add a new SAML 2.0 Service Provider plugin to the list of Service Providers and configure it as follows.
  3. As SP Entity Config, add a new SAML 2.0 Service Provider Entity plugin with the following values:
    • SP Entity ID: Use the same value as used in the SP metadata files above.
      In our example, we used the value https://remote-sp1.com/auth/saml/. We suggest that the entity ID should be included in the plugin identifier so it is easier to choose the right SP Entity ID plugin when configuring the target application later on.
    • Metadata File: point to the SP metadata file.
      Example: instances/auth/saml/remote-sp1.xml
    • Extended Metadata File: point to the extended SP metadata file.
      Example: instances/auth/saml/remote-sp1-extended.xml
  5. For the property Default Flow Application ID create a new Application ID plugin with a sensible Id for the remote SP's target application. The application ID will be used in the target application definition in the next step. It defines which target application configuration to use if the SAML flow was started using SP-initiated SSO.
    In our example, we use remote-sp1-application as ID.
  6. Information about RequestedAuthnContext to Flow Application ID can be found in Authentication context classes in the SAML IDP.
  7. specified in Relay State URI (IdP-Initiated SSO) is used as SAML relay state for IDP-initiated SSO: it tells the SP where to redirect the browser to after verifying the SAML assertion.
  8. The Attributes property allows to include additional information to the SAML assertion. Use the Config Editor to choose from a large set of elements such as context data, roles, client IP address, and more.

Defining the target Target Application for the remote SP

In this step, a target application is configured for the application accessed on the remote SP. Just like any other target application definition, it basically tells Airlock IAM how to authenticate users and how to propagate the user's identities to the protected application.

 
Info

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

To access the remote SP's protected application - regardless of whether the SAML flow was started on the IDP (in this case Airlock IAM) or the SP - the authentication flow of the target application has to be passed.

To configure the target application for the remote SAML SP, do the following:

  1. Go to:
    Loginapp >> Target Applications and Authentication
  2. Add a new Target Application to the list of Applications and configure it as follows:
  3. Use the Application ID created above in the IDP settings.
    In our example, we called it remote-sp1-application.
  4. If suitable, configure an Application Selector (see also Flow-based authentication). This is not necessary if the SAML flow is started on the SP (SP-initiated SSO).
  5. Connect or create an Authentication Flow. To access the remote SP's protected application, the authentication flow must be passed. It does not matter whether the SAML flow was started on the SP or on the IDP.
  6. As Identity Propagator, use the plugin SAML 2.0 Identity Propagator. Configure it to refer to the corresponding SP Entity ID.
    In our example, this is the SP Entity ID for https://remote-sp1.com/auth/saml/.
  7. Airlock IAM uses the internal username when propagating the identity to the remote SP. To send a different attribute (e.g. the email address), use the Username to Propagate Provider property.
 
Notice

If using Airlock IAM's web UI (Loginapp UI) do not forget to add a UI configuration for the target application.

See Using the Loginapp 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.

 
Notice

If using SAML with a custom web UI (SPA), consider using property Custom Header URI Propagation Settings in the SAML 2.0 Identity Propagator plugin. It defines how redirect URIs are made available to the custom UI so that it can redirect the browser to them after identity propagation.

Configuration hints

 
Info

Activate the configuration to make the changes effective.

 
Info

Make sure to use an up-to-date Airlock Gateway mapping template file (IAM 7.6 or newer) and activate the SAML allow rule.

 
Info

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