This article explains how to configure the SAML SP.
Prerequisites
- The SAML directory and the key store information as explained in Prerequisites to setup IAM as SAML SP.
Structure of the configuration
The SP configuration consists of the following parts:
Part | Purpose |
---|---|
Key store files | The key store and password files are used to securely store the key pairs used by the SP to sign and encrypt SAML messages. |
Metadata file | The SAML metadata file contains information about the SP in a standardized XML format. It is made available to the service providers. |
Extended metadata file | The extended SAML metadata file contains additional information in an XML file. It is not shared with the identity provider. |
other SAML settings | Other SAML settings are part of the IAM configuration and can be edited using the Config Editor. |
SP metadata file (sp.xml)
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 have been introduced with IAM 7.7. Old endpoints are still supported so that SSO and SLO integrations with existing IDPs will continue working without reconfiguring the Loginapp UI.
- Configuring the sp.xml
- Copy the SP metadata template file to the SAML directory.
- entityID (XML attribute)
The EntityDescriptor's attributeentityID
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 IDhttps://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. - ds:X509Certificate (XML tags)
Replace the certificate data (the chunk of base-64 dataMIICujCC ... 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. - URLs (various XML attributes)
Replace all URLs in the files starting withhttps://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/
- 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 byHTTP-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.
SP extended metadata file (sp-extended.xml)
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.
- Configuring the sp-extended.xml
- Copy the sp extended metadata template file to the SAML directory.
- entityID (XML attribute)
The entityID must be exactly the same as in the SP metadata file. - 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):
- Set the cotlist attribute to exactly the same value as in idp-extended.xml (e.g. "iam")
- 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.
- Leave all other attributes unchanged as they configure various important plugin classes.
SP settings (Config Editor)
- To complete the SP configuration, open the IAM Config Editor and perform the following steps:
- Go to:
Loginapp >> SAML Settings >> Service Provider Settings (Flow Auth) - Create end edit a new SAML 2.0 Flow SP plugin in the SAML 2.0 Service Providers list
- 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.
- 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.
Federation settings (Config Editor)
- The federation settings affect both the IDP and the SPs and are configured in a separate plugin:
- Go to:
Loginapp >> SAML Settings >> SAML Federation Settings (create plugin if required) - 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 isinstances/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 isinstances/auth/saml/.keystorepass
- Keystore Private Key Password File: The file containing the private key password.
In our example, this isinstances/auth/saml/.privatekeypass
- Set the Error Page URL to ui/app/error/message.
Defining the target Target Application for the SP
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
- To configure the target application for the SAML SP, do the following:
- Go to:
Loginapp >> Applications and Authentication - Add a new Target Application to the list of Applications and configure it as follows:
- Create a new Application ID.
- If suitable, configure an Application Selector (see also Flow-based authentication). Note that an Application Selector is required whenever the Target Application selection is based on the Releay State.
- 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 further 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. two-factor authentication).
- 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 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.
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.
If any of the SAML metadata files are changed, a restart of the IAM instance may be necessary.