Skip to main content
Trusted device authentication
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. The Mobile SDK is used for two key steps:
  1. Registering a mobile device for trusted device authentication by adding a device credential. This step creates a new public/private key pair.
  2. Responding to an authentication request by approving or rejecting a device challenge. This step uses the device’s private key to sign a message which is verified on the server using the public key.

​
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

​
Implementing registration

​
1. Backend - Generate registration token

Track an action (e.g. “addAuthenticator”) to generate a short-lived token which can be used to authorize adding a new authentication method for a user. 
const request = {
  userId: "dc58c6dc-a1fd-4a4f-8e2f-846636dd4833",
  action: "addAuthenticator",
  attributes: {
    scope: "add:authenticators",
  },
};

const response = await authsignal.track(request);

const token = response.token;

​
2. Mobile app - Add device credential

Use the token obtained in step 1 to register a new device credential in the app. 
await authsignal.device.addCredential(token: "eyJhbGciOiJ...")
Device registration should be implemented after login or when the app is launched in an authenticated state. Registration tokens should only ever be generated for authenticated users in order to ensure a strong binding between authentication methods.

​
Implementing authentication

​
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. 
const request = {
  userId: "dc58c6dc-a1fd-4a4f-8e2f-846636dd4833",
  action: "signIn",
  attributes: {
    redirectUrl: "https://yourapp.com/callback",
  },
};

const response = await authsignal.track(request);

const url = response.url;
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.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 Mobile 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
⌘I