SDK setup

Last updated on Jun 1, 2023

This guide enables you to set up each of the Beyond Identity SDKs and to learn about the functionality they contain.

The Embedded SDK offers the entire passkey creation and authentication experience embedded in your product. A set of functions are provided to you through the Embedded namespace. The SDKs support OIDC and OAuth2.

Prerequisites

• Set up a developer account
• Create an application

Sample App

JavaScript

JavaScript

Sample App Sample apps are available to explore. Check out Example for the Embedded SDK.

Kotlin

Kotlin

Sample App Sample apps are available to explore. Check out Example for the Embedded SDK.

Swift

Swift

Sample App Sample apps are available to explore. Check out Example for the Embedded SDK.

React Native

React Native

Sample App Sample apps are available to explore. Check out Example for the Embedded SDK.

Flutter

Flutter

Sample App Sample apps are available to explore. Check out Example for the Embedded SDK.

Installation

To use Beyond Identity functionality in your application, you will need to install the SDK.

JavaScript

The JavaScript SDK provides functionality from passkey creation to passwordless authentication. A set of functions are provided to you through an Embedded namespace.

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'

Setup

First, before calling the Embedded functions, make sure to initialize the SDK.

JavaScript

Once you've installed the SDK, initialize it so that you can call the Embedded functions.

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

const embedded = await Embedded.initialize();

Kotlin

import com.beyondidentity.embedded.sdk.EmbeddedSdk

EmbeddedSdk.init(
    app: Application,
    keyguardPrompt: (((allow: Boolean, exception: Exception?) -> Unit) -> Unit)?,
    logger: (String) -> Unit,
    biometricAskPrompt: String, /* Optional */
    allowedDomains: List<String>?, /* Optional */
)

Swift

import BeyondIdentityEmbedded

Embedded.initialize(
    allowedDomains: [String] = ["beyondidentity.com"],
    biometricAskPrompt: String,
    logger: ((OSLogType, String) -> Void)? = nil,
    callback: @escaping(Result<Void, BISDKError>) -> Void
)

React Native

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

Embedded.initialize(
  biometricAskPrompt: string,
  allowedDomains?: string[]
): Promise<Success>;

You may also add a listener to log native events with Embedded.logEventEmitter after initializing.

Usage

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

Embedded.initialize("Please verify it's really you").catch(console.error);

Embedded.logEventEmitter.addListener(
  "BeyondIdentityLogger",
  (message: string) => {
    console.log(message);
  }
);

Flutter

import 'package:bi_sdk_flutter/embeddedsdk.dart';

EmbeddedSdk.initialize(
    String biometricAskPrompt,
    List<String>? allowedDomains, /* Optional */
    Future<Function>? logger, /* Optional */
)

Documentation

JavaScript

JavaScript

Documentation Documentation is available to explore. Check out SDK API Documentation for the Embedded SDK. Also, feel free to check out Bind a Passkey Authentication

Kotlin

Kotlin

Documentation Documentation is available to explore. Check out SDK API Documentation for the Embedded SDK. Also, feel free to check out Bind a Passkey Authentication

Swift

Swift

Documentation Documentation is available to explore. Check out SDK API Documentation for the Embedded SDK. Also, feel free to check out Bind a Passkey Authentication

React Native

React Native

Documentation Documentation is available to explore. Check out SDK API Documentation for the Embedded SDK. Also, feel free to check out Bind a Passkey Authentication

Flutter

Flutter

Documentation Documentation is available to explore. Check out SDK API Documentation for the Embedded SDK. Also, feel free to check out Bind a Passkey Authentication

Binding a Passkey

The bindPasskey function expects a URL. This can either be a binding passkey link fetched directly from our public API, or a binding passkey instruction that is the result of a redirection to your web application. This function should be used in conjunction with isBindPasskeyUrl in order to determine if the URL being passed in is a valid bind passkey URL.

Checkout the Bind passkey to an identity guide for more information.

Usage

JavaScript

const bindPasskeyResponse = await embedded.bindPasskey(url);

Where the response type consists of an object containing a Passkey and an optional postBindingRedirectUri URL to redirect to upon succesfully binding a passkey.

{
    passkey: Passkey;
    postBindingRedirectUri?: string;
}

Kotlin

EmbeddedSdk.bindPasskey(
    url: String,
) { result ->
    result.onSuccess { }
    result.onFailure { }
}

Where the response type consists of an object containing a Passkey and an optional postBindingRedirectUri URL to redirect to upon succesfully binding a passkey.

data class BindPasskeyResponse(
    val passkey: Passkey,
    val postBindingRedirectUri: String?,
)

Swift

Embedded.shared.bindPasskey(
    url: URL,
    callback: @escaping(Result<BindPasskeyResponse, BISDKError>) -> Void
)

Where the response type consists of an object containing a Passkey and an optional postBindingRedirectUri URL to redirect to upon succesfully binding a passkey.

struct BindPasskeyResponse: Codable, Equatable {
    let passkey: Passkey
    let postBindingRedirectUri: URL?
}

React Native

Embedded.bindPasskey(
    url: string,
): Promise<BindPasskeyResponse>

Where the response type consists of an object containing a Passkey and an optional postBindingRedirectUri URL to redirect to upon succesfully binding a passkey.

interface BindPasskeyResponse {
  passkey: Passkey;
  postBindingRedirectUri?: string;
}

Flutter

await Embeddedsdk.bindPasskey(
    String url,
)

Where the response type consists of an object containing a Passkey and an optional postBindingRedirectUri URL to redirect to upon succesfully binding a passkey.

class BindPasskeyResponse(
    Passkey passkey,
    String postBindingRedirectUri,
)

Authentication

The authenticate function expects a URL and a PasskeyId. This Beyond Identity specific URL is generated during the OAuth2 authorization flow and carries with it a JWT that contains information specific to the current authorization request. When passing this URL into the authenticate function, this will perform a challenge/response against the private key bound to the passkey on your device. You will be required to select from one of the passkeys bound to your device if more than one passkey belongs to a single Realm. This function should be used in conjunction with isAuthenticateUrl in order to determine if the URL being passed in is a valid authenticate URL.

Before calling this function you will need to ask the user to select a passkey that has been bound to the device. A selection view can be built in conjunction with getPasskeys.

Checkout the add authentication guide for more information.

Usage

JavaScript

const authenticateResponse = await embedded.authenticate(url, passkeyId);

Where the response consists of an object containing a redirectUrl that you should redirect back to in order to complete the authentication flow, and an optional message to display to the user.

{
    redirectUrl: string;
    message?: string;
}

Kotlin

EmbeddedSdk.authenticate(
    url: String,
    passkeyId: PasskeyId,
) { result ->
    result.onSuccess { }
    result.onFailure { }
}

Where the response consists of an object containing a redirectUrl that you should redirect back to in order to complete the authentication flow, and an optional message to display to the user.

data class AuthenticateResponse(
    val redirectUrl: String?,
    val message: String?,
)

Swift

Embedded.shared.authenticate(
    url: URL,
    id: Passkey.Id,
    callback: @escaping(Result<AuthenticateResponse, BISDKError>) -> Void
)

Where the response consists of an object containing a redirectUrl that you should redirect back to in order to complete the authentication flow, and an optional message to display to the user.

struct AuthenticateResponse: Codable, Equatable {
    let redirectUrl: URL
    let message: String?
}

React Native

Embedded.authenticate(
    url: string,
    passkeyId: string,
): Promise<AuthenticateResponse>

Where the response consists of an object containing a redirectUrl that you should redirect back to in order to complete the authentication flow, and an optional message to display to the user.

interface AuthenticateResponse {
  redirectUrl: string;
  message?: string;
}

Flutter

await Embeddedsdk.authenticate(
    String url,
    String passkeyId,
)

Where the response consists of an object containing a redirectUrl that you should redirect back to in order to complete the authentication flow, and an optional message to display to the user.

class AuthenticateResponse(
    String redirectUrl,
    String message,
)

URL Validation

Bind Passkey URL Validation

This function is used to validate if a given URL is able to be used by the bindPasskey function.

JavaScript

if (embedded.isBindPasskeyUrl(url)) {
  // bind the passkey using `bindPasskey`
}

Kotlin

if (EmbeddedSdk.isBindPasskeyUrl(url)) {
    // bind the passkey using `bindPasskey`
}

Swift

if (Embedded.shared.isBindPasskeyUrl(url)) {
    // bind the passkey using `bindPasskey`
}

React Native

if (await Embedded.isBindPasskeyUrl(url)) {
  // bind the passkey using `bindPasskey`
}

Flutter

if (await Embeddedsdk.isBindPasskeyUrl(url)) {
    // bind the passkey using `bindPasskey`
}

Authenticate URL Validation

This function is used to validate if a given URL is able to be used by the authenticate function.

JavaScript

if (embedded.isAuthenticateUrl(url)) {
  // authenticate against a passkey bound to the device
}

Kotlin

if (EmbeddedSdk.isAuthenticateUrl(url)) {
    // authenticate against a passkey bound to the device
}

Swift

if (Embedded.shared.isAuthenticateUrl(url)) {
    // authenticate against a passkey bound to the device
}

React Native

if (await Embedded.isAuthenticateUrl(url)) {
  // authenticate against a passkey bound to the device
}

Flutter

if (await Embeddedsdk.isAuthenticateUrl(url)) {
    // authenticate against a passkey bound to the device
}

Passkey Management

Listing Passkeys

The getPasskeys function enables you to get all passkeys currently bound to the device.

JavaScript

const allPasskeys = await embedded.getPasskeys();

Where the response is a [Passkey].

Kotlin

EmbeddedSdk.getPasskeys() { result ->
    result.onSuccess { }
    result.onFailure { }
}

Where the response is a List<Passkey>.

Swift

Embedded.shared.getPasskeys(
    callback: @escaping (Result<[Passkey], BISDKError>) -> Void
)

Where the response is a [Passkey].

React Native

Embedded.getPasskeys(): Promise<Passkey[]>

Where the response is a list of passkeys.

Flutter

await Embeddedsdk.getPasskeys()

Where the response is a List<Passkey>.

Deleting a Passkey

The deletePasskey function allows you to delete a passkey given its ID.

JavaScript

await embedded.deletePasskey(passkey.id);

Kotlin

EmbeddedSdk.deletePasskey(
    id: String,
) { result ->
    result.onSuccess { }
    result.onFailure { }
}

Swift

Embedded.shared.deletePasskey(
    for id: Passkey.Id,
    callback: @escaping (Result<(), BISDKError>) -> Void
)

React Native

Embedded.deletePasskey(id: string): Promise<string>

Where the response is passkey id.

Flutter

await Embeddedsdk.deletePasskey(
    String id,
)