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 TypeSAML 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

  1. In Client 0, enable the SAML parameter in the UC_SYSTEM_SETTINGS variable, see SAML.

    This step generates and populates the *SP key in the UC_SAML_SETTINGS variable. The key contains the metadata that allows you to set up the Automation Engine as the SAML Service Provider with your Identity Provider application.

  2. 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.

  3. Use the XML content that was edited in the previous step. You use it to 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.

  4. In the UC_SAML_SETTINGS variable, add departments as keys and map them to the relevant Identity Provider. For more information, see UC_SAML_SETTINGS - Single Sign-On.

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

    You can save the variable after each new key entry or after all new keys are entered.

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 - Configuring Your Local Setup.

If your system is an Automic Automation Kubernetes Edition, you can enable single sign-on by setting the AUTOMIC_SSO_SAML_ENABLED environment variable to true in the values.yaml file before the installation. Once your installation is provisioned, you must enable it in the awi-properties section of the configmap. For more information, see Configuring Container-Based Systems.

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 Response must be signed. Signing only the Assertion leads to an access denied.

  • 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.

See also: