Nightly Perpetrated Mischief

    apollo-link-jwt

    1.1.5 • Public • Published

    Apollo Link JWT Logo

    Apollo Link JWT

    npm version Bulid Status codecov contributions welcome GitHub license

    An Apollo Link utility to handle JWT Authorization requests by automatically setting the headers with the access token and handling the refresh logic when the access token expires.

    Introduction

    The package automatically detects when an access token has expired using JWT decode to keep the secret out of the client. It works with any existing endpoint that returns a new access token and refresh token from a provided refresh token by using a callback to handle any response structure.

    Note: This package supports tokens stored in async-storage or any other manner of async lookup, helpful for React Native projects

    Install

    npm i apollo-link-jwt

    Note: Apollo V3 is a required peer depedency expected to be installed in your project already

    Example

    const httpLink = createHttpLink({
      uri: GRAPHQL_API,
    });
     
    /**
     * Create Apollo Link JWT
     */
    const apolloLinkJWT = ApolloLinkJWT({
      apiUrl: 'https://your-api-url',
      getTokens: async () => {
        const accessToken = await AsyncStorage.getItem('ACCESS_TOKEN');
        const refreshToken = await AsyncStorage.getItem('REFRESH_TOKEN');
     
        return { accessToken, refreshToken };
      },
      fetchBody: async () => {
        // Define fetch query
        const query = {...};
     
        return { query };
      },
      onRefreshComplete: async (data) => {
        // Parse 'data' to extract the tokens from your existing refresh token API response
        // Handle errors if fetch failed, call existing methods such as signOut();
        ...
        return { newAccessToken, newRefreshToken };
      },
    });
     
    return new ApolloClient({
      link: from([
        apolloLinkJWT,
        httpLink, // Add terminating link last
      ]),
    });

    Request Headers

    This utility will set the Authorization: Bearer token headers on requests when an access token is provided. This scheme is described by the rfc6750

    Motivation

    Becasue handling JWT in the client should be an easy process and consistently handled across projects using Apollo Client. In addition, there are many times when you will want to provide an access token and refresh token stored in AsynStorage (if you're using React Native), which requires async support by the utlity. With Apollo Link JWT, you can pass async functions which get the tokens on the client with aysnc support.

    The premise is simple:

    1. Set the request headers once the app has a valid access token and refresh token
    2. Check the expiration of the access token in the utility before every network request, if the access token has an expired 'exp' attribute, then use the refresh token to make a fetch and retrieve a new access token and refresh token
    3. Send the tokens back to your client application so they can store them someplace (potentially async storage or local storage)
    4. Automatically append the access token JWT to the headers going forward
    5. Allow the app to handle a graceful logout when the refresh token fetch has failed (in the case of the refresh token being invalid)

    The manual process of checking the access tokens expiration should be done in the client before every network request so an unnecessary network request is not made once it's expired. We can use JTW Decode here because we're only validating the token expiration time, even if this was faked by the user, it would only trigger a refresh token lookup sooner than expected.

    API

    Attribute Required Async Default Description
    apiUrl true false - The URL string of your API endpoint where the refresh token call should be made.
    getTokens true true - An async supported function that should return a valid accessToken and refreshToken stored in the client. Because this supports aysnc, you can use local storage or async storage which requires 'await'.
    fetchBody true true - The query required to fetch a new access token with when a valid refresh token was given. The package also accepts an optional 'variables' attribute which can contain additional fields if required by the server, such as 'email'.
    fetchHeaders false false { 'Content-Type': 'application/json' } An optional attribute to set the headers needed during the refresh token fetch.
    onRefreshComplete true true - The main callback required to handle the fetch logic. This function should contain the logic required to parse the tokens from the response and return the new access and refresh tokens to the utility. You can also perform any other logic in here on failures, such as calling a sign out method already defined in the application.
    debugMode false false false Optional boolean that sends helpful console logs to the output for debugging purposes. Recommended to leave this off for production.

    Usage

    const getTokens = async () => {
      const accessToken = await getAsyncStorage(ACCESS_TOKEN);
      const refreshToken = await getAsyncStorage(REFRESH_TOKEN);
     
      return {
        accessToken,
        refreshToken,
      };
    };
     
    const onRefreshComplete = async (data) => {
      // Find and return the access token and refresh token from the provided fetch callback
      const newAccessToken = data?.data?.token?.accessToken;
      const newRefreshToken = data?.data?.token?.refreshToken;
     
      // Handle sign out logic if the refresh token attempt failed
      if (!newAccessToken || !newRefreshToken) {
        console.log('Redirect back to login, because the refresh token was expired!');
     
        signOutHandler();
     
        return;
      }
     
      // Update tokens in AsyncStorage
      await setAsyncStorage(ACCESS_TOKEN, newAccessToken);
      await setAsyncStorage(REFRESH_TOKEN, newRefreshToken);
     
      // Return the tokens back to the lib to cache for later use
      return {
        newAccessToken,
        newRefreshToken,
      };
    };
     
    /**
     * Configure the body of the token refresh method
     */
    const fetchBody = async () => ({
      query: `mutation RefreshAccessToken($email: String!, $refreshToken: String!) {
        token (email: $email, refreshToken: $refreshToken) {
          accessToken
          refreshToken
        }
      }`,
      variables: {
        email: await getAsyncStorage(EMAIL),
      },
    });
     
    /**
     * Create Apollo Link JWT
     */
    const apolloLinkJWT = ApolloLinkJWT({
      apiUrl: GRAPHQL_API,
      getTokens,
      fetchBody,
      onRefreshComplete,
      debugMode: true,
    });
     
    const httpLink = createHttpLink({
      uri: GRAPHQL_API,
    });
     
    return new ApolloClient({
      link: from([
        apolloLinkJWT,
        httpLink, // Add terminating link last
      ]),
    });

    Technologies

    Roadmap

    1. Add unit tests
    2. Convert project to TypeScript

    Install

    npm i apollo-link-jwt

    DownloadsWeekly Downloads

    51

    Version

    1.1.5

    License

    MIT

    Unpacked Size

    17.7 kB

    Total Files

    14

    Last publish

    Collaborators

    • avatar