https://github.com/curityio/express-oauth-jwt
A Node.js Express example API Secured with OAuth tokens
https://github.com/curityio/express-oauth-jwt
api claims jwt-validation oauth2 scopes sdk zero-trust
Last synced: 11 months ago
JSON representation
A Node.js Express example API Secured with OAuth tokens
- Host: GitHub
- URL: https://github.com/curityio/express-oauth-jwt
- Owner: curityio
- License: apache-2.0
- Created: 2020-04-16T06:39:58.000Z (about 6 years ago)
- Default Branch: master
- Last Pushed: 2024-11-07T08:40:21.000Z (over 1 year ago)
- Last Synced: 2024-12-03T06:35:48.438Z (over 1 year ago)
- Topics: api, claims, jwt-validation, oauth2, scopes, sdk, zero-trust
- Language: JavaScript
- Homepage: https://curity.io/resources/learn/express-jwt/
- Size: 115 KB
- Stars: 11
- Watchers: 6
- Forks: 4
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# Securing endpoints in Express with OAuth JWT tokens
[](https://curity.io/resources/code-examples/status/)
[](https://curity.io/resources/code-examples/status/)
This library allows you to secure your Express endpoints with JWTs. The implementation uses a JWKS endpoint of an
Authorization Server to get keys required for the verification of the token signature.
## Running the example
1. Download the code and install dependencies running `npm i`.
2. In `settings.js` in the `example` directory set the URI of the JWKS endpoint exposed by the Authorization Server.
3. Start the demo server with `npm run example`.
4. The server exposes endpoints `/secured/token`, `/secured/scope` and `/secured/claim` which present different options
of securing the endpoints.
## Installing the dependency
Use `npm` to install the library in your project:
```bash
npm install express-oauth-jwt
```
## Usage
### Preparing the Middleware
The `secure` middleware needs a method to obtain keys. You can use the `jose`-provided method, or create your own instance.
The method is responsible for obtaining signature verification keys for a concrete token, and has the signature:
`function(headerParameters: JWSHeaderParameters, input: FlattenedJWSInput): Promise | KeyLike | Uint8Array`
The easiest way is to use the method provided by the `jose` library. The method caches the result of the JWKS endpoint request
in memory to limit sending requests to the server.
```javascript
const jwksService = createRemoteJWKSet(new URL(settings.jwks_uri))
const midleware = secure(jwksService)
```
### Securing an endpoint
To secure an endpoint apply the `secure` middleware to it. Any endpoint with this middleware applied will require a valid
JWT token sent in the `Authorization` header in the form `Bearer `. The token, if valid, will be decoded
and all its claims will be set in the request in a `claims` field.
If the token does not pass validation, a 403 response will be returned. If no JWT token is found in the request, a 401
response will be returned. The response will have the `WWW-Authenticate` header set with detailed information on
the error (as specified in the [RFC 6750: The OAuth 2.0 Authorization Framework: Bearer Token Usage](https://tools.ietf.org/html/rfc6750)).
If you want the `WWW-Authenticate` to return a `realm` value, pass the middleware an `options` object with the `realm`
option set.
```javascript
const { secure } = require('express-oauth-jwt');
router.use(secure(jwksService, { realm: 'my-realm' }));
```
The `WWW-Authenticate` header in the error response will then might look like this:
```curl
WWW-Authenticate: Bearer realm="my-realm", error="invalid_token", error_description="..."
```
### Authorizing the request based on scopes
In order to limit the request to given scope values pass the middleware an `options` object with a list of strings in the
`scope` field:
```javascript
const secure = require('express-oauth-jwt');
router.use(secure(jwksService, { scope: ["scope1", "scope2"] }));
```
### Authorizing the request based on claims
In order to limit the request based on the presence or value of concrete claims, pass the middleware an `options` object
with a list of claims in the `claims` field. Each claim should be an object with at least the `name` field. Optionally
you can set the `value` field. If only the `name` field is set then the validator checks whether the claim
exists in the token. If `value` is set as well, then the value of the claim in the token must also match.
```javascript
const secure = require('express-oauth-jwt');
router.use(secure(jwksService, { claims: [ { name: "someClaim", value: "withValue" } ] }));
```
## Using Opaque tokens
This middleware uses JSON Web Tokens, which can be easily decoded offline into a JSON object containing claims about
the user or client sending the request. But this is not always the case that JWT tokens are used for authorization.
Sometimes the Authorization Server will issue an opaque token, which is just an identifier of the user's data, and the
data itself is kept safely with the Authorization Server.
If you use opaque tokens for authorization then the token needs to be exchanged for data associated with it. It
cannot be decoded, as the value of the token does not contain any data. In such situation, the best approach is to use the
Phantom token approach - let your API gateway exchange the opaque token for a JWT. This way your service will always
receive a JWT which can be decoded with the approach shown here.
You can find out more on the Phantom token approach in the
[Phantom Token Pattern](https://curity.io/resources/architect/api-security/phantom-token-pattern/) article.
If you're using Curity Identity Server you can learn how to enable Phantom tokens with the help of
[this tutorial](https://curity.io/resources/operate/tutorials/integration/introspect-with-phantom-token/).
## Access token claims in Request object
The `secure` middleware adds claims obtained from the access token into the Express request object, in the `claims`
field. You can access these claims in any other middleware which is next in chain and in the controllers.
```javascript
function getLibraryData(req, res) {
if (req.claims.myClaim == 'someValue') {
...
}
...
}
```
## Questions and Support
For questions and support, contact Curity AB:
> Curity AB
>
> info@curity.io
> https://curity.io
Copyright (C) 2020 Curity AB.