External IdP Setup Guide

Overview

omAccounts supports integration with a variety of identity providers through the protocols Security Assertion Markup Language 2.0 (SAML v2.0) and OpenID Connect (OIDC), such as Ping Fed, PingOne, Okta, Keycloak. In implementing Single Sign-On (SSO), users can log in via their organization's Identity Provider on the Omilia login screen.

A successful External Identity Provider setup greatly enhances the user experience for your organisation's users, offering a seamless login process that leverages your existing Identity Provider. With Omilia, setting up an IdP is part of our commitment to providing streamlined, secure, and efficient communication solutions.

SAML v2.0 SSO Setup

Omilia's Responsibilities

Determine an alias for the customer's Identity Provider (IdP).
Determine the Assertion Consumer Service (ACS) URL by following this format: <omAccounts-url>/auth/realms/master/broker/<alias from step a>/endpoint
Create an entity ID value.
Send the entity ID, the determined alias and the ACS URL to the customer, along with Omilia’s public certificates for signing/encryption.

Customer's Responsibilities

Provide an XML that contains the SAML metadata for your application. This data should include:

SSO login and logout URLs, and
Public keys.

It's important for customers to maintain the accuracy of data shared in XML file and assertion response document, and transfer sensitive information through secure channel.

Provide an assertion response document that should contain these specific arguments:

firstname: The user's first name.
lastname: The user's last name.
email: The user's email address.
Subject NameID: A unique identifier for the user needed during login. It can be either an email address or a username.

The Subject NameID is needed during login, hence make sure it is unique for each user.

Once Omilia receives these files from the customer, it can proceed to set up an Identity Provider.

How to Complete the Setup

Upon receiving the necessary files from the customer, Omilia can then begin the process of establishing an Identity Provider. The entire process unfolds as described below:

Omilia's Customer Support will confirm the receipt of the necessary SAML metadata and assertion response document from the customer.
The Support team will then configure an Identity Provider on omAccounts. During configuration, the Customer’s Identity Provider alias and the ACS URL will be used as provided.
After the Identity Provider is created and properly configured, users of the customer organisation will have the option to authenticate their identities through the Omilia login screen using organisation's identity provider.

OpenID Setup

Customer’s Responsibilities

Setting up an OpenID external Identity Provider is a straightforward process that can be accomplished in the following ways:

Using the well-known URL

All Identity Providers that implement the OpenID protocol expose a publicly accessible URL containing information about the OpenID configuration. If the customer can provide this URL, Omilia's system can automatically detect all the necessary information to set up an OpenID Identity Provider.

Manual setup

To configure OpenID manually, the customer must provide Omilia with the following information:

Mandatory information is marked with an asterisk.

Authorization URL*
Token URL*
Logout URL
User Info URL
Issuer
Whether signature validation is required*
JWKS URL, or public key and key ID*

Additional information

Additionally, Omilia requires the OpenID application (or OpenID client) credentials to authenticate with the external Identity Provider. This authentication can be done using various methods:

Client ID / Secret (most common and preferred)
JWT signed with client secret
JWT signed with a private key.

Finally, the customer is also required to include the following claims in the JWT created by their Identity Provider (IdP):

first_name: claim name for the user's first name
last_name: claim name for the user's last name
email: claim for the user's email address

Security Considerations

Any confidential, private, or sensitive information should be exchanged via secure and trusted communication channels to protect your privacy and security.

Public Keys: Make sure the public keys that are shared in the SAML metadata are stored and transported securely.
Assertion Response Document: Keep the assertion response document, especially the Subject NameID, secure to prevent unauthorized access or identity theft.
SSO Login/logout URLs: The URLs involved in the login/logout process are significant access points to your organisation's SSO application. It's critical to ensure they are correctly pointed to secured and functional endpoints at your Identity Provider (IdP).
User information: Handling the arguments in the assertion response document requires great care. The user's first name, last name, and email are all personally identifiable information. Make sure these details are gathered, stored, and transmitted in compliance with data privacy regulations such as GDPR.

Troubleshooting

If the users in your organisation experience difficulties in logging in using the organisation's IdP, please verify first that the error isn't on your IdP's end. Then, double-check the accuracy of the data contained in the XML file and assertion response document. If the problem persists, please contact Omilia's support team for further assistance.

Ensure that the data related to the SSO login/logout URLs and public keys in the XML file and assertion response document are up-to-date in line with your IdP. If there are any changes, please communicate with Omilia's Customer Support as soon as possible and provide the updated files.

FAQ on Specifications

What are the third-party providers supported by omAccounts for SAML v2.0 federation?

omAccounts supports several external providers for SAML v2.0 federation including Ping Fed, PingOne, Okta, Keycloak and so on.

Can SSO be initiated by either IdP or SP?

Yes, omAccounts supports both IdP initiated and Service Provider (SP) initiated SSO processes.

Does omAccounts support SAML HTTP Artifact bindings?

No, at present, SAML HTTP Artifact bindings are not supported in omAccounts.

Is single logout supported by omAccounts?

Yes, omAccounts supports the Single logout function. This means a user can sign out from all sessions with a single action.

Does omAccounts support auto provisioning?

Yes, omAccounts does support auto provisioning. This feature automatically creates and manages user accounts.

How is user provisioning handled in omAccounts?

In omAccounts, pre-provisioning and de-provisioning of user accounts need to be managed manually. Pre-provisioning involves creating a user's account prior to their first login, and de-provisioning refers to the process of deleting, suspending or archiving user accounts when they are no longer needed or when a user leaves the organization.