https://github.com/ackeecz/petrus
A tool for handling token-based authentication in react, redux, redux-saga applications.
https://github.com/ackeecz/petrus
ackee authentication frontend javascript oauth2-client react redux redux-saga tokens-persistence tokens-refreshment
Last synced: 10 months ago
JSON representation
A tool for handling token-based authentication in react, redux, redux-saga applications.
- Host: GitHub
- URL: https://github.com/ackeecz/petrus
- Owner: AckeeCZ
- License: mit
- Created: 2018-12-13T08:54:58.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2024-12-17T13:11:53.000Z (over 1 year ago)
- Last Synced: 2025-03-27T01:06:54.386Z (about 1 year ago)
- Language: TypeScript
- Homepage:
- Size: 2.81 MB
- Stars: 7
- Watchers: 7
- Forks: 1
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
> # ⚠️ Deprecated in favour of [Bear Auth](https://github.com/AckeeCZ/bear-auth/tree/main)
> Why?
> - `@ackee/petrus` works great in the stack of redux and redux saga, i.e. generators but in promise-based stack, it's basically useless.
> - The API design is old and somewhat cumbersome.
>
> __On the contrary, the Bear Auth can be used just in vanilla JS and in within generators stack as well. It's over 3x smaller. The API has been designed like pure functions (rather than one heavy object) to support tree-shaking. Plus it got some new features__.
>
> - 👉 [Bear Auth](https://github.com/AckeeCZ/bear-auth/tree/main)
> - 👉 [Migration guide from `@ackee/petrus` to the Bear Auth](https://github.com/AckeeCZ/petrus/blob/master/MIGRATION_GUIDE_TO_BEAR_AUTH.md)
---
# [](https://github.com/AckeeCZ/petrus/blob/master/LICENSE) [](https://bundlephobia.com/result?p=@ackee/petrus)
# Petrus
A tool for handling token-based authentication in `react`, `redux`, `redux-saga` applications.
It automatically refreshes an access token based on provided expiration timestamp, persists state, so the authentication session can last longer.
---
## Table of contents
- [Installation](#installation)
- [Usage Examples](#usage-examples)
- [API](https://github.com/AckeeCZ/petrus/wiki/Exports)
---
## Installation
```bash
$ yarn add @ackee/petrus
```
### Stack Dependencies
`@ackee/petrus` requires a following peer dependencies:
```
"core-js": "3.x",
"react": "16.x | 17.x | 18.x",
"react-redux": "7.x | 8.x",
"redux": "4.x",
"redux-saga": "1.x"
```
---
## Usage examples
### Authentication flows
1. Direct authentication (with password)
- [Basic config](https://githubbox.com/AckeeCZ/petrus/tree/master/codesandboxes/basic)
- Obtaining tokens with `authenticate` method by sending credentials to an endpoint from `loginRequest` Redux action.
- Fetching authorized user with `getAuthUser` method.
- Automatically refreshing `accessToken` based on provided `expiration` prop.
- Tokens and auth. user local persistence in IndexedDB.
- Using custom TS types for auth user, tokens, and credentials.
2. Federated authentication (with a token)
- [OAuth 2.0 – Authorization Code Flow](https://githubbox.com/AckeeCZ/petrus/tree/master/codesandboxes/oauth-authorization-code)
> What's an authorization code flow?
>
> - The front channel flow is used by the client application to obtain an authorization code grant.
> - The back channel is used by the client application to exchange the authorization code grant for an access token (and optionally a refresh token).
> - High security flow.
- OAuth 2.0 – Implicit Flow
> What's an implicit flow?
>
> - An access token is returned directly from the authorization request (front channel only). It typically does not support refresh tokens.
> - This flow is also called 2 Legged OAuth.
> - Low security by default, make sure to follow at least [these security rules](https://developer.okta.com/blog/2017/06/21/what-the-heck-is-oauth#security-and-the-enterprise).
Of course, you can choose from any other numerous flows available.
Learn more about OAuth flows in ["What the heck is OAuth?"](https://developer.okta.com/blog/2017/06/21/what-the-heck-is-oauth) article.
### Other examples
3. Usage with [`@ackee/antonio` API client](https://github.com/AckeeCZ/antonio/tree/master/packages/@ackee/antonio-auth#requestauthheaderinterceptorrequest-request-request)