Open ID Connect Integration

If your organisation uses Microsoft Entra ID or another similar system, your home directory can be federated with IRIS Identity using Open ID Connect (OIDC).

Before Federating your Directory with IRIS Identity

Before federating your directory with IRIS Identity, contact your IRIS account representative to discuss options. Directory integrations are assessed case-by-case and subject to conditions. If agreement to federate your directory is given, they will provide you with a technical contact to share the details required for the process.

Prerequisites

To be able to federate your directory: 

  • All employees must be using a common email domain or domains, such as acme.com, that are owned by your company

    If your organisation uses generic email domains, such as Gmail, federating does not work. To discuss available options, contact your IRIS account representative.

  • The tasks in this integration guide must be performed by a technical user with administrative permissions in Microsoft Entra ID to create and modify applications

Open ID Connect Integration Guide

To federate your directory with IRIS Identity, complete the steps in the integration process.

Some of the processes are completed in third-party software, and therefore, label names or locations of sections may not be exact or could be out of date. If you need further help, please refer to the latest documentation available from the software provider.

Create an IRIS Application in your Microsoft Entra ID Directory

  1. Open Microsoft Entra ID in the Azure cloud portal.
  2. From the left menu, select App Registrations.
  3. Select New Registration.
  4. Enter the name of the application, for example, IRIS Identity OIDC.
  5. Leave all other fields and settings as the default
  6. To save, select Register.

Configure Basic Open ID Connect

When configuring Open ID Connect, unless otherwise stated in the instructions, leave the settings as the default.

  1. From the left menu, select Authentication.
  2. Select Add a Platform.
  3. From the menu, select Web.
  4. Enter the default redirect URI as https://identity.iris.co.uk/oauth2/v1/authorize/callback

  5. To enter the required additional URIs, select Add URI.

    Redirect URIs sections, with Add URI button highlighted

  6. Add the additional redirect URIs required from the following:
    • You must add https://iris.okta.com/oauth2/v1/authorize/callback
    • If integrating with a North American application, also add https://identity.irisglobal.com/oauth2/v1/authorize/callback
    • If integrating with Staffology Payroll, also add https://identity.payroll-app.com/oauth2/v1/authorize/callback
  7. In Front-Channel Logout URL, enter https://identity.iris.co.uk/login/signout

  8. For the token selection, only select ID Token.

    Do not select Access Token.

  9. Select Save.

Create a Client Secret

  1. From the left menu, select Certificates & Secrets.
  2. Select Client Secrets.
  3. Select New Client Secret.
  4. Enter a name for the secret.

  5. Choose an expiry.

    For expiry, Microsoft recommend 6 months but to minimise maintenance, we would recommend something longer, for example 1 or 2 years.

    To prevent interruption of service, you are responsible for tracking the expiry of your client secret and providing an updated client secret to IRIS Software Group in a timely manner.

  6. Copy the value of the secret to share with IRIS Software Group later.

Configure Permissions

  1. From the left menu, select API Permissions.
  2. In Configured Permissions, select Add a Permission.
  3. From the menu, select Microsoft Graph.
  4. Select Delegated Permissions.
  5. If not already displayed, search for OpenID Permissions.
  6. Select the openid, email, and profile permissions.

  7. Select Add Permissions.

    Shows the permissions that must be selected as described in the steps

Add Users

  1. From the left menu, select Overview.

  2. In the table, find and select the Managed Application link.

    Shows the managed application link that must be selected

  3. On the application settings page, from the left menu, select Users & Groups.
  4. Add the individual users or groups of users you want to allow to log into IRIS Software Group applications using the federated directory option.

Share Integration Details with IRIS Software Group

When you have set up the required details for integration, to complete and test the set up, you must share the required integration details with IRIS Software Group:

  1. Go back to the app registration settings.
  2. From the left menu, select Overview.
  3. In the table, copy the Application (client) ID.

  4. Then, select Endpoints.

  5. For IRIS Software Group to get the details of the other endpoints required, copy the OpenID Connect metadata document.

  6. Send the following details to your technical contact at IRIS Software Group: 
    • The IRIS Software Group applications and products your organisation uses
    • Your organisation's email domains suffixes
    • The Application (client) ID
    • The Client Secret
    • The OpenID Connect metadata document

Test Logging Into an IRIS Software Group Application

Your technical contact at IRIS Software Group uses the details you provide to set up the directory integration. When they contact you to confirm integration is complete, you must test logging into an IRIS Software Group application.

To prevent errors being displayed during testing, the account used must also already have an account set up for the IRIS application you want to use for testing.

  1. For the IRIS application you want to use for the test, go to the login page.
  2. Enter the email address of the test account, then select Next.
  3. You are redirected to your tenant's Microsoft Entra ID login screen, enter the required details to log in.
  4. When logging in for the first time, if prompted to consent to IRIS Identity having access to your profile data, give the consent.
  5. You are redirected to the IRIS application.

If no error messages other than the user does not have an account (which the wording may vary by application), or unusual behaviours happen during testing, the federation has been successful.

During testing, if any other error messages, other than the user does not have an account (which the wording may vary by application), are displayed or any other unusual behaviours happen during testing, share the details with your technical contact at IRIS Software Group.