Version: 4.xx.xx

Auth Provider

Auth provider is an object which contains methods to handle authentication and authorization in your app. It provides a way to authenticate users and authorize them to access resources. refine consumes these methods via auth hooks.

By default, refine doesn't handle authentication in the app. When you need, you can pass authProvider to the <Refine> component as a prop.

Auth provider's methods expect to return a resolved Promise. So, you can use async methods to create auth provider. Therefore, to create auth provider from scratch, you can use any third-party authentication service like Auth0, Okta, etc., or your own custom methods.

Refer to the "Create Auth Provider From Scratch" tutorial for more information &#8594

Usage

To use authProvider in refine, we have to pass the authProvider to the <Refine /> component.

App.tsx
import { Refine } from "@refinedev/core";
import dataProvider from "@refinedev/simple-rest";

import authProvider from "./auth-provider";

const App = () => {
    return (
        <Refine
            authProvider={authProvider}
            dataProvider={dataProvider("https://api.fake-rest.refine.dev")}
        >
            {/* ... */}
        </Refine>
    );
};

Examples

You can use the following auth provider examples as a starting point for your own auth provider or you can use them as it is. Check the links below to see the details of each example.

Basic - A basic auth provider example.
Keycloak - An auth provider example with Keycloak.
Auth0 - An auth provider example with Auth0.
Google Auth - An auth provider example with Google Auth.
OTP Login - An auth provider example with OTP Login.
Appwrite - An auth provider example with Appwrite.
Supabase - An auth provider example with Supabase.
Strapi - An auth provider example with Strapi.
Strapi Graphql - An auth provider example with Strapi Graphql.
Nhost - An auth provider example with Nhost.
Basic with Nextjs - A basic auth provider example with Nextjs.
Basic with Remix - A basic auth provider example with Remix.

Methods

Auth provider's methods are expected to return a resolved Promise. So, you can use these async methods to create auth provider.

An authProvider includes the following methods:

import type { AuthBindings } from "@refinedev/core";

const authProvider: AuthBindings = {
    // required methods
    login: async (params: any) => ({}),
    check: async (params: any) => ({}),
    logout: async (params: any) => ({}),
    onError: async (params: any) => ({}),
    // optional methods
    register: async (params: any) => ({}),
    forgotPassword: async (params: any) => ({}),
    updatePassword: async (params: any) => ({}),
    getPermissions: async (params: any) => ({}),
    getIdentity: async (params?: any) => ({}),
};

login, logout, register, forgotPassword, updatePassword expect to return a resolved Promise with the following type:

type AuthActionResponse = {
    success: boolean;
    redirectTo?: string;
    error?: Error;
    [key: string]: unknown;
};

success: A boolean indicating whether the operation was successful.
redirectTo: A string indicating the URL to redirect to after the operation completes.
error: An object containing details about any errors encountered during the operation.
[key: string]: Any additional data you wish to include in the response, keyed by a string identifier.

check expects to return a Promise with the following type:

type CheckResponse = {
    authenticated: boolean;
    redirectTo?: string;
    logout?: boolean;
    error?: Error;
};

authenticated: A boolean indicating whether the user is authenticated or not.
redirectTo: A string indicating the URL to redirect to after the operation completes.
error: An object containing details about any errors encountered during the operation.
[key: string]: Any additional data you wish to include in the response, keyed by a string identifier.

getPermission expects to return a Promise with the following type:

type PermissionResponse = unknown;

You can return any type of data from getPermission method.

getIdentity expects to return a Promise with the following type:

type IdentityResponse = unknown;

You can return any type of data from getIdentity method.

info

refine consumes these methods using authorization hooks. Authorization hooks are used to manage authentication and authorization operations like login, logout, catching HTTP errors, etc.

Refer to the Auth Provider tutorial for more information and usage examples. &#8594

Required Methods

login method is used to authenticate users.

You can use useLogin hook to call login method.

check
required

check method is used to check if the user is authenticated.

You can use useIsAuthenticated hook to call check method.

logout
required

logout method is used to log out users.

You can use useLogout hook to call logout method.

onError
required

onError method is called when you get an error response from the API. You can create your own business logic to handle the error such as refreshing the token, logging out the user, etc.

You can use useOnError hook to call onError method.

Optional Methods

getPermissions

getPermissions method is used to get the user's permissions.

You can use usePermissions hook to call getPermissions method.

getIdentity

getIdentity method is used to get the user's identity.

You can use useGetIdentity hook to call getIdentity method.

register

register method is used to register a new user.

You can use useRegister hook to call register method.

forgotPassword

forgotPassword method is used to send a password reset link to the user's email address.

You can use useForgotPassword hook to call forgotPassword method.

updatePassword

updatePassword method is used to update the user's password.

You can use useUpdatePassword hook to call updatePassword method.

Hooks and Components

These hooks can be used with the authProvider authentication and authorization operations.

Legacy Auth Provider

refine's v4 release is backward compatible and supports the legacy auth provider implementations until v5.

If you want to use a legacy auth provider, you can pass them to the <Refine /> component using the legacyAuthProvider prop.

Refer to the Migration Guide for more information. &#8594

import { LegacyAuthProvider, Refine } from "@refinedev/core";

const legacyAuthProvider: LegacyAuthProvider = {
    /* --- */
};

const App = () => {
    return (
        <Refine
            // ---
            legacyAuthProvider={legacyAuthProvider}
        >
            {/* --- */}
        </Refine>
    );
};

FAQ

API Reference

Properties

Property	Description	Success condition
login Required	Logs user in	Auth confirms login
logout Required	Logs user out	Auth confirms logout
check Required	Checks credentials on each route changes	Authentication still persist
onError Required	Checks if a dataProvider returns an error	Data provider doesn't return an error
getPermissions	Can be use to get user credentials	Authorization roles accepted
getIdentity	Can be use to get user identity	User identity available to return
register	Register user	Auth confirms register
forgotPassword	Can be use to get password reset	Auth confirms forgot password
updatePassword	Can be use to get update password	Auth confirms update password

Example

VIEW SOURCE CODE →

RUN IN YOUR LOCAL

npm create refine-app@latest -- --example auth-antd

Usage​

Examples​

Methods​

Required Methods​

login required​

check required​

logout required​

onError required​

Optional Methods​

getPermissions​

getIdentity​

register​

forgotPassword​

updatePassword​

Hooks and Components​

Legacy Auth Provider​

FAQ​

How can I create authProvider?​

How can I set authorization credentials?​

How can I implement refresh token mechanism?​

API Reference​

Properties​

Example​