React Native mobile SDK
Configuration
This is your configuration object for the client. The config is passed into each of the methods with optional overrides.
import { authorize } from 'strivacity-react-native';
// base config
const config = {
issuer: '<YOUR_ISSUER_URL>', // Example: https://yourdomain.strivacity.com
clientId: '<YOUR_CLIENT_ID>', // Your application Client ID
redirectUrl: '<YOUR_REDIRECT_URL>', // Example: com.myapp://auth
scopes: ['<YOUR_SCOPE_ARRAY>'], // Example: ['openid']
};
// use the client to make the auth request and receive the authState
try {
// result includes accessToken, accessTokenExpirationDate and refreshToken
const result = await authorize(config);
} catch (error) {
console.log(error);
}
API
- issuer - (
string
) base URI of the authentication server. If noserviceConfiguration
(below) is provided, issuer is a mandatory field, so that the configuration can be fetched from the issuer's OIDC discovery endpoint. - serviceConfiguration - (
object
) you may manually configure token exchange endpoints in cases where the issuer does not support the OIDC discovery protocol, or simply to avoid an additional round trip to fetch the configuration. If noissuer
(above) is provided, and the service configuration is mandatory.- authorizationEndpoint - (
string
) REQUIRED fully formed URL to the OAuth authorization endpoint - tokenEndpoint - (
string
) REQUIRED fully formed URL to the OAuth token exchange endpoint - revocationEndpoint - (
string
) fully formed URL to the OAuth token revocation endpoint. If you want to be able to revoke a token and noissuer
is specified, this field is mandatory. - registrationEndpoint - (
string
) fully formed URL to your OAuth/OpenID Connect registration endpoint. Only necessary for servers that require client registration. - endSessionEndpoint - (
string
) fully formed URL to your OpenID Connect end session endpoint. If you want to be able to end a user's session and noissuer
is specified, this field is mandatory.
- authorizationEndpoint - (
- clientId - (
string
) REQUIRED your client ID on the auth server - clientSecret - (
string
) client secret to pass to token exchange requests. ⚠️ Read more about client secrets - redirectUrl - (
string
) REQUIRED the URL that links back to your app with the auth code - scopes - (
array<string>
) the scopes for your token, e.g.['email', 'offline_access']
. - additionalParameters - (
object
) additional parameters that will be passed in the authorization request. Must be string values! E.g. settingadditionalParameters: { hello: 'world', foo: 'bar' }
would addhello=world&foo=bar
to the authorization request. - clientAuthMethod - (
string
) ANDROID Client Authentication Method. Can be eitherbasic
(default) for Basic Authentication orpost
for HTTP POST body Authentication - dangerouslyAllowInsecureHttpRequests - (
boolean
) ANDROID whether to allow requests over plain HTTP or with self-signed SSL certificates. ⚠️ Can be useful for testing against local server, should not be used in production. This setting has no effect on iOS; to enable insecure HTTP requests, add a NSExceptionAllowsInsecureHTTPLoads exception to your App Transport Security settings. - customHeaders - (
object
) ANDROID you can specify custom headers to pass during authorize request and/or token request.- authorize - (
{ [key: string]: value }
) headers to be passed during the authorization request. - token - (
{ [key: string]: value }
) headers to be passed during token retrieval requests. - register - (
{ [key: string]: value }
) headers to be passed during registration requests.
- authorize - (
- additionalHeaders - (
{ [key: string]: value }
) IOS you can specify additional headers to be passed for all authorize, refresh, and register requests. - useNonce - (
boolean
) (default: true) optionally allows not sending the nonce parameter, to support non-compliant providers. To specify custom nonce, provide it inadditionalParameters
under thenonce
key. - usePKCE - (
boolean
) (default: true) optionally allows not sending the code_challenge parameter and skipping PKCE code verification, to support non-compliant providers. - skipCodeExchange - (
boolean
) (default: false) just return the authorization response, instead of automatically exchanging the authorization code. This is useful if this exchange needs to be done manually (not client-side) - iosCustomBrowser - (
string
) (default: undefined) IOS overrides the used browser for authorization, used to open an external browser. If no value is provided, theASWebAuthenticationSession
orSFSafariViewController
are used by theAppAuth-iOS
library. - iosPrefersEphemeralSession - (
boolean
) (default:false
) IOS indicates whether the session should ask the browser for a private authentication session. - androidAllowCustomBrowsers - (
string[]
) (default: undefined) ANDROID overrides the used browser for authorization. If no value is provided, all browsers are allowed. - androidTrustedWebActivity - (
boolean
) (default:false
) ANDROID UseEXTRA_LAUNCH_AS_TRUSTED_WEB_ACTIVITY
when opening web view. - connectionTimeoutSeconds - (
number
) configure the request timeout interval in seconds. This must be a positive number. The default values are 60 seconds on iOS and 15 seconds on Android.
Authorization
This is the main function to use for authentication. Invoking this function will do the whole login flow and return the access token, refresh token, and access token expiry date when successful, or it throws an error when not successful.
import { authorize } from 'react-native-app-auth';
const config = {
issuer: '<YOUR_ISSUER_URL>',
clientId: '<YOUR_CLIENT_ID>',
redirectUrl: '<YOUR_REDIRECT_URL>',
scopes: ['<YOUR_SCOPES_ARRAY>'],
};
const result = await authorize(config);
result
result
This is the result from the auth server:
- accessToken - (
string
) the access token - accessTokenExpirationDate - (
string
) the token expiration date - authorizeAdditionalParameters - (
Object
) additional URL parameters from the authorizationEndpoint response. - tokenAdditionalParameters - (
Object
) additional URL parameters from the tokenEndpoint response. - idToken - (
string
) the ID token - refreshToken - (
string
) the refresh token - tokenType - (
string
) the token type, e.g. Bearer - scopes - ([
string
]) the scopes the user has agreed to be granted - authorizationCode - (
string
) the authorization code (only ifskipCodeExchange=true
) - codeVerifier - (
string
) the codeVerifier value used for the PKCE exchange (only if bothskipCodeExchange=true
andusePKCE=true
)
Refresh Token
This method will refresh the accessToken using the refreshToken. Some auth providers will also give you a new refreshToken.
import { refresh } from 'react-native-app-auth';
const config = {
issuer: '<YOUR_ISSUER_URL>',
clientId: '<YOUR_CLIENT_ID>',
redirectUrl: '<YOUR_REDIRECT_URL>',
scopes: ['<YOUR_SCOPES_ARRAY>'],
};
const result = await refresh(config, {
refreshToken: `<REFRESH_TOKEN>`,
});
Revoke Token
This method will revoke a token. The tokenToRevoke can be either an accessToken or a refreshToken.
import { revoke } from 'react-native-app-auth';
const config = {
issuer: '<YOUR_ISSUER_URL>',
clientId: '<YOUR_CLIENT_ID>',
redirectUrl: '<YOUR_REDIRECT_URL>',
scopes: ['<YOUR_SCOPES_ARRAY>'],
};
const result = await revoke(config, {
tokenToRevoke: `<TOKEN_TO_REVOKE>`,
includeBasicAuth: true,
sendClientId: true,
});
Error Messages
Values are in the code
field of the rejected Error object.
- OAuth Authorization error codes
- OAuth Access Token error codes
- OpenID Connect Registration error codes
service_configuration_fetch_error
- could not fetch the service configurationauthentication_failed
- user authentication failedtoken_refresh_failed
- could not exchange the refresh token for a new JWTregistration_failed
- could not registerbrowser_not_found
(Android only) - no suitable browser installed
Android Prefetch
This will prefetch the authorization service configuration. Invoking this function is optional and will speed up calls to authorization. This is only supported on Android.
import { prefetchConfiguration } from 'react-native-app-auth';
const config = {
warmAndPrefetchChrome: true,
issuer: '<YOUR_ISSUER_URL>',
clientId: '<YOUR_CLIENT_ID>',
redirectUrl: '<YOUR_REDIRECT_URL>',
scopes: ['<YOUR_SCOPES_ARRAY>'],
};
prefetchConfiguration(config);
Updated 3 days ago