Explicitly define cookieDomain as a parameter of Auth0Provider

[igor-q-bio]

Describe the problem you'd like to have solved

Problem description

In our React applications we rely on @auth0/auth0-react to implement integration with Auth0.
We want to have applications hosted on different subdomains benefit from the SSO via Auth0's Universal Login (not the Social features, however).
To achieve that, we leverage the cookieDomain field from @auth0/auth0-spa-js.
This results in a shared cookie being issued for .company.com which can be used by both apps hosted at dashboard.company.com and registration.company.com.

In our SPA code we are setting the cookieDomain directly on <Auth0Provider>.
The provider is then passing that option down to Auth0Client.
The issue is that the Auth0Provider does not mention this option in the documentation or in TypeScript declaration file.

Essentially, this is a hack that only works because currently toAuth0ClientOptions function makes sure to spread all fields the options object it received:

const toAuth0ClientOptions = (
  opts: Auth0ProviderOptions
): Auth0ClientOptions => {
  const { clientId, redirectUri, maxAge, ...validOpts } = opts;  // <<<<<
  return {
    ...validOpts,   // <<<<<
    client_id: clientId,
    redirect_uri: redirectUri,
    max_age: maxAge,
    auth0Client: {
      name: 'auth0-react',
      version: __VERSION__,
    },
  };
};

// ...

const Auth0Provider = (opts: Auth0ProviderOptions): JSX.Element => {
  const {
    children,
    skipRedirectCallback,
    onRedirectCallback = defaultOnRedirectCallback,
    context = Auth0Context,
    ...clientOpts                      // <<<<<
  } = opts;                               // <<<<<
  const [client] = useState(
    () => new Auth0Client(toAuth0ClientOptions(clientOpts))   // <<<<<
  );
  const [state, dispatch] = useReducer(reducer, initialAuthState);
  const didInitialise = useRef(false);
// ...

We want to continue using cookieDomain but are concerned that since this implementation detail is not documented as a feature, it can change any time causing us a regression and application outage.

What we want

We would like:

1. The Auth0 React SDK to explicitly document each property (including cookieDomain) that is passed down to Auth0Client.
2. Have the TypeScript declarations of Auth0ProviderOptions to reflect the same contract.

What we considered

We considered depending on @auth0/auth0-spa-js directly instead of using the React SDK, which will be a lot of unnecessary effort.
We want to keep using @auth0/auth0-react instead of reinventing the wheel/bicycle.

Additional context

Related issue and the PR that introduced that feature in @auth0/auth0-spa-js.

[adamjmcgrath]

Hi @igor-q-bio -

We want to continue using cookieDomain but are concerned that since this implementation detail is not documented as a feature, it can change any time causing us a regression and application outage.

auth0-react is a thin wrapper around spa js, so all the options available to spa js are available to auth0-react. Sometimes the documentation get's a little behind spa js - thanks for raising this, we'll make sure it gets fixed.

[igor-q-bio]

Thank you for the confirmation @adamjmcgrath !

[ewanharris]

Hey @igor-q-bio we just shipped a fix for this in the Auth0-React v2 beta, the types within Auth0-React now extend the Auth0-SPA-JS types so any properties supported by Auth0-SPA-JS are now included automatically.

You can install the beta using npm i @auth0/auth0-react@beta and the migration guide can be found here, if you'd like to try it out and provide any feedback that would be great!

Naturally moving forward there may be some delay in Auth0-React updating to include any new types, for TypeScript you should be able to get new types by updating the @auth0/auth0-spa-js dependency of Auth0-React in your app using npm update @auth0/auth0-spa-js. The docs site currently isn't updated and that will be done during the GA release of Auth0-React.