Passwordless | Sign in with passcodes

[coldlink]

What does this change?

Following on from passcodes for registration and reset password, the next step including an option to sign in via passcodes too.

This functionality has been added behind the usePasscodeSignIn query parameter flag, so we're able to test this behaviour in production, and implement and UI/UX improvements before we go fully live with it to all users.

User status behaviour

This PR implements this behaviour for all user statuses described below:

Status	Behaviour
ACTIVE - with email authenticator	Use IDX API to send email factor challenge email.
ACTIVE - with only password authenticator	Set placeholder password. Send email factor verification email.
non-ACTIVE	Deactive then reactivate user and set placeholder password to force user into ACTIVE state. Then send the email factor challenge/verification email depending on which ACTIVE the user ended up in.
non-existent	Don't send an email, but still show passcode input page.

IDX API calls

The general IDX API flow for users to sign in via passcodes for users in the ACTIVE state is as follows:

1. Call the POST /oauth2/<custom_auth_server>/v1/interact endpoint
   • Same parameters auth an authorization code flow call (/authorize endpoint)
     • We only want to allow the profile application to do this (this is the gateway one)
     • And maybe the sample application for testing
   • This returns a single key in the response body - interaction_handle
2. Call the POST /idp/idx/introspect endpoint with the interaction_handle in the post body
   • This returns a number of things in the response body, effectively all the information needed to generate a login form
   • The only thing we need from this is the stateHandle key, which identifies the current authentication request
     • There is an expiresAt key here, which initially is set to 2 hours in the future
     • The other things here include information on how to generate a login form, and the social options (and links) available to do this
   • You can also call this endpoint at any other time with the stateHandle in the body to get the current transaction state to see if it’s valid
3. Call the POST /idp/idx/identify endpoint with the email, rememberMe=true, and stateHandle in the body
   • This returns an object very similar to the /introspect endpoint but with different things
     • The expiresAt key has now changed to 5 mins
   • The remediation key has everything in it relating to how to resolve the current request
   • This also lists which authenticators the user has available, and lets us identify the users in each given state
     • If there an email authenticator, then the user can be sent a passcode to sign in
     • If there is only a password authenticator, then we have to set a placeholder password for the user, and send them an email verifcation code

At this point, depending on if the user has the email authenticator or not the steps become different

For users who have the email authenticator it's as follows.

4. Call POST /idp/idx/challenge with stateHandle authenticator:methodType=email,id=email_authenticator_id
   • This sends the user an email with the passcode
   • The remediation step now says we need to enter a passcode
   • expiresAt has updated to 30 minutes
5. Once the user types the passcode, call the POST /idp/idx/challenge/answer with stateHandle, credentials:passcode=<passcode> in body
   • This authenticates the code, if valid returns a 200 with the user object inside the response and no remediation
   • The user has authenticated at this point.
6. Redirect the user to /login/token/redirect?stateToken=${stateHandle.split('~')[0]}
   • This sets the Okta global session idx cookie
   • The stateToken is the stateHandle everything before the first ~ character
   • This will redirect the user to the callback defined in the interact call at the start and completes the interaction code flow, and eventually the user back to where they were going

For users who only have the password authenticator it's as follows

4. Use the dangerouslySetPlaceholderPassword method to set a placeholder password for the user
5. Call POST /idp/idx/challenge with stateHandle authenticator:methodType=password,id=password_authenticator_id
   • This starts the password authenticator challenge
6. Use the placeholder password, call the POST /idp/idx/challenge/answer with stateHandle, credentials:passcode=<password> in body
   • The remediation will suggest. we need to enroll in the email authenticator
7. Call POST /idp/idx/credential/enroll with stateHandle authenticator:methodType=email,id=email_authenticator_id
   • This sends the user a verification email with a passcode
8. Once the user types the passcode, call the POST /idp/idx/challenge/answer with stateHandle, credentials:passcode=<passcode> in body
   • This authenticates the code, if valid returns a 200 with the user object inside the response and no remediation
   • The user has authenticated at this point.
9. Redirect the user to /login/token/redirect?stateToken=${stateHandle.split('~')[0]}
   • This sets the Okta global session idx cookie
   • The stateToken is the stateHandle everything before the first ~ character
   • This will redirect the user to the callback defined in the interact call at the start and completes the interaction code flow, and eventually the user back to where they were going

For users in a non-ACTIVE state, we use the forceUserIntoActiveState function, which first calls deactivateUser followed by activateUser to get an activation/recovery token. It then sets a placeholder password for the user using the dangerouslySetPlaceholderPasswordUsingRecoveryToken helper, which forces the user into the ACTIVE state. At this point the user will be in one of the above states, so we can call oktaIdxApiSignInPasscodeController to send the user an OTP to sign in.

Current UX

While we attempt to get support regarding improving our UX, the following behaviour is used in order to sign in with passcodes when the flag is used.

Passcode	Password
https://github.com/user-attachments/assets/00092a1a-e2d6-4efe-af0d-f34c6b299f94	https://github.com/user-attachments/assets/2cb4eb3c-c352-4067-baf4-928607f457e7

Tested

• CODE - with the usePasscodeSignIn flag
• CODE - no flag (existing behaviour)
• CODE - with flag, on apps

[github-actions]

Deploy build 10135 of identity:identity-gateway to CODE

All deployment options

• Deploy build 10135 of identity:identity-gateway to CODE
• Deploy parts of build 10135 to CODE by previewing it first
• What's on CODE right now?

---

From guardian/actions-riff-raff.

[akinsola-guardian]

LGTM.