Federated ID

This guide explains how to log in using your own (third party) federated identity provider (IdP) with our platform. The following sections detail the configuration process and setup requirements.

Federated IdP

We support SAML 2.0 federated flow, and also support Google as a “social” provider. This documentation currently covers our supported identity providers. If you’re interested in using a different identity provider that isn’t currently documented, please contact support@modicagroup.com to discuss implementation options.

Before You Begin

Before you begin configuring an Identity Provider for your account

• Your organisations account will need to be enabled for federated login.

• To configure things you will need to ensure you have the correct permissions associated with the user account you have with us. Your Service Delivery or Account Manager can confirm this if needs be.

• You will need to have the appropriate access level to your organisations Identity Provider in order to configure the federated connection.

• Make sure you have configured a user account in your identity provider that maps to the corresponding user account at our end. The assertions for the user account we expect to be mapped from the identity provider are:

  • firstName

  • lastName

  • email (this may also need to be mapped to ‘principaID’ or similar IdP attribute denoting the username used for logging into our messaging platform)

Note: the assertion names are case sensitive and need to be entered as firstName, lastName and email. Incorrect case will cause the federated login to fail.

Configure the Account

Navigate to Settings

To start the configuration process:

• Login to the messaging platform with the appropriate user account.

• Navigate to Client then Settings in the side menu

• Then click Login Settings

Login Settings

On the Login Settings page, locate the Identity Provider dropdown:

From the dropdown options, select the required Identity Provider. This will load the appropriate settings forms as detailed in the sections below.

Set up SAML IdP

Process:

1. The Assertion Consumer Service (ACS) URL field displays the URL the identity provider will redirect to. This is a read only field.

2. The Entity ID value is used by the identity provider. This is a read only field.

3. Enter a name for the identity provider (example: JumpCloud-OMNI).

4. The identity provider will be able to generate an XML metadata document for importing by the service provider. Use this to open a file picking window and select the XML file.

5. The content of the uploaded XML file will display here. This is a read only field.

6. The identity provider can import the service provider settings from an XML metadata document. This document will include the ACS URL, entity ID and user account attributes. Click here to generate this document.

Note: The user account attributes that the messaging platform expects to be mapped from the identity provider are -

• firstName
• lastName
• email (this may also need to be mapped to ‘principalID’ or similar IdP attribute denoting the username used for logging into the messaging platform)

Click the Update button at the bottom of the page to set the identity provider settings for this client account

Set up Google IdP

To add a social identity provider, you first create a developer account with the identity provider. After you have your developer account, register your app with the identity provider. The identity provider creates an app ID and an app secret for your app, and you configure those values in your messaging platform account. See here for additional information to get you started with Google - https://developers.google.com/identity/

Process:

1. Enter the Google App ID that you received when you created your client app.

2. Enter the App secret that you received when you created your client app.

3. Enter the names of the social identity provider scopes that you want to map to user pool attributes. Scopes define which user attributes, such as name and email, you want to access with your app.

Note: The user account attributes that the messaging platform expects to be mapped from the identity provider are -

• firstName
• lastName
• email (this may also need to be mapped to ‘principalID’ or similar IdP attribute denoting the username used for logging into OMNI)

Click the Update button at the bottom of the page to set the identity provider settings for this client account.

Legacy “SSO” settings

Legacy SSO settings are only applicable for clients using version 1.0 of the federate identity solution. New federated clients should not be using this option, and will not see a legacy option in the Provider Type dropdown. Legacy clients will be able to update the IdP URL if required, and generate / download the Service Provider XML metadata file.

1. Click the Generate SP Metadata link to generate the client specific metadata for use with your IdP

2. Enter the URL for the client IdP. This will take the form of something like this: https://myapps.myidp.com/signin/bunch_of_numbers_and_letters?tenantId=bunch_of_numbers_and_letters

3. Don’t worry about the 2 tick boxes.

Enable Federated ID

Part of configuring federation identity is enabling the user accounts to use federation.

1. As the user account with the proper permission, go to Clients; User Accounts

2. Click on the User Name you wish to enable. This will open the Contact Details for the user account.

On the Contact Details screen, enable the Federated checkbox as shown. The next time the user logs in to the messaging platform the federated login flow will apply to the user account, and they will be redirected to the identity provider configured for the client account. The user account will continue to use federated identity until this check box is disabled.

Configuring Entra ID

This section provides more information on configuring Entra ID, a popular identity provider for business use.

Before You Begin

Before you configure Entra ID, you should ensure you:

• Have an Active Directory account

• Have one of the following roles for Active Directory:

  • Global Administrator

  • Cloud Application Administrator

  • Application Administrator

  • Owner of the service principal

• Have created and assigned a user account in Entra ID that will map to the associated messaging platform user account

• Have administrator access to the messaging platform client account wishing to use federated identity.

• Have the Service Provider XML Metadata file for the applicable messaging platform client account. You can generate this from the Client Settings > Login Settings page for the applicable messaging platform account.

• Have enabled the associated messaging platform user account to use federation login.

Add To Entra ID

1. Sign in to the Microsoft Entra admin centre as at least a Cloud Application Administrator

2. Browse to Identify > Applications > App registrations and select New registration.

3. Enter a Display Name for your Application.

4. Specify who can use the application, sometimes called its sign-in audience.

5. Leave Redirect URI (optional) alone for now as you configure a redirect URI in the next section.

6. Select Register to complete the initial app registration.

Set up Entra ID SSO

1. In the Manage section of the left menu, select Single sign-on to open the Single sign on pane for editing.

2. Select SAML to open the SSO configuration page. After the application is configured, users can sign in to it by using their credentials from the Microsoft Entra tenant.

3. Select “Upload metadatafile” option to import the XML file you generate in the application

4. In Basic SAML Configuration the XML will replace the default Identifier ID (Entity ID) with the Identifier (Entity ID).

5. Click ‘Save’.

6. Copy the Sign on URL from the messaging platform page into your Entra ID settings. The Sign on URL will allow your new users to initiate the sign on from IdP side, which in turn will trigger the Just-in-Time (JIT) provisioning in Omni. This is only needed for JIT purposes, existing users can login via the standard platform login page.

Map Attributes and Claims

Note: The assertion names are case sensitive and need to be entered as firstName, lastName and email. Incorrect case will cause the federated login to fail.

Steps	View
Navigate to Attributes & Claims
Click on Required Claim Set this to user.principalname
Click on user.mail Delete content in Namespace field Change Name to email Ensure Source is set to Attribute when editing the claim
Click on user.givername Delete content in Namespace field Change Claim name to firstName Ensure Source is set to Attribute when editing the claim
Click on user.surname Delete content in Namespace field Change Claim name to lastName Ensure Source is set to Attribute when editing the claim
Click on user.principalname Delete content in Namespace field Change Claim name to user.mail Ensure Source is set to Attribute when editing the claim
The result should look like this

FAQ

Glossary of terms

Attribute

Attributes are used in Federated Authentication to pass data about an authenticated user. They are shared by the Identity Provider (IdP) with a Service Provider (SP). The exact format of the attribute depends on the underlying technology, e.g. SAML, OpenID Connect.

Federated identity

An authentication process that allows a user to log in with a single ID and password to any of several independent, unrelated, software systems. This is an expansion of the term Single Sign-on (SSO).

Identity Federation, aka “Federation”

A group that operates a trust framework for exchange of authentication assertions between its members and/or customers, that are Identity Providers and Service Providers. This describes the relationship between the messaging platform (SP) and the client (IdP) when configured for federated identity.

Identity Provider, aka "IdP"

A member or a customer of an identity federation that assigns access credentials to qualifying individual natural persons. Some examples of IdPs are JumpCloud and Entra ID.

Online Platform

An Online Platform is a platform through which a Service Provider provides access to resources, such as messaging applications and reports, that requires end users accessing those resources to be reliably authenticated.

Security Assertion Markup Language, aka "SAML"

SAML is an open standard for authentication and authorisation. See https://en.wikipedia.org/wiki/Security_Assertion_Markup_Language

Single Sign On, aka "SSO"

An authentication process that allows a user to log in with a single ID and password to any of several related, yet independent, software systems. When using the term “SSO” the topic usually describes logging into related yet independent systems within a single organisation. When SSO is supported outside a single organisation, it becomes federated authentication.

User

An individual natural person to whom access credentials have been assigned by Identity Providers thereby enabling them to access resources supplied on the online platform of a given Service Provider by means of a log-in or sign-on.

How does Federated ID work?

Federated ID uses a SAML claims-based authentication workflow. First, when a user tries to access the messaging platform, the platform will ask the identity provider to authenticate the user. Then the platform uses the SAML assertion issued by the identity provider to grant the user access. Here’s an example.

1. The user opens their browser and navigates to the messaging platform login page, and enters their Username. The Username belongs to a client that has been configured to use an identity provider for authentication.

2. The messaging platform recognises the Username provided belongs to a federated ID client and responds with a SAML request.

3. The browser passes the SAML request to the identity provider.

4. The identity provider parses the SAML request.

5. The identity provider authenticates the user by prompting for a username and password or some other authentication factor. NOTE: The identity provider will skip this step if the user is already authenticated.

6. The identity provider generates the SAML response and returns it to the user’s browser.

7. The browser sends the generated SAML response to the messaging platform which verifies it.

8. If the verification succeeds, the platform grants the user access to their platform dashboard page

Can I configure Entra ID for federated ID with the platform?

Yes you can! We have created a comprehensive User Guide for Entra ID as part of the user guide to help you set things up.

Some other useful tips are here:

Q. Do I need separate Entra ID applications for each messaging platform user?

A. In the messaging platform, each client is a separate entity with a unique ID. This unique ID maps to the entity ID in the Entra ID application, and ensures the user account is authenticated against the correct platform client, allowing each user to access the correct applications under their profile. Using the incorrect client ID will prevent the user account from accessing applications.

Q. I’ve configured Entra ID but after authenticating with the platform I receive a user access error.

A. This will happen with Parent / Child client accounts where the Entra ID application is using the wrong client ID (probably using the Parent ID for a Child account). Ensure you are using the correct data from the metadata file for the relevant messaging platform client account. Each Parent / Child client account needs an Entra ID application / group

Q. I’ve configured Entra ID but when I authenticate with the messaging platform I’m sent back to the login page in a continuous loop.

A. Ensure the User Attribute user.principalname is mapped to user.mail

Q. I’m getting a ‘user access error’ from the messaging platform.

A. If you have configured Entra ID but are getting a user access error after authenticating with the platform it is likely due to the Parent / Child client accounts set up, where the Entra ID application is using the wrong client ID (probably using the Parent ID for a Child account). You can check you are using the correct data from the metadata file for the right messaging platform client account.

Each Parent / Child client account needs its own Entra ID application / group

I'm getting a message from the platform saying I don't have permission to view that page?

In the messaging platform, each client is a separate entity with a unique ID. This unique ID maps to the entity ID in the IdP application, and ensures the user account is authenticated against the correct platform client, allowing each user to access the correct applications under their profile. Using the incorrect client ID will prevent the user account from accessing applications. Check to make sure you have the correct entity ID and metadata file for the user account from the correct messaging platform client account.

I'm getting a message saying "oops, this link isn't working"

If you are getting a page that looks something like this when trying to login with federated ID, it will most likely mean the user account has been configured within the incorrect client account in the IdP:

This normally happens when the customer has parent / child accounts and the user account is placed in the incorrect client at the IdP side. To fix this, check the user account is configured correctly.

What other Identity Providers can I use?

Any Identity Providers that supports SAML 2.0 assertions can be used to federate your identity. 

Some examples are;

• Microsoft Entra ID

• CyberArk

• JumpCloud

• Okta

• OneLogin

• Ping Identity

You can also use “social” providers that include Google, Facebook, Apple and AWS.

I'm getting an "Oops!" message from the messaging platform on login attempt

If you are getting an “Oops! Sorry an error occurred” from the messaging platform when trying to login for the first time, this will normally indicate the expected user attributes have not been mapped correctly within the IdP.

See the user guide for more information on mapping user attributes.

Can I change the username?

Short answer, no you cannot change the username of an existing account. When the identity provider provides assertions to the messaging platform (the service provider), we check the username. If the username does not exist a new user account will be created using just-in-time provisioning. So changing a username at the identity provider to one that doesn’t exist will create a new account on the platform.