Integrate Sign In Pages for Passwordless Authentication

Sign In Pages can be integrated with SecureAuth for passwordless authentication of users stored in Identity Pools. To integrate your login page, you can use either the authorization code flow or the resource owner password credentials flow.

Prerequisites

Identity Pool configured for passwordless authentication
Client application registered in the System Workspace for your tenant for the purpose of minting tokens for the authentication code generation.
A client application connected to the workspace where you did connect the Identity Pool of the users you are going to authenticate.

Generate Authentication Codes

For authentication using Magic Links or Verification Codes, you need to be able to generate authentication codes using SecureAuth Generate Code of Specific Type API.

Call the SecureAuth OAuth 2.0 Token Endpoint for the client application you connected to the System Workspace of your tenant.

You need a token with the identity_self_registration scope.

Sample CURL request:

curl -X POST https://$TENANT_ID.$REGION_ID.authz.cloudentity.io/$TENANT_ID/system/oauth2/token \
--header "Content-Type: application/x-www-form-urlencoded" \
--data-raw "grant_type=client_credentials&client_id=$CLIENT_ID&client_secret=$CLIENT_SECRET&scope=identity_self_registration"

Call the Generate Code of Specific Type API requesting a code of authentication type.
Sample request:
```
curl -k -X POST https://$TENANT_ID.$REGION_ID.authz.cloudentity.io/api/identity/$TENANT_ID/system/pools/$IDENTITY_POOL_ID/user/code/generate \
--header "Authorization: Bearer $AT" \
--data '{
"address": "johndoe@example.com",
"type": "authentication"
}'
```
See that the request contains the identifier of the Identity Pool the user for whom you are generating the code is registered within. You also provide this user's email address to indicate for who do you generate the authentication code.
Sample response:
```
{"extended_code":"NjgzM2I5Yjk5MDg3NDBiMmIxYzY4NjA4MDU0YzE0Nzc6NDY1NTkzMjQ","code":"46559324"}
```

User Authentication in Authorization Code Flow

Login pages that integrate with SecureAuth can use the OAuth authorization code flow with passwordless authentication. When this method is used, client registered with SecureAuth can provide the user with an authentication OTP either used as a verification code or as part of a Magic Link.. When the client starts the authorization flow on behalf of the user, it passes the OTP in the authentication_code parameter in a request to the /authorize endpoint, which is a sign for SecureAuth to skip user authentication in the flow.

Magic Links or Verification Codes

For the authorization code flow, we strongly advise choosing Magic Links for authentication rather than authenticating users with verification codes. The latter can be still used for custom authentication flows, but, in general, is considered less user friendly.

When client apps generate authentication codes, they receive a code and an extended_code. The code length can be configured, but it is a plain text. The extended_code is a URL-safe base64-encoded user identifier and the verification code. Extended codes make it possible for SecureAuth to know for which users the authorization flow happens - since, unlike in ROPC flow, there is no username present in the /authorize request. Because of that, SecureAuth expects the extended code as a value of the authentication_code parameter when clients request authorization. Making the user type in an extended code can be considered not optimal in terms of the user experience - therefore, it is much better to add the extended code to a link and use the Magic Links authentication.

Magic Link Authentication in Authorization Code Flow: Recommended

The user provides their email/username in your custom login page and selects the Request Code button.
The client application of your sign in page, sends a request to the SecureAuth Generate Code Of Specific Type API.
The request must contain the type query parameter set to authentication.
SecureAuth provides the code and extended_code parameters in the request response.
The sign in page must now provide the user with an URL that contains the extended_code as its query parameter over the email/text message.
User selects the link.
Sign in page's client application sends a request to the SecureAuth OAuth 2.0 Authorize Endpoint.
The request must contain the authentication_code parameter with the value set to the value of the extended_code parameter the client received in the third step as a response the Generate Code Of Specific Type API call. You use the extended code as it is tied to this particular user trying to authenticate and there is no user identifier provided as part of the request to the /authorize API.
Example request:
```
curl --location \
--get \
--url "https://$TENANT_ID.$REGION_ID.authz.cloudentity.io/$TENANT_ID/$WORKSPACE_ID/oauth2/authorize" \
--data-urlencode "response_type=code" \
--data-urlencode "client_id=$CLIENT_ID" \
--data-urlencode "authentication_code=$extended_code"
```
SecureAuth verifies the code and skips usual user authentication that takes place when clients call the /authorize endpoint.
The user is redirected to the consent page.
The user provides their consent.
SecureAuth redirects the user to the callback URL registered for the client application and provides the authorization code as part of the URL.

The client application may now request tokens from SecureAuth on behalf of the user and access the resources if the token is granted.

Verification Code Authentication in Authorization Code Flow

The user provides their email in your custom login page and selects the Request Code button.
The client application of your sign in page, sends a request to the SecureAuth Generate Code Of Specific Type API.
The request must contain the type query parameter set to authentication.
SecureAuth provides the code and extended_code parameters in the request response.
The sign in page must now provide the user with the value of the code parameter over the email/text message.
User enters their verification code on the sign in page.
Sign in page's client application sends a request to the SecureAuth OAuth 2.0 Authorize Endpoint.
The request must contain the authentication_code parameter with the value set to the value of the extended_code parameter the client received in the third step as a response the Generate Code Of Specific Type API call. You use the extended code as it is tied to this particular user trying to authenticate.
Sample call to the authorize endpoint with SecureAuth as an authorization server including authentication code:
```
curl --location \
--get \
--url "https://$TENANT_ID.$REGION_ID.authz.cloudentity.io/$TENANT_ID/$WORKSPACE_ID/oauth2/authorize" \
--data-urlencode "response_type=code" \
--data-urlencode "client_id=$CLIENT_ID" \
--data-urlencode "authentication_code=$extended_code"
```
SecureAuth verifies the code and skips usual user authentication that takes place when clients call the /authorize endpoint.
The user is redirected to the consent page.
The user provides their consent.
SecureAuth redirects the user to the callback URL registered for the client application and provides the authorization code as part of the URL.

The client application may now request tokens from SecureAuth on behalf of the user and access the resources if the token is granted.

User Authentication in Resource Owner Password Credentials (ROPC) Flow

Login pages that integrate with SecureAuth can use the Resource Owner Password Credentials Flow with passwordless authentication. When this method is used, client registered with SecureAuth can provide the user with an authentication OTP either used as a verification code or as part of a Magic Link. Either after the user selects a magic link or after the user provides their code,the client provides it as a part of the call to the OAuth 2.0 Token Endpoint.

Remember

Please, note that, in general, the ROPC flow is considered less secure than Authorization Code Flow and should be used only by trusted applications.

Verification Code Authentication in ROPC Flow

The user provides their email in your custom login page and selects the Request Code button.
The client application of your sign in page, sends a request to the SecureAuth Generate Code Of Specific Type API.
The request must contain the type query parameter set to authentication.
SecureAuth provides the code and extended_code parameters in the request response.
The sign in page must now provide the user with the value of the code parameter over the email/text message.
User enters their verification code on the sign in page.
The client requests token by calling the token endpoint.
The password query parameter must be set to either:
- Value of the code parameter which is less secure due to the code being in plain text and easier to guess.
- Value of the extended_code parameter which is safer due to the base64 encoding of the user identifier and actual authentication code.
The username parameter can be set to either the username or email of the user.
Sample request to the /token endpoint with client authentication method set to client secret post:
```
curl -X POST https://$TENANT_ID.$REGION_ID.authz.cloudentity.io/$TENANT_ID/$WORKSPACE_ID/oauth2/token \                                                                                   ~/repo
--header 'Content-Type: application/x-www-form-urlencoded' \
-d grant_type=password \
-d client_id=$CLIENT_ID \
-d client_secret=$CLIENT_SECRET \
-d password=$EXTENDED_CODE \
-d username=johndoe@example.com
```
Authorization server validates user credentials.
Authorization server returns the access and ID tokens.
The client application may now request access to resources on behalf of the user using the access token it got from SecureAuth.

Magic Link Authentication in ROPC Flow

The user provides their email/username in your custom login page and selects the Request Code button.
The client application of your sign in page, sends a request to the SecureAuth Generate Code Of Specific Type API.
The request must contain the type query parameter set to authentication.
SecureAuth provides the code and extended_code parameters in the request response.
The sign in page must now provide the user with an URL that contains the extended_code as its query parameter over the email/text message.
User selects the link.
The client requests token by calling the token endpoint.
The password query parameter must be set to either:
- Value of the code parameter which is less secure due to the code being in plain text and easier to guess.
- Value of the extended_code parameter which is safer due to the base64 encoding of the user identifier and actual authentication code.
The username parameter can be set to either the username or email of the user.
Sample request to the /token endpoint with client authentication method set to client secret post:
```
curl -X POST https://$TENANT_ID.$REGION_ID.authz.cloudentity.io/$TENANT_ID/$WORKSPACE_ID/oauth2/token \                                                                                   ~/repo
--header 'Content-Type: application/x-www-form-urlencoded' \
-d grant_type=password \
-d client_id=$CLIENT_ID \
-d client_secret=$CLIENT_SECRET \
-d password=$EXTENDED_CODE \
-d username=johndoe@example.com
```
Authorization server validates user credentials.
Authorization server returns the access and ID tokens.
The client application may now request access to resources on behalf of the user using the access token it got from SecureAuth.

In this section: