Mobile

​

Requirements

• iOS
• Android
• React Native
• Flutter

​

Installation

• iOS
• Android
• React Native
• Flutter

pod 'Authsignal', '~> 1.0.10'

dependencies: [
    .package(
        url: "https://github.com/authsignal/authsignal-ios.git",
        from: "1.0.10"
    )
]

​

Initialization

Initialize the client with your tenant ID and the base URL for your region.

You can find your tenant ID in the Authsignal Portal.

​

Passkeys

​

Prerequisites

After you have configured your Relying Party you should follow the steps below.

• iOS
• Android

GET https://<yourrelyingparty>/.well-known/apple-app-site-association

{
   "applinks": {},
   "webcredentials": {
      "apps": ["ABCDE12345.com.example.app"]
   },
   "appclips": {}
}

​

Creating a passkey

Creating a passkey must be authorized by presenting a challenge with an existing method or tracking an action to obtain a short-lived token.

​

Parameters

​

Response

​

Using a passkey

Calling signIn will present the passkey sign-in prompt if a credential is available on the device. If the user successfully authenticates with their passkey, send the result token to your server to validate the challenge.

​

Parameters

​

Response

​

Passkey autofill (iOS)

This feature requires rendering a text field with the textContentType property.

Then when the screen loads, you should initialize the text field for passkey autofill by running the following code.

​

Cancelling an autofill request (iOS)

If you call signIn to present the passkey sign-in prompt, you will need to cancel any autofill request that is already in progress.

This is typically required if your UI presents an username input with autofill as well as a separate “Sign in with passkey” button.

​

Push

The mobile SDK’s push authentication methods can be used to lookup and respond to authentication requests initiated from another device (e.g. desktop web browser) using public key cryptography.

These authentication requests can either be initiated using the pre-built UI or the client API. For more detail on the integration model for push authentication refer to our sequence diagram.

​

Adding a credential

Adding a push credential generates a private/public key pair, where the private key is secured on the user’s mobile device and the public key is held by Authsignal.

This operation must be authorized with a short-lived token, which can be obtained by tracking an action from your backend in an authenticated context.

​

Parameters

​

Response

​

Removing a credential

​

Response

​

Getting a challenge

​

Response

​

Updating a challenge

After presenting the user with a prompt to approve or reject the request, you should update the challenge with their response.

​

Response

​

Requiring user authentication (Android)

When adding a credential, it is possible to require that the user authenticate whenever they subsequently access the credential (i.e. when approving or rejecting a push challenge).

authsignal.push.addCredential(
    token = token,
    userAuthenticationRequired = true
)

It’s also possible to specify additional user authentication parameters.

authsignal.push.addCredential(
    token = token,
    userAuthenticationRequired = true,
    timeout = 60,
    authorizationType = 0
)

The timeout param determines the time (in seconds) that the credential can be accessed after authenticating - or 0 if authentication must occur for every credential use. The authorizationType param determines if authentication is required via biometrics and/or device credential (e.g. pin).

If user authentication is required for a credential, you must call updateChallenge in a biometric prompt authentication callback.

1. Initialize a signature before displaying the biometric prompt

val signature = authsignal.push.startSigning()

val cryptoObject = CryptoObject(signature)

// Initialize biometric prompt and prompt info
val biometricPrompt = ...
val promptInfo = ...

biometricPrompt.authenticate(promptInfo, cryptoObject);

2. Retrieve the signature from the crypto object in your prompt’s authentication callback

override fun onAuthenticationSucceeded(result: AuthenticationResult) {
    super.onAuthenticationSucceeded(result)

    val cryptoObject = result.cryptoObject
    val signer = cryptoObject.signature

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

​

Email OTP

All email OTP SDK methods require you to set a token first.

​

Enroll email

Start enrollment for a new email OTP authenticator by sending the user an email containing an OTP code.

This method is typically used when you’ve not yet verified the user’s email address.

​

Parameters

​

Response

​

Challenge email

Start re-authentication for an existing email OTP authenticator by sending the user an email containing an OTP code.

This method is typically used when you’ve already verified the user’s email address.

​

Response

​

Verify email

Finish enrolling or re-authenticating a new or existing email OTP authenticator by verifying the code submitted by the user.

​

Parameters

​

Response

​

SMS OTP

All SMS OTP SDK methods require you to set a token first.

​

Enroll SMS

Start enrollment for a new SMS OTP authenticator by sending the user an SMS containing an OTP code.

This method is typically used when you’ve not yet verified the user’s phone number.

​

Parameters

​

Response

​

Challenge SMS

Start re-authentication for an existing SMS OTP authenticator by sending the user an SMS containing an OTP code.

This method is typically used when you’ve already verified the user’s phone number.

​

Response

​

Verify SMS

Finish enrolling or re-authenticating a new or existing SMS OTP authenticator by verifying the code submitted by the user.

​

Parameters

​

Response

​

Authenticator app (TOTP)

All authenticator app SDK methods require you to set a token first.

​

Enroll TOTP

Start enrollment for a new TOTP authenticator by generating a QR code to display to the user.

​

Response

​

Verify TOTP

Finish enrolling or re-authenticating a TOTP authenticator by verifying the code submitted by the user.

​

Parameters

​

Response

​

Setting a token

When using mobile SDK methods for email OTP, SMS OTP or authenticator app (TOTP) you must first track an action using a Server SDK or the Server API to generate a time-limited token (valid for 10 minutes by default).

Then you can use the SDK’s setToken method. You must use the same token for the initial enroll/challenge call and the subsequent verify call.

​

Error handling

Mobile SDK methods can return the following fields when encountering an error.

​

Error codes