How-tos

6 mins read

Set Up Custom Identity Source for Authentication

Instructions on how to connect your authentication providers that are neither SAML/OIDC compliant to Cloudentity

Process Overview

Cloudentity allows to connect your authentication providers that are neither SAML/OIDC compliant by integrating it as a custom Identity Provider with Cloudentity and with the use of Cloudentity APIs.

In case you are looking to migrate away from legacy or existing home grown solutions, Cloudentity offers a highly scalable and customizable identity provider functionality termed Identity pools that can be configured and used out of the box. With use of Cloudentity extension points, you may still be able to devise a seamless authentication journey for your users. Our recommendation would be to move towards usage of the Identity pool model but in case that’s not feasible consider below integration pattern to integrate with your authentication provider.

Integrating with Custom Identity Provider

For this integration pattern, your authentication provider must be able to handle redirects from Cloudentity and also submit back information to Cloudentity once the authentication process is complete.

The process of user authentication, when a custom IDP is used, works as follows:

Authentication and consent approval flow

  1. The OAuth 2.0 client initiates the authorize code or implicit flow (1a) and gets redirected by Cloudentity to the custom login page (1b).

    GET https://authorization.cloudentity.com:8443/default/default/oauth2/authorize
     ?client_id=my-client
     &redirect_uri=https://authorization.cloudentity.com:8443/default/default/demo
     &response_type=code
     &state=ed92md193j
     &nonce=d8dfj19s

> Status: 302
> Location: https://demo.cloudentity.com/login?login_id=43579ea6860f6&login_state=29n93

  2. The custom login page, once the user has successfully logged in (2a), calls Cloudentity to accept the login request and redirects the user to the returned redirect URL (2b).

    Note

    The custom login page must pass login_state from query parameters to accept the login request body and use login_id from query parameters as id in the accept login request path.

    curl -X POST "https://authorization.cloudentity.com:8443/api/system/default/logins/43579ea6860f6/accept" \
  -d '{ "auth_time": "2019-11-20T08:20:46.294Z", "subject": "user@example.com", "login_state": "29n93"}' \
  -H "Authorization: Bearer PUT-YOUR-ACCESS-TOKEN-HERE"

> {"redirect_to": "https://authorization.cloudentity.com:8443/default/default/oauth2/authorize?..."}

    The accept login request endpoint requires authentication.

    2.1. In the admin authorization server of the same tenant that you are building the custom login page for, create a client and use its client_id and client_secret to issue the access token.

    Note

    Make sure the client credentials grant flow is enabled.

    2.2. Replace PUT-YOUR-ACCESS-TOKEN-HERE with the access token issued by the admin authorization server.

  3. Cloudentity checks if the login request has been accepted and redirects the user to the Cloudentity consent page.

    GET https://authorization.cloudentity.com:8443/default/default/oauth2/authorize
  ?client_id=my-client
  &login_verified=true
  &nonce=d8dfj19s
  &redirect_uri=https://authorization.cloudentity.com:8443/default/default/demo
  &response_type=code
  &login_id=43579ea6860f6
  &login_state=9d2k5
  &state=123456789

> Status: 302
> Location: https://authorization.cloudentity.com:8443/default/default/scope-grant?login_id=43579ea6860f6&login_state=7sj23

  4. The Cloudentity consent page asks the user to grant requested scopes. Upon approval, it accepts the consent request and redirects the user to the returned redirect URL.

  5. Cloudentity checks if both login and consent requests have been approved. If so, it issues the authorization code (or access and ID tokens in the case of the implicit grant flow) and redirects the user to the redirect URL.

    GET https://authorization.cloudentity.com:8443/default/default/oauth2/authorize
  ?client_id=my-client
  &consent_verified=true
  &nonce=d8dfj19s
  &redirect_uri=https://authorization.cloudentity.com:8443/default/default/demo
  &response_type=code
  &login_id=43579ea6860f6
  &login_state=7sj23
  &state=123456789

> Status: 302
> Location: https://authorization.cloudentity.com:8443/default/default/demo?code=...

APIs

You can find all Cloudentity login APIs here.

There are three internal-only APIs provided by administrative Cloudentity endpoints that can be used in the authentication and consent approval flow:

  • GET /api/system/{tenant_id}/logins/{login_id} for getting login request details

  • PUT /api/system/{tenant_id}/logins/{login_id}/accept for accepting the login request

  • PUT /api/system/{tenant_id}/logins/{login_id}/reject for rejecting the login request

login_id is provided as a query parameter when the user gets redirected to the login or consent page from the Cloudentity authorize endpoint.

The authorize endpoint is protected using CSRF cookies. If cookies that are associated with a given login are missing, the authorization code (or token) is not issued.

Implementation

The custom login application(idenitty provider) must provide/expose an endpoint that can be used for redirect by Cloudentity.

The application must read login_id from query parameters within the redirect request.

The request can be approved immediately if the user has already been logged in. Otherwise, user must be taken through the regular authentication process.

The custom login application must submit the result of authentication process as an API call(accept or reject login endpoints) to Cloudentity .

The custom login application also must redirect the user to the URL returned from accept or reject login endpoints.

Configuration

You need to update the authorization server login_url attribute.

Learn more

See APIs for more information.

Connecting Custom IDPs to Cloudentity

Prerequisites

Select Workspace

  1. Go to the Cloudentity administrator portal in your browser and log in with your credentials.

  2. From Workspace Directory, select a workspace that you want to enter.

Add Identity Provider

  1. Go to Identities.

  2. Click ADD IDENTITY to create a new IDP.

  3. In the Create Connection page, select Custom IDP, enter the name for your IDP, and click Next.

  4. In the Register Custom IDP view, enter the login URL for your IDP that you have integrated with Cloudentity, and select Save.

Result

You have enabled your users to connect to Cloudentity using your custom login page.

Configure Advanced Settings

Go to Identities in the left sidebar and select your IDP from the list of available IDP connections.

Configure IDP settings

To configure your new IDP advanced settings:

  1. Make sure that you are in the Configuration view and select Advanced settings at the bottom.

  2. Select Authentication Method Reference from the dropdown menu.

  3. Select Save.

Configure Authentication Context Attributes

You can configure authentication context attribues for your custom IDP.

Read More

To know more about authentication context attributes, see the authentication context documentation.

To add an attribute:

  1. Select the Attributes view.

  2. Click the Add attribute button.

  3. In the Add attribute window, specify the following features:

    • Source (ID token, Access token, User object, Root)
    • Display name
    • Variable name
    • Data type

  4. Click Next.

Configure Mappings of the Attributes

You can map your IDP attributes between your custom IDP and the authentication context.

Read More

To know more about mapping authentication context attributes, see the mapping documentation.

To add a mapping:

  1. Select the Mappings view.

  2. Click the Add mapping button.

  3. Provide the following information on:

    • Source name
    • Target name

Enable Stateful Authorization

This step is optional.

To have the user’s data cached in Cloudentity and avoid re-authenticating within one use’s session, follow the instruction in Enable the stateful authZ in Cloudentity.

User’s Test

Test your connection between the Cloudentity and your custom Identity Provider as a user.

Prerequisites

Your provider is configured as a user-authentication method by your administrator.

Test

  1. Use the URL of your existing workspace and select Demo application.

  2. In the displayed Demo application window, click LOG IN TO DEMO APP.

  3. Select your configured IDP (if you have multiple IDPs) and, next, authenticate in the IDP.

Result

Cloudentity displays the consent page that lists data scopes to be shared with the application. When you proceed to the application (ALLOW ACCESS), the PII data coming from the IDP is delivered through the access token and the ID token generated by Cloudentity.

Read More

For information on granting and managing Cloudentity consents, see Cloudentity OAuth consents.

Developer’s Test

Test your connection between the Cloudentity and your custom Identity Provider as a user.

Prerequisites

Your provider is configured as a developer-authentication method by your administrator. To register your IDP for the developer, follow the instructions in Configure IDP, this time selecting the Developer workspace in step 2.

Test

  1. Use the URL of your existing workspace and select your Cloudentity developer portal to access it.

  2. Log in to your account by entering your login credentials and selecting LOG IN.

Result

You are logged in to the Cloudentity developer portal with the newly-configured IDP.

Updated: Apr 14, 2023