Obtaining authentication result

ReachFive signup and authentication flows use the OAuth 2.0 and OpenID Connect protocols from a first-party standpoint.

All signup, login, and refresh SDK methods lead to a set of JWT tokens, including an ID Token, Access Token and, optionally, a Refresh Token.

The SDK will always emit events that you can listen to using the on method.

The AuthResult object is the success model that contains the set of tokens or, if implementing an authorization code grant, the resulting code to be exchanged against the token endpoint. Errors are conveyed using the ErrorResponse object. In both cases, any passed state will be carried throughout the respective flow.

There are two main ways of obtaining your authentication result

Using redirection for auth result

By default, the SDK redirects the user-agent through ReachFive’s authorization endpoint, which then redirects the user-agent back to the provided redirect_uri (or the original page in case of an implicit grant) along with the authentication result. This is the authorization code or set of tokens.

When using redirection to obtain an authentication result, we recommended you set responseType to code and make sure that PKCE is enforced in the client configuration.

{
    "responseType": "code",
    "redirectUri": "https://www.example.com/login/callback"
}

Did you know? The implicit grant will be deprecated in OAuth 2.1.

Using web messages for auth result

Alternatively, you can leverage the useWebMessage boolean option in AuthOptions.

Instead of redirecting user-agents through an authorization endpoint, the web message approach uses a hidden iframe and obtains the authentication result directly from within the webpage. No user-agent redirection is involved in this flow, and the SDK method will conveniently return a Promise<AuthResult>. Error responses are conveyed in the form of failed promises.

When useWebMessage is set to true, then responseType is hardcoded to code for increased security purposes. The authorization code will be automatically exchanged against a token set for your convenience, along with any existing PKCE code verifier that might be involved.

Despite there being no user-agent involved, the redirectUri parameter is nonetheless still required as per RFC 6749 Section 1.3.1. You may set any whitelisted URIs as defined in your client configuration.


SameSite cookies

The SameSite attribute (set on the Set-Cookie HTTP response header) enables you to declare if your cookies are restricted to first-party clients or same-site context.

At ReachFive, we set SameSite to Lax for all browsers except Safari. For Safari, we use SameSite = None.

What’s the difference?
Lax

Cookies are not sent on normal cross-site subrequests, but are sent when a user is navigating to the origin site.

None

Cookies are sent in all contexts.

For more details, see Mozilla’s SameSite reference docs.

Safari

Apple Safari does not currently handle SameSite=None HTTPS cookies properly, meaning cookies might not be set for Safari users.

This can be mitigated by using Refresh Tokens to handle long-term sessions. To obtain a Refresh Token, make sure PKCE is enforced in your client configuration, and that the requireRefreshToken option is set to true or that your scope includes the offline_access value.