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:
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
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 uselogin_id
from query parameters asid
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.
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
andclient_secret
to issue the access token.Note
Make sure the client credentials grant flow is enabled.
Replace
PUT-YOUR-ACCESS-TOKEN-HERE
with the access token issued by the admin authorization server.
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
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.
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 detailsPUT
/api/system/{tenant_id}/logins/{login_id}/accept
for accepting the login requestPUT
/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
Go to the SecureAuth administrator portal in your browser and log in with your credentials.
From Workspace Directory, select a workspace that you want to enter.
Add Identity Provider
Go to Identities.
Click ADD IDENTITY to create a new IDP.
In the Create Connection page, select Custom IDP, enter the name for your IDP, and click Next.
In the Register Custom IDP view, enter the login URL for your IDP that you have integrated with SecureAuth, and select Save.
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:
Make sure that you are in the Configuration view and select Advanced settings at the bottom.
Select Authentication Method Reference from the drop down menu.
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:
Select the Attributes view.
Click the Add attribute button.
In the Add attribute window, specify the following features:
Source (ID token, Access token, User object, Root)
Display name
Variable name
Data type
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:
Select the Mappings view.
Click the Add mapping button.
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
Use the URL of your existing workspace and select Demo application.
In the displayed Demo application window, click LOG IN TO DEMO APP.
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.
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
Use the URL of your existing workspace and select your SecureAuth developer portal to access it.
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.