Configuring the remote SPs 

• Get a valid SAML 2.0 metadata file from the SP application (sp-abc.xml) and copy it into the SAML folder.


The meta data file from the SP contains the SP's public key(s) for signing and decryption. You must make sure, that the obtained meta data files really belong to the actual SP!

• Create a extended meta data file (sp-abc-extended.xml) in the SAML folder. You can use this template: sp-extended.xml 
• Edit the extended meta data file as follows:
• The "entityID" attribute in the element  EntityConfig must be exactly the same as the one in the SP SAML 2.0 metadata file (sp-abc.xml).
• The "hosted" attribute in the element  EntityConfig must be "0".
• 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.
• The attribute named "attributeMap" represents a legacy way to define which attributes should be added to the SAML assertion if this file is only used on the IDP (or which attributes shall be imported from the assertion if used on the SP). Instead this should be configured in the "Target Application using SAML 2.0". If using this attribute for legacy reasons or because it is also used on an IAM SP (where importing the attributes is currently only supported via this property). In those cases, 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.
• The attribute named "wantLogoutResponseSigned" defines if SAML 2.0 logout response messages to this SP should be signed.
• The attribute named "wantLogoutRequestSigned" defines if SAML 2.0 logout request messages to this SP should be signed.

To connect a target application on the SP's site, do the following:

• Open the "Application Settings" (accessible either via "MAIN SETTINGS" or directly in the "Login Application")
• Create a new "SAML2 Target Application"
• Fill in all required target application information 
• The URL pattern is the one of the actual target application (which is not necessarily the same as the URL for the SAML SP)
• As "SP Entity ID", "SP Meta Data File", and "SP Extended Meta Data File" use the values chosen above





Remember, that for security reasons the target application URL must be white-listed in the Loginapp - Security Setting's "Allowed Forward Location Patterns"!

If the target application URL does not match one of the patterns, IAM will not send the user to the URL and note this in the log file.

• Activate the configuration.

If any of the SAML settings are changed (and have been activated in the ConfigEditor), a restart of the IAM instance may be necessary (see e.g. Starting and stopping Airlock IAM (system service integration)). 

Using IAM as IDP and SP

If Airlock IAM is used on both the IDP and the SP side, not only the standard SAML meta data files (idp.xml and sp.xml) can be exchanged but also the extended files (idp-extended.xml and sp-extended.xml).

If doing so:

• Copy the idp-extended.xml from the IDP to the SP (and not the other way round)
• Copy the sp-extended.xml from the SP to the IDP (and not the other way round)
• Do not forget to switch the hosted flags when receiving the file from the other party
• hosted="true" in the idp-extended.xml means: I am the IDP
• hosted="true" in the sp-extended.xml means: I am the SP

Connecting external SAML Service Providers to the IDP.

The current implementation supports AES128, AES192, AES256 and TRIPLEDES as encryption algorithms. The default is AES128. Notice that AES with a key size larger than 128bits will require the "Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files" to be installed in your JDK!

The encryption is configured in the SP's or IDP's standard metadata xml like this: (Notice that the KeySize is mandatory for AES and must always match the Algorithm)

sp.xml

        <KeyDescriptor use="encryption">
            <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
                <ds:X509Data>
                    <ds:X509Certificate>
                        MII...
                    </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>

Possible algorithms are:

http://www.w3.org/2001/04/xmlenc#aes128-cbc  (KeySize 128)

http://www.w3.org/2001/04/xmlenc#aes192-cbc  (KeySize 192)

http://www.w3.org/2001/04/xmlenc#aes256-cbc  (KeySize 256)

http://www.w3.org/2001/04/xmlenc#tripledes-cbc  (KeySize can be omitted)

The certificates used in SAML 2.0 primarily serve as a container for the public key (and the private key). Therefore, the attributes of the certificates themselves are ignored. This means that certificates do not have to expose certain key usages or other attributes nor is it important if they are signed by another CA or if they are self-signed. It also means that expired certificates will continue to work, since the expiry date is completely ignored (however third party SAML implementations may choose to verify such attributes).