Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/articulate/authentic
Proper validation of JWT's against JWK's
https://github.com/articulate/authentic
auth0 javascript jwks jwt nodejs oidc okta
Last synced: 26 days ago
JSON representation
Proper validation of JWT's against JWK's
- Host: GitHub
- URL: https://github.com/articulate/authentic
- Owner: articulate
- License: mit
- Created: 2018-01-22T20:41:46.000Z (almost 7 years ago)
- Default Branch: main
- Last Pushed: 2024-01-03T17:05:27.000Z (12 months ago)
- Last Synced: 2024-04-29T21:23:11.945Z (8 months ago)
- Topics: auth0, javascript, jwks, jwt, nodejs, oidc, okta
- Language: TypeScript
- Homepage:
- Size: 262 KB
- Stars: 7
- Watchers: 56
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Codeowners: CODEOWNERS
Awesome Lists containing this project
README
# @articulate/authentic
Proper validation of JWT's against JWK's.
## Motivation
The process of validating JWT's against JWK's is [quite involved](https://auth0.com/blog/navigating-rs256-and-jwks/), but at the end of the day, you probably have an auth server with a `/.well-known/openid-configuration` endpoint, and you just want to know if an incoming JWT is valid. End of story. You don't want to fumble with parsing the JWT, matching `kid` values, converting certs, or caching JWK's.
Now you don't need to. Initialize `authentic` with an `issWhitelist`, and you'll receive a function that accepts a JWT and validates it. The rest is handled for you.
## Usage
```haskell
authentic :: { k: v } -> String -> Promise Boom { k: v }
```
Initialize `authentic` with an options object containing an `issWhitelist` array listing the `token.payload.iss` values you will accept. For example:
| Provider | Sample `issWhitelist` |
| -------- | ------------------- |
| [Auth0](https://auth0.com/) | `[ 'https://${tenant}.auth0.com/' ]` |
| [Okta](https://www.okta.com/) | `[ 'https://${tenant}.oktapreview.com/oauth2/${appName}' ]` |
**Note:** The urls in the list need to be **exact matches** of the `payload.iss` values in your JWT's.
You'll receive a unary function which takes a JWT and returns a `Promise` that resolves with the parsed JWT payload if it is valid, or rejects with a `401` [Boom](https://github.com/hapijs/boom) error if it is invalid.
```js
// lib/authentic.js
import { authentic } from '@articulate/authentic'
export default authentic({
issWhitelist: process.env.ISS_WHITELIST.split('|'),
})
// main.js
import authentic from './lib/authentic'
const handler = req =>
authentic(req.cookies.token)
.then(token => {
/* the JWT has been validated */
})
.catch(/* invalid token */)
```
## Options
`authentic` accepts a JSON object with the following options:
* `jwks` Object: options to forward to `jose.createRemoteJWKSet` from [`jose`](https://github.com/panva/jose/blob/main/docs/interfaces/jwks_remote.RemoteJWKSetOptions.md) with the following defaults:
| option | default |
| ----------- | ------- |
| `timeoutDuration` | `5000` (5 seconds) |
| `cooldownDuration` | `30000` (30 seconds) |
| `cacheMaxAge` | `60000` (10 minutes) |
* `verify` Object: options to forward to `jose.jwtVerify` from [`jose`](https://github.com/panva/jose/blob/main/docs/interfaces/jwt_verify.JWTVerifyOptions.md)
* `issWhitelist` Array: list of trusted OIDC issuers
* `claimsInError` Array: list of jwt payload claims to receive as the `data` property of the error when verification fails. When a list is not provided a `data` property will not be added to the error.
## Contributing
Changes are tracked & published using [changesets](https://github.com/changesets/changesets).
### Adding a Changeset
1. Create a git branch. Make your desired changes.
1. Run `yarn changesets`. Follow the prompts & specify if your change is a
major, minor, or patch change.
1. Add all the changes to `.changesets` & commit.
1. Create a Pull Request. Merge into the main branch when ready.
### Publishing to NPM
Changesets will create a "Release" pull request whenever unpublished changesets
are merged into main. When ready to publish to NPM, merge this pull request,
and changes will be automatically published.