@maglr/laravel-passport-spa-js
v0.1.8
Published
Toolkit to use Laravel's Passport Authorization flow (PKCE) from a Javascript web app context.
Downloads
8
Maintainers
Readme
laravel-passport-spa-js
This package handles the token management from a Laravel back-end using Passport authentification in a Single-Page Application using the OAuth authorization flow (PKCE). It allows you to safely get tokens without storing them in the local storage or cookies.
Content
How does it work
The package retrieves tokens by making an authorization request to the server through an iframe. The authorization code is then exchanged for a token which is cached in memory. When this token expires, a new one is retrieved using the same approach.
This will work as long as the user has an active session at the authentication server. When this session expires, the user is redirected to the authentication server's sign in page.
This package has been inspired by @auth0/auth0-spa-js.
Installation
Using npm:
npm install @maglr/laravel-passport-spa-js
Getting started
Before starting here, make sure your authentification server is up and running and that you have the id of your public Passport client (see Laravel's doc).
1. Creating the client
The first step is to create a LaravelPassportClient
instance as everything is done through this object.
import createLaravelPassportClient from 'laravel-passport-spa-js';
const lpClient = createLaravelPassportClient({
// the domain of your authentication server (protocol is optional and defaults to https://)
domain: 'auth.server.com',
// the id of your Passport client
client_id: 1,
// the uri the authentication server will send the authorization codes to
redirect_uri: 'http://localhost:8080/auth/callback',
});
Note that the redirect_uri
must match exactly the one stored for your Passport client.
⚠️ Make this object available in your app but do not expose it to the global scope.
2. Sign in (optional)
// async / await
const isSuccessfullySignedIn = await lpClient.signIn();
or
// Promise
lpClient.signIn().then(signInResult => {});
This will acquire a token through an iframe and cache it. If the iframe method fails, the user will be redirected to the sign in page of your authentication server.
This step is optional as getting a token will perform a signIn()
if no valid token is present.
3 Handling redirect callback
// async / await
const isSuccessfullySignedIn = await lpClient.handleRedirectCallback();
or
// Promise
lpClient.handleRedirectCallback().then(signInResult => {});
This should be present on the page reached by the specified redirect_uri
to extract and consume the given authorization code.
By using the Promise syntax you can immediately redirect your user to another page of your app and have the promise resolve in the background. If the redirect is done by changing the location
, the Promise will most likely not be fullfiled but now that your user has a session at the authentication server, you can simply get a token (see below) and the sign in will be performed silently through an iframe.
4. Getting a token
// async / await
const token = await lpClient.getToken();
or
// Promise
lpClient.getToken().then(token => {});
This will give the token in cache or perform a signIn()
as described in point 2.
5. Sign out (optional)
lpClient.signOut();
This will clear the token cache.
Documentation
Client options
When creating the LaravelPassportClient
instance, you can pass several options. Some are required, others are optional and come with default value if not specified.
const laravelClientOptions = {
/**
* REQUIRED
* Your Laravel Passport authentification url such as
* `'auth.server.com' or 'http://auth.server.localhost'`.
*/
domain: string;
/**
* REQUIRED
* The Client ID.
*/
client_id: string;
/**
* REQUIRED
* The default URL where Laravel Passport will redirect your browser to with the
* authentication result.
*/
redirect_uri: string;
/**
* The prefix fow Passport's routes on the authentication server.
* Defaults to `'oauth'`.
*/
oauthPrefix: string;
/**
* The default scope to be used on authentication requests.
* Defaults to `'*'`.
*/
scope: string;
/**
* A maximum number of seconds to wait before declaring background calls to /
* authorize as failed for timeout.
* Defaults to `60`.
*/
authorizeTimeoutInSeconds: number;
/**
* Whether a new sign in should be attempted if no valid token is present when
* `getToken()` is called.
* Defaults to `true`.
*/
isAutoRefresh: boolean;
};
const lpClient = createLaravelPassportClient(laravelClientOptions);
The optional elements can be accessed and modified on the client after creation:
// get / set oauthPrefix
lpClient.oauthPrefix;
// get / set scope
lpClient.scope;
// get / set authorizeTimeoutInSeconds
lpClient.authorizeTimeoutInSeconds;
// get / set isAutoRefresh
lpClient.isAutoRefresh;
Available methods
lpClient.getToken()
Returns
Promise<string | null>
Get the token this client has in cache. Resolves on the token (string
) or null
if no valid token present and lpClient.isAutoRefresh
is false
.
lpClient.getTokenScopes()
Returns
string[] | null
Get this client token's scope(s) as an array. Returns null
if no token present. Note that the scopes are returned even if the token is expired.
lpClient.getTokenExpiration()
Returns
Date | null
Get this client token's expiration date. Returns null
if no token present. Note that the Date is returned even if the token is expired.
lpClient.isTokenValid()
Returns
boolean
Returns true
if the client has a token which is not expired, false
otherwise.
lpClient.getSignedInUserId()
Returns
number | null
Get this client token's user id. Returns null
if no valid token present.
lpClient.signIn(scope?: string)
Returns
Promise<boolean>
Sign the client in. Starts with the iframe flow and fallsback to redirect flow if needed. If provided, the given scope
value will override the client's scope. Resolves on true
if the sign in has been successful, false
otherwise.
lpClient.signInWithRedirect(scope?: string)
Returns
Promise<void>
Redirect to the authorize URL ('/oauth/authorize'
by default) with appropriate parameters. If provided, the given scope value will override the client's scope.
lpClient.handleRedirectCallback()
Returns
Promise<boolean>
Extract the authorization code returned in the query string and exchange it for a new token. Resolves on true
if the sign in has been successful, false
otherwise.
lpClient.signOut()
Returns
void
Remove the cached token.
Support and Feedback
For support or to provide feedback, please raise an issue on the GitHub page.
License
This project is licensed under the MIT license. See the LICENSE file for more info.