Your suggested change has been received. Thank you.

close

Suggest A Change

https://thales.na.market.dpondemand.io/docs/dpod/services/kmo….

Thales Logo

All

  • All
back

React Native SDK

Reference guides

search

Reference guides

This section describes the APIs that are exposed by the React Native SDK.

The following methods are available:

Start

User

Authenticators

Device

Resource

Mobile authentication

Events

acceptMobileAuthConfirmation

When a user is enrolled for mobile authentication, they are able to receive and respond to mobile authentication requests. This method accepts the mobile authentication request. See Mobile authentication and Mobile authentication with OTP for more details.

OneWelcomeSdk.acceptMobileAuthConfirmation()
    .then(() => {
        console.log('Accept mobile auth success! ')
    })
    .catch(error => {
        console.error('Accept mobile auth failed: ', error.message)
    })

addEventListener

The SDK uses events to communicate changes in the current state.

Example code - add event listeners

Listeners for a specific event can be added with the following functions and are described in their corresponding topic guides.

Property Type Description
Property Type Description
eventType SdkNotification Name of the event e.g. Events.PinEvent
callback (event: Events.SdkEvent) => void Callback function 
interface NativeMethods {
  addEventListener(
    eventType: Events.SdkNotification.Pin,
    callback?: (event: Events.PinNotificationEvent) => void,
    ): EmitterSubscription;

  addEventListener(
    eventType: Events.SdkNotification.CustomRegistration,
    callback?: (event: Events.CustomRegistrationNotificationEvent) => void,
    ): EmitterSubscription;

  addEventListener(
    eventType: Events.SdkNotification.MobileAuthOtp,
    callback?: (event: Events.MobileAuthOtpNotificationEvent) => void,
    ): EmitterSubscription;

  addEventListener(
    eventType: Events.SdkNotification.Fingerprint,
    callback?: (event: Events.FingerprintNotificationEvent) => void,
    ): EmitterSubscription;

 // ...
}

Example code - handling pinEvent

Handling the events with a switch allows for automatic type inference of the events.

const handleNotification = useCallback(
  async (event: Events.PinEvent) => {
    console.log('handle PIN notification event: ', event);
    // Handling the events with a switch on the event.action will result in type inference.
    switch (event.action) {
      case Events.Pin.Open:
        await handleOpen(event);
        break;
      case Events.Pin.Close:
        setInitialState();
        break;
      case Events.Pin.IncorrectPin:
        handleIncorrectPin(event);
        break;
      case Events.Pin.PinNotAllowed:
        handlePinNotAllowed(event);
        break;
    }
  },
  [handleOpen, setConfirmState, handleError, setInitialState],
);

useEffect(() => {
  const listener = OnewelcomeSdk.addEventListener(
    Events.SdkNotification.Pin,
    handleNotification,
  );

  return () => {
    listener.remove();
  };
}, [handleNotification]);

Example code - event signatures

export type SdkEvent =
  | PinCreateEvent
  | PinAuthenticationEvent
  | CustomRegistrationEvent
  | FingerprintEvent
  | MobileAuthOtpEvent
  | RegistrationURLEvent;

// Pin
export type PinCreateEvent =
  | PinCreateCloseEvent
  | PinCreateOpenEvent
  | PinNotAllowedEvent;

export type PinAuthenticationEvent =
  | PinAuthenticationCloseEvent
  | PinAuthenticationOpenEvent
  | IncorrectPinEvent;

// Create Pin
export type PinCreateCloseEvent = {
  action: PinCreate.Close;
  flow: PinFlow.Create;
};

export type PinCreateOpenEvent = {
  flow: PinFlow.Create;
  action: PinCreate.Open;
  profileId: string;
  pinLength: number;
};

export type PinNotAllowedEvent = {
  flow: PinFlow.Create;
  action: PinCreate.PinNotAllowed;
  errorType: number;
  errorMsg: string;
};

// Authentication Pin

export type PinAuthenticationCloseEvent = {
  action: PinAuthentication.Close;
  flow: PinFlow.Authentication;
};

export type PinAuthenticationOpenEvent = {
  flow: PinFlow.Authentication;
  action: PinAuthentication.Open;
  profileId: string;
};

export type IncorrectPinEvent = {
  flow: PinFlow.Authentication;
  action: PinAuthentication.IncorrectPin;
  errorType: number;
  errorMsg: string;
  remainingFailureCount: number;
};
//Registration
export type RegistrationURLEvent = {
  url: string;
};

//CustomRegistration
export type CustomRegistrationEvent =
  | initRegistrationEvent
  | finishRegistrationEvent;

export type initRegistrationEvent = {
  action: CustomRegistration.InitRegistration;
  identityProviderId: string;
  customInfo?: {
    data: string;
    status: number;
  };
};

export type finishRegistrationEvent = {
  action: CustomRegistration.FinishRegistration;
  identityProviderId: string;
  customInfo?: {
    data: string;
    status: number;
  };
};

//MobileAuthOtp
export type MobileAuthOtpEvent =
  | startOtpAuthenticationEvent
  | finishOtpAuthenticationEvent;

export type startOtpAuthenticationEvent = {
  action: MobileAuthOtp.StartAuthentication;
  mobileAuthenticationRequest: {
    message: string;
    type: string;
    transactionId: string;
    signingData: string;
  };
};

export type finishOtpAuthenticationEvent = {
  action: MobileAuthOtp.FinishAuthentication;
  mobileAuthenticationRequest: {
    message: string;
    type: string;
    transactionId: string;
    signingData: string;
  };
};

//FingerPrint
export type FingerprintEvent =
  | startFingerprintAuthenticationEvent
  | onNextFingerprintAuthenticationAttemptEvent
  | onFingerprintCapturedEvent
  | finishFingerprintAuthenticationEvent;
export type startFingerprintAuthenticationEvent = {
  action: Fingerprint.StartAuthentication;
  userProfile: {
    profileId: string;
  };
};
export type onNextFingerprintAuthenticationAttemptEvent = {
  action: Fingerprint.OnNextAuthenticationAttempt;
};
export type onFingerprintCapturedEvent = {
  action: Fingerprint.OnFingerprintCaptured;
};
export type finishFingerprintAuthenticationEvent = {
  action: Fingerprint.FinishAuthentication;
};

authenticateUser

Your users can authenticate themselves using any authenticator registered to them. If a user is already authenticated when calling this function, they will be logged out and have to authenticate again.

It may be required to handle authentication with some additional action (PIN/Fingerprint) handling. Refer to addEventListener for more information.

Property Type Description
profileId string The profile ID for which you want to authenticate
authenticatorId string null The authenticator that you want to use, uses preferred when null 
OneWelcomeSdk.authenticateUser(profileId, authenticatorId)
  .then(authData => {
    console.log('User authentication succeed!')
  })
  .catch(error => {
    console.log('User authentication failed!: ', error.message)
  })

authenticateDeviceForResource

The device can be authenticated for anonymous resource calls with specific (or the default) scopes.

Property Type Description
scopes string[] Set of scopes the client authentication is requested for 
OneWelcomeSdk.authenticateDeviceForResource(path)
  .then(() => {
    console.log('Device Authentication succeed!')
  })
  .catch(error => {
    console.log('Device Authentication failed!: ', error.message)
  })

authenticateUserImplicitly

You can use implicit authentication to authenticate users based on their client credentials. This means you can assume the user has successfully completed the registration process in the past. After authenticating implicitly, you can fetch resources that require implicit authentication. Implicit authentication requires no user interaction like asking for their PIN or fingerprint.

Property Type Description
profileId string The profile ID you previously stored during registration
scopes string[] An array of scopes the user will authenticate with (optional) 
OneWelcomeSdk.authenticateUserImplicitly(profileId, ['account-balance'])
  .then(profile => {
    console.log('User implicitl authentication succeed!')
  })
  .catch(error => {
    console.log('User implicitl authentication failed!: ', error.message)
  })

cancelPinCreation

You can call this method in order to cancel the PIN creation. If PIN creation is in progress, this will also cause the PinCreate.Close event to be sent.

Canceling the PIN creation during the user registration or change PIN flows will cause these flows to be canceled.

If this method succeeds, it will cause the original promise that started the PIN creation to succeed.

cancelPinCreation(): Promise<void>;

cancelBrowserRegistration

This method cancels the browser registration flow. See user registration for more information.

Warning

This method should not be used when PIN creation has already started. Use the cancelPinCreation method instead.

cancelBrowserRegistration(): Promise<void>;

cancelCustomRegistration

You can call this method in order to cancel any custom registration flow that is currently active.

This method cancels any custom registration flow that is active. See User registration for more information.

Property Type Description
message string The error message that will get relayed back to the rejection of the registerUser (only on Android)

Warning

This method should not be used when PIN creation has already started. Use the cancelPinCreation method instead.

cancelCustomRegistration(message: string): Promise<void>;

cancelPinAuthentication

You can call this method in order to cancel the PIN authentication. If PIN authentication is in progress, this will also cause the PinAuthentication.Close event to be sent.

Canceling the PIN creation during user authentication or change PIN flows will cause these flows to be canceled.

cancelPinAuthentication(): Promise<void>;

changePin

Once authenticated, a user is able to change their PIN. This method starts the flow. For further actions refer to ChangePIN for more details.

OneWelcomeSdk.changePin()
  .then(() => {
    console.log('Change Pin action succeed!')
  })
  .catch(error => {
    console.log('Change Pin action failed!: ', error.message)
  })

denyMobileAuthConfirmation

When a user is enrolled for mobile authentication, they are able to receive and respond to mobile authentication requests. This method declines the mobile authentication request.

OneWelcomeSdk.denyMobileAuthConfirmation()
    .then(() => {
        console.log('Accept mobile auth success! ')
    })
    .catch(error => {
        console.error('Accept mobile auth failed: ', error.message)
    })

deregisterAuthenticator

Used to deregister an authenticator for the currently authenticated user.

Property Type Description
type string The ID of the authenticator you want to deregister 
OneWelcomeSdk.deregisterAuthenticator('com.onegini.authenticator.TouchID')
  .then(() => {
    console.log('Register Authenticator succeed!')
  })
  .catch(error => {
    console.log('Register Authenticator failed!: ', error.message)
  })

deregisterUser

Deregistration is the process of removing a user (profile) from the device and server.

Property Type Description
profileId string The profile that you want to deregister 
OneWelcomeSdk.deregisterUser(profileId)
    .then(() => console.log('Deregister succeed!'))
    .catch(error => console.error('Deregister failed: ', error.message))

enrollMobileAuthentication

Authenticated users can enroll for mobile authentication, allowing them to execute mobile authentication with OTP. See the mobile authentication and mobile authentication with OTP topics for more information.

OneWelcomeSdk.enrollMobileAuthentication()
    .then(() => {
        console.log('Enroll success! ')
    })
    .catch(error => {
        console.error('Enroll failed: ', error.message)
    })

getAccessToken

This method returns the current access token if authenticated.

OneWelcomeSdk.getAccessToken()
  .then((token) => {
    console.log('Current accessToken', token)
  })
  .catch(error => {
    console.log('Error: ', error.message)
  })

getAllAuthenticators

Used to get an array of authenticators available for a specific user.

Property Type Description
profileId string The profile for which you want to retrieve all authenticators 
getAllAuthenticators(profileId: string): Promise<Authenticator[]>

OneWelcomeSdk.getAllAuthenticators(profileId)
  .then(authenticators => {
    console.log('getAllAuthenticators succeed: ', authenticators)
  })
  .catch(error => {
    console.log('getAllAuthenticators failed!: ', error.message)
  })

getAuthenticatedUserProfile

This method retrieves the currently authenticated user (profile).

Property Type Description
authenticatedProfile Profile Currently authenticated user profile 
OneWelcomeSdk.getAuthenticatedUserProfile()
  .then(profile => {
    console.log('Authenticated Profile succeed! ', profile)
  })
  .catch(error => {
    console.log('Authenticated Profile failed!: ', error.message)
  })

getIdentityProviders

This method returns the list of identity providers that are available in the IDAAS-core.

Property Type Description
identityProviders IdentityProvider[] The list of identityProviders available in the IDAAS-core 
interface OneWelcomeSdk {
    getIdentityProviders(): Promise<Types.IdentityProvider[]>;
}

OneWelcomeSdk.getIdentityProviders().then((identityProviders) => {
  console.log('identityProviders: ', identityProviders);
}).catch(error => {
  console.log('Error: ', error.message)
});

getRedirectUri

Returns the current redirect URI used in registration with a browser IdP. See Registration with browser IdP for more details.

OneWelcomeSdk.getRedirectUri()
  .then((uri: string) => {
    console.log('Redirect Uri succeed! ', uri)
  })
  .catch(error => {
    console.log('Redirect Uri failed!: ', error.message)
  })

getRegisteredAuthenticators

Used to get an array of authenticators registered for a specific user.

Property Type Description
profileId string The profile for which you want to get the registered authenticators 
OneWelcomeSdk.getRegisteredAuthenticators(profileId)
  .then(authenticators => {
    console.log('getRegisteredAuthenticators succeed: ', authenticators)
  })
  .catch(error => {
    console.log('getRegisteredAuthenticators failed!: ', error.message)
  })

getResourceBaseUrl

This method returns the resource BaseUrl as defined in the config so it can be used to as a path for a resourceRequest.

const baseUrl = await OnewelcomeSdk.getResourceBaseUrl();

getUserProfiles

This method returns the list of registered user profiles on the device.

Property Type Description
profiles Profile[] The list of registered user profiles 
OneWelcomeSdk.getUserProfiles()
  .then((profiles) => {
    console.log('Registered profiles: ', profile)
  })
  .catch(error => {
    console.log('Error: ', error.message)
  })

handleMobileAuthWithOtp

When a user is enrolled for mobile authentication, they are able to receive and respond to mobile authentication requests. This method responds to the mobile authentication with OTP request with an otpCode. See Mobile authentication with OTP for more details.

Property Type Description
otpCode string One-time password code to be sent 
OneWelcomeSdk.handleMobileAuthWithOtp('base64 encoded OTP')
  .then(() => {
    console.log('Handle Mobile Auth with Otp succeed!')
  })
  .catch(error => {
    console.log('Handle Mobile Auth with Otp failed!: ', error.message)
  })

handleRegistrationCallback

Used to pass the redirect URI, received from the browser registration, to the SDK.

Property Type Description
uri string Registration URI 
useEffect(() => {
    const handleOpenURL = (event: {url: string}) => {
      if (event.url.substring(0, event.url.indexOf(':')) === redirectUri) {
        OneWelcomeSdk.handleRegistrationCallback(event.url);
      }
    };

    const listener = Linking.addListener('url', handleOpenURL);
    return () => {
      if (listener) {
        listener.remove();
      }
    };
  }, [redirectUri]);

logout

For security reasons, it is always advisable to explicitly logout a user. The OneWelcome Identity Platform React Native SDK exposes the following function to do so.

OneWelcomeSdk.logout()
  .then(() => {
    console.log('Logout succeed!')
  })
  .catch(error => {
    console.log('Logout failed!: ', error.message)
  })

registerAuthenticator

Used to register a new authenticator for the currently authenticated user.

Property Type Description
type string The ID of the authenticator you want to register. 
OneWelcomeSdk.registerAuthenticator('com.onegini.authenticator.TouchID')
  .then(() => {
    console.log('Register Authenticator succeed!')
  })
  .catch(error => {
    console.log('Register Authenticator failed!: ', error.message)
  })

registerUser

Before a user can authenticate using a PIN or fingerprint, a user will need to register with your IDAAS-core. Registration can be initiated using this method.

It may be required to handle registration with some additional action (PIN or fingerprint) handling. The SDK notifies the app about the state of the registration by the use of events. The application should listen for these using the addEventListener.

Property Type Description
identityProviderId string null Identity provider ID or null for default
scopes (optional) string[] An array of scopes the user will register for 
OneWelcomeSdk.registerUser(providerId)
    .then(authData => {
        console.log('Registration success! ')
    })
    .catch(error => {
        console.error('Registration failed: ', error.message)
    })

const handleNotification = useCallback(
  async (event: any) => {
    switch (event.action) {
      case Events.PinNotification.Open:
        await handleOpen(event.flow, event.profileId, event.data);
        break;
      case Events.PinNotification.Error:
        handleError(event.errorMsg, event.userInfo ?? undefined);
        break;
      case Events.PinNotification.Close:
        setInitialState();
        break;
    }
  },
  [handleOpen, setConfirmState, handleError, setInitialState],
);

// The Flow of registration gets passed by events. 
const listener = OnewelcomeSdk.addEventListener(
  Events.SdkNotification.Pin,
  handleNotification,
);

resourceRequest

Resources can be fetched using user authentication, implicit authentication, or anonymous authentication.

Property Type Description
type ResourceRequestType Request type User, ImplicitUser, Anonymous
details ResourcesDetails Request details, such as method type ('GET') 
const baseUrl = await OnewelcomeSdk.getResourceBaseUrl();

const details = {
  path: baseUrl + 'user-id-decorated',
  method: ResourceMethod.GET
}

OneWelcomeSdk.resourceRequest('Anonymous', details)
  .then(response => {
    console.log('Resources request succeed! ')
  })
  .catch(error => {
    console.log('Resources request failed!: ', error.message)
  })

setPreferredAuthenticator

Used to get the preferred authenticator for the currently authenticated user.

Property Type Description
authenticatorId string The authenticator ID that you want to set as a preferred authenticator 
OneWelcomeSdk.setPreferredAuthenticator(authenticatorId)
  .then(()) => {
    console.log('setPreferredAuthenticator succeed!')
  })
  .catch(error => {
    console.log('setPreferredAuthenticator failed!: ', error.message)
  })

startClient

The first thing that needs to be done when the app starts is to initialize the OneWelcome Identity Platform React Native SDK. This will perform a few checks and report an error in case of any problems.

Property Type Description
sdkConfig Config Config used for initializing the SDK 
const config: Types.Config = {
  enableFingerprint: true,
  securityControllerClassName:
    'com.onegini.mobile.rnexampleapp.SecurityController',
  enableMobileAuthenticationOtp: true,
  customProviders: [
    {id: '2-way-otp-api', isTwoStep: true},
    {id: 'qr_registration', isTwoStep: false},
  ],
  configModelClassName: null,
};

OneWelcomeSdk.startClient(config)
    .then(() => console.log('Start succeed'))
    .catch(error => console.log('Start failed: ', error.message))

startSingleSignOn

Returns a single sign-on data object that allows you to continue the session in an external browser. Observable app behavior is a redirection of the user to a web app where the user is logged in.

Call the startSingleSignOn with the target URI and wait for the result. In case of success, the SingleSignOnData object will be returned. 

const exampleUrl = "https://login-mobile.test.onegini.com/personal/dashboard"

OneginiSdk.startSingleSignOn(exampleUrl)
  .then((it) => {
    // open external browser
    Linking.openURL(it.url)
  })
  .catch(error) => {
    Alert.alert('Error', error.message)
  })

submitCustomRegistrationAction

Method that allows you to submit the token for a custom registration with a custom identity provider.

Property Type Description
identityProviderId string The ID of the identity provider for which you want to submit the token
token string The token to be submitted 
OneWelcomeSdk.submitCustomRegistrationAction(
  event.identityProviderId,
  token,
).then(() => {
  console.log('Token submit successfully');
}.catch((error) => {
  console.log('Error: ' + error.message)
}))

submitFingerprintAcceptAuthenticationRequest

Submit accept for a fingerprint authorization request.

Note

This method is Android only, because iOS handles this natively with the native prompt.

OneWelcomeSdk.submitFingerprintAcceptAuthenticationRequest()
    .then(() => {
        console.log('Submit accept success!')
    })
    .catch(error => {
        console.error('Submit accept failed: ', error.message)
    })

submitFingerprintDenyAuthenticationRequest

Submit deny for a fingerprint authorization request.

Note

This method is Android only, because iOS handles this natively with the native prompt.

OneWelcomeSdk.submitFingerprintDenyAuthenticationRequest()
    .then(() => {
        console.log('Submit deny success!')
    })
    .catch(error => {
        console.error('Submit deny failed: ', error.message)
    })

submitFingerprintFallbackToPin

If fingerprint authorization can't be used, you can force the SDK to fallback to PIN.

Note

This method is Android only, because iOS handles this natively with the native prompt.

OneWelcomeSdk.submitFingerprintFallbackToPin()
    .then(() => {
        console.log('Fallback success! ')
    })
    .catch(error => {
        console.error('Fallback failed: ', error.message)
    })

submitPin

stf_product: OneWelcome Identity Platform

Method that allows you to submit the PIN for PIN authentication or PIN creation.

Property Type Description
flow PinFlow Current flow, such as 'authentication', 'create'
pin string PIN 
OneWelcomeSdk.submitPin(
    Events.PinFlow.Create,
    '123456'
)

validatePinWithPolicy

Validates the supplied PIN against the PIN policy enforced by the IDAAS-core, the policy will be checked on the device and the PIN will never be sent over the internet.

OneWelcomeSdk.validatePinWithPolicy(pin)
    .then(() => {
        console.log('The pin is allowed!')
    })
    .catch(error => {
        console.error('Error: ', error.message)
    })

On this page