Add /login-callback route and optional new authProvider.handleLoginCalback() method

docs/Admin.md

@@ -41,6 +41,7 @@ Here are all the props accepted by the component:
 - [`theme`](#theme)
 - [`layout`](#layout)
 - [`loginPage`](#loginpage)
+- [`loginCallbackPage`](#logincallbackpage)
 - [`history`](#history)
 - [`basename`](#basename)
 - [`ready`](#ready)
@@ -441,6 +442,24 @@ See The [Authentication documentation](./Authentication.md#customizing-the-login
 
 **Tip**: Before considering writing your own login page component, please take a look at how to change the default [background image](./Theming.md#using-a-custom-login-page) or the [MUI theme](#theme). See the [Authentication documentation](./Authentication.md#customizing-the-login-component) for more details.
 
+## `loginCallbackPage`
+
+If you want to customize the LoginCallback page, pass a component of your own as the `loginCallbackPage` prop. React-admin will display this component whenever the `/login-callback` route is called.
+
+```jsx
+import MyLoginCallbackPage from './MyLoginCallbackPage';
+
+const App = () => (
+    <Admin loginCallbackPage={MyLoginCallbackPage}>
+        ...
+    </Admin>
+);
+```
+
+You can also disable it completely along with the `/login-callback` route by passing `false` to this prop.
+
+See The [Authentication documentation](./Authentication.md#handling-external-authentication-services-callbacks) for more details.
+
 ## ~~`history`~~
 
 **Note**: This prop is deprecated. Check [the Routing chapter](./Routing.md) to see how to use a different router.

docs/Authentication.md

@@ -34,6 +34,8 @@ What's an `authProvider`? Just like a `dataProvider`, an `authProvider` is an ob
 const authProvider = {
     // send username and password to the auth server and get back credentials
     login: params => Promise.resolve(),
+    // validate authentication from an external service (e.g. OAuth)
+    handleLoginCallback: () => Promise.resolve(),
     // when the dataProvider returns an error, check if this is an authentication error
     checkError: error => Promise.resolve(),
     // when the user navigates, make sure that their credentials are still valid
@@ -82,6 +84,15 @@ Now the admin is secured: The user can be authenticated and use their credential
 
 If you have a custom REST client, don't forget to add credentials yourself.
 
+## Handling External Authentication Services Callbacks
+
+When using external authentication services such as those implementing OAuth, you usually need a callback route. React-admin provides a default one at `/login-callback`. It will call the `AuthProvider.handleLoginCallback` method
+that may validate the params received from the URL and redirect users to any page (the home page by default) afterwards.
+
+It's up to you to decide when to redirect users to the third party authentication service, for instance:
+    - Directly in the `AuthProvider.checkAuth` method;
+    - After a user interaction on the login page;
+
 ## Allowing Anonymous Access
 
 As long as you add an `authProvider`, react-admin restricts access to all the pages declared in the `<Resource>` components. If you want to allow anonymous access, you can set the `disableAuthentication` prop in the page components. 

packages/ra-core/src/auth/index.ts

@@ -15,6 +15,7 @@ export * from './types';
 export * from './useAuthenticated';
 export * from './useCheckAuth';
 export * from './useGetIdentity';
+export * from './useHandleLoginCallback';
 
 export {
     AuthContext,

packages/ra-core/src/auth/useHandleLoginCallback.spec.tsx

@@ -0,0 +1,178 @@
+import * as React from 'react';
+import expect from 'expect';
+import { screen, render, waitFor } from '@testing-library/react';
+import { unstable_HistoryRouter as HistoryRouter } from 'react-router-dom';
+import { QueryClientProvider, QueryClient } from 'react-query';
+import { createMemoryHistory } from 'history';
+
+import { useHandleLoginCallback } from './useHandleLoginCallback';
+import AuthContext from './AuthContext';
+
+import { BasenameContextProvider } from '../routing';
+import { useRedirect } from '../routing/useRedirect';
+import { AuthProvider } from '../types';
+
+jest.mock('../routing/useRedirect');
+
+const redirect = jest.fn();
+// @ts-ignore
+useRedirect.mockImplementation(() => redirect);
+
+const TestComponent = ({ customError }: { customError?: boolean }) => {
+    const [error, setError] = React.useState<string>();
+    useHandleLoginCallback(
+        customError
+            ? {
+                  onError: error => {
+                      setError(error as string);
+                  },
+              }
+            : undefined
+    );
+    return error ? <>{error}</> : null;
+};
+
+const authProvider: AuthProvider = {
+    login: () => Promise.reject('bad method'),
+    logout: () => {
+        return Promise.resolve();
+    },
+    checkAuth: params => (params.token ? Promise.resolve() : Promise.reject()),
+    checkError: params => {
+        if (params instanceof Error && params.message === 'denied') {
+            return Promise.reject(new Error('logout'));
+        }
+        return Promise.resolve();
+    },
+    getPermissions: () => Promise.reject('not authenticated'),
+    handleLoginCallback: () => Promise.resolve(),
+};
+
+const queryClient = new QueryClient();
+
+describe('useHandleLoginCallback', () => {
+    afterEach(() => {
+        redirect.mockClear();
+    });
+
+    it('should redirect to the home route by default when the callback was successfully handled', async () => {
+        const history = createMemoryHistory({ initialEntries: ['/'] });
+        render(
+            <HistoryRouter history={history}>
+                <AuthContext.Provider value={authProvider}>
+                    <QueryClientProvider client={queryClient}>
+                        <TestComponent />
+                    </QueryClientProvider>
+                </AuthContext.Provider>
+            </HistoryRouter>
+        );
+        await waitFor(() => {
+            expect(redirect).toHaveBeenCalledWith('/');
+        });
+    });
+
+    it('should redirect to the provided route when the callback was successfully handled', async () => {
+        const history = createMemoryHistory({ initialEntries: ['/'] });
+        render(
+            <HistoryRouter history={history}>
+                <AuthContext.Provider
+                    value={{
+                        ...authProvider,
+                        handleLoginCallback: () =>
+                            Promise.resolve({ redirectTo: '/test' }),
+                    }}
+                >
+                    <QueryClientProvider client={queryClient}>
+                        <TestComponent />
+                    </QueryClientProvider>
+                </AuthContext.Provider>
+            </HistoryRouter>
+        );
+        await waitFor(() => {
+            expect(redirect).toHaveBeenCalledWith('/test');
+        });
+    });
+
+    it('should redirect to the home route by default when the callback was not successfully handled', async () => {
+        const history = createMemoryHistory({ initialEntries: ['/'] });
+        render(
+            <HistoryRouter history={history}>
+                <AuthContext.Provider
+                    value={{
+                        ...authProvider,
+                        handleLoginCallback: () => Promise.reject(),
+                    }}
+                >
+                    <QueryClientProvider client={queryClient}>
+                        <TestComponent />
+                    </QueryClientProvider>
+                </AuthContext.Provider>
+            </HistoryRouter>
+        );
+        await waitFor(() => {
+            expect(redirect).toHaveBeenCalledWith('/');
+        });
+    });
+
+    it('should redirect to the provided route when the callback was not successfully handled', async () => {
+        const history = createMemoryHistory({ initialEntries: ['/'] });
+        render(
+            <HistoryRouter history={history}>
+                <AuthContext.Provider
+                    value={{
+                        ...authProvider,
+                        handleLoginCallback: () =>
+                            Promise.reject({ redirectTo: '/test' }),
+                    }}
+                >
+                    <QueryClientProvider client={queryClient}>
+                        <TestComponent />
+                    </QueryClientProvider>
+                </AuthContext.Provider>
+            </HistoryRouter>
+        );
+        await waitFor(() => {
+            expect(redirect).toHaveBeenCalledWith('/test');
+        });
+    });
+
+    it('should use custom useQuery options such as onError', async () => {
+        const history = createMemoryHistory({ initialEntries: ['/'] });
+        render(
+            <HistoryRouter history={history}>
+                <AuthContext.Provider
+                    value={{
+                        ...authProvider,
+                        handleLoginCallback: () =>
+                            Promise.resolve({ redirectTo: '/test' }),
+                    }}
+                >
+                    <QueryClientProvider client={queryClient}>
+                        <TestComponent customError />
+                    </QueryClientProvider>
+                </AuthContext.Provider>
+            </HistoryRouter>
+        );
+        await waitFor(() => {
+            expect(redirect).toHaveBeenCalledWith('/test');
+        });
+    });
+
+    it('should take basename into account when redirecting to home route', async () => {
+        const history = createMemoryHistory({ initialEntries: ['/foo'] });
+        render(
+            <HistoryRouter history={history}>
+                <BasenameContextProvider basename="/foo">
+                    <AuthContext.Provider value={authProvider}>
+                        <QueryClientProvider client={queryClient}>
+                            <TestComponent />
+                        </QueryClientProvider>
+                    </AuthContext.Provider>
+                </BasenameContextProvider>
+            </HistoryRouter>
+        );
+        await waitFor(() => {
+            expect(redirect).toHaveBeenCalledWith('/foo/');
+        });
+    });
+});

packages/ra-core/src/auth/useHandleLoginCallback.ts

@@ -0,0 +1,57 @@
+import { useQuery, UseQueryOptions } from 'react-query';
+import { useBasename, useRedirect } from '../routing';
+import { removeDoubleSlashes } from '../routing/useCreatePath';
+import { AuthRedirectResult } from '../types';
+import useAuthProvider from './useAuthProvider';
+
+/**
+ * This hook calls the `authProvider.handleLoginCallback()` method. This is meant to be used in a route called
+ * by an external authentication service (e.g. Auth0) after the user has logged in.
+ * By default, it redirects to the `redirectTo` location, home page if undefined.
+ *
+ * @returns The result of the `handleLoginCallback` call. Destructure as { isLoading, data, error, refetch }.
+ */
+export const useHandleLoginCallback = <
+    HandleLoginCallbackResult = AuthRedirectResult | void
+>(
+    options?: UseQueryOptions<HandleLoginCallbackResult>
+) => {
+    const authProvider = useAuthProvider();
+    const redirect = useRedirect();
+    const basename = useBasename();
+
+    return useQuery(
+        ['handleLoginCallback', 'auth'],
+        () => authProvider.handleLoginCallback<HandleLoginCallbackResult>(),
+        {
+            retry: false,
+            onSuccess: data => {
+                const redirectTo = (data as AuthRedirectResult)?.redirectTo;
+
+                if (redirectTo === false) {
+                    return;
+                }
+
+                redirect(
+                    data == null || redirectTo === true
+                        ? removeDoubleSlashes(`${basename}/`)
+                        : redirectTo
+                );
+            },
+            onError: err => {
+                const redirectTo = (err as AuthRedirectResult)?.redirectTo;
+
+                if (redirectTo === false) {
+                    return;
+                }
+
+                redirect(
+                    err == null || redirectTo === true
+                        ? removeDoubleSlashes(`${basename}/`)
+                        : redirectTo
+                );
+            },
+            ...options,
+        }
+    );
+};

packages/ra-core/src/core/CoreAdminUI.tsx

@@ -26,6 +26,7 @@ export interface CoreAdminUIProps {
     disableTelemetry?: boolean;
     layout?: LayoutComponent;
     loading?: LoadingComponent;
+    loginCallbackPage?: LoginComponent | boolean;
     loginPage?: LoginComponent | boolean;
     /**
      * @deprecated use a custom layout instead
@@ -45,6 +46,7 @@ export const CoreAdminUI = (props: CoreAdminUIProps) => {
         layout = DefaultLayout,
         loading = Noop,
         loginPage: LoginPage = false,
+        loginCallbackPage: LoginCallbackPage = false,
         menu, // deprecated, use a custom layout instead
         ready = Ready,
         title = 'React Admin',
@@ -70,6 +72,14 @@ export const CoreAdminUI = (props: CoreAdminUIProps) => {
             {LoginPage !== false && LoginPage !== true ? (
                 <Route path="/login" element={createOrGetElement(LoginPage)} />
             ) : null}
+
+            {LoginCallbackPage !== false && LoginCallbackPage !== true ? (
+                <Route
+                    path="/login-callback"
+                    element={createOrGetElement(LoginCallbackPage)}
+                />
+            ) : null}
+
             <Route
                 path="/*"
                 element={

packages/ra-core/src/core/useConfigureAdminRouterFromChildren.tsx

@@ -10,7 +10,7 @@ import {
     useEffect,
     useState,
 } from 'react';
-import { useLogout, usePermissions, useAuthState } from '../auth';
+import { useLogout, usePermissions } from '../auth';
 import { useSafeSetState } from '../util';
 import {
     AdminChildren,
@@ -79,7 +79,6 @@ const useRoutesAndResourcesFromChildren = (
     // We need to know right away wether some resources were declared to correctly
     // initialize the status at the next stop
     const doLogout = useLogout();
-    const { authenticated } = useAuthState();
     const [
         routesAndResources,
         setRoutesAndResources,
@@ -142,7 +141,6 @@ const useRoutesAndResourcesFromChildren = (
             updateFromChildren();
         }
     }, [
-        authenticated,
         children,
         doLogout,
         isLoading,

packages/ra-core/src/types.ts

@@ -67,9 +67,14 @@ export type AuthProvider = {
     checkError: (error: any) => Promise<void>;
     getIdentity?: () => Promise<UserIdentity>;
     getPermissions: (params: any) => Promise<any>;
+    handleLoginCallback?: <
+        HandleLoginCallbackResult = AuthRedirectResult
+    >() => Promise<HandleLoginCallbackResult | void>;
     [key: string]: any;
 };
 
+export type AuthRedirectResult = { redirectTo?: string | boolean };
+
 export type LegacyAuthProvider = (
     type: AuthActionType,
     params?: any

packages/ra-ui-materialui/src/AdminUI.tsx

@@ -9,7 +9,7 @@ import {
     NotFound,
     Notification,
 } from './layout';
-import { Login } from './auth';
+import { Login, LoginCallback } from './auth';
 
 export const AdminUI = ({ notification, ...props }: AdminUIProps) => (
     <ScopedCssBaseline enableColorScheme>
@@ -27,5 +27,6 @@ AdminUI.defaultProps = {
     catchAll: NotFound,
     loading: LoadingPage,
     loginPage: Login,
+    loginCallbackPage: LoginCallback,
     notification: Notification,
 };