Integrate Logto with Expo (React Native)
- The following demonstration is built on Expo ~50.0.6.
- The sample project is available on our SDK repository.
Prerequisites
- A Logto Cloud account or a self-hosted Logto (Check out the ⚡ Get started guide to create one if you don't have).
- A Logto native application created.
Installation
Install Logto SDK and peer dependencies via your favorite package manager:
- npm
- Yarn
- pnpm
npm i @logto/rn
npm i expo-crypto expo-secure-store expo-web-browser @react-native-async-storage/async-storage
yarn add @logto/rn
yarn add expo-crypto expo-secure-store expo-web-browser @react-native-async-storage/async-storage
pnpm add @logto/rn
pnpm add expo-crypto expo-secure-store expo-web-browser @react-native-async-storage/async-storage
The @logto/rn
package is the SDK for Logto. The remaining packages are its peer dependencies. They couldn't be listed as direct dependencies because the Expo CLI requires that all dependencies for native modules be installed directly within the root project's package.json
.
If you're installing this in a bare React Native app, you should also follow these additional installation instructions.
Integration
Init Logto provider
Import and use LogtoProvider
to provide a Logto context:
import { LogtoProvider, LogtoConfig } from '@logto/rn';
const config: LogtoConfig = {
endpoint: '<your-logto-endpoint>',
appId: '<your-application-id>',
};
const App = () => (
<LogtoProvider config={config}>
<YourAppContent />
</LogtoProvider>
);
Implement sign-in and sign-out
Before we dive into the details, here's a quick overview of the end-user experience. The sign-in process can be simplified as follows:
- Your app invokes the sign-in method.
- The user is redirected to the Logto sign-in page. For native apps, the system browser is opened.
- The user signs in and is redirected back to your app (configured as the redirect URI).
Regarding redirect-based sign-in
- This authentication process follows the OpenID Connect (OIDC) protocol, and Logto enforces strict security measures to protect user sign-in.
- If you have multiple apps, you can use the same identity provider (Logto). Once the user signs in to one app, Logto will automatically complete the sign-in process when the user accesses another app.
To learn more about the rationale and benefits of redirect-based sign-in, see Logto sign-in experience explained.
Switch to the application details page of Logto Console. Add a native redirect URI (for example, io.logto://callback
), then click "Save".
-
For iOS, the redirect URI scheme does not really matter since the
ASWebAuthenticationSession
class will listen to the redirect URI regardless of if it's registered. -
For Android, the redirect URI scheme must be filled in Expo's
app.json
file, for example:app.json{
"expo": {
"scheme": "io.logto"
}
}
Now back to your app, you can use useLogto
hook to sign in and sign out:
import { useLogto } from '@logto/rn';
import { Button } from 'react-native';
const Content = () => {
const { signIn, signOut, isAuthenticated } = useLogto();
return (
<div>
{isAuthenticated ? (
<Button title="Sign out" onPress={async () => signOut()} />
) : (
// Replace the redirect URI with your own
<Button title="Sign in" onPress={async () => signIn('io.logto://callback')} />
)}
</div>
);
};
Checkpoint: Test your application
Now, you can test your application:
- Run your application, you will see the sign-in button.
- Click the sign-in button, the SDK will init the sign-in process and redirect you to the Logto sign-in page.
- After you signed in, you will be redirected back to your application and see the sign-out button.
- Click the sign-out button to clear local storage and sign out.
Get user information
Display user information
To display the user's information, you can use the getIdTokenClaims()
method:
import { useLogto } from '@logto/rn';
import { Button, Text } from 'react-native';
const Content = () => {
const { getIdTokenClaims, isAuthenticated } = useLogto();
const [user, setUser] = useState(null);
useEffect(() => {
if (isAuthenticated) {
getIdTokenClaims().then((claims) => {
setUser(claims);
});
}
}, [isAuthenticated]);
return (
<div>
{isAuthenticated ? (
<>
<Text>{user?.name}</Text>
<Text>{user?.email}</Text>
<Button title="Sign out" onPress={async () => signOut()} />
</>
) : (
<Button title="Sign in" onPress={async () => signIn('io.logto://callback')} />
)}
</div>
);
};
Request additional claims
You may find some user information are missing in the returned object from getIdTokenClaims()
. This is because OAuth 2.0 and OpenID Connect (OIDC) are designed to follow the principle of least privilege (PoLP), and Logto is built on top of these standards.
By default, limited claims are returned. If you need more information, you can request additional scopes to access more claims.
A "claim" is an assertion made about a subject; a "scope" is a group of claims. In the current case, a claim is a piece of information about the user.
Here's a non-normative example the scope - claim relationship:
The "sub" claim means "subject", which is the unique identifier of the user (i.e. user ID).
Logto SDK will always request three scopes: openid
, profile
, and offline_access
.
To request additional scopes, you can pass the scopes to the LogtoConfig
object:
import { LogtoProvider, LogtoConfig, UserScope } from '@logto/rn';
const config: LogtoConfig = {
appId: '<your-application-id>',
endpoint: '<your-logto-endpoint>',
scopes: [
UserScope.Email,
UserScope.Phone,
UserScope.CustomData,
UserScope.Identities,
UserScope.Organizations,
],
};
const App = () => <LogtoProvider config={config}>{/* Your app content */}</LogtoProvider>;
Claims that need network requests
To prevent bloating the ID token, some claims require network requests to fetch. For example, the custom_data
claim is not included in the user object even if it's requested in the scopes. To access these claims, you can use the fetchUserInfo()
method:
import { useLogto } from '@logto/rn';
import { Button, Text } from 'react-native';
const Content = () => {
const { fetchUserInfo, isAuthenticated } = useLogto();
const [user, setUser] = useState(null);
useEffect(() => {
if (isAuthenticated) {
fetchUserInfo().then((userInfo) => {
setUser(userInfo);
});
}
}, [isAuthenticated]);
return (
<div>
{isAuthenticated ? (
<>
<Text>{user?.name}</Text>
<Text>{user?.email}</Text>
<Button title="Sign out" onPress={async () => signOut()} />
</>
) : (
<Button title="Sign in" onPress={async () => signIn('io.logto://callback')} />
)}
</div>
);
};
Scopes and claims
Logto uses OIDC scopes and claims conventions to define the scopes and claims for retrieving user information from the ID token and OIDC userinfo endpoint. Both of the "scope" and the "claim" are terms from the OAuth 2.0 and OpenID Connect (OIDC) specifications.
Here's the list of supported scopes and the corresponding claims:
openid
Claim name | Type | Description | Needs userinfo? |
---|---|---|---|
sub | string | The unique identifier of the user | No |
profile
Claim name | Type | Description | Needs userinfo? |
---|---|---|---|
name | string | The full name of the user | No |
username | string | The username of the user | No |
picture | string | URL of the End-User's profile picture. This URL MUST refer to an image file (for example, a PNG, JPEG, or GIF image file), rather than to a Web page containing an image. Note that this URL SHOULD specifically reference a profile photo of the End-User suitable for displaying when describing the End-User, rather than an arbitrary photo taken by the End-User. | No |
created_at | number | Time the End-User was created. The time is represented as the number of milliseconds since the Unix epoch (1970-01-01T00:00:00Z). | No |
updated_at | number | Time the End-User's information was last updated. The time is represented as the number of milliseconds since the Unix epoch (1970-01-01T00:00:00Z). | No |
Other standard claims include family_name
, given_name
, middle_name
, nickname
, preferred_username
, profile
, website
, gender
, birthdate
, zoneinfo
, and locale
will be also included in the profile
scope without the need for requesting the userinfo endpoint. A difference compared to the claims above is that these claims will only be returned when their values are not empty, while the claims above will return null
if the values are empty.
Unlike the standard claims, the created_at
and updated_at
claims are using milliseconds instead of seconds.
email
Claim name | Type | Description | Needs userinfo? |
---|---|---|---|
string | The email address of the user | No | |
email_verified | boolean | Whether the email address has been verified | No |
phone
Claim name | Type | Description | Needs userinfo? |
---|---|---|---|
phone_number | string | The phone number of the user | No |
phone_number_verified | boolean | Whether the phone number has been verified | No |
address
Please refer to the OpenID Connect Core 1.0 for the details of the address claim.
custom_data
Claim name | Type | Description | Needs userinfo? |
---|---|---|---|
custom_data | object | The custom data of the user | Yes |
identities
Claim name | Type | Description | Needs userinfo? |
---|---|---|---|
identities | object | The linked identities of the user | Yes |
sso_identities | array | The linked SSO identities of the user | Yes |
urn:logto:scope:organizations
Claim name | Type | Description | Needs userinfo? |
---|---|---|---|
organizations | string[] | The organization IDs the user belongs to | No |
organization_data | object[] | The organization data the user belongs to | Yes |
urn:logto:scope:organization_roles
Claim name | Type | Description | Needs userinfo? |
---|---|---|---|
organization_roles | string[] | The organization roles the user belongs to with the format of <organization_id>:<role_name> | No |
Considering performance and the data size, if "Needs userinfo?" is "Yes", it means the claim will not show up in the ID token, but will be returned in the userinfo endpoint response.
API resources and organizations
We recommend to read 🔐 Role-Based Access Control (RBAC) first to understand the basic concepts of Logto RBAC and how to set up API resources properly.
Configure Logto client
Once you have set up the API resources, you can add them when configuring Logto in your app:
import { LogtoConfig } from '@logto/rn';
const config: LogtoConfig = {
appId: '<your-application-id>',
endpoint: '<your-logto-endpoint>',
// Add API resources
resources: ['https://shopping.your-app.com/api', 'https://store.your-app.com/api'],
};
Each API resource has its own permissions (scopes).
For example, the https://shopping.your-app.com/api
resource has the shopping:read
and shopping:write
permissions, and the https://store.your-app.com/api
resource has the store:read
and store:write
permissions.
To request these permissions, you can add them when configuring Logto in your app:
import { LogtoConfig } from '@logto/rn';
const config: LogtoConfig = {
appId: '<your-application-id>',
endpoint: '<your-logto-endpoint>',
scopes: ['shopping:read', 'shopping:write', 'store:read', 'store:write'],
resources: ['https://shopping.your-app.com/api', 'https://store.your-app.com/api'],
};
You may notice that scopes are defined separately from API resources. This is because Resource Indicators for OAuth 2.0 specifies the final scopes for the request will be the cartesian product of all the scopes at all the target services.
Thus, in the above case, scopes can be simplified from the definition in Logto, both of the API resources can have read
and write
scopes without the prefix. Then, in the Logto config:
import { LogtoConfig } from '@logto/rn';
const config: LogtoConfig = {
appId: '<your-application-id>',
endpoint: '<your-logto-endpoint>',
scopes: ['read', 'write'],
resources: ['https://shopping.your-app.com/api', 'https://store.your-app.com/api'],
};
For every API resource, it will request for both read
and write
scopes.
It is fine to request scopes that are not defined in the API resources. For example, you can request the email
scope even if the API resources don't have the email
scope available. Unavailable scopes will be safely ignored.
After the successful sign-in, Logto will issue proper scopes to API resources according to the user's roles.
Fetch access token for the API resource
To fetch the access token for a specific API resource, you can use the getAccessToken
method:
import { useLogto } from '@logto/rn';
const AccessToken = () => {
const { isAuthenticated, getAccessToken } = useLogto();
const [accessToken, setAccessToken] = useState('');
useEffect(() => {
(async () => {
if (isAuthenticated) {
const token = await getAccessToken('https://shopping.your-app.com/api');
setAccessToken(token);
}
})();
}, [isAuthenticated, getAccessToken]);
return <p>{{ accessToken }}</p>;
};
This method will return a JWT access token that can be used to access the API resource when the user has related permissions. If the current cached access token has expired, this method will automatically try to use a refresh token to get a new access token.
Fetch organization token for user
If organization is new to you, please read 🏢 Organizations (Multi-tenancy) to get started.
You need to add UserScope.Organizations
scope when configuring the Logto client:
import { LogtoConfig, UserScope } from '@logto/rn';
const config: LogtoConfig = {
// ...other configs
scopes: [UserScope.Organizations],
};
Once the user is signed in, you can fetch the organization token for the user:
import { useLogto } from '@logto/rn';
import { useEffect, useState } from 'react';
const Organizations = () => {
const { isAuthenticated, getOrganizationToken, getIdTokenClaims } = useLogto();
const [organizationIds, setOrganizationIds] = useState<string[]>();
useEffect(() => {
(async () => {
if (!isAuthenticated) {
return;
}
const claims = await getIdTokenClaims();
console.log('ID token claims', claims);
setOrganizationIds(claims?.organizations);
})();
}, [isAuthenticated, getIdTokenClaims]);
return (
<section>
<ul>
{organizationIds?.map((organizationId) => {
return (
<li key={organizationId}>
<span>{organizationId}</span>
<button
type="button"
onClick={async () => {
console.log('raw token', await getOrganizationToken(organizationId));
}}
>
fetch token (see console)
</button>
</li>
);
})}
</ul>
</section>
);
};
export default Organizations;
Troubleshooting
Unable to resolve @logto/client/shim
For Expo projects, if you encounter the error Unable to resolve "@logto/client/shim" from "node_modules/@logto/rn/lib/index.js"
, you can resolve it by adding the following to your metro.config.js
file:
const config = {
// ...
resolver: {
unstable_enablePackageExports: true,
},
};
module.exports = config;
This error indicates that @logto/rn
package not being able to resolve the @logto/client/shim
module.
As the node exports were used in the@logto/client
package, and package exports are not enabled by default in Metro bundler, you need to enable them manually.
See the React Native package exports support for more details.