@cryptr/cryptr-react-native

React Native SDK for Cryptr Authentication through SSO

Summary

• @cryptr/cryptr-react-native
  • Summary
  • Expo integration
    • Install SDK and link to Expo
    • Add plugin to handle android's manifest update
  • Prerequisites
    • Android
    • iOS
  • Installation
    • 1 - Create Mobile Application on Cryptr
    • 2 - Dependency
    • 3 - Android
  • Usage
    • Basis
      • iOS Alert dialog on SSO log-in
    • Hooks
      • isAuthenticated
      • user
      • accessToken
      • idToken
      • signInWithDomain
      • signInWithEmail
      • refreshTokens
      • logOut
      • error
      • isLoading
      • signIn
    • Components
  • Migration details
    • To v1.0.0

Expo integration

:warning: Follow below steps to use our SDK with Expo

Install SDK and link to Expo

npm i @cryptr/cryptr-react-native

// Expo link
(npx) expo install @cryptr/cryptr-react-native

Add plugin to handle android's manifest update

1. Create a file to insert in your expo config, ex named insertCryptrStrategyPlugin.js with below code

const { withAppBuildGradle } = require('@expo/config-plugins');

module.exports = function withAndroidStrategiesPlugin(config) {
  return withAppBuildGradle(config, (config) => {
    const targetSdkVersionLine = "targetSdkVersion rootProject.ext.targetSdkVersion";
    const manifestPlaceholders = 'manifestPlaceholders = [cryptrDomain: "your-app-domain", cryptrScheme: "cryptr"]';

    // Check if the manifestPlaceholders already exist
    if (!config.modResults.contents.includes(manifestPlaceholders)) {
      config.modResults.contents = config.modResults.contents.replace(
        targetSdkVersionLine,
        `${targetSdkVersionLine}\n        ${manifestPlaceholders}`
      );
    }

    return config;
  });
};

2. add config to your expo config

Update your app.json file to add the above file as plugin

// ./app.json
{
  "expo" : {
    //...
    "plugins": [
      //...
      "./insertCryptrStrategyPlugin"
    ]
  }
}

3. rebuild Expo

(npx) expo prebuild

Prerequisites

Android

Support with minSdkVersion=23

iOS

Full support with iOS>=13.0

Installation

1 - Create Mobile Application on Cryptr

Through your API or on your dashboard create a react-native application with the following attributes:

| Attribute Name | Value | | --- | --- | | Name | Desired name for your App | | Application type | mobile | | Allowed Redirect URI | cryptr://your-tenant |

⚠️ Choose wisely your domain to avoid conflicts with other apps.

When the application is registered, the configuration will be displayed, keep it for implementation.

2 - Dependency

# Yarn
yarn add @cryptr/cryptr-react-native

# NPM
npm install @cryptr/cryptr-react-native

3 - Android

Check your minSdkVersion

In android/build.gradle check that the version is 23 or greater

//android/build.gradle
minSdkVersion = 23

Update your manifestPlaceholders

In android/app/build.gradle setup as below. If manifestPlaceholders is not present add it with proper values.

android {
  //...
  defaultConfig {
    //...
    manifestPlaceholders = [cryptrDomain: "your-account-domain", cryptrScheme: "cryptr"]
  }
}

The cryptrDomain should have the same value in the allowed redirect URI for this app on Cryptr.

You are now good to go.

Usage

Basis

Cryptr implementation is based on React Context and Provider. At the top level of your React Native App set the configuration you got on the first step, like this one:

const config: CryptrConfig = {
  accountDomain: 'your-account-domain',
  clientId: 'CLIENT_ID',
  audience: 'cryptr://your-account-domain',
  defaultRedirectUri: 'cryptr://your-account-domain',
  cryptrServiceUrl: 'YOUR_SERVER_URL',
  dedicated_server: true, // if you have a dedicated Cryptr service
};

Then you can use it into <CryptrProvider {...config}>

Example: Inside this Provider, you can handle Cryptr Authentication using our Hooks and/or components.

iOS Alert dialog on SSO log-in

If you want to avoid the display of the below Alert dialog on iOS. you can add no_popup_no_cookie: true to your config.

:warning: With this configuration, even the default browser has registered credentials, the user will have to type them each type.

Hooks

access to our hooks like this

import { useCryptr } from `@cryptr/cryptr-react-native`

// ...

const { /* Any required hook */ } = useCryptr()

isAuthenticated

Hook to know if a Cryptr session is active

The return type is a boolean

const { isAuthenticated } = useCryptr()

if(isAuthenticated) { /**/ }

user

Hook to retrieve the User information (extracted from current oAuth Cryptr active session ID Token)

The return type is a key/value pair Object.

const { user } = useCryptr()

// ...
user?.email

accessToken

Hook to retrieve the current accessToken value

The return type is a ** nullable string**.

const { accessToken } = useCryptr()

//..
{accessToken && <Text>{accessToken}</Text>}

idToken

Hook to retrieve the current idToken value

The return type is a string.

const { idToken } = useCryptr()

//...
{idToken && <Text>{idToken}</Text>}

Actions

signInWithDomain

Hook action to sign in the user using his organization's domain.

const { signInWithDomain } = useCryptr();

// Signature
signInWithDomain(domain: string, successCallback? (data: any) => any, errorCallback?: (data: any) => any)

// Sign in for domain `company-dot-io`
signInWithDomain('company-dot-io')

signInWithEmail

Hook action to sign in the user using his business email. Requires email value.

const { signInWithEmail } = useCryptr();

// Signature
signInWithEmail(email: string, successCallback? (data: any) => any, errorCallback?: (data: any) => any)

// Sign in for email `[email protected]`
signInWithEmail('[email protected]')

refreshTokens

Hook action to refresh tokens to new ones.

const { refreshTokens } = useCryptr()

// Signature
refreshTokens(successCallback?: (data: any) => any, errorCallback?: (data: any) => any)

logOut

Hook action to log out the user.

const { logOut } = useCryptr()

// Signature
logOut(successCallback?: (data: any) => any, errorCallback?: (data: any) => any)

--

error

Hook to know if a Cryptr error occured

The return type is a String

const { error } = useCryptr()

isLoading

Hook to inform you that a Cryptr process is in progress.

The return type is a boolean

const { isLoading } = useCryptr()

signIn

Hook action to sign in the user using his organization's domain.

const { signIn } = useCryptr();

// Signature
signIn(successCallback? (data: any) => any, errorCallback?: (data: any) => any)

// Sign in for domain `company-dot-io`
signIn()

Components

This SDK also includes Components to simplify your integration.

• CryptrGatewayButton to log in either with domain or email (hides when session is already active [autoHide={false} to disable])
• SignInButton to log in either when not knowing neither email or domain, the user will be asked to fill a form (hides when session is already active [autoHide={false} to disable])
• LogOutButton to logout user (hides when no session is active [autoHide={false} to disable])
• RefreshButton to get new tokens (hides when session is already active [autoHide={false} to disable])

Migration details

To v1.0.0

Configuration change

| old key | new key | | --- | --- | | tenant_domain | accountDomain | | client_id | clientId | | default_redirect_uri | defaultRedirectUri | | cryptr_base_url | cryptrServiceUrl | | dedicated_server | dedicatedServer |

Components/hooks

If you either used signInWithDomain() hook or <CryptrGatewayButton/> component without domain parameter, please use now signIn or <SignInButton/> accordingly

For easier usage of user hook this one changed from function () => User | undefined, now it's directly a User | undefined