The Okta React Native library makes it easy to add authentication to your React Native app. This library is a wrapper around Okta OIDC Android and Okta OIDC iOS.
This library follows the current best practice for native apps using:
This library also exposes APIs to interact with Authentication API directly to implement native UI for authentication.
You can learn more on the Okta + ReactNative page in our documentation. You can also download our sample application
In Okta, applications are OpenID Connect clients that can use Okta Authorization servers to authenticate users. Your Okta Org already has a default authorization server, so you just need to create an OIDC client that will use it.
Setting | Value |
---|---|
App Name | My Native App |
Login redirect URIs | com.mynativeapp:/ |
Grant Types Allowed | Authorization Code, Refresh Token |
After you have created the application there are two more values you will need to gather:
Setting | Where to Find |
---|---|
Client ID | In the applications list, or on the “General” tab of a specific application. |
Org URL | On the home screen of the developer dashboard, in the upper right. |
Note: As with any Okta application, make sure you assign Users or Groups to the OpenID Connect Client. Otherwise, no one can use it.
These values will be used in your React application to setup the OpenID Connect flow with Okta.
This library is available through npm. To install it, simply add it to your project:
$ npm install @okta/okta-react-native --save
$ react-native link @okta/okta-react-native
Perform the following Manual installation steps if you’re not using react-native link
.
Libraries
➜ Add Files to [your project's name]
node_modules
➜ @okta/okta-react-native
and add ReactNativeOktaSdkBridge.xcodeproj
libReactNativeOktaSdkBridge.a
to your project’s Build Phases
➜ Link Binary With Libraries
Cmd+R
)<android/app/src/main/java/[...]/MainApplication.java
import com.oktareactnative.OktaSdkBridgePackage;
to the imports at the top of the filenew OktaSdkBridgePackage()
to the list returned by the getPackages()
methodAppend the following lines to android/settings.gradle
:
include ':@okta/okta-react-native'
project(':@okta/okta-react-native').projectDir = new File(rootProject.projectDir, '../node_modules/@okta/okta-react-native/android')
Insert the following lines inside the dependencies block in android/app/build.gradle
:
compile project(':@okta_okta-react-native')
To setup iOS, there are three steps that you must take.
11.0
and above.This library supports iOS version 11.0
and above. Go to your project -> Build settings
-> iOS Deployment Target
, and set it to at least version 11.0
.
This library depends on the native Okta OIDC iOS library. It is not distributed as part of the React Native library to keep your dependency management consistent.
You can currently add Okta OIDC iOS through CocoaPods:
CocoaPods
React Native >= 0.60: With React Native 0.60 pods are added to podfile automatically. Run pod install
command to install dependecies:
cd ios
pod install
React Native < 0.60: Make sure your Podfile
looks like this:
platform :ios, '11.0'
target '{YourTargetName}' do
pod 'OktaOidc', '~> 3.0'
end
Then run pod install
.
Carthage With Carthage, add the following line to your Cartfile:
github "okta/okta-oidc-ios" ~> 3.5.0
Then run carthage update --platform iOS
.
Open project settings and choose your application target. Then open Build Phases
and add OktaOidc.framework
from ios/Carthage/Build/iOS
into Embed Frameworks
section
For Android, there are two steps that you must take:
This library depends on the native Okta OIDC Android library. You have to add this library through Gradle. Follow the following steps:
Add this line to android/build.gradle
, under allprojects
-> repositories
.
maven {
url "https://dl.bintray.com/okta/com.okta.android"
}
Make sure your minSdkVersion
is 21
in android/build.gradle
.
Defining a redirect scheme to capture the authorization redirect. In android/app/build.gradle
, under android
-> defaultConfig
, add:
manifestPlaceholders = [
appAuthRedirectScheme: 'com.sampleapplication'
]
You will need the values from the OIDC client that you created in the previous step to set up. You will also need to know your Okta Org URL, which you can see on the home page of the Okta Developer console.
Before calling any other method, it is important that you call createConfig
to set up the configuration properly on the native modules.
Importing methods would follow this pattern:
import { createConfig, signIn, signOut, getAccessToken } from '@okta/okta-react-native';
createConfig
This method will create a configured client on the native modules. Resolves true
if successfully configures a client. Note: requireHardwareBackedKeyStore
is a configurable setting only on android devices. If you’re a developer testing on android emulators, set this field to false
.
Note: issuer
is an optional field in config, for more information please refer to About the Issuer
Note: androidChromeTabColor
is an optional field in config, and is used only by Android for the Chrome Custom Tabs color for the OIDC flow.
Note: httpConnectionTimeout
and httpReadTimeout
are optional fields in config. These are used for HTTP requests performed by the SDK. Timeouts are in seconds.
await createConfig({
issuer: "https://{yourOktaDomain}/oauth2/default", // optional
clientId: "{clientId}",
redirectUri: "{redirectUri}",
endSessionRedirectUri: "{endSessionRedirectUri}",
discoveryUri: "https://{yourOktaDomain}",
scopes: ["openid", "profile", "offline_access"],
requireHardwareBackedKeyStore: true,
androidChromeTabColor: "#FF00AA",
httpConnectionTimeout: 15,
httpReadTimeout: 10,
});
getAuthClient
This method will return an instance of @okta/okta-auth-js
client to communicate with Okta Authentication API. For more information, please checkout Okta AuthJs Node JS and React Native Usage section.
signIn
This method will handle both browser-sign-in
and custom-sign-in
scenarios based on provided options.
This async method will automatically redirect users to your Okta organziation for authentication. It will emit an event once a user successfully signs in. Make sure your event listeners are mounted and unmounted. Note: on iOS there isn’t a onCancelled
event. If the sign in process is cancelled, onError
will be triggered.
browser-sign-in
browser-sign-in
leverages device’s native browser to automatically redirect users to your Okta organziation for authentication. By providing no argument, this method will trigger the browser-sign-in
flow. It will emit an event once a user successfully signs in. Make sure your event listeners are mounted and unmounted. Note: on iOS there isn’t a onCancelled
event. If the sign in process is cancelled, onError
will be triggered.
signInWithBrowser();
Note: IDP can be passed by specifying an argument with the idp parameter.
signInWithBrowser({ idp: 'your_idp_here' });
custom-sign-in
custom-sign-in
provides the way to authenticate the user within the native application. By providing options
object with username and password fields, this method will retrieve sessionToken
then exchange it for accessToken
. Both Promise
and Event listeners
are supported. This method is leveraging @okta/okta-auth-js
SDK to perform authentication API request. For more information, please checkout Okta AuthJs signIn options section.
signIn({ username: "{username}", password: "{password}" })
.then(token => {
// consume accessToken from token.access_token
})
.catch(error => {
// { code: "", message: "", detail: { message: "", status: "" } }
// handle error
})
import { signIn, EventEmitter } from '@okta/okta-react-native';
componentDidMount() {
this.signInSuccess = EventEmitter.addListener('signInSuccess', function(e: Event) {
console.log(e.access_token);
// Do something ...
});
this.signOutSuccess = EventEmitter.addListener('signOutSuccess', function(e: Event) {
//...
});
this.onError = EventEmitter.addListener('onError', function(e: Event) {
//...
});
this.onCancelled = EventEmitter.addListener('onCancelled', function(e: Event) {
//...
});
}
componentWillUnmount() {
this.signInSuccess.remove();
this.signOutSuccess.remove();
this.onError.remove();
this.onCancelled.remove();
}
authenticate
If you already logged in to Okta and have a valid session token, you can complete authorization by calling authenticate
method. It will emit an event once a user successfully signs in. Make sure your event listeners are mounted and unmounted. Note: on iOS there isn’t a onCancelled
event. If the authenticate
process is cancelled, onError
will be triggered.
authenticate({sessionToken: sessionToken});
signOut
Clear the browser session and clear the app session (stored tokens) in memory. Fires an event once a user successfully logs out. For sample usage, refer to signIn
.
Note: This method apply for browser-sign-in scenario only. Use a combination of revokeToken
(optional) and clearTokens
methods to signOut when use custom-sign-in.
signOut();
await revokeAccessToken(); // optional
await revokeIdToken(); // optional
await clearTokens();
isAuthenticated
Returns a promise that resolves to true
if there is a valid access token or ID token. Otherwise false
.
await isAuthenticated();
If authenticated:
{
"authenticated": true
}
Else:
{
"authenticated": false
}
getAccessToken
This method returns a promise that will return the access token as a string. If no access token is available (either does not exist, or expired), then the promise will be rejected.
await getAccessToken();
If an access token is available:
{
"access_token": "{accessToken}"
}
getIdToken
This method returns a promise that will return the identity token as a string. The promise will be rejected if no id token is available.
await getIdToken();
If an id token is available:
{
"id_token": "{idToken}"
}
getUser
Returns a promise that will fetch the most up-to-date user claims from the OpenID Connect /userinfo
endpoint.
await getUser();
If a user is available:
{
"sub": "00uid4BxXw6I6TV4m0g3",
"name" :"John Doe",
"nickname":"Jimmy",
"given_name":"John",
"middle_name":"James",
"family_name":"Doe",
"profile":"https://example.com/john.doe",
"zoneinfo":"America/Los_Angeles",
"locale":"en-US",
"updated_at":1311280970,
"email":"john.doe@example.com",
"email_verified":true,
"address" : { "street_address":"123 Hollywood Blvd.", "locality":"Los Angeles", "region":"CA", "postal_code":"90210", "country":"US" },
"phone_number":"+1 (425) 555-1212"
}
getUserFromIdToken
Returns the user claims decoded from the identity token.
await getUserFromIdToken();
Sample user claims:
{
"sub": "00uid4BxXw6I6TV4m0g3",
"name": "John Doe",
"preferred_username": "john.doe@example.com"
"ver": 1,
"iss": "https://dev-example.okta.com",
"aud": "00uid4BxXw6I6TV4m0g3",
"auth_time": 1561679776,
"exp": 1561683377,
"iat": 1561679777,
"idp": "00uid4BxXw6I6TV4m0g3"
}
revokeAccessToken
Revoke the access token to make it inactive. Resolves true
if access token has been successfully revoked.
await revokeAccessToken();
revokeIdToken
Revoke the identity token to make it inactive. Resolves true
if id token has been successfully revoked.
await revokeIdToken();
revokeRefreshToken
Revoke the refresh token to make it inactive. Resolves true
if refresh token has been successfully revoked.
await revokeRefreshToken();
clearTokens
Removes all tokens from local storage. Resolves true
if tokens were successfully cleared.
await clearTokens();
introspectAccessToken
Introspect the access token.
await introspectAccessToken();
Sample responses can be found here
introspectIdToken
Introspect the id token.
await introspectIdToken();
Sample responses can be found here
introspectRefreshToken
Introspect the id token.
await introspectRefreshToken();
Sample responses can be found here
refreshTokens
Refreshes all tokens. Resolves with the refreshed tokens.
await refreshTokens();
{
"access_token": "{accessToken}",
"id_token": "{idToken}",
"refresh_token": "refreshToken"
}
We welcome contributions to all of our open-source packages. Please see the contribution guide to understand how to structure a contribution.
We use yarn for dependency management when developing this package:
yarn install
Author: okta
Source Code: https://github.com/okta/okta-react-native
#react-native #react #mobile-apps