Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/koajs/userauth
koa user auth middleware
https://github.com/koajs/userauth
koa koa-middleware
Last synced: 2 months ago
JSON representation
koa user auth middleware
- Host: GitHub
- URL: https://github.com/koajs/userauth
- Owner: koajs
- License: mit
- Created: 2014-04-14T10:18:19.000Z (over 10 years ago)
- Default Branch: master
- Last Pushed: 2023-05-29T09:31:34.000Z (over 1 year ago)
- Last Synced: 2024-04-14T09:56:21.233Z (8 months ago)
- Topics: koa, koa-middleware
- Language: JavaScript
- Size: 78.1 KB
- Stars: 135
- Watchers: 7
- Forks: 19
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
- Changelog: History.md
- License: LICENSE
Awesome Lists containing this project
- awesome-koa - userauth - koa user auth middleware (Middleware)
README
# koa-userauth
[![NPM version][npm-image]][npm-url]
[npm-image]: https://img.shields.io/npm/v/koa-userauth.svg?style=flat-square
[npm-url]: https://npmjs.org/package/koa-userauth
`koa` user auth abstraction layer middleware.
## Install
```bash
npm install koa-userauth
```
## Usage
`koa-userauth` is dependent on [koa-session](https://github.com/koajs/session) or [koa-generic-session](https://github.com/koajs/generic-session).
```js
var koa = require('koa');
var userauth = require('koa-userauth');
var session = require('koa-generic-session');
var app = new koa();
app.keys = ['i m secret'];
app.use(session());
app.use(userauth({
match: '/user',
// auth system login url
loginURLFormatter: function (url) {
return 'http://login.demo.com/login?redirect=' + url;
},
// login callback and getUser info handler
getUser: async ctx => {
var token = this.query.token;
// get user
return user;
}
}));
```
### Arguments
If `options.match` or `options.ignore` is `String` instance,
we will use [path-match](https://github.com/expressjs/path-match) transfer it to `Regex` instance.
```js
/**
* User auth middleware.
*
* @param {Object} [options]
* - {String|Regex|Function(pathname, ctx)} match, detect which url need to check user auth.
* `''` empty string meaning match all, @see `path-match` package.
* - {String|Regex|Function(pathname, ctx)} ignore, detect which url no need to check user auth.
* If `match` exists, this argument will be ignored.
* - {Function(url, rootPath, ctx)} loginURLFormatter, format the login url.
* - {String} [rootPath], custom app url root path, default is '/'.
* - {String} [loginPath], default is '/login'.
* - {String} [loginCallbackPath], default is `options.loginPath + '/callback'`.
* - {String} [logoutPath], default is '/logout'.
* - {String} [userField], logined user field name on `this.session`, default is 'user', `this.session.user`.
* - {Async Function (ctx)} getUser, get user function, must get user info with `req`.
* - {Async Function (ctx, user)} [loginCallback], you can handle user login logic here,return [user, redirectUrl]
* - {Function(ctx)} [loginCheck], return true meaning logined. default is `true`.
* - {Async Function (ctx, user)} [logoutCallback], you can handle user logout logic here.return redirectUrl
* - {Function(ctx)} [getRedirectTarget], customize how to get the redirect target after login
* @return {Async Function (next)} userauth middleware
* @public
*/
```
## Login flow
1. unauth user, redirect to `$loginPath?redirect=$currentURL`
2. user visit `$loginPath`, redirect to `options.loginURLFormatter()` return login url.
3. user visit $loginCallbackPath, handler login callback logic.
4. If user login callback check success, will set `req.session[userField]`,
and redirect to `$currentURL`.
5. If login check callback error, next(err).
6. user visit `$logoutPath`, set `req.session[userField] = null`, and redirect back.
> [Source image file](https://www.lucidchart.com/documents/edit/4749f226-b75f-42ef-934f-b89f7bd68c7f?driveId=0ACmMEQjF7GJGUk9PVA)
## License
[MIT](LICENSE)