SAML IDP configuration for the Loginapp REST API

This article explains how to configure the SAML IDP.

It requires the SAML directory and the key store information as explained in Prerequisites to setup IAM as SAML IDP.

The IDP configuration consists of the following parts:

• Copy the key store file into the SAML directory.
• Create a text file with the password of the key store and place it into the SAML directory (e.g. .keystorepass)
• The password protecting the private key within the key store: Create another text file with the password of the private key and place it into the SAML directory (e.g. .privatekeypass)

copy

cp saml-keystore.jks instances/auth/saml/
echo "uZvRDEBXAnMbs7HHLwL615" > instances/auth/saml/.keystorepass
echo "RNsO45xwDESu4iAeHrF1Zv" > instances/auth/saml/.privatekeypass 

For security reasons, it may make sense to put the password files in a folder outside the Airlock IAM installation (e.g. /etc/airlock/saml/ or alike) so the passwords are not part of any Airlock IAM instance backup.

If doing so, remember the folder when configuring the SAML IDP in the Config Editor (see below) and remember the passwords for later recovery or re-installation.

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

It may be given to any trusted service provider that wants to connect to the IDP.

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

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

Show moreShow lesscopy

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<EntityDescriptor entityID="https://iam.host.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://iam.host.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://iam.host.com/auth/saml2/idp/slo/metaAlias/iamIdp"
			ResponseLocation="https://iam.host.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://iam.host.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://iam.host.com/auth/saml2/idp/sso/metaAlias/iamIdp" />
	</IDPSSODescriptor>
</EntityDescriptor>

0. Configuring the idp.xml
1. Copy the IDP metadata template file to the SAML directory.
copy



cp idp.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 IDP is used as its entityID. In our examples, we use the entity ID https://iam.host.com/auth/saml/.
   The entityID must be exactly the same in the IDP metadata file, the IDP extended metadata file, and the Airlock IAM configuration.
3. ds:X509Certificate (XML tags)
   Replace the certificate data  (the chunk of base-64 data MIIFyjCCBLKg ... k49stQ==) 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. Artifact Resolution URL
   The previous step also included the Artifact Resolution URL (XML tag ArtifactResolutionService, attribute Location): it specifies the URL called by the service provider (SP) in order to exchange artifacts for SAML assertions. Thus it is called directly by the SP and not the user's web browser.
   In some setups, the artifact resolution endpoint is reachable by the SP by another URL. If so, adapt the URL accordingly.
6. The IDP metadata template assumes that your IDP 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 idp.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 extended metadata file (usually idp-extended.xml) contains IAM-specific information and must not be given to the service provider unless the service 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"?>

<!-- The attribute "hosted" must be "true" if this entity is hosted on THIS server. -->
<EntityConfig entityID="https://iam.host.com/auth/saml/" hosted="true" 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="/iamIdp">
		<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>iam</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>

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



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

2. entityID (XML attribute)
   The entityID must be exactly the same as in the IDP metadata file.
3. hosted (XML attribute)
   The hosted attribute in the element  EntityConfig must be 1 or true.
4. metaAlias (XML attribute)
   The metaAlias attribute in the element IDPSSOConfig must be a short identifying string that is suitable to be a part of an URL (e.g. /iamIdp). It is part of all SAML endpoint URLs (see IDP metadata file above). If it is changed, make sure to change the idp.xml and provide it to all SPs.
5. signingCertAlias (XML attribute)
   Specify the alias (friendly name) identifying the signing key pair in the key store. It must identify the same certificate as specified in the IDP SAML 2.0 metadata file with the  KeyDescriptor element with attribute use=signing.
   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

6. encryptionCertAlias (XML attribute)
   As in the previous step for signing, specify the alias (friendly name) identifying the encryption key pair in the key store. It must identify the same certificate as specified in the IDP SAML 2.0 metadata file with the  KeyDescriptor element with attribute use=encryption.
7. idpAuthncontextClassrefMapping (XML attribute)
   Defines the list of possible authentication contexts (authentication methods) to be reported in the assertion sent to the SP. See Authentication context classes in the SAML IDP for details.
8. 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. In the usual setup, this must be the same string for the IDP and the SPs.
9. assertionEffectiveTime (XML attribute)
   The attributes assertionEffectiveTime defines how long assertions issued by the IDP are valid. Review the values and change them if required. Make sure to provide a reasonably high value for assertionNotBeforeTimeSkew so SPs accept the assertions even if their clocks are not exactly synchronized with the IDP's clock.

To complete the IDP configuration, open the IAM Config Editor and perform the following steps:

1. Go to:
   Loginapp >> SAML Settings >> SAML 2.0 Identity Provider (create plugins if necessary)
2. Add or fill in the IdP Entity Settings:
• Idp 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/.
• 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

3. At least one Service Provider needs to be configured. This is described in Adding SAML SPs to the IDP configuration for the Loginapp REST API .

This is sufficient for the SAML IDP to work. All advanced configuration options are covered in separate articles or described in the Config Editor.

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 Config (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.

To configure the SPs, proceed with Adding SAML SPs to the IDP configuration for the Loginapp REST API .

• Authentication context classes in the SAML IDP
• SAML IDP URLs