Configure a Custom IDP Connection (External)
The User Service allows Mosaic customers to enable user authentication via Managed and Custom IDPs. This document describes the steps to configure a Custom IDP for end-user authentication.
Any ID Provider that supports the OAuth 2.0 protocol can be configured as a Custom IDP Connection. In this guide, we will set use GitHub as the ID Provider and configure it to be used within the Mosaic User service.
The User Service can be enabled and configured for any environment through the Environment Administration Portal.
Figure 1 shows you the configuration options for User service in the Service Configuration station.
A custom IDP is an ID Provider which supports either Open ID Connect or OAuth 2.0 protocols but not supported through Mosaic User Service by default.
The IDPs that are supported by Mosaic User Service are
These are called Managed ID Providers, and how a Managed IDP can be configured is explained here.
To setup a Custom IDP Connection, navigate to the IDP Connections station from the User Service Configuration Options (Figure 1), and click on the New button on the top right.
You will get a screen similar to the following. Pick Other (Custom) from the drop down menu to configure a custom IDP. Then give it a Provider Name and a Title. In this article, we’ll setup GitHub as the Custom ID Provider.
After filling out the required information, click on proceed. This will create a new IDP Connection with the new ID Provider and navigate you to the IDP Connection Details station. It will look similar to the below screenshot.
As you can notice, the information such as the Authorization Endpoint URL, Token Endpoint URL or Discovery Document URL in case of a OIDC compatible ID Provider are all empty. The administrator must manually configure all required details. After the configuration for GitHub it would look like below.
Implementing a User Info Retrieval Webhook is mandatory for Custom IDPs because Mosaic User Service does not know how to decode the information sent by the IDP. The access token generated by the User Service will be passed, and the webhook should implement the logic to accurately decode the user information sent by the IDP and embed it to the user token, and respond back to the user service with it.
To complete the IDP Connection configuration, set the status to Enabled.
The next step would be to define an Application and connect the IDP Connection we created in the previous section.
Click on Applications tile in the Service Configuration station. (Figure 1) You will be navigated to the Applications Explorer. Click on the New button on the top right corner.
You will be navigated to the New Application station.
Give a name for your application and click on Proceed.
You will be navigated to the Application Details station which will contain details related to the application you created. A few fields are required to be filled here to make the Application usable.
Allowed Origins - The base URI from which your end-user application will be making requests for the User Service Authentication API must be listed here. This is for the purpose of whitelisting these URIs from CORS policies. Only the base URI must be added in the format <scheme>://<full-domain>. For example: https://app.ottstream.com.
Allowed Proxy URLs - The User Service Authentication API will be running behind a proxy (i.e. https://id.ottstream.com) such that the top-level domain name matches that of the 'Allowed Origins' mentioned above. These Proxy URLs must be whitelisted in order for requests to pass-through.
After setting the Allowed Origins and Allowed Proxy URLs, set the status of the Application to Enabled. We do not need the Application Key and Access Token Enrichment Token at this point.
Now that we have an Application configured, the next task is to connect the IDP connection we created in an above section to the Application.
For this, click on the Manage IDP Connections action on the top of the actions list. This will take you to the Manage IDP Connections station. It will have an empty table with a plus sign (+).
Click on the row, and it you will be navigated back to the Manage IDP Connections station with the new row added.
All required configuration and data set up that needs to be done in the Environment Administration Portal is now complete.