2021.2 (latest)

Integrations

On this page:

Azure Adapter

The Azure-Adapter allows SSO (single sign-on) in Azure over the OpenID Connect (OIDC) protocol. Use the information in this guide to configure the Azure AD server and set-up adapter-azure_aaa for the Itential platform.

Important Reminder: The information provided herein was developed in a lab environment. Input for various settings and fields should be populated with details specific to your production environment.

Azure AD Setup

This section outlines the process and permissions that are required for the Azure AAA adapter to communicate with the Azure AD system.

Note: Admin privileges in the Azure AD system are required to perform the initial set-up.

Create New Application

  1. Login to the Azure AD system and access the Azure AD Page.

  2. Select the App Registration section.

  3. Click New registration

    Recommendation: Create a separate application for each environment so that passwords and configurations are unique to each environment.

    new registration

  4. Complete the application fields. For example:

    • Name: Itential Automation Platform - Production
    • Supported Account Types: Default
    • Redirect URI: Leave blank we will update later

  5. Click the Register button.

  6. Review the application details.

  7. Record the Application ID. It will be used by the adapter as the "client id".

  8. Record the Tenant ID. It will be used by the adapter as the "tenant id".

    application ID

Authentication Settings

  1. Go to the Authentication section.

  2. Verify the Redirect URIs. These are the acceptable return URIs after authentication. If a redirect is attempted to a URI that does not exist here, the redirect will fail to complete. Pay close attention to the ports as you must have URI for each port

    Typically the URL is the same as the sign-on, or a sign-on with a specific SSO page. For example:

    • https://itential.customer.com/login
    • https://localhost:3443/login


    redirect uri

  3. Enable the ID tokens under Advanced settings.

    id tokens

Set Application Permissions

  1. Go to the API Permissions section.

  2. Click the +Add a permission button to add new API permissions.

  3. Find and select Microsoft Graph API from the list.

  4. From the list of Application Permissions (top section) check the following:

    • Directory - Directory.Read.All
    • Group - Group.Read.All
    • User - User.Read.All

  5. No delegated permissions are required.

  6. Click Add Permission to save changes.

    required permissions

  7. Click Grant admin consent and then click the Yes button to grant admin consent.

Set the API Key

  1. Go to the Settings → Keys section.

  2. Create a new password by completing the following fields. Be sure to use a secure password.

    • Description: IAP API Key
    • Expires: Never
    • Value: <super_secret_password>

    required permissions

Note: Expiration policies vary across different organizations. Please follow the guidelines for your respective organization.

  1. Click Add. A warning message displays reminding the user to keep a safe copy of the Value, which has been encrypted.

  2. The value/password will be used in the secret field by the Azure AAA adapter.

    api key

Choose a Method of Group Tracking

As part of the integration between Azure AD and IAP groups are used to allow users to be assigned roles within IAP. Therefore it's important that the Azure AD adapter be configured to read those groups from Azure AD.

To that end several methods are supported and listed below with some recommendations for usage.

Method Recommended Notes
all See notes Using the all method tells the Azure AD adapter to read and track all Azure AD groups, while this may seem the simplest options, If your Azure AD server more than a couple hundred groups this may impact login performance. This option is recommended for smaller scale Azure AD servers.
master Yes This method uses a created group in Azure AD to identify which AD Groups to track. The Azure admin will create a unique group in Azure AD, and then add as many other groups as are required for tracking. The adapter will query Azure AD for the list of members in this group. Those member groups then become the list of groups that IAP will track and matched against users on login.
account Yes Very similar method to "master", however in this case a Azure AD Account is used, any listed groups assigned to this user will be tracked by IAP and matched against users at login.


  1. Select a group sync method.

  2. Create the required group or account and capture the Object ID of the group/account.

    master ObjectID

Azure AAA Adapter Setup

Use the following information to setup the Azure AAA Adapter.

  1. The following values are required by the Azure AD Admin that creates the IAP Application in Azure:

    • Tenant ID ("tenant"): This value is found in the endpoints of the Azure AD → IAP App → Tenant ID setup.
    • Client ID ("client"): This value is found in the Azure AD → IAP App → Application ID.
    • IAP API Key ("secret"): This value is obtained during the key setup in Azure AD → IAP App → Keys.

  2. Update the active IAP_Profile in the service configuration in Admin Essentials to add the Azure AAA adapter. Copy the JSON code below into the properties section of the Service_Config for the Azure AAA adapter.

        {
        "id": "Azure AAA",
        "type": "azure_aaa",
        "properties": {
            "tenant": "a38145b3-f428-3645-cb19-ac6fe574ec71",
            "client": "d54381f6-43ae-33cd-bc79-112233dce3c6",
            "secret": "7hcq6sruo5GZAEDzRh6+S4LnKmL1Mb+KK2qlP6uT8w0=",
            "groupSync": {
                "interval": 3600,
                "method": "all / master / account",
                "masterGroup": "<object id of master group or empty for all>",
                "serviceAccount": "<object id of service account or empty for all>"
            }
        },
        "brokers": [
            "aaa"
        ]
    },

  3. Find the properties section of the Service_Config for the Local AAA adapter. Remove the "AAA" value from brokers section leaving the array empty []. Make sure no other adapters are using the "AAA" config.

        "brokers": [
        "aaa"
    ]

  4. Configure the uiProps login schema in IAP_Profile. This will redirect to the Azure SSO page. The path is relative to the base IAP directory.

    "uiProps": {
    "login": "custom/sso.html",

  5. Update authenticationProps in IAP_Profile** to specify the Administrator Group or Groups to be used from the Azure adapter. Any user within these groups will have full administrator permissions within the Itential platform.

    Note: To sync the groups correctly, provenance must match the id value of the adapterProps and group value should match with the group name created on Azure AD.

    "authenticationProps": {
    "admins": [
        {
        "provenance": "Azure AAA",
        "group": "IAP-Administrator"
        }
    ]
},

Itential SSO Set-Up

Whenever users attempt to access the Itential login page, they are redirected to the Azure SSO page. To do this, another HTML page is created and specified in the uiProps.login section of IAP_Profile.

  1. A sample sso.html is available for use and should work for most default installations. It's located within the node_modules/@itential/adapter-azure_aaa/samples directory

  2. Locate or create the sso.html which can be renamed as long as it matches the uiProps.login path. Itential recommends that you place the file in a custom directory under the /opt/itential/current/ directory and name the file sso.html:

    custom/sso.html

  3. To edit the file, modify the following values to match the set-up.

    Note: The secret is not required and should not appear in this file as sso.html can be read by any browser.

    var host = 'https://login.microsoftonline.com/';
var tenant = 'a28044b2-e519-4675-ab09-eb6ee673ed72';
var client = 'd42380f6-4fae-43ed-bb78-415243bce4c7';

  4. Verify the tenant/client values are the same used in Service_Config.