How-tos

Setting Up Intelligent Identity Source Selection for Users

With the Cloudentity platform, you can add Extensions to selectively filter identity sources displayed to the end user during login flows. You can, for example, narrow the list of available identity sources based on the contextual information. Learn how to improve the user experience with Extensions that are placed at the IDP discovery Extension point.

About Modifying Login Flow

With Cloudentity Extensions, developers can narrow down or suggest the list of identity sources presented to the end users during the authorization flow. When the user needs to authenticate and there is a large number of identity sources available, it is best to provide them with identity sources that are tailored to the user and their session context. With Cloudentity Extensions, you can:

  • Display selected identity sources based on a specific email domain

  • Display selected identity sources tied to a specific client application

  • Display selected identity sources based on an incoming IP address

  • Display selected identity sources based on the provided username of the end user

Learn more

You can learn more about Cloudentity Extensions and modifying the login flow by reading the Extending Cloudentity Capabilities.

Available Inputs

When creating Extension scripts that modify the login flow for the end users, developers may use the following input objects:

  • request - to have access to the request information such as headers or query parameters

    Sample input:

                    
                        
      {
        "request": {
            "headers": {
              "Content-Type": [
                "application/json"
              ],
              "Testing": [
                "value"
              ]
            },
            "query_params": {
              "limit": [
                "1000"
              ],
              "login_hint": [
                "myuser"
              ]
            }
          }
      }
      
  • client - to have access to information about the client application that initiated the authorization flow

    Client schema:

                    
                        
      {
        "application_type": "web",
        "application_types": [
          "single_page",
          "server_web",
          "mobile_desktop",
          "service",
          "legacy",
          "dcr"
        ],
        "audience": [
          "client_id"
        ],
        "authorization_server_id": "default",
        "backchannel_authentication_request_signing_alg": "string",
        "backchannel_client_notification_endpoint": "string",
        "backchannel_token_delivery_mode": "string",
        "backchannel_user_code_parameter": true,
        "client_id": "string",
        "client_id_issued_at": 0,
        "client_name": "My app",
        "client_secret": "stringstringstringstringstringst",
        "client_secret_expires_at": 0,
        "client_uri": "string",
        "description": "string",
        "developer_id": "string",
        "developer_metadata": {
          "property1": {},
          "property2": {}
        },
        "dynamically_registered": true,
        "grant_types": [
          "password",
          "refresh_token",
          "client_credentials",
          "implicit",
          "authorization_code"
        ],
        "hashed_rotated_secrets": [
          "string"
        ],
        "hashed_secret": "string",
        "id_token_encrypted_response_alg": "RSA-OAEP",
        "id_token_encrypted_response_enc": "A256GCM",
        "id_token_signed_response_alg": "ES256",
        "jwks": {
          "keys": []
        },
        "jwks_uri": "string",
        "logo_uri": "string",
        "metadata": {
          "property1": {},
          "property2": {}
        },
        "organisation_id": "5647fe90-f6bc-11eb-9a03-0242ac130003",
        "policy_uri": "string",
        "privacy": {
          "scopes": {
            "property1": {
              "pii_categories": [
                {
                  "name": "HIPAA"
                }
              ],
              "purpose": "string"
            },
            "property2": {
              "pii_categories": [
                {
                  "name": "HIPAA"
                }
              ],
              "purpose": "string"
            }
          }
        },
        "redirect_uris": [
          "https://example.com/callback"
        ],
        "request_object_signing_alg": "none",
        "request_uris": [
          "string"
        ],
        "require_pushed_authorization_requests": true,
        "response_types": [
          "token",
          "id_token",
          "code"
        ],
        "rotated_secrets": [
          "string"
        ],
        "scope": "email offline_access openid",
        "scopes": [
          "email",
          "offline_access",
          "openid"
        ],
        "sector_identifier_uri": "https://api.jsonbin.io/b/5db6ef08688fed59d2841f1e",
        "software_id": "string",
        "software_statement": "string",
        "software_version": "string",
        "subject_type": "public",
        "system": true,
        "tenant_id": "string",
        "tls_client_auth_san_dns": "string",
        "tls_client_auth_san_email": "string",
        "tls_client_auth_san_ip": "string",
        "tls_client_auth_san_uri": "string",
        "tls_client_auth_subject_dn": "string",
        "tls_client_certificate_bound_access_tokens": true,
        "token_endpoint_auth_method": "client_secret_basic",
        "token_endpoint_auth_signing_alg": "none",
        "tos_uri": "string",
        "trusted": true,
        "userinfo_signed_response_alg": "none"
      }
      
  • idps - to have access to the list of identity sources

    Sample input:

                    
                        
      {
      "idps": [
          {
            "id": "c9h7eug70d3tqc8c272g",
            "tenant_id": "tenantID",
            "authorization_server_id": "serverID",
            "name": "Default",
            "method": "static"
          },
          {
            "id": "c0h7eug82d3tqc8c270g",
            "tenant_id": "tenantID",
            "authorization_server_id": "serverID",
            "name": "OpenID",
            "method": "oidc"
          }
        ]
      }
      

Tip

You can see the available input example in the Extensions editor:

Available input example

Available Output

Extensions modifying the login flow for end users produce one output object:

  • idps_ids - an array of identity sources returned by the Extension script. In other words, this object is a list of identity sources that are available for the end user to be used for authentication.

Example Output

{
  "idps_ids": [
    "c9h7eug70d3tqc8c272g",
    "70d3tqc8c272gc9h7eug"
  ]
}

Modify Login Flow for End Users

  1. Create your Extension.

    When creating the Extension, use available inputs, outputs, and dependencies.

    Creating Extensions

    For instructions on how to create Cloudentity Extensions, test using test mode, and to learn what are recommended best practices when working with Extensions, see the Creating and Testing Extensions How-to article.

    To check how Extensions modifying the login flow for end users work and look, see the Sample Script section.

  2. Go to Identity Data > Identity Providers and select the Discovery tab.

    1. For the radio buttons, select Script.

    2. Assign the Extension that modifies the login flow.

    Assigning Extension

  3. Verify the login flow using Sandbox IDP and Demo Application/API

Sample Script

module.exports = async function (context) {
  var idpIDs = [];
  for (var i = 0; i < context.idps.length; i++) {
    if (
      context.client.client_id === "default-demo" &&
      context.idps[i].name === "Default" &&
      context.request.headers["Testing"].includes("value") &&
      context.request.query_params["login_hint"].includes("myuser")
    ) {
      idpIDs.push(context.idps[i].id);
    }
  }
  return {
    idps_ids: idpIDs,
  };
};

In the Extension script above, you can see a for loop that goes through the list of all identity sources available within the tenant. If an identity source matches the criteria, for example, the request to the /authorize endpoint had the login_hint query parameter included with the value set to myuser, identifier of such identity source is added to the list of returned identity sources (idps_ids). It means that when the user is going to authenticate, only the identity sources returned by the script are available to be used.

Verify Modified Login Flow

Besides testing the Extension by running it in the Test Mode, it is possible to test it with the Demo Application.

I Do Not Have Demo Application

If the Demo Application is not available within your workspace, do not worry! You can test your modified login flow using any application connected to the Cloudentity platform and your workspace. Enable the OAuth Authorization Code Grant Type in your client application configuration and call the OAuth 2.0 Authorize Endpoint for your workspace. During the flow, you will need to authenticate with your identity source and it should provide you with a list of identity sources returned by your Extension script.

Prerequisites

  1. Identity sources of your choice are connected to the workspace where the Extension Script is available.

  2. Extension script is enabled in the Discovery tab of the Identity Providers view.

Test Login Flow

  1. Within your workspace, navigate to Dashboards > Overview and select the Launch portal button for the Demo Application (in the Connected portals panel).

    Optionally, you can access the Demo Application under the https://{tid}.authz.cloudentity.io/{tid}/{aid}/demo URL where the {tid} variable stands for your tenant identifier and the aid variable stands for your workspace (authorization server) identifier.

  2. Select LOGIN TO DEMO APP.

Result

The list of all identity sources available for the workspace should be filtered out and only the identity sources that were returned by the Extension Script should be available for use.

Updated: Jul 11, 2022