Skip to main content
Version: 4.xx.xx

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:

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​

PropertyDescriptionSuccess condition
login
Required
Logs user inAuth confirms login
logout
Required
Logs user outAuth confirms logout
check
Required
Checks credentials on each route changesAuthentication still persist
onError
Required
Checks if a dataProvider returns an errorData provider doesn't return an error
getPermissionsCan be use to get user credentialsAuthorization roles accepted
getIdentityCan be use to get user identityUser identity available to return
registerRegister userAuth confirms register
forgotPasswordCan be use to get password resetAuth confirms forgot password
updatePasswordCan be use to get update passwordAuth 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​

RUN IN YOUR LOCAL
npm create refine-app@latest -- --example auth-antd