Setting up Single Sign-On - SAML

The Security Assertion Markup Language 2.0 (SAML 2.0) is one of the protocols that are supported by the Automation Engine for single sign-on. As a system administrator, you set up SAML to use it with your system. Each department that is defined in the Automation Engine can be assigned to a SAML Identity Provider of your choice. The Automation Engine itself acts as the Service Provider toward the SAML Identity Provider. Once a department is configured for SAML, an attempt to use the Login Type Automation Engine is no longer accepted and the Login Type SAML must be used instead. In this case, the Department field becomes mandatory.

Oracle DB only: To ensure that the JWP processes XML variables correctly, you have to copy the files orai18n.jar, xdb6.jar, xdb.jar and xmlparserv2.jar to the lib folder of the JWP. The files are either part of the database or can be downloaded from the Oracle SQL Developer site.

Configuring SAML

In Client 0, enable the SAML parameter in the UC_SYSTEM_SETTINGS variable, see SAML.This step generates and populates the *CONFIG and *SP keys in the UC_SAML_SETTINGS variable.
- The *CONFIG key contains an xml file with predefined elements that allow you to define different settings.
- The *SP key contains the metadata that allows you to set up the Automation Engine as the SAML Service Provider with your Identity Provider application.
In the UC_SAML_SETTINGS variable, edit the XML content of the *SP key and replace the three _INSERT_ values, see UC_SAML_SETTINGS - Single Sign-On.
(Optional) In the XML content of the *SP key, you can configure your SAML Identity Provider to interact with the Automation Engine as a Service Provider.

The Automation Engine maps the AE Username with the value of one of the following attributes of the SAML response:
- subject-id
  
  Format: urn:oasis:names:tc:SAML:2.0:attrname-format:uri
  
  When this attribute is defined, the unique ID that precedes the @ character is mapped with the AE Username.
- NameID
  
  Format: urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
  
  The value that is defined here is mapped with the AE Username when no value is defined for subject-id. Which part of the value is used to map with the AE Username depends on how the value is defined:
  - @ character: If the value contains this character, the part that precedes it is used for mapping
  - \ character: If the value contains this character, the part that follows it is used for mapping
  - If neither of the characters is used, the complete value is mapped with the AE Username.
- aename
  
  Format: urn:oasis:names:tc:SAML:2.0:attrname-format:uri)
  
  Use this attribute if you cannot use neither subject-id nor NameID with your Identity Provider.
  
  Note: If this value is defined, it is mapped with the AE Username by default.
In the UC_SAML_SETTINGS variable, add a department as a key by clicking Add Key, and insert the downloaded XML content of the Identity Provider (IDPSSODescriptor) as a value. For more information, see UC_SAML_SETTINGS - Single Sign-On.

Use the department name as the name/value for the new key entry. Then paste the XML metadata from the SAML Identity Provider to the XML field of the new entry.

... urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

You can save the variable after each new key entry or after all new keys are entered.
(Optional) Ensure that you have a user for the department that you use as the key in step 4 where you insert the Identity Provider XML content.

In systems installed manually, after SAML has been successfully configured, you can enable single sign-on in your AWI instance. To do so, set the sso.saml.enabled property in the configuration.properties file to true. For more information, see configuration.properties.

Notes:

By default, the method REDIRECT is used for binding to the Identity Provider. If POST is to be used, the REDIRECT binding must be removed from the Identity Provider metadata (key/department).
To ensure message integrity, it is recommended signing both, the SAML Response and the Assertion. However, at least the SAML Assertion must be signed.
If the department is configured to be used with SAML, the user password can no longer be changed through the drop-down list at the top right corner menu. You have to change it through your Identity Provider. Also, changing the password in the User object has no practical effect. It becomes effective again when SAML is removed for the department the user belongs to, or when SAML has been disabled in the UC_SYSTEM_SETTINGS variable. For more information, see SAML.
The x509 certificate that is generated automatically is valid for 20 years. If you want to renew it (x509 certificate and private key), you must disable SAML in the UC_SYSTEM_SETTINGS variable and must delete the *SP key from the UC_SAML_SETTINGS variable. After the certificate and key have been removed, you have to enable SAML in the UC_SYSTEM_SETTINGS variable again. This action triggers a new key generation, rendering the old X509 certificate invalid. You then have to configure your SAML Identity Provider for all enabled departments again using the new x509 certificate. For more information, see SAML.

Examples of a Valid SAML Response


<saml2p:Response Destination="http://publicawihost/awi" ID="id290636362662992466264760"
    InResponseTo="a39679651-5ffd-48ea-9a59-bf1b9ad4b7f8" IssueInstant="2019-04-10T08:59:13.357Z"
    Version="2.0" xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol">
    <saml2:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity"xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">http://www.okta.com/exk1gximcianQOEbY0h8</saml2:Issuer>
    <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <ds:SignedInfo><ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/><ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
            <ds:Reference URI="#id290636362662992466264760">
                <ds:Transforms><ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/><ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/></ds:Transforms><ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
                <ds:DigestValue>CHD+p3Y2Fb2wMQZExoB9AB5murdi3c3ZdPOkvv65Yqs=</ds:DigestValue>
            </ds:Reference>
        </ds:SignedInfo>
        <ds:SignatureValue>...==</ds:SignatureValue>
        <ds:KeyInfo>
            <ds:X509Data>
                <ds:X509Certificate>...</ds:X509Certificate>
            </ds:X509Data>
        </ds:KeyInfo>
    </ds:Signature>
    <saml2p:Status xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol"><saml2p:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/></saml2p:Status>
    <saml2:Assertion ID="id29063636266376672635017193" IssueInstant="2019-04-10T08:59:13.357Z"
        Version="2.0" xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
        <saml2:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity"xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">http://www.okta.com/exk1gximcianQOEbY0h8</saml2:Issuer>
        <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
            <ds:SignedInfo><ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/><ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
                <ds:Reference URI="#id29063636266376672635017193">
                    <ds:Transforms><ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/><ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/></ds:Transforms><ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
                    <ds:DigestValue>4yc8XUmrGQuBMjupKPwBPTYgzDC/Yj84tySpSN4tQZ4=</ds:DigestValue>
                </ds:Reference>
            </ds:SignedInfo>
            <ds:SignatureValue>...==</ds:SignatureValue>
            <ds:KeyInfo>
                <ds:X509Data>
                    <ds:X509Certificate>...</ds:X509Certificate>
                </ds:X509Data>
            </ds:KeyInfo>
        </ds:Signature>
        <saml2:Subject xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
            <saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">AE_USERNAME</saml2:NameID>
            <saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer"><saml2:SubjectConfirmationData InResponseTo="a39679651-5ffd-48ea-9a59-bf1b9ad4b7f8"
                NotOnOrAfter="2019-04-10T09:04:13.357Z" Recipient="http://publicawihost/awi"/></saml2:SubjectConfirmation>
        </saml2:Subject>
        <saml2:Conditions NotBefore="2019-04-10T08:54:13.357Z" NotOnOrAfter="2019-04-10T09:04:13.357Z"xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
            <saml2:AudienceRestriction>
                <saml2:Audience>http://publicawihost/SAML2</saml2:Audience>
            </saml2:AudienceRestriction>
        </saml2:Conditions>
        <saml2:AuthnStatement AuthnInstant="2019-04-10T08:59:13.357Z"
            SessionIndex="a39679651-5ffd-48ea-9a59-bf1b9ad4b7f8"xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
            <saml2:AuthnContext>
                <saml2:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</saml2:AuthnContextClassRef>
            </saml2:AuthnContext>
        </saml2:AuthnStatement>
    </saml2:Assertion>
</saml2p:Response>

<samlp:Response Destination="http://publicawihost/awi" ID="_6aed358d707b5a312dfb"
    InResponseTo="a4cabf300-c365-4bb9-8fb5-88786c90b778" IssueInstant="2019-04-10T09:08:49Z"
    Version="2.0" xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol">
    <saml:Issuer xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">urn:dev-iv83r8oz.eu.auth0.com</saml:Issuer>
    <Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
        <SignedInfo><CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/><SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
            <Reference URI="#_6aed358d707b5a312dfb">
                <Transforms><Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/><Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/></Transforms><DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
                <DigestValue>2nDFArabdm2Jfpb+08pmY95YaKE=</DigestValue>
            </Reference>
        </SignedInfo>
        <SignatureValue>...==</SignatureValue>
        <KeyInfo>
            <X509Data>
                <X509Certificate>...</X509Certificate>
            </X509Data>
        </KeyInfo>
    </Signature>
    <samlp:Status><samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/></samlp:Status>
    <saml:Assertion ID="_Jr2Kdk5SGcvZ8HFbvs4mNikuLX4MqXW9" IssueInstant="2019-04-10T09:08:49.615Z"
        Version="2.0" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">
        <saml:Issuer>urn:dev-iv83r8oz.eu.auth0.com</saml:Issuer>
        <saml:Subject>
            <saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">ae_username@automic.com</saml:NameID>
            <saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer"><saml:SubjectConfirmationData 
            InResponseTo="a4cabf300-c365-4bb9-8fb5-88786c90b778"
                NotOnOrAfter="2019-04-10T10:08:49.615Z" Recipient="http://publicawihost/awi"/></saml:SubjectConfirmation>
        </saml:Subject>
        <saml:Conditions NotBefore="2019-04-10T09:08:49.615Z" NotOnOrAfter="2019-04-10T10:08:49.615Z">
            <saml:AudienceRestriction>
                <saml:Audience>http://publicawihost/SAML2</saml:Audience>
            </saml:AudienceRestriction>
        </saml:Conditions>
        <saml:AuthnStatement AuthnInstant="2019-04-10T09:08:49.615Z"
            SessionIndex="_Celn0TWdmITVRqMxGGxhZk4tjpMRe-0U">
            <saml:AuthnContext>
                <saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified</saml:AuthnContextClassRef>
            </saml:AuthnContext>
        </saml:AuthnStatement><saml:AttributeStatement xmlns:xs="http://www.w3.org/2001/XMLSchema"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/></saml:Assertion>
</samlp:Response>

Example of Use with Okta Apps

You want to use Okta Apps to logon to AWI directly from a related application in Okta. To do so, you have to make sure that the information provided in the SAML Issuer ID field in the SAML Settings of all your Clients (Apps) point to the same entityID defined for the department in the UC_SAML_SETTING variable in the Automation Engine:

AE Settings:

SAML (Advanced) Settings:

For more information, see UC_SAML_SETTINGS - Single Sign-On.