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 →
Usage
To use authProvider
in refine, we have to pass the authProvider
to the <Refine />
component.
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(),
}
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. →
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'sdata
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'sdata
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.
- useAuthenticated
- useCheckError
- useGetIdentity
- useLogin
- useLogout
- usePermissions
<Authenticated />
- useRegister
- useForgotPassword
- useUpdatePassword
FAQ
How can I create authProvider?
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 →
API Reference
Properties
Property | Description | Resolve condition |
---|---|---|
login Required | Logs user in | Auth confirms login |
logout Required | Logs user out | Auth confirms logout |
checkAuth Required | Checks credentials on each route changes | Authentication still persist |
checkError 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 |
getUserIdentity | 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
npm create refine-app@latest -- --example auth-antd