authenticateOtp

Last updated on Aug 1, 2023

This function is only available on the JavaScript SDK. Support for more SDKs will be coming soon.

The authenticateOtp function enables an app using the Beyond Identity SDK to initiate authentication using an OTP. The OTP gets sent to the provided email address. This function is used in conjunction with redeemOtp.

Dependencies

The authenticateOtp function requires the Beyond Identity Javascript SDK.

JavaScript

yarn add @beyondidentity/bi-sdk-js

or

npm install @beyondidentity/bi-sdk-js

Kotlin

Gradle

To enable the retrieval of Cloudsmith hosted packages via Gradle, we need to add the Cloudsmith repository to the root/build.gradle file.

repositories {
    maven {
        url "https://packages.beyondidentity.com/public/bi-sdk-android/maven/"
    }
}

After the repository is added, we can specify the Beyond Identity dependencies.

dependencies {
    implementation 'com.beyondidentity.android.sdk:embedded:[version]'
}

Swift

Swift Package Manager

From Xcode

1. From the Xcode File menu, select Add Packages and add the following url:

https://github.com/gobeyondidentity/bi-sdk-swift

2. Select a version and hit Next.
3. Select a target matching the SDK you wish to use.

From Package.swift

1. With Swift Package Manager, add the following dependency to your Package.swift:

dependencies: [
    .package(url: "https://github.com/gobeyondidentity/bi-sdk-swift.git", from: [version])
]

2. Run swift build

Cocoapods

Add the pod to your Podfile:

pod 'BeyondIdentityEmbedded'

And then run:

pod install

After installing import with

import BeyondIdentityEmbedded

React Native

Using react-native init or an expo app.

react-native init

Install the SDK with yarn or npm:

yarn add @beyondidentity/bi-sdk-react-native

npm install @beyondidentity/bi-sdk-react-native

Update native requirements in your ios and android folders:

iOS

Make sure your ios/Podfile supports "minimum deployment target" 13.0 or later

ios/Podfile

platform :ios, '13.0'

Navigate to your ios folder and run:

cd ios && pod install

Android

Make sure your android/build.gradle supports minSdkVersion 26 or later

android/build.gradle

buildscript {
  ext {
    minSdkVersion = 26
  }
}

Add the following maven url to your repositories in your android/build.gradle

allprojects {
  repositories {
    maven {
      url "https://packages.beyondidentity.com/public/bi-sdk-android/maven/"
    }
  }
}

expo

info

This package requires custom native code and can be used with Development builds or prebuild and cannot be used with Expo Go.

npx expo install @beyondidentity/bi-sdk-react-native

Add the SDK config plugin to the plugins array of your app.{json,config.js,config.ts}:

{
  "expo": {
    "plugins": [["@beyondidentity/bi-sdk-react-native"]]
  }
}

The SDK requires certain minimum native versions. Set these requirments with expo-build-properties.

npx expo install expo-build-properties

{
  "expo": {
    "plugins": [
      ["@beyondidentity/bi-sdk-react-native"],
      [
        "expo-build-properties",
        {
          "android": {
            "minSdkVersion": 26
          },
          "ios": {
            "deploymentTarget": "13.0"
          }
        }
      ]
    ]
  }
}

Finally, rebuild your app as described in Expo's Adding custom native code guide.

Flutter

Pub.Dev

Add the Beyond Identity Embedded SDK to your dependencies

dependencies:
  bi_sdk_flutter: x.y.z

and run an implicit flutter pub get.

Update Android

Please make sure your android/build.gradle supports minSdkVersion 26 or later.

buildscript {
  ext {
    minSdkVersion = 26
  }
}

Update iOS

Please make sure your project supports "minimum deployment target" 13.0 or later. In your ios/Podfile set:

platform :ios, '13.0'

Prerequisites

Before making a call to authenticateOtp, you must complete the following prerequisite calls:

1. Import the required types and functions from the SDK.

   JavaScript

   import { Embedded } from '@beyondidentity/bi-sdk-js';

   Kotlin

   import com.beyondidentity.embedded.sdk.EmbeddedSdk

   Swift

   import BeyondIdentityEmbedded

   React Native

   import { Embedded } from '@beyondidentity/bi-sdk-react-native';

   Flutter

   import 'package:bi_sdk_flutter/embeddedsdk.dart';

2. Initialize the SDK.

   JavaScript

   // --- Initialize with required arguments
   try {
     const embedded = await Embedded.initialize();
     console.log("Initialization successful", embedded);
   } catch (error) {
     console.error("Initialization failed:", error);
   }
   
   // --- Initialize with required and optional arguments
   const config = {
     allowedDomains: ["example.com", "another-example.com"],
     logger: function (logType, message) {
       console.log(`[${logType}] ${message}`);
     },
   };
   
   try {
     const embedded = await Embedded.initialize(config);
     console.log("Initialization successful", embedded);
   } catch (error) {
     console.error("Initialization failed:", error);
   }

   Kotlin

   // --- Initialize with required arguments
   EmbeddedSdk.init(
     app = this,
     keyguardPrompt = { allowCallback ->
       // launch the keyguard service and then
       // call allowCallback with the result
     },
     logger = { logMessage ->
       Log.d("BeyondIdentityLog", logMessage)
     }
   )
   
   // --- Initialize with required and optional arguments
   EmbeddedSdk.init(
     app = this,
     keyguardPrompt = { allowCallback ->
       // launch the keyguard service and then
       // call allowCallback with the result
     },
     logger = { logMessage ->
       Log.d("BeyondIdentityLog", logMessage)
     },
     biometricAskPrompt = getString(R.string.embedded_export_biometric_prompt_title),
     allowedDomains = listOf("example.com", "another-example.com")
   )

   Swift

   // --- Initialize with required arguments
   Embedded.shared.initialize(
     biometricAskPrompt: "Please provide your biometric"
   ) { result in
     switch result {
     case .success():
       print("Initialization successful")
     case .failure(let error):
       print("Initialization failed: \(error)")
     }
   }
   
   // --- Initialize with required and optional arguments
   Embedded.shared.initialize(
     allowedDomains: ["example.com", "another-example.com"],
     biometricAskPrompt: "Please provide your biometric",
     logger: { (logType, message) in
       print("\(logType): \(message)")
     }
   ) { result in
     switch result {
     case .success():
       print("Initialization successful")
     case .failure(let error):
       print("Initialization failed: \(error)")
     }
   }

   React Native

   // --- Initialize with required arguments
   try {
     const response = await Embedded.initialize("Please provide your biometric");
     console.log(response);
   } catch (error) {
     console.error("Initialization failed:", error);
   }
   
   // --- Initialize with required and optional arguments
   try {
     const response = await Embedded.initialize(
       "Please provide your biometric", [
       ("example.com", "another-example.com"),
     ]);
     console.log(response);
   
     Embedded.logEventEmitter.addListener(
       "BeyondIdentityLogger",
       (message: string) => {
         console.log(message);
       }
     );
   } catch (error) {
     console.error("Initialization failed:", error);
   }

   Flutter

   // --- Initialize with required arguments
   EmbeddedSdk.initialize('Please provide your biometric');
   
   // --- Initialize with required and optional arguments
   EmbeddedSdk.initialize(
     'Please provide your biometric',
     allowedDomains: ["example.com", "another-example.com"],
     logger: EmbeddedSdk.enableLogger
   ).then(() {
     print('Initialization successful');
   }).catchError((error) {
     print('Initialization failed: $error');
   });

3. Use authenticateOtp to initiate authentication using an OTP.

   await embedded.authenticateOtp(url, email);

Parameters

Parameter	Type	Description
url	string	Required. The authentication URL of the current transaction. This URL is generated by the Beyond Identity API's /authorize endpoint in response to a standard OpenID Connect request from your app (see example below). The generated URL is unique for each authentication request. It contains an encoded JWT token containing the challenge for the passkey to sign. (/bi-authenticate?request=someToken)
email	string	Required. The email address where the OTP gets sent.

Returns

On success, the authenticateOtp function returns a Promise that resolves to an OtpChallengeResponse, which itself is a JSON object that contains the following keys:

url: object containing a URL containing the authentication state.

note

This URL should be saved and used when calling redeemOtp.

Examples

Example: Call authenticateOtp

let authenticateResponse = await embedded.authenticateOtp(url, email);

Example: Retrieve Beyond Identity authentication url via OIDC call

The app sends an OIDC call to the Beyond Identity API's /authorize endpoint:

GET https://auth-us.beyondidentity.com/v1/tenants/{TENANT_ID}/realms/{REALM_ID}/applications/{APPLICATION_ID}/authorize?client_id={CLIENT_ID}&scope=openid&response_type=code&redirect_uri={REDIRECT_URI}&state=8LIY29kN8Oz7zrAhb8xb0yvem-gvnRy1HTn03MAuL_E

where the following elements match the corresponding properties of the app as configured in your Beyond Identity tenant:

Property	Description
TENANT_ID	The Tenant ID of the tenant in which the app is configured.
REALM_ID	The Realm ID of the realm in which the app is configured.
APPLICATION_ID	The Application ID from the header of the app's configuration page.
CLIENT_ID	The Client ID from the External Protocol tab of the app's configuration page.
REDIRECT_URI	Matches one of the Redirect URIs configured on the External Protocol tab of the app's configuration page, URL encoded.

When the Invocation Type configured on the Authenticator Config tab of the app's configuration page is set to Manual, it returns a JSON object:

{ "authenticate_url": "http://localhost:8083/bi-authenticate?request={BI_JWT}" }

where BI_JWT is a base64url encoded JWT token containing the challenge and other data to kick off the passkey authentication.

When the Invocation Type on the app is set to Automatic, it returns an HTTP 302 to the authentication URL:

http/1.1 302 Found
...
location: http://localhost:8083/bi-authenticate?request={BI_JWT}

where BI_JWT is a base64url encoded JWT token containing the challenge and other data to kick off the passkey authentication.