Enabling SAML authentication
IAM supports SAML authentication. When SAML authentication is turned on for an IAM instance, users can log into the service using the home IdP credentials.
To enable SAML authentication for your IAM instance you have to:
- Choose an entityId for your IAM instance; see the Shibboleth docs for guidance on this
- Generate a self-signed certificate for your IAM instance that will be used for SAML cryptographic operations and include it in a Java keystore;
- Obtain SAML metadata from your IdP or identity federation;
- If the metadata is signed, import the certificate that must be used to verify the signature in the Java keystore generated above;
- Enable the
samlprofile for the IAM and configure SAML support via the appropriate environment variables.
Generate a Self-signed certificate
To generate a self-signed certificate that lasts 5 years use the following openssl command:
openssl req -newkey rsa:2048 -nodes -x509 -days 1825 -keyout self-signed.key.pem \ -out self-signed.cert.pem
The above command will generate a private key and the corresponding certificate in PEM format. You will be asked to provide a subject for the certificate being generated.
To import this certificate in a Java keystore we need in in p12 format. Use the following commands to convert the certificate in p12 format and import it in a Java keystore:
openssl pkcs12 -export -inkey self-signed.key.pem \ -name self-signed \ -in self-signed.cert.pem \ -out self-signed.p12 keytool -importkeystore -destkeystore self-signed.jks \ -srckeystore self-signed.p12 \ -srcstoretype PKCS12
During the above process you will be asked to provide a p12 export password and a keystore password. Use the same password, at least 6 characters long, otherwise it will not work for the java keystore.
You can list the contents of the keystore with the following command:
keytool -list -keystore self-signed.jks
Obtain SAML metadata for your IdP or identity federation
You IdP or identity federation will have a SAML metadata document describing, in SAML terms, which authentication flows are enabled and providing access to cryptographic material and other information that make the federated authentication schemes work reliably and securely. For more information on SAML metadata, see the Shibboleth metadata documentation.
Signed metadata advice
Typically identity federations sign the SAML metadata for security reasons, and provide a certificate (and linked public key) that can be used to verify signatures on the metadata at a well-known location (e.g., the federation website).
To support metadata signature verification you will need to import this certificate in the Java keystore created above.
Certificates are typically published in PEM format, while to import a certificate in a Java keystore you will need it in DER format.
The following commands show how to import a PEM certificate into a Java keystore:
openssl x509 -outform der -in idem_signer_2019.pem -out idem_signer_2019.der keytool -import -alias idem_signer_2019 -keystore self-signed.jks -file idem_signer_2019.der
The IdP or federation metadata to be trusted can be specified with the
IAM_SAML_IDP_METADATA environment variable, which contains an URL pointing to
If the metadata is signed, you can enforce signature validation with the
Metadata needs to be periodically refreshed to learn about new entities in the
federation or updated key material. The metadata refresh interval can be
specified with the
environment variable, which defines a refresh period in seconds (a reasonable
value is typically refresh metadata every hour).
An example metadata configuration could be:
IAM_SAML_IDP_METADATA=http://www.garr.it/idem-metadata/idem-metadata-sha256.xml IAM_SAML_METADATA_REQUIRE_VALID_SIGNATURE=true IAM_SAML_METADATA_LOOKUP_SERVICE_REFRESH_PERIOD_SEC=3600
IAM SAML attribute requirements
IAM requires that the IdP used for authentication releases a persistent identifier attribute that can be used to link the external identity to local IAM accounts. If the IdP does not release persistent identifier attributes, it cannot be integrated with the IAM.
The attribute used to link the external SAML account is configurable. In the default configuration, IAM uses the following attributes (in the given order):
The order of these can be changed with the
IAM_SAML_ID_RESOLVERS environment variable,
which accepts a list of aliases for the attributes to be searched.
The following tables maps attribute names to the aliases currently supported:
The default value for IAM_SAML_ID_RESOLVERS is:
Checking SAML assertion and authentication freshness
IAM provides the ability to set a maximum age for SAML assertion and authentication statements received from IdPs.
IAM_SAML_MAX_ASSERTION_TIME allows to define an upper bound (in seconds)
on the SAML assertion lifetime, so that assertions that exceed such limit are
IAM_SAML_MAX_AUTHENTICATION_AGE allows to define an upper bound (in
seconds) on the authentication age linked to SAML authentication statements, so
that users are forced to reauthenticate when this limit is exceeded.
Limiting authentication only to selected IdPs
IAM provides the ability to define constraints on which IdPs will be allowed for authentication. This is useful when you want to limit which IdPs in a large federation (e.g., EduGAIN) will be trusted for authentication.
Currently three types of IdPs limiting are supported:
- entity id whitelist
- SIRTFI compliance
- Research and Scholarship compliance
Limiting by entity id
IAM_SAML_IDP_ENTITY_ID_WHITELIST environment variable can be used to
define a comma-separated whitelist of IdPs entity IDs that will be trusted for
The following example limits trusted IdPs to the INFN IdP:
Limiting by SIRTFI compliance
To limit authentication only to IdPs that are SIRFTI-compliant, set
IAM_SAML_METADATA_REQUIRE_SIRTFI environment variable to true.
Customizing SAML login button text
You can customize the SAML login button text shown in the IAM login page with
IAM_SAML_LOGIN_BUTTON_TEXT environment variable.
Minimal SAML configuration example
IAM_SAML_ENTITY_ID=urn:example:iam-saml-example IAM_SAML_KEYSTORE=file:///self-signed.jks IAM_SAML_KEYSTORE_PASSWORD=xxxxxx IAM_SAML_KEY_ID=self-signed IAM_SAML_KEY_PASSWORD=xxxxxx IAM_SAML_IDP_METADATA=http://www.garr.it/idem-metadata/idem-metadata-sha256.xml IAM_SAML_METADATA_REQUIRE_VALID_SIGNATURE=true IAM_SAML_METADATA_LOOKUP_SERVICE_REFRESH_PERIOD_SEC=3600 IAM_SAML_LOGIN_BUTTON_TEXT="Sign in with IDEM"
Custom SAML configuration
The configuration based on environment variables relies on a configuration template that fits most use cases embedded in the IAM war file.
To have full control on the SAML configuration, provide a custom
application-saml.yml file in the IAM configuration directory.
See the configuration reference for more SAML metadata options and instructions on how to override the default IAM configuration.