Trusted Device Authentication

A trusted device.

Trusted device authentication uses device credentials to verify that high-risk actions are performed on authorized devices. This method leverages public key cryptography where private keys are securely stored on the user’s device.
This method uses the Device SDK to sign a challenge with the user’s device credentials.Device enrollment required: Users must have a device that they can use to complete the challenge. This can be done by adding device credentials via our mobile SDK.

​
Sequence diagram

​
Grab your Authsignal credentials

Head to Settings and grab your Tenant ID, API URL and API secret key. Add them as environment variables in your project: 
AUTHSIGNAL_API_URL=your_region_api_url
AUTHSIGNAL_TENANT_ID=your_tenant_id
AUTHSIGNAL_SECRET_KEY=your_secret_key

​
Implementation

​
1. Backend – Track an action (optional)

Skip to step 2 if you don’t need to run rules on the action for adaptive MFA or want to associate additional data with the action through the custom data field. Track an action from your backend using our Server SDK or Server API. Return the state and token to your mobile app. On your mobile app, check the state parameter to conditionally challenge the user. If the state is CHALLENGE_REQUIRED, call the setToken method to set the token. 
if (response.state === "CHALLENGE_REQUIRED") {
  await authsignal.device.setToken(response.token);
} else if (response.state === "ALLOW") {
  // Allow the user to continue
} else if (response.state === "BLOCK") {
  // Block the user from signing in
}
The ALLOW state only works if you are building your own challenge dialog. If you have created device credentials using the userAuthenticationRequired flag, you are restricted to using the CHALLENGE_REQUIRED and BLOCK states. To learn more, see our Device SDK documentation.

​
2. Mobile App – Verify the device

Use our Mobile SDK to verify the device. If the device credentials were created without using the userAuthenticationRequired flag, you may optionally present your own challenge dialog such as a PIN screen prior to calling the verify method. If the device credentials were created using the userAuthenticationRequired flag, the OS will present the challenge dialog upon calling the verify method. To learn more, see our Device SDK documentation. 
await authsignal.device.verify()

​
3. Backend – Validate the challenge

Note that if you did not track an action in step 1, you will need to pass the action to the validate challenge API. This allows us to associate the challenge with the action for analytics.
Once the user has completed the challenge, pass the token returned from the previous step to your backend. Your backend should call the validate challenge API to validate the challenge. 
const request = {
  token: "eyJhbGciOiJ...",
};

const response = await authsignal.validateChallenge(request);

if (response.state === "CHALLENGE_SUCCEEDED") {
  // The user completed the challenge successfully
  // Proceed with authenticated action or integrate with IdP to create authenticated session
} else {
  // The user did not complete the challenge successfully
}

​
Next steps

  • Push notification - Implement push notification authentication
  • QR code - Implement QR code authentication
  • Passkeys - Offer the most secure and user-friendly passwordless authentication
  • Adaptive MFA - Set up smart rules to trigger authentication based on risk