AWP

AWP supports the Security Assertion Markup Language (SAML) for single sign-on. The setup depends on the used Identity Provider (IdP), therefore this guide cannot cover all possible situations and is only meant to give an overview about the required steps.

When logging in with enabled single sign-on, AWP does not request user name and password but forwards the user to the IdP which will request user name and password if required. After authenticating the user, the IdP redirects the user back to AWP which will be able to read the required metadata to log-in the user at the Cumulus server.

The communication between IdP and AWP is at least signed, but usually also encrypted, so both IdP and AWP must have the according certificates in place.

The Service Provider (SP) role of AWP must be configured first. Specify the Issuer ID of the AWP installation which is used at the IdP for identification. The recommended value is the public URL of AWP. In addition you have to specify the Endpoint URL which is used by the IdP when sending information back to AWP. Usually this is the public URL of AWP suffixed by /saml .

The last step is the creation of the certificate which is used by AWP for signing and encrypting its messages towards the IdP and the Cumulus server. Click the Generate button and specify the certificate password to use. AWP will then create a new certificate. The given password is not saved because of security reason. To enable the AWP to use the certificate, open the WEB-INF/conf/awp-config.xml file with an UTF-8 compatible editor and write the password for the certificate into <samlPassword></samlPassword> tag. For example, if your password is my-password, change <samlPassword></samlPassword> to <samlPassword>my-password</samlPassword>, save the file and restart Tomcat.

After finishing the Service Provider configuration, the IdP must learn about the new SP. This can either be done manually using the IdP management tools or by exporting the SP configuration as a metadata.xml file. Click the Export button and select the Metadata option. The generated file can then be imported at the IdP.

Most IdP also offer a metadata file or URL resource which contains the most important information for communicating with the IdP which can be imported into AWP:

When starting the import you have the option to also select a certificate to check the authenticity of the metadata import data. The import will populate all fields where the according information is contained in the metadata.xml file.
You must at least provide the Issuer ID, the SSO Authentication URL and the certificate to be able to communicate with the IdP.
Depending on the IdP configuration you also need to select the configured Authentication Contexts.

When getting metadata for an authenticated user, AWP has to know which IdP attribute should be mapped to which user information. The first required attribute is the User UID which specifies a unique ID for the user. The recommended attribute is the email address of the user. The second required attribute specifies the User Roles mapping. Additional attributes, for example for the First Name or the Last Name, can be managed with the User Field Mappings as required.
You can get the attribute ID from the IdP administrator or by enabling extended SAML logging. To enable the extended logging, open the WEB-INF/log4j2.xml with an UTF-8 compatible editor and change the log level for the services.saml from info to debug. After saving the change restart Tomcat and try to login. The IdP authenticated user will produce the required log statement, which will look like this:

  setLoginCredentials(155): Received user details: --------------
  setLoginCredentials(158):     mail (urn:oid:0.9.2342.19200300.100.1.3) = [user@company.com]
  setLoginCredentials(158):     uid (urn:oid:0.9.2342.19200300.100.1.1) = [user]
  setLoginCredentials(158):     urn:oasis:names:tc:SAML:attribute:subject-id = [user@company.com]
  setLoginCredentials(158):     displayName (urn:oid:2.16.840.1.113730.3.1.241) = [FirstName LastName]
  setLoginCredentials(158):     givenName (urn:oid:2.5.4.42) = [FirstName]
  setLoginCredentials(158):     sn (urn:oid:2.5.4.4) = [LastName]
  setLoginCredentials(160): -------------------------------------

The logged attribute id for the email address in this example would be: urn:oid:0.9.2342.19200300.100.1.3
After extracting the required attribute ids change the log-level back to info and restart Tomcat to avoid writing sensitive data to log-files.

To keep the IdP metadata up-to-date, you can configure the available Scheduler job to check for updates regularly.

The last step enables AWP to send SAML sign-on tickets to the Cumulus server. Click the Export button again and select the option SAMLSingleSignOn.xml.



Copy that file to the Cumulus Server\conf directory. This file contains the certificate which allows the Cumulus server to validate the tickets send to it.