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

This article explains how to add a remote identity provider (IDP) as part of the SP configuration.

For more information about configuring Airlock IAM as SAML IDP see SAML IDP setup with the Loginapp REST API.

Info

The article is based on the first steps of the SAML SP setup.

Structure of the configuration

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

Part	Purpose
Metadata file (idp.xml)	The SAML metadata file contains information about the IDP in a standardized XML format. It is usually provided by the service provider.
Extended metadata file (idp-extended.xml)	The extended SAML metadata file contains additional information about the remote IDP in an XML file. It is not provided by the service provider (unless the IDP is an Airlock IAM).
SAML settings	The IDP configuration within the SP configuration in the IAM configuration (Config editor).
Target application	A target application configuration for a protected backend application. This involves an authentication flow and an identity propagator suitable for SAML.

IDP metadata file

Info

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

The file should be provided by the identity provider.

Risk

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

If the remote IDP 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-idp.com/auth/saml/" xmlns="urn:oasis:names:tc:SAML:2.0:metadata">
	<IDPSSODescriptor WantAuthnRequestsSigned="false" 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>
						MIIFyjCCBLKgAwIBAgIQAJaCHAnPZh8Y4V6ebT12ZjANBgkqhkiG9w0BAQUFADBV
						...
						pNDfVN90Z4CekN/fvdDT2L+0a4La3ai68qeW9SfH/npbKm/7Qjwc6gkEk49stQ==
					</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>
						MIIFyjCCBLKgAwIBAgIQAJaCHAnPZh8Y4V6ebT12ZjANBgkqhkiG9w0BAQUFADBV
						...
						pNDfVN90Z4CekN/fvdDT2L+0a4La3ai68qeW9SfH/npbKm/7Qjwc6gkEk49stQ==
					</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>

		<!-- The ArtifactResolutionService. The SP must be able to directly connect
			to this Location.
			In case of load balanced servers, one entry for every IdP must be
			specified. See separate documentation for load balancing. -->
		<ArtifactResolutionService index="0" isDefault="true"
			Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP"
			Location="https://remote-idp.com/auth/saml2/idp/resolve-artifact/metaAlias/iamIdp" />
	
		<!-- The first specified SLO service is used for IdP initiated SLO. -->
		<SingleLogoutService
			Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
			Location="https://remote-idp.com/auth/saml2/idp/slo/metaAlias/iamIdp"
			ResponseLocation="https://remote-idp.com/auth/saml2/idp/slo/metaAlias/iamIdp" />
	
		<!-- The default NameIDFormat -->
		<NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:unspecified</NameIDFormat>
		
		<!-- SSO service to be used with Redirect binding or Redirect/Artifact Resolution binding. -->
		<SingleSignOnService
			Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
			Location="https://remote-idp.com/auth/saml2/idp/sso/metaAlias/iamIdp" />
	
		<!-- SSO service to be used with POST binding or POST/Artifact Resolution binding. -->
		<SingleSignOnService
			Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
			Location="https://remote-idp.com/auth/saml2/idp/sso/metaAlias/iamIdp" />
	</IDPSSODescriptor>
</EntityDescriptor>

Configuration instructions

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

IDP extended metadata file

Info

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

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

Example

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<!-- The attribute "hosted" must be "true" if this entity is hosted on THIS server. -->
<EntityConfig entityID="https://remote-idp.com/auth/saml/" hosted="false" xmlns="urn:sun:fm:SAML:2.0:entityconfig">

		<!-- metaAlias is the name of this IdP as referenced in the endpoints. Must start with a "/". -->
	<IDPSSOConfig metaAlias="/remoteIdp">
		<Attribute name="signingCertAlias"><Value>airlock-iam-idp</Value></Attribute>
		<Attribute name="encryptionCertAlias"><Value>airlock-iam-idp</Value></Attribute>
		<Attribute name="idpAuthncontextClassrefMapping">
			<!--
				Lists possible authentication contexts (authentication methods) to be reported in the assertion
				sent to the SP. The authentication context to be used is defined by the IAM configuration.
				If the IAM configuration does not define an authentication context (or if it defines one
				that is not in the list):
				- for IDP-initiated SSO, the first entry in the list is used
				- for SP-initiated SSO, the first requested authentication context in the list is used. 
				  If none matches the first entry in the list is used.
			-->
			<Value>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</Value>
		</Attribute>
		<Attribute name="cotlist">
			<!-- Name(s) of the 'circle of trust' this IdP belongs to. Entities within the same COT trust each other. -->
			<Value>remote-idp</Value>
		</Attribute>
		<Attribute name="assertionEffectiveTime">
			<!-- Defines how long the Assertion will be valid in seconds. Sets NotOnOrAfter condition to <now> + <this value>. -->
			<Value>80</Value>
		</Attribute>
		<Attribute name="assertionNotBeforeTimeSkew">
			<!-- Defines how many seconds the clocks can be skewed. Sets NotBefore condition to <now> - <this value>. -->
			<Value>20</Value>
		</Attribute>
	</IDPSSOConfig>
</EntityConfig>

Configuring the IDP extended metadata file (remote-idp-extended.xml)

Copy the IDP extended metadata template file to the SAML directory and name it such that it is clearly associated with the remote IDP's metadata file from the previous step.
cp idp-extended-template.xml instances/auth/saml/remote-idp-extended.xml
entityID (XML attribute)
The entityID must be exactly the same as in the SP metadata file.
In our example: https://remote-idp.com/auth/saml/
hosted (XML attribute)
The hosted attribute in the element EntityConfig must be set to 0 or false.
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.
idpAuthncontextClassrefMapping (XML attribute)
The idpAuthncontextClassrefMapping defines a list of authentication contexts that the SP will request the IDP to provide. Based on this request, the IDP chooses an appropriate authentication flow that meets the requirements. See Authentication context classes in the SAML IDP for more details.
Signing and encryption preferences (various XML attributes)
There are various attributes defining the requirements of the remote IDP regarding signing and encrypting SAML messages. The remote IDP should provide this information. If the information is not available, try using the values of the above template.

Adding the remote IDP to the SP settings (Config Editor)

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

Go to:
Loginapp >> SAML Settings >> Service Provider Settings (Flow Auth)
Open the SAML 2.0 Flow SP plugin from the list of SAML 2.0 Service Providers and configure it as follows.
As IdP Entity Settings, add a new SAML 2.0 Identity Provider Entity plugin with the following values:
- IdP Entity ID: Use the same value as used in the metadata files above. In our example, we used the value https://remote-idp/auth/saml.
- Metadata File: point to the IDP metadata file. Example: instances/auth/saml/idp.xml
- Extended Metadata File: point to the extended IDP metadata file. Example: instances/auth/saml/idp-extended.xml
Information about RequestedAuthnContext to Flow Application ID can be found in Authentication context classes in the SAML IDP.
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.
The Attribute Settings property allows including additional information in the SAML assertion. Use the Config Editor to choose from a large set of elements such as UserID, language, context data, roles, client IP address, and more.

Configuration hints

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.

Info

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

Further information and links

Authentication context classes in the SAML IDP