@maglr/laravel-passport-spa-js
    TypeScript icon, indicating that this package has built-in type declarations

    0.1.8 • Public • Published

    laravel-passport-spa-js

    GitHub package.json version Build Quality Gate Status Sonar Coverage install size License

    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.

    Install

    npm i @maglr/laravel-passport-spa-js

    DownloadsWeekly Downloads

    10

    Version

    0.1.8

    License

    MIT

    Unpacked Size

    174 kB

    Total Files

    89

    Last publish

    Collaborators

    • sherin_maglr