Skip to main content
Version: 3.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 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 '@pankod/refine-core'
import routerProvider from '@pankod/refine-react-router-v6'
import dataProvider from '@pankod/refine-simple-rest'

import authProvider from './auth-provider'

const API_URL = 'https://api.fake-rest.refine.dev'

const App = () => {
return (
<Refine
authProvider={authProvider}
routerProvider={routerProvider}
dataProvider={dataProvider(API_URL)}
/>
)
}

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 Promise. So, you can use these async methods to create auth provider.

An authProvider includes the following methods:

import { AuthProvider } from '@pankod/refine-core'

const authProvider: AuthProvider = {
// required methods
login: () => Promise.resolve(),
checkAuth: () => Promise.resolve(),
logout: () => Promise.resolve(),
checkError: () => Promise.resolve(),
// optional methods
register: () => Promise.resolve(),
forgotPassword: () => Promise.resolve(),
updatePassword: () => Promise.resolve(),
getPermissions: () => Promise.resolve(),
getUserIdentity: () => Promise.resolve(),
}
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
required

login method is used to authenticate users. It expects to return a Promise.

  • If the Promise resolves, the user is authenticated and pages that require authentication will be accessible.

  • If the Promise rejects, the user is not authenticated and stays on the login page.

You can use useLogin hook to call login method.

checkAuth
required

checkAuth method is used to check if the user is authenticated. Internally, it is called when the user navigates to a page that requires authentication.

checkAuth method expects to return a Promise.

  • If the Promise resolves, the user is authenticated and pages that require authentication will be accessible.

  • If the Promise rejects, the user is not authenticated and pages that require authentication will not be accessible and by default, the user will be redirected to the /login page.

You can use useAuthenticated hook to call checkAuth method.

logout
required

logout method is used to log out users. It expects to return a Promise.

  • If the Promise resolves, the user is logged out and pages that require authentication will not be accessible and by default, the user will be redirected to the /login page.

  • If the Promise rejects, the user is not logged out and stays on the page.

You can use useLogout hook to call logout method.

checkError
required

checkError 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.

checkError method expects to return a Promise.

  • If the Promise resolves, the user is not logged out and stays on the page.

  • If the Promise rejects, the logout method is called to log out the user and by default, the user is redirected to the /login route.

You can use useCheckError hook to call checkError method.

Optional Methods

getPermissions

getPermissions method is used to get the user's permissions. It expects to return a Promise.

  • If the Promise resolves with data, the user's permissions will be available in the usePermissions hook's data property.

  • If the Promise rejects, the user's permissions will not be available and usePermissions hook throw an error.

You can use usePermissions hook to call getPermissions method.

getUserIdentity

getUserIdentity method is used to get the user's identity. It expects to return a Promise.

  • If the Promise resolves with a data, the user's identity will be available in the useGetIdentity hook's data property.

  • If the Promise rejects, the user's identity will not be available and useGetIdentity hook throw an error.

You can use useGetIdentity hook to call getUserIdentity method.

register

register method is used to register a new user. It is similar to the login method. It expects to return a Promise.

  • If the Promise resolves, by default, the user will be redirected to the / page.

  • If the Promise rejects, the useRegister hook will throw an error.

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. It expects to return a Promise.

You can use useForgotPassword hook to call forgotPassword method.

updatePassword

updatePassword method is used to update the user's password. It expects to return a Promise.

You can use useUpdatePassword hook to call updatePassword method.

Hooks and Components

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

FAQ

How can I create authProvider?

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

How can I set authorization credentials?

Refer to the "Setting Authorization Credentials" section in the tutorial for more information &#8594

API Reference

Properties

PropertyDescriptionResolve condition
login
Required
Logs user inAuth confirms login
logout
Required
Logs user outAuth confirms logout
checkAuth
Required
Checks credentials on each route changesAuthentication still persist
checkError
Required
Checks if a dataProvider returns an errorData provider doesn't return an error
getPermissionsCan be use to get user credentialsAuthorization roles accepted
getUserIdentityCan 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

Example

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