https://github.com/koole/react-sanctum
Easily hook up your React app to Laravel Sanctum and Laravel Fortify
https://github.com/koole/react-sanctum
authentication laravel-fortify laravel-sanctum react react-components sanctum two-factor-authentication
Last synced: 25 days ago
JSON representation
Easily hook up your React app to Laravel Sanctum and Laravel Fortify
- Host: GitHub
- URL: https://github.com/koole/react-sanctum
- Owner: koole
- License: mit
- Created: 2020-02-29T22:29:04.000Z (about 5 years ago)
- Default Branch: master
- Last Pushed: 2025-03-26T13:55:23.000Z (about 1 month ago)
- Last Synced: 2025-04-01T12:08:56.393Z (about 1 month ago)
- Topics: authentication, laravel-fortify, laravel-sanctum, react, react-components, sanctum, two-factor-authentication
- Language: PHP
- Homepage:
- Size: 4.91 MB
- Stars: 153
- Watchers: 5
- Forks: 27
- Open Issues: 29
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
## Introduction
React Sanctum package provides an easy way to authenticate your React application with [Laravel Sanctum](https://laravel.com/docs/8.x/sanctum#introduction).
- Easily hook up your React app to Laravel Sanctum
- Works with both hooks and class components
- Built in support for two factor authentication with [Laravel Fortify](https://laravel.com/docs/8.x/fortify#introduction)
- Just one dependency: [axios](https://github.com/axios/axios)
## Usage
Install from NPM
```
npm i react-sanctum
```
Wrap your application in a `` component
### Example
```js
import React from "react";
import { Sanctum } from "react-sanctum";
const sanctumConfig = {
apiUrl: "http://foobar.test",
csrfCookieRoute: "sanctum/csrf-cookie",
signInRoute: "login",
signOutRoute: "logout",
userObjectRoute: "user",
};
const App = () => (
/* Your application code */
);
```
You can then use the `useSanctum()` hook to get authentication status, user data and sanctum related
methods in any component.
```js
import React from "react";
import { useSanctum } from "react-sanctum";
const LoginButton = () => {
const { authenticated, user, signIn } = useSanctum();
const handleLogin = () => {
const email = "[email protected]";
const password = "example";
const remember = true;
signIn(email, password, remember)
.then(() => window.alert("Signed in!"))
.catch(() => window.alert("Incorrect email or password"));
};
if (authenticated === true) {
return
Welcome, {user.name}
;
} else {
return Sign in;
}
};
export default LoginButton;
```
Or use the `withSanctum()` higher-order component to get these same values.
```js
import React from "react";
import { withSanctum } from "react-sanctum";
const LoginButton = ({ authenticated, user, signIn }) => {
...
};
export default withSanctum(LoginButton);
```
You can also directly consume the Sanctum context by importing `SanctumContext`.
The `useSanctum` hook and the `withSanctum` HOC give you access to the `SanctumContext`, which contains the following
data and methods:
| | Description |
|-|------------------------------------------------------------------------------------|
| `user` | Object your API returns with user data |
| `authenticated` | Boolean, or null if authentication has not yet been checked |
| `signIn()` | Accepts `(email, password, remember?)`, returns a promise, resolves with `{twoFactor: boolean, signedIn: boolean, user: {}}`. |
| `signOut()` | Returns a promise |
| `setUser()` | Accepts `(user, authenticated?)`, allows you to manually set the user object and optionally its authentication status (boolean). |
| `twoFactorChallenge()` | Accepts `(code, recovery?)`, returns a promise, resolves with the user object. |
| `checkAuthentication()` | Returns the authentication status. If it's null, it will ask the server and update `authenticated`. |
# Setup
All URLS in the config are required. These need to be created in your Laravel app.
```js
const sanctumConfig = {
// Your application URL
apiUrl: "http://foobar.test",
// The following settings are URLS that need to be created in your Laravel application
// The URL sanctum uses for the csrf cookie
csrfCookieRoute: "sanctum/csrf-cookie",
// {email: string, password: string, remember: true | null} get POSTed to here
signInRoute: "api/login",
// A POST request is sent to this route to sign the user out
signOutRoute: "api/logout",
// Used (GET) for checking if the user is signed in (so this should be protected)
// The returned object will be avaiable as `user` in the React components.
userObjectRoute: "api/user",
// The URL where the OTAP token or recovery code will be sent to (optional).
// Only needed if you want to use two factor authentication.
twoFactorChallengeRoute: "two-factor-challenge",
// An axios instance to be used by react-sanctum (optional). Useful if you for example need to add custom interceptors.
axiosInstance: AxiosInstance,
// Optional key used for the username POSTed to Laravel, defaults to "email".
usernameKey: "email";
};
```
react-sanctum automatically checks if the user is signed in when the the ``
component gets mounted. If you don't want this, and want to manually use the
`checkAuthentication` function later, set `checkOnInit` to `false` like so:
```js
```
# Handling registration
Methods for signIn and signOut are provided by this library. Registration is not included as there seem to be many ways
people handle registration flows.
If you want to sign in your user after registration, there's an easy way to do this. First, make sure the endpoint you
post the registration data to signs in the user (`Auth::guard()->login(...)`) and have it return the user object to the
front-end.
In your front-end you can then pass this user object into the `setUser()` function, et voilà, your new user has been
signed in.
For example:
```js
axios
.post(`${API_URL}/register`, data)
.then(function (response) {
const user = response.data;
setUser(user); // The react-sanctum setUser function
...
})
.catch(function (error) {
...
});
```
# Two factor authentication
This package supports two factor authentication using Laravel Fortify out of the box.
1. Install Laravel Fortify using the following instructions
https://laravel.com/docs/8.x/fortify#installation
2. Add the `TwoFactorAuthenticable` trait to the User model
https://laravel.com/docs/8.x/fortify#two-factor-authentication
3. Make sure the `two-factor-challenge` route is included in the `config/cors.php` file.
Example for implementation:
```js
import React, { useState } from "react";
import { useSanctum } from "react-sanctum";
const Login = () => {
const [showTwoFactorForm, setShowTwoFactorForm] = useState(false);
const [code, setCode] = useState("");
const [recoveryCode, setRecoveryCode] = useState("");
const { authenticated, user, signIn, twoFactorChallenge } = useSanctum();
const handleLogin = () => {
const email = "[email protected]";
const password = "password";
const remember = true;
signIn(email, password, remember)
.then(({ twoFactor }) => {
if (twoFactor) {
setShowTwoFactorForm(true);
return;
}
window.alert("Signed in without token!");
})
.catch(() => window.alert("Incorrect email or password"));
};
const handleTwoFactorChallenge = (recovery = false) => {
twoFactorChallenge(recovery ? recoveryCode : code, recovery)
.then(() => window.alert("Signed in with token!"))
.catch(() => window.alert("Incorrect token"));
};
if (authenticated === true) {
return
Welcome, {user.name}
;
} else {
if (showTwoFactorForm) {
return (
setCode(event.currentTarget.value)}
/>
handleTwoFactorChallenge()}>
Sign in using OTAP-token
setRecoveryCode(event.currentTarget.value)}
/>
handleTwoFactorChallenge(true)}>
Sign in using recovery token
);
}
return Sign in;
}
};
export default Login;
```
# Axios
Quick tip for people using axios: react-sanctum uses Axios for making requests to your server. If your project is also
using axios, make sure to set
`axios.defaults.withCredentials = true;`. That way axios will authenticate your requests to the server properly.