Skip to main content

Set Up Custom Identity Source for Authentication

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

Process Overview

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

In case you are looking to migrate away from legacy or existing home grown solutions, SecureAuth 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 SecureAuth 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 SecureAuth and also submit back information to SecureAuth once the authentication process is complete.

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

Integrating_with_Custom_Identity_Provider.svg

  1. The OAuth 2.0 client initiates the authorize code or implicit flow (1a) and gets redirected by SecureAuth 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 SecureAuth 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.

    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. Replace PUT-YOUR-ACCESS-TOKEN-HERE with the access token issued by the admin authorization server.

  3. SecureAuth checks if the login request has been accepted and redirects the user to the SecureAuth 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 SecureAuth 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. SecureAuth 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 SecureAuth login APIs here.

There are three internal-only APIs provided by administrative SecureAuth 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 SecureAuth 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 SecureAuth.

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 SecureAuth .

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.

See APIs for more information.

Connecting Custom IDPs to SecureAuth

Prerequisites

  • You have already set up your first workspace in SecureAuth.

  • You have already integrated your custom IDP with SecureAuth.

Select Workspace

  1. Go to the SecureAuth 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 SecureAuth, and select Save.

    acp_how-to_connect_custom_url.png

    Result: You have enabled your users to connect to SecureAuth 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 drop down menu.

  3. Select Save.

Configure Authentication Context Attributes

You can configure authentication context attributes for your custom IDP.

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.

    acp_how-to_connect_custom_attributes.png

  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.

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.

    acp_how-to_connect_custom_mappings.png

  3. Provide the following information on:

    • Source name

    • Target name

Enable Stateful Authorization

Note

This step is optional.

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

User's Test

Test your connection between the SecureAuth 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.

    acp_how-to_connect_custom_login_demo_app.png

  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: SecureAuth 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 SecureAuth.

    acp_how-to_connect_azure_user.png

Note

For information on granting and managing SecureAuth consents, see Consents.

Developer's Test

Test your connection between the SecureAuth 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 SecureAuth 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 SecureAuth developer portal with the newly-configured IDP.

    acp_how-to_connect_azure_dev.png
In this section: