Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/wkh237/react-native-azure-ad

React Native module implements Azure AD authentication flow in pure js
https://github.com/wkh237/react-native-azure-ad

azure azure-active-directory react-native

Last synced: 5 months ago
JSON representation

React Native module implements Azure AD authentication flow in pure js

Awesome Lists containing this project

README 

          
# react-native-azure-ad

[![npm version](https://badge.fury.io/js/react-native-azure-ad.svg)](https://badge.fury.io/js/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](#user-content-installation)

* [Usage](#user-content-usage-example)

 * [Login](#user-content-login)

 * [Logout](#user-content-logout)

 * [RefreshToken](#user-content-refresh-token)

* [ADLoginView](#user-content-adloginviewwebview)

* [Class ReactNativeAD](#user-content-class-reactnativead)

  * [Constructor](#user-content-constructor)

  * [Properties](#user-content-properties)

     * [config](#user-content-config-ADConfig)

     * [credentials](#user-content-credentials-ADCredentials)

  * [Frequently used methods](#user-content-frequently-used-methods)

     * [getConfig ():ADConfig](#user-content-getconfig-adconfig)

     * [getCredentials ():ADCredentials](#user-content-getcredentials-adcredentials)

     * [assureToken (resource:string):Promise]()

  * [Methods for internal mechanism](#user-content-methods-for-internal-mechanism)

     * [getAccessToken (resource:string):string | null]()

     * [saveCredentials (data:ADCredentials):Promise]()

     * [refreshToken (resourceId:string):Promise]()

     * [checkCredential (resourceId:string):Promise]()

     * [grantAccessToken (grantType:string, params:any):Promise]()

* [Flow Types](#user-content-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.



```js



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 : 'user@domain.com',	  

      // 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 

  }



  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.



```



```



### 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](https://facebook.github.io/react-native/docs/webview.html#content) 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



```js

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](http://facebook.github.io/react-native/releases/0.25/docs/asyncstorage.html#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 :



```js



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//oauth2/authorize` by default, where `` 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](https://docs.microsoft.com/en-us/azure/active-directory/active-directory-protocols-openid-connect-code) 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` **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]`](#user-content-adconfig)



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



[`credentials:[ADCredentials]`](#user-content-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](#user-content-ReactNativeADCredential) object as value.



### Frequently used methods



#### getConfig ():[ADConfig](#user-content-adconfig)



This method returns the ReactNativeAD instance's `config` property.



#### getCredentials ()`:[ADCredentials](#user-content-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



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



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



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 | 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'

}

```