Enrich onRedirectCallback method with User object (#400)

[devjmetivier]

Description

Enhance the onRedirectCallback prop in the Auth0Provider to expose the user, in this case, to conditionally redirect users.

For example:

Say a user is marked as a VIP in Auth0 as a means of enhancing that user's experience in the app. When the user logs in or creates an account as a VIP, they're redirected to a particular page and presented with special content as a VIP.

// in Next.js...

import { Auth0Provider } from '@auth0/auth0-react';
import Router from 'next/router';

const onRedirectCallback = (appState, user) => {
  const isVip = user['https://namespace.com/isVip'];  

  if (isVip) return Router.replace(`/welcome/vip`);
  
  Router.replace(appState && appState.returnTo ? appState.returnTo : window.location.pathname);
};

// ...

export default function App({ Component, pageProps }) {
  return (
    <>
      <Auth0Provider
        // ... other props
        onRedirectCallback={onRedirectCallback}
      >
        <Component {...pageProps} />
      </Auth0Provider>
    </>
  );
}

The implementation above allows developers to tailor the user's experience based on context from both the appState and any special properties attached to the user object after authentication with Auth0. Effectively creating a shorter journey to get the user where they need to be.

Without this implementation, where the user should be redirected to would be delegated to logic further down the component tree and would not have access to context from appState. This would require a different means of storing context about the user's authentication journey, likely in localStorage, before the user begins authentication with Auth0. That would look something like:

// in Next.js `pages/callback.js`

import * as React from 'react';

import { useAuth0 } from '@auth0/auth0-react';
import { useRouter } from 'next/router';

const CallbackPage = () => {
  const router = useRouter();
  const { user, isLoading, error } = useAuth0();
  
  const isVip = user ? user['https://namespace.com/isVip'] : undefined;

  React.useEffect(() => {
      if (!isLoading) {
        if (user) {
          const returnTo = localStorage.getItem('returnTo')

          if (isVip) {
            router.push(`/vip/${returnTo}`);
          } else {
            router.push(`/${returnTo}`);
          }

        if (error) router.replace('/');
      }
    }
  }, [error, isLoading, router, user]);

  return (
    // ...
  );
}

To my knowledge, this would be a non-breaking change with a minimal API change that only surfaces the user object to the onRedirectCallback method's second function argument.

References

Resolves #400

Testing

• This change adds test coverage for new/changed/fixed functionality

Authentication behavior can be tested by running the demo application included with this package. You could test the new implementation by setting conditional logic based on the user object inside a custom onRedirectCallback method.

My environment consists of:

• JS/TS
• MacOS
• Next.js
• Latest version of Chrome

Checklist

• I have added documentation for new/changed functionality in this PR or in auth0.com/docs
• All active GitHub checks for tests, formatting, and security are passing
• The correct base branch is being used, if not the default branch

[devjmetivier]

@adamjmcgrath

I'm having a bit of trouble completing the PR checklist. Something doesn't seem to work with the CircleCI step, and I also don't know where the proper place is to document this API change.

I'm assuming it would be documented by generating new docs with npm run docs?

[adamjmcgrath]

Hey @devjmetivier - PR lgtm, thanks

Let me figure out what's going on with the CI and get back to you

[adamjmcgrath]

I'm assuming it would be documented by generating new docs with npm run docs?

Yep, typedoc will generate new docs with the updated signature on the next release

[adamjmcgrath]

CI is passing here https://app.circleci.com/pipelines/github/auth0/auth0-react/686/workflows/0c265e51-0e74-4f12-bc02-96c6793210c3/jobs/857