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 SP in the ConfigEditor (see below) and remember the passwords for later recovery or re-installation.
SP metadata files (sp.xml and sp-extended.xml)
The SP metadata file (usually sp.xml) contains all standardized information about the SP. It may be given to any trusted IDP that wants to connect to the SP.
The extended metadata file (sp-extended.xml) contains SP specific information and must not be given to IDPs unless the IDP is an IAM as well.
To keep security up, 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.
Creating and editing the sp.xml:
Create the sp.xml based on the following example and store it in the SAML directory:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<EntityDescriptor entityID="iamSp" xmlns="urn:oasis:names:tc:SAML:2.0:metadata">
<SPSSODescriptor AuthnRequestsSigned="true" WantAssertionsSigned="true" 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>
MIIC4TCC...
</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>
MIIC4TCC...
</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>
<SingleLogoutService
Location="https://test.example.com/auth/SPSloResponder/metaAlias/iamSp"
ResponseLocation="https://test.example.com/auth/SPSloResponder/metaAlias/iamSp"
Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" />
<SingleLogoutService
Location="https://test.example.com/auth/SPSloResponder/metaAlias/iamSp"
ResponseLocation="https://test.example.com/auth/SPSloResponder/metaAlias/iamSp"
Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" />
<NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:unspecified</NameIDFormat>
<!-- Each index must be unique. Counting must start at zero and increment without gaps. The entry with index="0" must also be marked with isDefault="true". -->
<AssertionConsumerService
isDefault="true"
Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
Location="https://test.example.com/auth/SPAcs" index="0" />
<AssertionConsumerService
Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact"
Location="https://test.example.com/auth/SPAcs" index="1" />
</SPSSODescriptor>
</EntityDescriptor>
Entity ID: Choose an entity ID which can be any string or URL identifying the SP. Use it for the entityID Attribute.
Signatures: add your certificate (base-64 encoded) into the <ds:X509Certificate> element of the <KeyDescriptor use="signing">
Encryption: To support encryption, paste the same or another (which would be more secure) certificate into the <ds:X509Certificate> element of the <KeyDescriptor use="encryption">. Remove or comment out that KeyDescriptor element, if encryption is not required.
Certificate attributes and expiry: 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).
Bindings: Depending on what the SP supports (POST-, or Artifact-Binding or both), remove one or the other "AssertionConsumerService"-Tag. If both are supported, the attributes "index" and "isDefault" define the order of preference.
URLs: Replace the URLs (https://test.example.com/auth/...) with the real ones as seen from the browser.
When changing the sp.xml, remember to inform the IDP by sending it the new metadata file.
Set the entityID to exactly the same value as in the sp.xml.
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.
Set the cotlist attribute to exactly the same value as in idp-extended.xml (e.g. "iam")
If the IdP sends any attributes you need to copy into the authenticated user, add a mapping for each attribute into attributeMap
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.
All further attributes: Please leave them unchanged as they configure various important plugin classes.
Do not change the metaAlias unless you also change it in the URLs of the sp.xml
Inspect the other configuration properties if there are specific requirements for certain signatures.
Remote IDP metadata files (idp.xml and idp-extended.xml)
Obtain the SAML IDP metadata file (idp.xml) from the remote IDP and store it in the SAML directory.
To keep security up, the transfer of the idp.xml to the SP must be authentic, i.e. you must be sure that the idp.xml really belongs to the trusted remote IDP.
In addition to the idp.xml, an extended meta data file idp-extended.xml is required to configure the IAM SAML components: Edit the following template and store it in the SAML directory:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<!-- The attribute "hosted" must be "false" since the IdP is NOT hosted on this server. -->
<!-- The entityID must exactly match the entityID of the idp.xml -->
<EntityConfig entityID="iamIdp" hosted="false" xmlns="urn:sun:fm:SAML:2.0:entityconfig">
<IDPSSOConfig metaAlias="/RemoteIDP">
<Attribute name="cotlist">
<!--
Name of the 'circle of trust' this IdP belongs to. Entities within the same COT trust each other.
Can be any string but the exact same string must be configured for the SP.
-->
<Value>iam</Value>
</Attribute>
</IDPSSOConfig>
</EntityConfig>
SP and remote IDP settings in the config editor
To enable SAML in the loginapp, open the ConfigEditor and to the following:
Open Loginapp >> SAML Settings (create if necessary).
Open the SAML Federation Config and add a new SAML XML Signature Provider. In it, configure all mandatory settings according to the key store settings chosen above.
Within the "SAML Settings" create a new "SAML SP Config" and fill in all necessary properties. Create a "SAML Entity Config" for the SP and point to the metadata files created above.
Within the "SAML SP Settings" create a new "Remote Idp Entity Settings" and point to the metadata files discussed above.
If no local login shall be possible (to always use SP-initiated SSO to the IDP), set the Loginapp >> Authentication Settings >> Login Page Type to SAML 2.0 SSO.
If Airlock IAM is used on both the IDP and the SP side, not only the standard SAML metadata 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 remote IDP
hosted="true" in the idp-extended.xml means: I am the IDP
hosted="true" in the sp-extended.xml means: I am the SP
Artifact Resolution over SSL/TLS
It is strongly recommended to use SSL/TLS also for artifact resolution.
Make sure the IDP's certificate chain can be verified by the SP.
If the root or issuer CA (certificate authority) is not automatically trusted by IAM instance, it may be necessary to define an alternative trust store file. This can be done as follows:
Use the IAM CLI command "build-trust-store"
Make sure the resulting trust store is used in the IAM instance. Consider the following example (instance.properties configuration):instance.properties
