react-native-azure-ad

An React Native module implements Azure AD authentication flow using pure React Native API. You can use both web application flow and mobile application client_id with this module.

• Installation
• Usage
• Login
• Logout
• RefreshToken
• ADLoginView
• Class ReactNativeAD
  • Constructor
  • Properties
    • config
    • credentials
  • Frequently used methods
    • getConfig ():ADConfig
    • getCredentials ():ADCredentials
    • assureToken (resource:string):Promise<?string>
  • Methods for internal mechanism
    • getAccessToken (resource:string):string | null
    • saveCredentials (data:ADCredentials):Promise
    • refreshToken (resourceId:string):Promise
    • checkCredential (resourceId:string):Promise<ReactNativeADCredential | null>
    • grantAccessToken (grantType:string, params:any):Promise
• Flow Types

Installation

Install package from npm

$ npm install --save react-native-azure-ad

react-native-azure-ad implements authentication flow using fetch API and Webview component in React Native, therefore there's no need to install Android and iOS native ADAL.

Usage Example

Login

The following example will show an Azure authorize page in your app, when user successfully logged in, it triggers onSuccess method.

import {ReactNativeAD, ADLoginView} from 'react-native-azure-ad'

const CLIENT_ID = 'xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'

class LandingView extends React.Component {

  constructor(props) {
    super(props)
    this.AzureADContext = {
      client_id : CLIENT_ID,
      // Optional
      redirect_url : 'http://localhost:8080',  
      // Optional
      authority_host : 'https://login.microsoftonline.com/common/oauth2/authorize',
      // Optional
      tenant  : 'common',  
      // Optional
      prompt : 'none',
      // Optional
      login_hint : '[email protected]',	  
      // This is required if client_id is a web application id
      // but not recommended doing this way.
      client_secret : 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
      resources : [
        'https://graph.microsoft.com',
        'https://outlook.office365.com',
        // ... more resources
      ]
    }
  }

  render() {

  new ReactNativeAD({
    client_id: CLIENT_ID,
    resources: [
      'https://outlook.office365.com'
    ]})
  
    return <ADLoginView
              context={ReactNativeAD.getContext(CLIENT_ID)}
              onSuccess={this.onLoginSuccess.bind(this)}/>
  }

  onLoginSuccess(credentials) {
    console.log(credentials[https://outlook.office365.com].access_token)
    // use the access token ..
  }

}

Logout

When a ADLoginView has prop needLogout set to true it redirect user to AD logout page for logout.

<ADLoginView
              context={ReactNativeAD.getContext(CLIENT_ID)}
              needLogout={true}/>

Refresh Token

Use assureToken method to assure access_token of specific resource is valid, when access token is expired, this method will attempt to refresh access token automatically and resolve renewed access token in promise. If it failed to renew the token, the access token in promise will be undefined, it means user may have to login again, so you might have to redirect user to ADLoginView for new authorization.

ReactNativeAD.getContext(CLIENT_ID).assureToken(RESOURCE_ID).then((token) => {

 // use token ..

})

ADLoginView:Webview

ADLoginView is it's a wrapped Webview component, it will display the login page by given prop context, when user is authorized, it execute the function in prop onSuccess.

props

style:object (opational)

Additional styles of the webview component.

context:ReactNativeAD Required

Azure AD context instance that apply to this ADLoginView, it should be a ReactNativeAD instance, usually you will have one or more ReactNativeAD instances in your app, once you new a ReactNativeAD with a client_id in config, you can access the context globally in your this way

let ctx = ReactNativeAD.getContext('client-id-of-the-instance')

onSuccess:function (optional)

A function to execute when ADLoginView completes authorization flow.

needLogout:bool (optional)

When it set to true, ADLoginView will logout user and redirect user to AD login page.

hideAfterLogin (optional)

When this property set to true, ADLoginView will be hidden after logged in, in prevention of displaying an empty/error web page.

onURLChange (optional)

A event listener which triggers when ADLoginView's URL change.

Class ReactNativeAD

You will need to create at least one ReactNativeAD object in your application, the ReactNativeAD object stores, and update authentication information in AsyncStorage automatically, it also provides several API for access theses informations.

Constructor

To create a ReactNativeAD instance you have to give a configuration object as the first argument of constructor. Once the ReactNativeAD object created, you can access it globally in your application like this :

new ReactNativeAD({
  client_id: 'client-id-#1',
  resources: [
    'https://outlook.office365.com'
  ]})

// this will return the object we created above  
let ctx = ReactNativeAD.getContext('client-id-#1')
// use the stored context
ctx.assureToken('https://outlook.office365.com').then((token) => {
  ...
})

The configuration object contains the following properties :

client_id:string Required

The application client_id, this property is required, it's also the identifier of each ReactNativeAD context.

redirect_url:string Optional

An url that ADLoginView will be redirect when login success, this property is optional.

authority_host:string Optional

The url of authorization page, if not specified, it will use https://login.microsoftonline.com/<tenant id>/oauth2/authorize by default, where <tenant id> will be replaced with property tenant, if the default tenant is common.

tenant:string Optional

The tenant id of application.

prompt:string Optional

Indicates the type of user interaction that is required. The only valid values are 'login', 'none' and 'consent'. For details, please refer to this documentation.

login_hint:string Optional

Can be used to pre-fill the username/email address field of the sign-in page for the user, if you know their username ahead of time.

client_secret:string Required if use web application client_id

This property is only required when your application uses a web application client_id, but it is not recommended to do this way, because store client_secret in application could be dangerous.

resouces:Array<string> Required

A list of Azure AD resource endpoints, once user has authorized ADLoginView will try to acquire access token and related information of each resource endpoint you specified in this property.

Properties

config:[ADConfig]

This property stores configurations (such as client_id, resources ..) of a ReactNativeAD instance.

credentials:[ADCredentials]

This property stores acquired credential informatio for each resource endpoint. It a hash map structured data, with resource id as key, and a ReactNativeADCredential object as value.

Frequently used methods

getConfig ():ADConfig

This method returns the ReactNativeAD instance's config property.

getCredentials ()`:ADCredentials

This method returns the ReactNativeAD instance's credentials property.

getAccessToken(resouceId:string):string | null

Get access token by given resource id, if no corresponding token exists returns null.

assureToken(resource:string):Promise<?string>

Assure that access_token of a resource is valid, when access token is expired, this method will attempt to refresh access token automatically and resolve renewed access token in promise. If it failed to renew the token, the access token in promise will be undefined, it means user may have to login again, so you might have to redirect user to ADLoginView for new authorization.

Methods for internal mechanism

saveCredentials(data:ADCredentials):Promise

This method replace the ReactNativeAD instance's credentials property with the object in data argument. It will also save the each entry in data into AsyncStorage, with key = .. For example, if client_id of this ReactNativeAD instance is eabc-123 and one of the entry's key is http://graph.microsoft.com(aka. resource id), then the data in this entry will be stored in AsyncStorage with key eabc-123.http://graph.microsoft.com.

refreshToken(resourceId:string):Promise<?string>

Refresh token of the resource, when credentials is empty, it will try to update access token for resource. The access token in promise is possible to be undefined, it means user may have to login again, so you might have to redirect user to ADLoginView for new authorization.

checkCredential(resourceId:string):Promise<ReactNativeADCredential | null>

Check credentials of the resource exist or not.

grantAccessToken(grantType:string, params:any):Promise

Get access_token by given grant_type and params, when this process success, it stores credentials in format of ReactNativeADCredentials, in both ReactNativeAD.credentials and AsyncStorage.

Flow Types

ADConfig

{
  client_secret : string | null,
  client_id : string | null,
  redirect_url : string | null,
  tenant : string | null,
  prompt : string | null,
  resources : Array<string> | null,
  login_hint : string | null,
}

ADCredentials

{
  [key:string] : ReactNativeADCredential | null
}

GrantTokenResp

{
  resource : string,
  response : Object
}

ReactNativeADConfig

{
  client_id : string,
  redirect_url? : string,
  authority_host : string,
  tenant : string,
  client_secret : string,
  resources : any,
  onSuccess : Function,
}

ReactNativeADCredential

{
  access_token : string,
  expires_in : number,
  expires_on : number,
  id_token : string,
  not_before : number,
  pwd_exp : string,
  pwd_url : string,
  refresh_token : string,
  resource : string,
  scope : string,
  token_type : 'Bearer'
}