Add Authentication to your React Native App

Follow the step-by-step guide to add authentication to your React Native application and screens for:

• login
• registration
• profile management
• update password
• recover password
• verify account

The examples use Ory Kratos, an open source identity and authentication REST API server written in Golang.

As the user storage / identity management we will use the open source Ory Kratos project. The React Native application shown in the screens below is available on github.com/ory/kratos-selfservice-ui-react-native as well. Both are maintained by @aeneasr and @zepatrik.

You can download the React Native example app right now from the Apple App Store!

In the future, this guide will also cover Two-Factor-Authentication (2FA/MFA), "Sign in with Google", password reset, email verification, phone number and SMS verification, "Sign in with GitHub", "Sign in with Facebook" and many other flows.

Authentication for React Native using Expo

This guide assumes that you have worked with ReactJS and React Native before as we will not cover React fundamentals and focus on implementing login, registration, and so on.

To make things a bit easier, we will use expo. At a minimum, you need NodeJS and NPM installed locally. We will use the Ory Kratos React Native Login, Registration and Profile Management template:

npm install -g expo-cli
expo init login-signup-app -t @ory/expo-login-registration-template --npm

# We also want to install and initialize all required components:
cd login-signup-app
npm i
npm run expo-install
# For iOS you also need to run:
npm run pod-install

In case you just want to start exploring, simply run:

• npm start opens a dashboard where you can open iOS, Android, or web.
• npm run android opens the app as an android app (requires a connected android VM or device).
• npm run ios opens the app in the iOS simulator (works only on Mac OSX).
• npm run web opens the app as a browser app.

Running these commands directly will use our hosted demo environment of Ory Kratos at playground.projects.oryapis.com. Configure this in app.config.js:

React Native Profile Management and Update Password Flow

This short screen capture shows using the apps' user login, user registration, dashboard, and profile management features:

User Management and Identity Management Admin API

To manage identities, use the Ory Kratos CLI. An overview of all commands can be found in the Ory Kratos documentation. Because we are using the playground in this example, we will use the Ory CLI instead as it allows to connect to Ory.

docker run oryd/ory:v0.0.57 help

To list all identities in the system, run:

# A public access token to manage the Ory playground project!
export ORY_ACCESS_TOKEN=eGWGK00ZoEZHuEpvARqxGvo1FDNkumLo
docker run \
  -e ORY_ACCESS_TOKEN=$ORY_ACCESS_TOKEN \
  oryd/ory:v0.0.57 \
  identities \
  list

ID					VERIFIED ADDRESS 1		RECOVERY ADDRESS 1		SCHEMA ID	SCHEMA URL
f9c33e56-5b43-458a-8cfa-f38a4fb98b9c	[email protected]		[email protected]		default		https://demo.tenants.staging.oryapis.dev/api/kratos/public/schemas/default
[...]

You can also search for the identity you just signed up using jq:

yourEmail=<the-email-you-used-for-signup>
# For example:
#   yourEmail=[email protected]
export ORY_ACCESS_TOKEN=eGWGK00ZoEZHuEpvARqxGvo1FDNkumLo
docker run \
  -e ORY_ACCESS_TOKEN=$ORY_ACCESS_TOKEN \
  oryd/ory:v0.0.57 \
  identities \
  list \
  --format json | \
    jq '.[] | select(.traits.email == "'$yourEmail'")'

{
  "id": "f9c33e56-5b43-458a-8cfa-f38a4fb98b9c",
  "recovery_addresses": [
    {
      "id": "bd7c396c-d893-4a2b-8627-b50aa38e2569",
      "value": "[email protected]",
      "via": "email"
    }
  ],
  "schema_id": "default",
  "schema_url": "https://demo.tenants.staging.oryapis.dev/api/kratos/public/schemas/default",
  "traits": {
    "email": "[email protected]",
    "name": {
      "first": "Aeneas",
      "last": "Hackerman"
    }
  },
  "verifiable_addresses": [
    {
      "id": "bee9b276-b57f-41dc-8c61-82eb83c2d4fd",
      "status": "completed",
      "value": "[email protected]",
      "verified": true,
      "verified_at": "2020-11-26T08:45:22.094Z",
      "via": "email"
    }
  ]
}

To learn more about administration of Ory Kratos' identities, head over to the Managing Users and Identities Documentation!

JSON Web Tokens versus Ory Kratos Session Tokens

Ory Kratos does not issue JSON Web Tokens but instead so-called opaque Ory Kratos Session Tokens. You can still convert those tokens to JSON Web Tokens if you want, but Ory Kratos Session Tokens are more secure because:

1. JSON Web Tokens can not hold secrets: Unless encrypted, JSON Web Tokens can be read by everyone, including 3rd Parties. Therefore, they can not keep secrets.
2. JSON Web Tokens can not be revoked / invalidated / logged out: Well, you can revoke them, but they will be considered valid until the "expiry" of the token is reached. Unless, of course, you have a blacklist or check with Hydra if the token was revoked, which however defeats the purpose of using JSON Web Tokens in the first place.

Run Ory Kratos Login, Registration, 2FA Server Locally in Docker

Instead of using the hosted demo environment, you can also deploy your Ory Kratos installation locally and run the React Native app against its API. To run the app against a local deployment, check out Ory Kratos locally and run the quickstart:

# You might want to cd into another directory:
#   cd ..

git clone https://github.com/ory/kratos.git
cd kratos
git checkout v0.5.4-alpha.1
docker-compose -f quickstart.yml -f quickstart-standalone.yml \
  up --build --force-recreate -d

Next you need to set up port forwarding for the Ory Kratos Docker Image you just started. We use the tool ngrok.

$ ngrok http 4433

Account                       ...
Version                       ...
Region                        ...
Web Interface                 ...
Forwarding                    ...
Forwarding                    https://04ee3e08367a.ngrok.io -> http://localhost:4433

Connections                   ttl     opn     rt1     rt5     p50     p90
                              0       0       0.00    0.00    0.00    0.00

Copy the HTTPS forwarding URL (example from above https://04ee3e08367a.ngrok.io) and in a new terminal, set it as an environment variable and start the app:

# Change into the directory of your react native app:
cd login-signup-app
KRATOS_URL=<the-ngrok-url> npm start

# For example:
#   KRATOS_URL=https://04ee3e08367a.ngrok.io npm start

Now your app will use the local deployment of Ory Kratos with your own database!

React Navigation with Authentication Session

The entry point for the app is App.tsx. Besides loading some fonts and setting up the views, this component includes the structure of the application - including the navigation:

The most interesting component here is the <AuthProvider>. This component adds an authentication / login context to the React Native component tree:

The helper methods in src/helpers/auth.tsx are simple wrappers around Expo's SecureStore. In order to work on the web as well, we use @react-native-community/async-storage as a fallback:

That's all it takes to make the magic happen! Everything else is handled by the Ory Kratos' Session Token.

We now have a place to store and refresh the user session. In addition, we have a way to see if the user session is still active in the navigation and show the dashboard or login / registration screens:

React Native Authentication Screens

Let's take a look at the different screens: To avoid writing a form renderer for every component - including styling - we abstracted the form rendering into their own components, which you can find in src/components/Layout/AuthLayout.tsx.

There isn't anything special happening there, but you can have a look if you intend to change the layout for example.

React Native Login Component Example

The User Login component uses the Ory Kratos TypeScript SDK and the User Login API Flow.

React Native Registration Component Example

The User Registration component performs a User Registration API Flow.

React Navigation Home Component Example

The Home component receives the user's authentication session and displays all relevant information. To learn more about Ory Kratos' Identity and User Management check out the Ory Kratos Identity Data Model.

React Navigation User Settings Component Example

The User Settings component performs a User Settings API Flow.

Adding Authentication to a React Native App From Scratch

Granted, using a template is the easiest way to get started. However, understanding how everything works even better. Let's have a look at the project set up process!

Assuming that you ran expo init with one of the default templates:

expo init login-signup-app --npm
cd login-signup-app

React Navigation with Authentication

To set up screen navigation, we use the standard React Native navigation component:

npm install @react-navigation/native @react-navigation/stack
expo install react-native-reanimated react-native-gesture-handler react-native-screens react-native-safe-area-context @react-native-community/masked-view

React Native with Expo Encrypted Credentials Storage

We will use expo-secure-store to securely store the user's session key in the encrypted device store (Android Keystore / Expo Secure Store). To install it we need to run:

expo install expo-secure-store @react-native-community/async-storage

# For iOS you also need to run:
npx pod-install

We're also adding @react-native-community/async-storage because expo-secure-store does not work on the Web.

Ory Kratos SDKs for React Native

We also need to install the Ory Kratos SDK. We'll also be making sure the app looks beautiful by installing the Ory Themes package and some fonts later.

# The package "url" is needed as it is not natively available in React Native.
npm install @ory/[email protected] url

React Native Environment Variable Support

Next we want to set up support for environment variables which we will use in the next section. You can either follow the Expo guide on Environment Variables or do the following:

expo install expo-constants

Create a file called app.config.js in the project's root:

You can use this variable when initializing the Ory Kratos SDK:

Fonts and Other Dependencies

To make things a bit prettier, we are going to add the Ory Theme and some fonts:

npm install @ory/themes styled-components
expo install expo font @expo-google-fonts/rubik \
    @expo-google-fonts/roboto expo-status-bar

You are of course free to use your own themes for this but for the sake of completeness we added this to the guide.

Conclusion

We have now implemented Ory Kratos Authentication with Login, Registration, Profile Management in React Native!

Thanks for taking the time to follow this guide and hopefully it helps you build secure apps more smoothly. Should you have further questions or feedback, visit the community forum or chat.

Ory Kratos is open-source and freely available on github, please consider starring the repository. It is free and helps grow the project and community.

Sign up to our newsletter to be notified of new updates to Ory Kratos and other Ory projects.