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

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

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

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

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

  5. (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 - 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 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.
  • The Callback URL where your AWI is reachable must always end with a trailing slash (such as http://localhost:8080/awi/).
  • Depending on the Provider, the entity ID (referred to as Identifier in Azure or Audience URI in Okta) must map with the entityID value defined in the *SP key of the UC_SAML_SETTINGS variable.

    • Example

    In SAML:

    In Automic Automation:

  • The ReplyURL must always match the AWI URL.

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>

Examples

The following examples refer to third-party products whose installation, upgrade, or maintenance processes are not handled by Broadcom. Therefore, detailed instructions are not included in the product documentation as they may change at any time. Refer to the websites of the individual vendors for more details

Using Auth0 as the SAML Identity Provider (IdP)

The following example shows how you can set up Auth0 as SAML IdP for SSO with Automic Automation:

  1. Create an Auth0 account at https://auth0.com/
  2. In User Management - User, create one or more AE users.
    • This user name must match the user name in the AE (without the department). Alternatively, you can use the email address for mapping the AE user name. If you do so, ensure that you remove the first entry in the "Settings" area under nameIdentifierProbes (see below).
    • Create a user with EMAIL address.
    • In Details - Name, edit the user and change its name to the required AE name
  3. In Applications - Applications, create an application and give it a name such as AE
    • Ignore the part Choose an application type and click Create
    • Select Addons from the title bar, and SAML2 Web App
    • Select Settings - Application Callback URL and enter the URL where your AWI is reachable (such as http://localhost:8080/awi/, with a slash (/) at the end)
    • Replace the contents from the Settings field with the following and save your changes:

      4. {
      "nameIdentifierFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified",
      "nameIdentifierProbes": [
      "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
      "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
      ],
      "mappings": {},
      "createUpnClaim": false,
      "passthroughClaimsWithNoMapping": false,
      "mapUnknownClaimsAsIs": false,
      "mapIdentities": false,
      "signatureAlgorithm": "rsa-sha256",
      "signResponse": true
      }

    • Do not close the view, select Usage from the title bar and download the Identity Provider Metadata (xml file).

  4. In Automic Automation, the UC_SYSTEM_SETTINGS variable of client 0, set the SAML key to Y
  5. In the UC_SAML_SETTINGS of client 0:
    • Create a department key by clicking Add Key (e.g., AUTH0), and use the downloaded metadata xml file for the value.
    • In the *SP key metadata, search for the value _INSERT_ and replace it three times with the URL where your AWI is reachable (such as http://localhost:8080/awi/). This URL must be the same as is set as the Application Callback URL in Auth0.
    • Important! Auth0 supports signing either the whole response OR the assertion only, but not both. By default, the AE expects both to be signed, but at least the response. The Auth0 settings described above show that the parameter signResponse is set to true, which ensures that the response is signed. Also, adjust this setting in the *SP metadata:

      • <md:EntityDescriptor .....">
      <md:SPSSODescriptor AuthnRequestsSigned="true" WantAssertionsSigned="false"

  6. Enable SAML Login in the AWI. Open its configuration.properties file and add sso.saml.enabled=true
  7.  Log on to your Automic Automation system. As the Login Type, select SAML; as the department, use Auth0 as you have previously defined in the UC_SAML_SETTINGS variable.
    • You should be redirected to the IdP, where you must authenticate once with the credentials defined in the user settings.
    • (Optional) If Multifactor Authentication is enabled and the Auth0 Guardian app is installed on your mobile phone, you should have received an authentication request on your mobile. Confirm it.
    • Now the IdP returns a SAML assertion. If the user name returned from auth0 matches a user in the AE with the department AUTH0, the response should be validated successfully and you are logged in.
    • The following login request is automatically processed. You do not have to enter your credentials again.

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

Using SAML with Azure Active Directory (AD)

Ensure, that you define the following in the UC_SAML_SETTINGS variable of Client 0:

  • In the metadata of the *CONFIG key, set disableRequestedAuthnContext to true.If set to true, RequestedAuthnContext of the SAML AuthnRequest is not sent to your Identity Provider

    <disableRequestedAuthnContext>true</disableRequestedAuthnContext>

  • In the metadata of the *SP key, set AuthnRequestsSigned and WantAssertionsSigned to false

    <md:SPSSODescriptor AuthnRequestsSigned="false" WantAssertionsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol

For details, see the MS Azure console as described in: https://learn.microsoft.com/en-us/azure/active-directory/develop/active-directory-saml-claims-customization. Search for the NameID format section, change from "Windows domain qualified name" to "Unspecified".

Important! Always clear the browser history (cache/cookies).

Using SAML with Active Directory Federation Services (ADFS)

Prerequisities:

  • ADFS must be configured and running.
  • The AWI must use an https endpoint as this is required by the ADFS side.
  • Automic Automation requires no particular configuration except for the values of the *SP key with _INSERT_ that need to be configured, as well as an import of the metadata.

To configure the ADFS side for SAML for the Automic AWI - Example

Note: The screens or settings might differ depending on the Windows versions and security policies used.

  1. Add Relaying Party Trust wizard:

    1. Select Claims aware.
    2. Select the option Enter Data about the relying party manually.
    3. Under Display name, enter Automic Saml, for example.
    4. Skip the token encryption and click Next.
    5. Check Enable support for the saml 2.0 WebSSO protocol and enter the AWI URL in the following format:

      6. https://servername:port/awi/

    6. Under Relying party trust identifier, add the entitiyID configured in the *SP key in Automic Automation.
    7. Access control policy should be selected depending on your internal security level.
    8. Add the relying party trust.

  2. Edit the Claim Issuance Policy and Add a Rule:

    1. For the Claim Rule template, set Send LDAP Attributes as Claims
    2. Set the Claim rule name to Sample Rule for Automic, and Attribute Store should be set to Active Directory.
    3. In the mapping section, set the following:
      • Ldap Attribute sam-Account-Name, and outgoing claim type to Name ID.
      • Ldap Attribute sam-Account-Name, and outgoing claim type to aename.
    4. Save and apply your changes in ADFS.

See also: