Push verification - Authsignal

Push verification allows users to authenticate in a web browser by sending an authentication request to a mobile app. Push notifications are used to improve the UX by prompting users to open their app but they are not required for the method to work. The authentication mechanism is based on public key cryptography where private keys are securely stored on the user’s mobile device and are used to sign messages which can be verified with the public key. The Mobile SDK is used in push verification for two key steps:

Enrolling a user for push verification by adding a credential in the mobile app. This step creates a new public/private key pair.
Responding to an authentication challenge in the mobile app by approving or denying it. This step uses the mobile device’s private key to sign a message which is verified on the server using the public key.

Sequence diagram

The diagram below illustrates the sequence for a push verification challenge.

Portal setup

Enable push verification for your tenant and configure a webhook endpoint for sending push notifications to your app. For more information on the payload which Authsignal sends to your webhook, refer to the webhook schema documentation for push.

Prefer not to run your own webhook? Authsignal can deliver push notifications for you - just connect your APNs and/or FCM credentials in the portal. See Managed push notifications.

SDK setup

Server SDK

Initialize the SDK using your Server API secret key from the API keys page and the API URL for your region.

import { Authsignal } from "@authsignal/node";

const authsignal = new Authsignal({
  apiSecretKey: "YOUR_SECRET_KEY",
  apiUrl: "YOUR_API_URL",
});

using Authsignal;

var authsignal = new AuthsignalClient(
    apiSecretKey: "YOUR_SECRET_KEY",
    apiUrl: "YOUR_API_URL"
);

import com.authsignal.AuthsignalClient;

AuthsignalClient authsignal = new AuthsignalClient(
    "YOUR_SECRET_KEY",
    "YOUR_API_URL"
);

require 'authsignal'

Authsignal.setup do |config|
    config.api_secret_key = ENV["YOUR_SECRET_KEY"]
    config.api_url = "YOUR_API_URL"
end

from authsignal.client import AuthsignalClient

authsignal = AuthsignalClient(
    api_secret_key="YOUR_SECRET_KEY",
    api_url="YOUR_API_URL"
)

Authsignal::setApiSecretKey("YOUR_SECRET_KEY");
Authsignal::setApiUrl("YOUR_API_URL");

import "github.com/authsignal/authsignalgo/v2/client"

client := NewAuthsignalClient(
    "YOUR_SECRET_KEY",
    "YOUR_API_URL",
)

Web and Mobile SDKs

Initialize the Web SDK and Mobile SDK using your tenant ID from the API keys page and your API URL.

import { Authsignal } from "@authsignal/browser";

const authsignal = new Authsignal({
  tenantId: "YOUR_TENANT_ID",
  baseUrl: "YOUR_API_URL",
});

import Authsignal

let authsignal = Authsignal(
    tenantID: "YOUR_TENANT_ID",
    baseURL: "YOUR_API_URL"
)

import com.authsignal.Authsignal

val authsignal = Authsignal(
    tenantID = "YOUR_TENANT_ID",
    baseURL = "YOUR_API_URL",
)

import { Authsignal } from "react-native-authsignal";

const authsignal = new Authsignal({
  tenantID: "YOUR_TENANT_ID",
  baseURL: "YOUR_API_URL",
});

import 'package:authsignal_flutter/authsignal_flutter.dart';

final authsignal = Authsignal(
    "YOUR_TENANT_ID",
    baseURL: "YOUR_API_URL"
);

Enrollment

Scenario - Enroll users for push verification in your mobile app so it can be used later as a method for adaptive MFA.

1. Generate enrollment token

In your backend, track an action for a user (e.g. “addAuthenticator”) to generate a short-lived token.

const request = {
  userId: "dc58c6dc-a1fd-4a4f-8e2f-846636dd4833",
  action: "addAuthenticator",
  attributes: {
    scope: "add:authenticators",
  },
};

const response = await authsignal.track(request);

const token = response.token;

var request = new TrackRequest(
    UserId: "dc58c6dc-a1fd-4a4f-8e2f-846636dd4833",
    Action: "addAuthenticator",
    Attributes: new TrackAttributes(
        Scope: "add:authenticators",
    )
);

var response = await authsignal.Track(request);

var token = response.Token;

TrackRequest request = new TrackRequest();
request.userId = "dc58c6dc-a1fd-4a4f-8e2f-846636dd4833";
request.action = "addAuthenticator";
request.attributes = new TrackAttributes();
request.attributes.scope = "add:authenticators";

TrackResponse response = authsignal.track(request).get();

String token = response.token;

response = Authsignal.track({
  user_id: "dc58c6dc-a1fd-4a4f-8e2f-846636dd4833",
  action: "addAuthenticator",
  attributes: {
    scope: "add:authenticators",
  }
})

token = response[:token]

response = authsignal.track(
    user_id="dc58c6dc-a1fd-4a4f-8e2f-846636dd4833",
    action="addAuthenticator",
    attributes={
        "scope": "add:authenticators",
    }
)

token = response["token"]

$response = Authsignal::track([
    'userId' => "dc58c6dc-a1fd-4a4f-8e2f-846636dd4833",
    'action' => "addAuthenticator",
    'attributes' => [
        'scope' => "add:authenticators",
    ]
]);

$token = $response["token"]

response, err := client.Track(
    TrackRequest{
        UserId: "dc58c6dc-a1fd-4a4f-8e2f-846636dd4833",
        Action: "addAuthenticator",
        Attributes: &TrackAttributes{
            scope: "add:authenticators",
        },
    },
)

token := response.Token

This token will be used to authorize enrolling a new push authentication method on their mobile device. The add:authenticators scope is required to enroll a new authentication factor for an existing user. This scope should only be used when the user is in an already authenticated state. For more information on using scopes safely refer to our documentation on authenticator binding.

2. Add credential

Use the token obtained in step 1 to enroll a new device credential for the user in the mobile app.

await authsignal.push.addCredential(token: "eyJhbGciOiJ...")

authsignal.push.addCredential(token = "eyJhbGciOiJ...")

await authsignal.push.addCredential({ token: "eyJhbGciOiJ..." });

await authsignal.push.addCredential("eyJhbGciOiJ...");

For more information on when in your app to add credentials refer to our documentation on the enrollment lifecycle for app verification.

Adaptive MFA

Scenario - Strongly authenticate users in a web browser with push verification and use rules to decide when and where to trigger the authentication.

1. Track action

When a user performs an action that requires push verification, your backend should track an action (e.g. “signIn”) using our Server SDK.

Custom UI
Pre-built UI

const request = {
  userId: "dc58c6dc-a1fd-4a4f-8e2f-846636dd4833",
  action: "signIn",
};

const response = await authsignal.track(request);

if (response.state === "CHALLENGE_REQUIRED") {
  // Obtain token to present challenge
  const token = response.token;
}

var request = new TrackRequest(
    UserId: "dc58c6dc-a1fd-4a4f-8e2f-846636dd4833",
    Action: "signIn"
);

var response = await authsignal.Track(request);

if (response.State == UserActionState.CHALLENGE_REQUIRED)
{
    // Obtain token to present challenge
    var token = response.Token;
}

TrackRequest request = new TrackRequest();
request.userId = "dc58c6dc-a1fd-4a4f-8e2f-846636dd4833";
request.action = "signIn";

TrackResponse response = authsignal.track(request).get();

if (response.state.equals(UserActionState.CHALLENGE_REQUIRED)) {
    // Obtain token to present challenge
    String token = response.token;
}

response = Authsignal.track({
  user_id: 'dc58c6dc-a1fd-4a4f-8e2f-846636dd4833',
  action: 'signIn'
})

case response[:state]
when "CHALLENGE_REQUIRED"
  # Obtain token to present challenge
  token = response[:token]
end

response = authsignal.track(
    user_id="dc58c6dc-a1fd-4a4f-8e2f-846636dd4833",
    action="signIn"
)

if response["state"] == "CHALLENGE_REQUIRED":
    # Obtain token to present challenge
    token = response["token"]

$response = $authsignal->track([
    'userId' => 'dc58c6dc-a1fd-4a4f-8e2f-846636dd4833',
    'action' => 'signIn'
]);

switch ($response['state']) {
    case 'CHALLENGE_REQUIRED':
        // Obtain token to present challenge
        $token = $response['token'];
}

response, err := client.Track(
    TrackRequest{
        UserId: "dc58c6dc-a1fd-4a4f-8e2f-846636dd4833",
        Action: "signIn",
    },
)

switch response.State {
case "CHALLENGE_REQUIRED":
    // Obtain token to present challenge
    token := response.Token
}

const request = {
  userId: "dc58c6dc-a1fd-4a4f-8e2f-846636dd4833",
  action: "signIn",
  attributes: {
    redirectUrl: "https://yourapp.com/callback",
  },
};

const response = await authsignal.track(request);

if (response.state === "CHALLENGE_REQUIRED") {
  // Return URL to your frontend to launch pre-built UI
  const url = response.url;
}

var request = new TrackRequest(
    UserId: "dc58c6dc-a1fd-4a4f-8e2f-846636dd4833",
    Action: "signIn",
    Attributes: new TrackAttributes(
        RedirectUrl: "https://yourapp.com/callback",
    )
);

var response = await authsignal.Track(request);

if (response.State == UserActionState.CHALLENGE_REQUIRED)
{
    // Return URL to your frontend to launch pre-built UI
    var url = response.Url;
}

TrackRequest request = new TrackRequest();
request.userId = "dc58c6dc-a1fd-4a4f-8e2f-846636dd4833";
request.action = "signIn";
request.attributes = new TrackAttributes();
request.attributes.redirectUrl = "https://yourapp.com/callback";

TrackResponse response = authsignal.track(trackRequest).get();

if (response.state.equals(UserActionState.CHALLENGE_REQUIRED)) {
    // Return URL to your frontend to launch pre-built UI
    String url = response.url;
}

response = Authsignal.track({
  user_id: 'dc58c6dc-a1fd-4a4f-8e2f-846636dd4833',
  action: 'signIn',
  attributes: {
    redirect_url: "https://yourapp.com/callback"
  }
})

case response[:state]
when "CHALLENGE_REQUIRED"
  # Return URL to your frontend to launch pre-built UI
  url = response[:url]
end

response = authsignal.track(
    user_id="dc58c6dc-a1fd-4a4f-8e2f-846636dd4833",
    action="signIn",
    attributes={
        "redirectUrl": "https://yourapp.com/callback"
    }
)

if response["state"] == "CHALLENGE_REQUIRED":
    # Return URL to your frontend to launch pre-built UI
    url = response["url"]

$response = $authsignal->track([
    'userId' => 'dc58c6dc-a1fd-4a4f-8e2f-846636dd4833',
    'action' => 'signIn',
    'attributes' => [
        'redirectUrl' => 'https://yourapp.com/callback'
    ]
]);

switch ($response['state']) {
    case 'CHALLENGE_REQUIRED':
        // Return URL to your frontend to launch pre-built UI
        $url = $response['url'];
}

response, err := client.Track(
    TrackRequest{
        UserId: "dc58c6dc-a1fd-4a4f-8e2f-846636dd4833",
        Action: "signIn",
        Attributes: &TrackAttributes{
            RedirectUrl: "https://yourapp.com/callback",
        },
    },
)

switch response.State {
case "CHALLENGE_REQUIRED":
    // Return URL to your frontend to launch pre-built UI
    url := response.Url
}

2. Initiate challenge in browser

In the browser, use our Web SDK to initiate a push challenge. This will trigger a call to your webhook with the push event schema so that it can send the user a push notification.

If a user has enrolled more than one push authenticator, you can target a specific one by passing its userAuthenticatorId to the push challenge. Only that authenticator receives the challenge and can approve it.

Custom UI
Pre-built UI

// Set the token obtained from the track response
authsignal.setToken(token);

// Initiate the push challenge
const response = await authsignal.push.challenge();

// Obtain a challenge ID to poll for the result in the next step
const challengeId = response.data?.challengeId;

Then you can immediately start polling for the challenge result.

// Poll for the challenge result
const { data, error } = await authsignal.push.verify({ challengeId });

if (error || !data) {
  // Handle error
} else if (!data.isConsumed) {
  // The challenge has not yet been consumed
  // Continue polling
} else {
  // The challenge has been consumed
  // Stop polling and check if approved or rejected
  if (data.isVerified) {
    // Challenge has been approved
    // Obtain new token to send to backend to validate action
    const validationToken = data.token;
  } else {
    // Challenge has been rejected
  }
}

// Launch the pre-built UI with the URL from the track response
const result = await authsignal.launch(url, { popup: true });

// Get a new token to validate the action on your backend
if (result.token) {
  const validationToken = result.token;
}

3. Check for pending challenge in mobile app

Use the mobile SDK’s Get Challenge method to check if there is a pending challenge for the device.

let response = await authsignal.push.getChallenge()

if let error = result.error {
    // The credential stored on the device is invalid
} else if let challenge = result.data {
    // A pending challenge request is available
    // Present the user with a prompt to approve or deny the request
    let challengeId = challenge.challengeId
} else {
    // No pending challenge request
}

val response = authsignal.push.getChallenge()

if (response.error != null) {
    // The credential stored on the device is invalid
} else if (response.data != null) {
    // A pending challenge request is available
    // Present the user with a prompt to approve or deny the request
    val challengeId = response.data.challengeId
} else {
    // No pending challenge request
}

const {data, error} = await authsignal.push.getChallenge();

if (error) {
    // The credential stored on the device is invalid
} else if (data) {
    // A pending challenge request is available
    // Present the user with a prompt to approve or deny the request
    val challengeId = data.challengeId
} else {
    // No pending challenge request
}

final response = await authsignal.push.getChallenge();

if (response.error != null) {
    // The credential stored on the device is invalid
} else if (response.data != null) {
    // A pending challenge request is available
    // Present the user with a prompt to approve or deny the request
    final challengeId = response.data.challengeId;
} else {
    // No pending challenge request
}

This check should be done when launching or foregrounding the app - either from a push notification or when opened manually - as well as when the app receives a push notification while it is already foregrounded.

To display custom data points passed into the initial track request, mark the relevant custom data points as public.

4. Present challenge in mobile app

If there is a pending challenge, present a dialog to allow the user to approve or reject the challenge. To approve or reject the challenge, use the mobile SDK’s Update Challenge method.

await authsignal.push.updateChallenge(
    challengeId: challengeId,
    approved: true
)

authsignal.push.updateChallenge(
    challengeId = challengeId,
    approved = true
)

await authsignal.push.updateChallenge({
  challengeId,
  approved: true,
});

await authsignal.push.updateChallenge(
    challengeId,
    true,
);

5. Complete authentication in browser

Once the challenge is approved, the polling request initiated in the web browser in step 2 will return a token that should be passed to your web browser app’s backend to validate the action in order to complete the authentication flow.

const response = await authsignal.validateChallenge({
  action: "signIn",
  token: "eyJhbGciOiJIUzI....",
});

if (response.state === "CHALLENGE_SUCCEEDED") {
  // User completed challenge successfully
}

var request = new ValidateChallengeRequest(
    Action: "signIn",
    Token: "eyJhbGciOiJIUzI...."
);

var response = await authsignal.ValidateChallenge(request);

if (response.State == UserActionState.CHALLENGE_SUCCEEDED) {
    // User completed challenge successfully
}

ValidateChallengeRequest request = new ValidateChallengeRequest();
request.action = "signIn";
request.token = "eyJhbGciOiJIUzI....";

ValidateChallengeResponse response = authsignal.validateChallenge(request).get();

if (response.state == UserActionState.CHALLENGE_SUCCEEDED) {
   // User completed challenge successfully
}

response = Authsignal.validate_challenge(action: "signIn", token: "eyJhbGciOiJIUzI....")

if response[:state] == "CHALLENGE_SUCCEEDED"
  # User completed challenge successfully
end

response = authsignal.validate_challenge(action="signIn", token="eyJhbGciOiJIUzI....")

if response["state"] == "CHALLENGE_SUCCEEDED":
    # User completed challenge successfully

$response = Authsignal::validateChallenge(action: "signIn", token: "eyJhbGciOiJIUzI....");

if ($response["state"] === "CHALLENGE_SUCCEEDED") {
    # User completed challenge successfully
}

response, err := client.ValidateChallenge(
    ValidateChallengeRequest{
        Action: "signIn",
        Token: "eyJhbGciOiJ...",
    },
)

if response.State == "CHALLENGE_SUCCEEDED" {
    // User completed challenge successfully
}

Next steps

Adaptive MFA - Set up smart rules to trigger authentication based on risk
QR code - Implement QR code authentication
Trusted device - Implement trusted device authentication
Passkeys - Offer the most secure and user-friendly passwordless authentication

​Sequence diagram

​Portal setup

​SDK setup

​Server SDK

​Web and Mobile SDKs

​Enrollment

​1. Generate enrollment token

​2. Add credential

​Adaptive MFA

​1. Track action

​2. Initiate challenge in browser

​3. Check for pending challenge in mobile app

​4. Present challenge in mobile app

​5. Complete authentication in browser

​Next steps

Sequence diagram

Portal setup

SDK setup

Server SDK

Web and Mobile SDKs

Enrollment

1. Generate enrollment token

2. Add credential

Adaptive MFA

1. Track action

2. Initiate challenge in browser

3. Check for pending challenge in mobile app

4. Present challenge in mobile app

5. Complete authentication in browser

Next steps