Configuring the IDP

• 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")
• If there is a separate 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")

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 ConfigEditor (see below) and remember the passwords for later recovery or re-installations.

The IDP metadata file (usually idp.xml) contains all standardized information about the IDP. It may be given to any trusted SP that wants to connect to the IDP.

The extended metadata file (idp-extended.xml) contains IAM specific information and must not be given to SPs unless the SP is an IAM as well.

To keep security up, 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 templates may be used as starting point: 
• IDP metadata: idp.xml 
• IDP extended metadata: idp-extended.xml

Store the metadata files in the SAML directory and edit them as follows:

• Editing the idp.xml:
• The file must comply to the XML schema as specified in: http://docs.oasis-open.org/security/saml/v2.0/saml-metadata-2.0-os.pdf
• The EntityDescriptor's attribute entityID can be chosen freely but it must be unique. Often, the public URL of the IDP is used as its entityID (e.g. "https://idp.example.com/SAML2/").
• The entityID string must be the same in both the SAML 2.0 metadata file, the extended metadata file and also the Airlock IAM configuration.
• Replace the certificate data  (the chunk of base-64 data MIIFyjCCBLKg ... k49stQ==) with the certificate(s) of your key store. The same certificate may be used for both signing and the encryption though for live environments it is recommended to use two different certificates.
• Replace all URLs in the files (except the one for ArtifactResolutionService) starting with "https://host:8443/auth-login/" with the URL of the Loginapp as seen from the browser.

For the ArtifactResolutionService however use an URL that is directly accessible from the SP (only relevant if the Artifact Binding is used though).

• The templates provided above assume that your IDP supports both POST- and Artifact-Binding (Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"). Remove (or comment out) the corresponding "SingleSignOnService"-Tag at the bottom of the file to force one of the bindings.
• Put both SAML metadata files into the SAML directory.

• Editing the idp-extended.xml:
• eThe "hosted" attribute in the element  EntityConfig must be "1" or "true".
• The "metaAlias" attribute in the element IDPSSOConfig must be a short identifying string that is suitable to be a part in a URL  (e.g. "iamIdp"). The string must match the URL part in the Location attributes of all the SingleSignOnService, ArtifactResolutionService and SingleLogoutService elements in the SAML 2.0 metadata file, e.g.


<SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST

" Location="https://saml.test.com/auth/SSOPOST/metaAlias/iamIdp"/>

• In the attribute named "AuthUrl" write down the external URL (as seen by the browser, see note above) of the Loginapp's check-login servlet; e.g. https://saml.test.com/auth/check-login. This is the URL a user gets redirected to when a SAML handshake is started but the user is not authenticated yet.
• In the attribute named "signingCertAlias" set the alias resp. "friendly name" of the key pair entry in the key store which is used for signing outgoing assertions. This must refer to the same certificate as specified in the IDP SAML 2.0 metadata file with the  KeyDescriptor element with attribute use=signing.
• In the attribute named "encryptionCertAlias" set the alias resp. "friendly name" of the key pair entry in the key store which is used for decrypting incoming assertions. This must refer to the same certificate as specified in the IDP SAML 2.0 metadata file with the  KeyDescriptor element with attribute use=encryption.
• The attribute named "attributeMap" represents a legacy way to define which attributes should be added to the SAML assertion. Instead this should be configured in the "Target Application using SAML 2.0". If using this attribute for legacy reasons, it defines the default map of attributes for all SPs not defining an own specific "attributeMap". It also defines the mapping between Airlock IAM user attributes and attribute names included in the SAML assertion. See Airlock IAM configuration transferring arbitrary context data attributes with SAML for more information.
• In the attribute named "cotlist" define 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 as well as every SP's extended metadata.
• Inspect the other configuration properties if there are specific requirements for certain signatures.
   

To enable SAML in the loginapp, open the ConfigEditor and do the following:

• Open the "SAML Settings" (within the "Login Application"). Create the node, if necessary
• Open the "SAML Federation Config" and add new "SAML XML Signature Provider". Within it configures all mandatory settings according to the key store settings chosen above.



• Within the "SAML Settings" - if necessary - create a new "SAML IDP Config" and fill in all necessary properties. Create a "SAML Entity Config" for the IDP and point to the meta data files created above.

• Activate the configuration.

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