React Native Example using HAAPI

An example React Native app that uses the Curity Identity Server's Hypermedia API to perform an OIDC flow.
Authentication uses native screens without the need for an external browser.

1. Prepare a React Native Environment

First make sure you have completed the React Native - Environment Setup.
Follow the React Native instructions and ensure that you can run a basic app.

2. Deploy the Curity Identity Server

Start with a local automated deployment to ensure that you understand the technical setup.
You can then apply the same configuration to deployed environments.
First ensure that the local computer has these prerequisites:

• A Docker engine.
• The envsubst tool, e.g with brew install gettext.
• The jq tool, e.g with brew install jq.

Copy a license.json file for the Curity Identity Server into the root folder.
Then deploy the system, and indicate how connected emulators or devices call the Curity Identity Server.

You can provide a host name with which connected emulators or devices call the Curity Identity Server.
For example, run the following commands to connect to a macOS computer using its IP address:

export USE_NGROK='false'
export IDSVR_HOST_NAME="$(ipconfig getifaddr en0)"
./start-idsvr.sh

You can set the IDSVR_HOST_NAME variable in various ways:

• You can set it to localhost if you only want to test on iOS simulators.
• Some older Android emulators might require IDSVR_HOST_NAME to use the special value 10.0.2.2.

3. View Security Configuration

The Mobile Deployments repository explains further information about the deployed backend infrastructure.
You can view the HAAPI Configuration to understand the settings to apply to deployed environments.

4. Configure the Application

The deployment script performs the following tasks, which you could also do manually:

• Populate base URLs in the configuration.android.jsx file from the configuration.android.template file.
• Populate base URLs in configuration.ios.jsx file from the configuration.ios.template file.

5. Run the Application

First install React native dependencies.

npm install

For iOS, also generate an Xcode workspace where you can run the example in an emulator.
You may need to apply this workaround if the pod install command fails.

cd ios
pod install

Run the Metro Server

Run the JavaScript bundler that ships with React Native from the root of the React Native project:

# using npm
npm start

# OR using Yarn
yarn start

Let Metro Bundler run in its own terminal and open a new terminal from the root of your React Native project.

For Android

Run the following command to start your Android app:

# using npm
npm run android

# OR using Yarn
yarn android

For iOS

Run the following command to start your iOS app:

# using npm
npm run ios -- --simulator='iPhone 16 Pro'

# OR using Yarn
yarn ios

6. Test Basic Logins

Run the app and first test basic logins using an HTML Form authenticator.
Sign in to the deployed environment and use a pre-shipped test user account.

• Username: demouser
• Password: Password1

7. Test Native Passkey Logins

Passkeys require hosting of assets documents at trusted internet HTTPS URL.
On iOS, you must also provide overrides with your own Apple team ID and unique bundle identifier.

You can use ngrok to host assets documents and test passkeys logins for both Android and iOS.
The following example commands deploy the Curity Identity Server with a passkeys configuration.
For more about ngrok, see the tutorial link at the end of this page.

export APPLE_TEAM_ID='MYTEAMID'
export APPLE_BUNDLE_ID='io.myorganization.haapi.react.example'
export USE_NGROK='true'
./start-idsvr.sh

Also open the ios folder in Xcode and set the team ID and bundle ID under Signing & Capabilities.
Then use Apple development tools to sign the app, such as with the Automatically manage signing option.

8. Free Deployment Resources

Once you have finished local testing, free all backend resources with the following command:

./stop-idsvr.sh

9. Learn about the React Native HAAPI Module

The example app uses the React Native HAAPI Module, whose README explains more about options.
Use pre-released modules by updating the example app to use a file based dependency.
You can change the module code, e.g. to add println debug statements, then run it with the example app.

git clone https://github.com/curityio/react-native-haapi-module.git
npm uninstall @curity/react-native-haapi-module
npm install <path-to-repo> --save

Alternatively, build the module as a .tgz file and update the example app to use it:

npm uninstall @curity/react-native-haapi-module
npm install <path-to-file>.tgz --save

10. Use Config Specs for Deployed Environments

This repo also includes some parameterized configuration (config specs) that you can import using the admin UI.
Run the Changes -> Run Config Spec command to upload a config spec and enter parameters:

• android config spec
• ios config spec

Tutorials

See also the following resources:

• The React Native HAAPI Code Example provides an overview of the code example's behaviors.
• The ngrok tutorials explain how to use an internet URL and view HAAPI messages.
• The Configure Native Passkeys for Mobile Logins tutorial explains the technical setup when using passkeys.
• The Implementing HAAPI Attestation Fallback explains how to manage non-compliant Android devices.

More information

Please visit curity.io for more information about the Curity Identity Server.