Logging in Users
Authenticating and authorizing users into your application.
We recommend setting up two routes in your application called
/auth/login and /auth/callback to manage the authorization flow.We have created a reference implementation using Remix and the Remix OAuth library here which we will refer to several times in this step.
To begin the authentication flow you will need to redirect users to the passport authorization endpoint and include the Client ID and a random state parameter in the query string so that it looks like this:
https://passport.rollup.id/authorize?client_id=<your app id>&state=<generated state>Typically you would do this by redirecting users to a route in your application that redirects users to the above route.
We do allow custom CNAMEs of passport for PRO accounts.
The state parameter should be persisted in a cookie or some other storage method so that it can be referred to in a later step. In our reference implementation the remix-oauth library handles this for us.
From here, Rollup will use the Client ID provided to lookup your application details so your application name and branding information will be displayed. If your application requires specific authorization scopes the user will then be presented with an authorization screen (example below).
When completed the user will then be redirected back to your app using the "Redirect URL" set in the previous step.
Your Redirect URL should be prepared to accept an exchange token and state parameters.
// https://<redirect_url>?code=<exchange code>&state=<state>
- Code: the exchange code needed request an access token
- State: this state should match the state you created for the user/client in step 1
The state parameter should match the state you sent when you kicked off the auth flow in Step 1. This is a security measure in the auth protocol to prevent replay attacks. The exchange code is then sent with the Client Secret and the grant type to Passport's token endpoint in order to receive the access token and refresh token as base64 encoded signed JWT as well as a minimal user profile (encoded in an ID token) completing the flow.
We use a javascript library called jose to encode and decode signed JWT. As an open standard there are libraries for all languages that do the same.
post
https://passport.rollup.id/token
Exchange access code for access token
Every access token is valid for 1 hour. This expiry time is stored in the "exp" property in the JWT. **** On the other hand, the refresh token is valid for **90 days** and can be used to request another access token using the same exchange code endpoint with the "refresh_token" grant type.
There are multiple ways to manage this refresh flow, here is our reference implementation. In summary, we store the tokens encrypted in a user cookie that is valid for 90 days and refresh when needed.
If you ever find yourself with an expired refresh token you can consider this as the user being "logged out" and redirect them back to passport for login to repeat this flow.
ID tokens are only supplied when the initial set of tokens is retrieved, and are not provided again during usage of refresh tokens. Use the
/userinfo endpoint to retrieve fresh user details. The response, as well as what is encoded in the ID token, is shaped as follows:{
name: string,
picture: string,
//...ID token encodes other claims as well
}
Inside the ID token object you will find a unique claim called
sub which will be consistent across all logins. This will match the value of the sub claim in access and refresh tokens also.Here is a link to the reference implementation doing just this. With the access token you can make authorized requests to the Profile Graph for this user.