Mobile

​

Requirements

​

Installation

pod 'Authsignal', '~> 1.0.10'

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

pod 'Authsignal', '~> 1.0.10'

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

buildscript {
    repositories {
        mavenCentral()
        ...
    }
}

implementation 'com.authsignal:authsignal-android:2.0.2'

yarn add react-native-authsignal

npx pod-install ios

flutter pub add authsignal_flutter

​

Initialization

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

You can find your tenant ID in the Authsignal Portal.

import Authsignal

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

​

Passkeys

​

Prerequisites

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

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

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

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

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

GET https://<yourrelyingparty>/.well-known/assetlinks.json

[{
    "relation": [
        "delegate_permission/common.handle_all_urls",
        "delegate_permission/common.get_login_creds"
    ],
    "target": {
        "namespace": "android_app",
        "package_name": "com.example",
        "sha256_cert_fingerprints": [
            "FA:C6:17:45:DC:09:03:78:6F:B9:ED:E6:2A:96:2B:39:9F:73:48:F0:BB:6F:89:9B:83:32:66:75:91:03:3B:9C"
        ]
    }
}]

​

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.

let response = await authsignal.passkey.signUp(
    token: "eyJhbGciOiJ...",
    username: "jane@authsignal.com",
    displayName: "Jane Smith"
)

​

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.

let response = await authsignal.passkey.signIn(action: "signInWithPasskey")

if let token = response.data?.token {
    // Send token to your server to validate the result
}

​

Parameters

​

Response

​

Passkey autofill (iOS)

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

userTextField.textContentType = .username

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

let result = await authsignal.passkey.signIn(
    action: "signInWithPasskeyAutofill",
    autofill: true
)

if let token = result.data?.token {
    // The user has focused your text input and authenticated with an existing passkey
    // Send the response token to your server to validate the result of the challenge
}

​

Cancelling a request (iOS)

If you call signIn to present the passkey sign-in prompt, you will need to cancel a request that is already in progress (e.g. an autofill request).

authsignal.passkey.cancel()

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.

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

​

Parameters

​

Response

​

Removing a credential

await authsignal.push.removeCredential()

​

Response

​

Getting a challenge

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
}

​

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.

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

​

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.

await authsignal.email.enroll(email: "jane@authsignal.com")

​

Parameters

​

Response

​

Challenge email

Start an email OTP challenge by sending the user an email containing an OTP code.

await authsignal.email.challenge()

​

Response

​

Verify email

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

await authsignal.email.verify(code: "123456")

​

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.

await authsignal.sms.enroll(phoneNumber: "+64271234567")

​

Parameters

​

Response

​

Challenge SMS

Start an SMS challenge by sending the user an SMS containing an OTP code.

await authsignal.sms.challenge()

​

Response

​

Verify SMS

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

await authsignal.sms.verify(code: "123456")

​

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.

let response await authsignal.totp.enroll()

if let data = response.data {
    let uri = data.uri // Convert to QR code
    let secret = data.secret // Can be entered manually
}

​

Response

​

Verify TOTP

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

await authsignal.totp.verify(code: "123456")

​

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).

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

const response = await authsignal.track(request);

const token = response.token;

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.

authsignal.setToken("eyJhbGciOiJ...")

// Send the user an email OTP code
// You can call this multiple times via a 'resend' button
await authsignal.email.challenge()

// Verify the inputted code matches the original code
let response = await authsignal.email.verify(code: "123456")

​

Error handling

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

​

Error codes