Reapit Connect
How to manage authentication of Reapit users with our hosted identity solution
From August 2024, it is essential that early Platform integrators ensure their identity token validation routines are updated. Please refer to Using identity tokens for more information
Overview
Reapit Connect is our hosted identity solution designed to allow applications to securely authenticate Reapit users against a single, trusted identity. Backed by our OpenID Connect compliant system, it is quick and easy to build applications that adhere to best security practices and extend an excellent experience to your users.
Building your application with Reapit Connect is our recommended way to interact with our Platform.
Why use Reapit Connect
Simplicity
Reapit Connect removes the overhead of having to build and maintain a user credential directory for your app. Instead, users can be securely authenticated against a single, trusted Reapit identity.
Security
Our identity provision is an implementation of OpenId Connect, the defacto industry standard for authentication and authorisation for web and mobile applications. Simply put, you don't need to worry about securely capturing or storing user credentials - we do that part for you.
Single sign on
Reapit Connect supports single sign on (SSO) to allow authenticated sessions to be shared between any application using Reapit Connect to manage its authentication. The experience of interacting with your application is streamlined as users aren't re-prompted for their credentials.
Cross platform
You can use Reapit Connect to authenticate users regardless of your front or back end technologies. Reapit Connect is agnostic of technology and integration is as simple as a redirect to our hosted login screen and a subsequent REST API call.
Trust
Your users will be presented with a unified login screen from a brand they already know and trust. They will receive the same user experience as they do from other Reapit applications and of those that exist in our AppMarket.
AppMarket integration
Registering your application
Registering your app in our AppMarket is the first step for it to be able to interact with Reapit customer data.
Our application submission page will capture information about your application, including the details required for integration with Reapit Connect.
Select Authenticate with Reapit Connect as your required authentication flow **
Provide one or more redirect URLs and a logout URL to define the acceptable URLs that Reapit Connect is permitted to redirect back to after a successful authentication or logout
Once you have successfully registered, you will be issued with a client id. You can obtain this by clicking your app in the My Apps area of our developer portal.
Customer installation
In order for Reapit Connect to authenticate your application on a users behalf, the user must belong to a Reapit customer that has opted to allow your application access to their data.
Customer administrators are able to control your applications access by choosing to install from our AppMarket. As part of this process, they will grant your application with any permissions (scopes) it requires to interact with Foundations API endpoints.
You can test Reapit Connect with our sandbox environment which does not require the customer installation step. Simply provide your developer portal credentials when Reapit Connect prompts for a username and password.
Authentication flow
OAuth 2.0 is an authorization framework that we use to allow a user to grant limited access to resources in our Foundations platform without having to expose their credentials.
We use the Authorization Code Grant **flow to authenticate, which is broken down into the following steps.
Your application redirects the user to our Reapit Connect in the browser
Reapit Connect presents the user with a login screen to capture their credentials
Reapit Connect will direct the browser back to your application with an authorization code in the query string
Your application exchanges the authorization code for tokens with a REST API call
Direct user to Reapit Connect
To initiate a login, your application should redirect users to our authorize endpoint:
https://connect.reapit.cloud/authorize?response_type=code&client_id=<client id>&redirect_uri=<redirect url>&state=<state>
Parameter
Description
response_type
The type of authentication flow that Reapit Connect should initiate. At present, this must be set to code
client_id
The unique client id that was issued to your application after registration
redirect_uri
The URL to redirect back to once the user has been authenticated. This must exactly match one of the URL's you provide during app registration
state
Optional parameter to pass state to our hosted login screen. Upon successful login, it will be returned back to you.
Present login form
The user will be presented with a Reapit branded login screen where they are required to input their credentials and submit. They can also initiate password recovery for their Reapit identity from this form.
This step will be automatically skipped if the user has an authenticated session with Reapit Connect. The user will immediately be redirected back to your app.
Redirect back to your app
If the user provides valid credentials, Reapit Connect will redirect back to your application using the redirect_uri
that was provided when directing the user to Reapit Connect.
A code
parameter will be appended to the redirected URL, as well as any state
you passed through to the authorize endpoint.
https://your_redirect_url?code=<code>&state=<state>
Reapit Connect will only redirect to URLs that were added during app registration. This is a security measure to prevent malicious users attempting to impersonate your application.
Exchange code for tokens
Once your application has successfully guided the user through the OAuth flow, you can extract the authorization code from the redirected URL. You are then able to use this code to exchange for JWT tokens for proof of authentication and access for Foundations resources. You can only attempt to exchange authorization codes once and they will expire 10 minutes after they have been issued.
To make the exchange, send a POST
request to the endpoint below with Content-type set to application/x-www-form-urlencoded
:
https://connect.reapit.cloud/token
Request payload
Description
client_id
The unique client id that was issued to your application after registration
code
The authorization code returned to you in URL
grant_type
Must be set to authorization_code
redirect_uri
The redirect URL that was submitted when directing user to Reapit Connect
If your request is properly formed and valid, you'll receive a response similar to below.
Making authenticated requests
If the user successfully logged in and your application performed the code exchange, you will receive a JSON payload containing a series of tamper proof JWT tokens:
Response payload
Description
access_token
Token to grant access to protected Foundations resources
id_token
Token containing claims about the users identity.
refresh_token
Token that can be issued to get a new id and access token.
expires_in
The number of seconds that the access token is valid for
token_type
The type of tokens issued. Will always be set to bearer
Using access tokens
Access tokens (also known as bearer tokens) are designed to provide your application with access to protected resources on the users behalf.
You can access Foundations API endpoints by including the access token as an Authorization
header in all requests your application issues, subject to the scopes that your application requested during registration.
Using identity tokens
Identity tokens are intended to provide proof of authentication with Reapit Connect. Your application should decode and validate the id token that it has been issued. There are a variety of third party libraries to help accomplish this and the token should not be trusted until validated.
When validating your id token, you will need the production well known public keys - these are publicly accessible online. You should build the URL to the published JWKs using the token issuer, but only after validating the issuer of the token. Valid issuers of Reapit Connect tokens are:
https://connect.reapit.cloud
https://cognito-idp.eu-west-2.amazonaws.com/${cognitoPoolId}
On or after 1st August 2024 tokens will begin to be issued by https://connect.reapit.cloud. If you integrated with our Platform before May 2024, you may have a single hard coded URL in your token validation routine, which will be https://cognito-idp.eu-west-2.amazonaws.com/eu-west-2_eQ7dreNzJ/.well-known/jwks.json.
Once you have validated the issuer, you can then go on to fetch the JWKs and continue with token validation. An example of how you might do this is shown below
Our Connect Session JS module decodes and verifies the id token for you (if you are using a client side application). We have patched all versions of the Connect Session library back to v2.x. Ideally, you should upgrade to the latest version of the library however if you encounter compatibility issues after May 2024, upgrading to the latest version of your current major version (ie v2.3.1 if running v2.3.0) will suffice,
Once decoded, your application can inspect the claims that the id token includes. Claims provide information about the users identity such as the customer they work for, their email address and name which your application can make use of.
You can also issue a GET
request to the following endpoint to get information on the user. Be sure to include your access token:
https://connect.reapit.cloud/oauth2/userInfo
Using refresh tokens
Access tokens issued from Reapit Connect will expire after 60 minutes. Refresh tokens provide your application with a means of retrieving a new set of tokens without requiring an interaction from the user.
Applications using the authorisation code grant (typically client side applications) now have refresh token rotation enabled. This means a refresh tokens can only be used once, and a fresh refresh token will be returned from the token endpoint each time a fresh access token is requested. The connect-session library handles this as part of the ReapitConnectBrowserSession
class. If your application manages it's own Reapit Connect session, ensure logic is in place to update the session's refresh token when using this endpoint.
To use a refresh token, issue a POST
request to the endpoint below with Content-type set to application/x-www-form-urlencoded
:
https://connect.reapit.cloud/token
Request payload
Description
client_id
The unique client id that was issued to your application after registration
refresh_token
The refresh token
grant_type
Must be set to refresh_token
For recommendations on how to safely store and interact with tokens, please see our web integration module Connect Session
Last updated