Auth Provider

Auth provider is an object that contains methods to handle authentication and access control in your app by having refine consume them. These methods expect to return a promise, so they can be used with async methods.

You can use any third-party authentication service like Auth0, Okta, etc. or your own custom methods while creating an auth provider from scratch.

For more information on how you can create your own data providers, refer to the Create a Data Provider tutorial→

Usage

To use authProvider in refine, just pass it 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

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;

getIdentity expects to return a promise with the following type:

type IdentityResponse = unknown;

tip

You can return any type of data from the getPermission and getIdentity methods.

---

info

refine consumes these methods using the authorization hooks, which are used for authorization operations like login, logout, catching HTTP errors, etc.

Required Methods

login

required

login method is used to authenticate users.

It can be called with the useLogin hook

check

required

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

It can be called with the useIsAuthenticated hook

logout

required

logout method is used to log out users.

It can be called with the useLogout hook

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.

It can be called with the useOnError hook

Optional Methods

getPermissions

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

It can be called with the usePermissions hook

getIdentity

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

It can be called with the useGetIdentity hook

register

register method is used to register a new user.

It can be called with the useRegister hook

forgotPassword

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

It can be called with the useForgotPassword hook

updatePassword

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

It can be called with the useUpdatePassword hook

Hooks and Components

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

• useIsAuthenticated
• useOnError
• useGetIdentity
• useLogin
• useLogout
• usePermissions
• <Authenticated />
• useRegister
• useForgotPassword
• useUpdatePassword

Legacy Auth Provider

refine's v4 release is backward compatible and supports 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. →

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

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

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

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

FAQ

How can I create an auth provider?

Refer to the "Create Auth Provider From Scratch" section in the tutorial for more information →

How can I set authorization credentials?

Refer to the "Setting Authorization Credentials" section in the tutorial for more information →

How can I implement refresh token mechanism?

Refer to the "Implementing Refresh Token Mechanism" section in the tutorial for more information →

Example

VIEW SOURCE CODE →

RUN IN YOUR LOCAL

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