1. Support
  2. Managing Users & Permissions

How do I set up Single Sign on with Microsoft for my Organisation?

This set up should only be done by someone with administration access to your school's Azure Active Directory account.

This is a premium feature available with a full subscription to iAM Compliant

This feature is currently in a closed beta, and only available to invited organisations. If you would like to join, please get in touch to request access.

iAM Compliant - Azure AD Install Instructions

Introduction

iAM Compliant allows you to configure single sign-on (SSO) functionality so that Microsoft Azure users can be added and managed directly from an Azure Active Directory (Azure AD) application. Once the integration between iAM and Azure AD is configured, an administrator can assign new users to the iAM application from Azure AD. User details are then synced automatically between the two systems and the Azure users can then log in to their iAM account using their Microsoft work/organisation login.


Once an iAM user is associated with an Azure account, it is not possible to update their user details from within the iAM Compliant user administration screen or user profile page. Instead, changes to user details are fed through automatically from Azure AD on a scheduled basis.


This document describes how to configure an iAM account to link with one or more Azure AD accounts.

Prerequisites

  • The Single Sign-on feature is only available to iAM Compliant accounts with a full subscription. Contact support to have the feature turned on for your account.
  • Your iAM account should be on a plan with sufficient user capacity.
  • You should have an Azure AD account with administration access to the AAD portal.
  • You should be familiar with configuring an Azure AD account and managing users within it.

To avoid the creation of duplicate accounts, please check that any existing iAM users in your account have the same details (i.e. email and name) as they do in Azure AD.

Configuration

1. Create a new iAM Compliant app in Azure AD

The first step is to set up a “non-gallery” app in Azure AD for the integration with iAM.

  1. Log in to the AAD portal enterprise applications page
  2. Click “New application” > “Create your own application”
  3. Select the non-gallery option (“Integrate any other application you don't find in the gallery”) and give your application a name. Your users will see this in their My Apps so it makes sense to call it “iAM Compliant” (or “iAM Compliant for [LOCATION NAME]” if you are working with multiple locations).
  4. Copy the application (client) id and directory (tenant) id values from your new application. To do this:
    1. Navigate to the AAD App Registrations page and locate your new iAM app (NB may be listed under “All applications”)
    2. Copy the displayed values for “Application (client) ID” and “Directory (tenant) ID”. You will need both these values to set up the SSO configuration in your iAM account (in step 2 below).
  5. Configure Web Platform
    1. Click “Authentication” from the left-hand menu
    2. Click “Add a platform” and select Web
    3. In the “Redirect URIs” field enter:
      https://app.iamcompliant.com/auth/microsoft/callback
    4. Click “Configure”
    5. In the “Front-channel logout URL” field enter:
      https://app.iamcompliant.com/logout
    6. Save your changes
  6. Create a client secret. To do this:
    1. Click “Certificates & secrets” from the left-hand menu
    2. Click “New client secret”
    3. Enter a description and expiry, then click “Add”
    4. You should see your new secret, copy the secret “Value” but don’t share it with anyone. You will need this value to set up the SSO configuration in your iAM account.
  7. Add application logo (optional). Adding a logo to your app is useful as it appears on the My Apps tile along with the app name entered in 1.3. To add a logo:
    1. Click “Branding & properties” from the left-hand menu
    2. Select a file to for the “Upload new logo” field and save your changes
    3. An iAM Compliant logo is available here:

iAM Compliant logo 215

Once you’ve created an Azure AD app and copied the client id, client secret and tenant id values you are ready to configure the iAM Compliant part of the integration.

2. Create an SSO configuration

This step sets up a configuration that enables iAM to recognise your users both when they sign in using single sign-on and when they are submitted to iAM from Azure provisioning. First log in to your iAM account as an account administrator and go to the account settings for your organisation.

  1. Click the “Single Sign-on” link in the right-hand sub-menu.
  2. To create a new configuration click the Add Config button
    1. Enter a display name for your configuration. Only account owners will see this name but it makes sense to call it something that relates to your Azure app (e.g. “Azure SSO” or “Azure SSO for [LOCATION NAME]” if you are working with multiple locations).
    2. Enter the values copied from your Azure app (1.4.a & 1.4.b above) for “Application (client) ID”, “Directory (tenant) ID” and “Client secret”
    3. If you have more than one location in your iAM organisation you should also select which locations your SSO users should be granted access to. Users added to iAM from your Azure app will be given access to the locations you select here. You must select at least one location. For more information see the section on Multiple SSO Integrations below.
      If your iAM organisation only has one location you can ignore this step - you will not see any options for applicable locations here.
  3. Finally save the new configuration.

3. Copy User Token & Login URL


Once you have successfully added a single sign-on configuration, you should see a summary of your new configuration. There are two fields to copy which will be used below to finish the Azure AD setup.

  1. User provisioning token
    This token should only be used to configure the user provisioning section of your Azure AD app. You can view and copy this token but please ensure that you keep it secure.
  2. Login URL
    This value is used to configure the Azure single sign-on in step 5 below.

4. Configure User Provisioning


This step configures your Azure AD app so that it automatically creates and updates your iAM users.

  1. Admin Credentials
    1. Go back to your Azure AD enterprise applications and select the app you created. 
    2. Select “Provisioning” from the menu. Then click “Get started”
    3. Select “Automatic” as the provisioning mode. You should see an admin credentials screen.
    4. In the “Tenant URL” field enter
      https://app.iamcompliant.com/api/scim_v2/
    5. In the Secret Token enter your user provisioning token copied in step 3 above.
    6. Recommended: You can use the Test Connection button to verify that a connection is made to the iAM server. This will only work if your provisioning token is valid.
    7. If the connection is OK, save your provisioning config.
  2. Mappings. Next you’re presented with options for mapping user properties from Azure to iAM.
    1. Configure user mapping. For single sign-on to work, iAM needs to be provided with five attributes for each user:

      Attribute

      Comment

      SSO external id

      Not visible, used when signing in from a Microsoft account

      Email address

      Always unique in iAM

      First name

       

      Last name

       

      Active

      Turns the iAM user account on/off

    2. To set up these mappings:
      1. Click “Provision Azure Active Directory Users”
      2. Set Enabled to “Yes”
      3. A typical mapping should look like this:
      Azure user mappings 
      1. Save and confirm
      2. If you cannot see objectId in your mappings click Add New Mapping and add the following details:
        1. Source Attribute: ObjectId
        2. Target attribute: externalId
        3. Match objects using this attribute: Yes
    3. Disable group provisioning. Provisioning iAM groups through Azure is not currently supported so that part of the provisioning should be turned off to avoid errors.
      1. Click “Provision Azure Active Directory Groups”
      2. Set Enabled to “No”
      3. Save and confirm
    4. Set Provisioning Status
      Setting the “Provisioning Status” box to “On” will make the automated Azure user provisioning cycle start. You can leave this for later or alternatively start or stop provisioning from the main provisioning screen.

    5. Configure Single Sign-on


    The single sign-on integration needs to use a custom login URL in order to tell iAM which client is accessing the system. To set this up:

    1. Go back to your Azure AD enterprise applications and select the app you created.
    2. Select “Single sign-on” from the menu
    3. Select “Linked” as the single sign-on method
    4. Enter the login URL value copied from your iAM SSO config in 3.2 as the “Sign on URL” value and save the changes.

    6. Start Provisioning


    Use the Provisioning menu in your Azure AD enterprise app to start and stop automated provisioning and to view logs and error messages. You can also provision users individually which can be useful for verifying that everything’s working as expected.

    Refer to the Microsoft documentation for more information about user provisioning. Be aware that there is a delay of as much as 40 minutes for changes to sync automatically between Azure AD and an iAM account.

    Once users have been provisioned successfully, the Azure AD logs will record success messages. Account administrators can view and filter SSO-enabled users inside their iAM account user settings:

    Filtered Azure SSO user list

    7. Assign Users


    Once the user provisioning mapping is set up it’s necessary to assign the iAM Compliant app to any of your Azure AD users who should be granted access to your iAM Compliant account.

    We recommend starting with one or two accounts first to ensure users are being created and updated correctly, and to test that single sign-on is working as expected.

    1. Go back to your Azure AD enterprise applications and select the app you created.
    2. Select “Users and groups” from the menu.
    3. Click “Add user/group”, then in the Users area click the “None/Selected” link to open a user selection interface.
    4. Select one or more users to assign to the app.
    5. Click “Assign” to save your changes.

    If you already have users with access to iAM Compliant their accounts will still work as before (with their existing passwords if they choose to login with a standard password login). Single sign-on is appended to their iAM user and they will also be able to login in by clicking the iAM Compliant tile in My Apps; this will initiate the single sign-on flow and not require an iAM password. Existing users will retain their existing iAM role.

    New users added to iAM via Azure AD provisioning will not automatically receive an iAM password. They should just use the My Apps login. New users will be assigned a “Reporter” role in iAM Compliant. Their role can be updated by another iAM user with sufficient user management privileges.

    Once an iAM user is synced with an Azure AD account, the user details for that account will no longer be editable within iAM:

    Azure SSO user profile

    8. Grant Permissions


    When first logging in using single sign-on users are presented with a consent screen asking them to allow the app to read their basic user profile. To eliminate this step an Azure user with owner privileges can accept these permissions on behalf of all users you assign the app to.

    To do this simply log in to iAM from My Apps and you should see a screen like this:
    Permissions requested screen

    Ensure the “Consent on behalf of your organisation” box is checked and then Accept. If you don’t see the box, check you are assigned as the owner of your Azure app by going to your enterprise application and navigation to the “Owners” menu item.

    9. Multiple SSO Integrations


    Steps 1 to 8 of this guide can be repeated for a single iAM account to support a number of scenarios:

    • An iAM account with multiple locations where users need to be provisioned with different location access
    • An Azure AD account with multiple directories
    • An organisation with multiple Azure AD accounts

    For any of these cases, repeating steps 1 to 8 of this guide will add multiple SSO configurations to your iAM account. If your iAM account has more than one location, pay particular attention to section 2.2.c as setting applicable locations can be used to manage user access across multiple locations.