{"id":22268066,"url":"https://github.com/curityio/express-oauth-jwt","last_synced_at":"2025-07-28T12:30:52.482Z","repository":{"id":42082189,"uuid":"256130978","full_name":"curityio/express-oauth-jwt","owner":"curityio","description":"A Node.js Express example API Secured with OAuth tokens","archived":false,"fork":false,"pushed_at":"2024-11-07T08:40:21.000Z","size":118,"stargazers_count":11,"open_issues_count":0,"forks_count":4,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-12-03T06:35:48.438Z","etag":null,"topics":["api","claims","jwt-validation","oauth2","scopes","sdk","zero-trust"],"latest_commit_sha":null,"homepage":"https://curity.io/resources/learn/express-jwt/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/curityio.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-04-16T06:39:58.000Z","updated_at":"2024-11-07T08:39:46.000Z","dependencies_parsed_at":"2024-03-29T09:50:31.232Z","dependency_job_id":null,"html_url":"https://github.com/curityio/express-oauth-jwt","commit_stats":{"total_commits":15,"total_committers":6,"mean_commits":2.5,"dds":0.7333333333333334,"last_synced_commit":"192e99573c071a20c77e53c566f126e30598298c"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/curityio%2Fexpress-oauth-jwt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/curityio%2Fexpress-oauth-jwt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/curityio%2Fexpress-oauth-jwt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/curityio%2Fexpress-oauth-jwt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/curityio","download_url":"https://codeload.github.com/curityio/express-oauth-jwt/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227905532,"owners_count":17837906,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","claims","jwt-validation","oauth2","scopes","sdk","zero-trust"],"created_at":"2024-12-03T11:10:57.410Z","updated_at":"2025-07-28T12:30:52.472Z","avatar_url":"https://github.com/curityio.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Securing endpoints in Express with OAuth JWT tokens\n       \n[![Quality](https://img.shields.io/badge/quality-test-yellow)](https://curity.io/resources/code-examples/status/)\n[![Availability](https://img.shields.io/badge/availability-source-blue)](https://curity.io/resources/code-examples/status/)\n\n\nThis library allows you to secure your Express endpoints with JWTs. The implementation uses a JWKS endpoint of an\nAuthorization Server to get keys required for the verification of the token signature.\n\n## Running the example\n\n1. Download the code and install dependencies running `npm i`.\n2. In `settings.js` in the `example` directory set the URI of the JWKS endpoint exposed by the Authorization Server.\n3. Start the demo server with `npm run example`.\n4. The server exposes endpoints `/secured/token`, `/secured/scope` and `/secured/claim` which present different options\nof securing the endpoints.\n\n## Installing the dependency\n\nUse `npm` to install the library in your project:\n\n```bash\nnpm install express-oauth-jwt\n```\n\n## Usage\n\n### Preparing the Middleware\n\nThe `secure` middleware needs a method to obtain keys. You can use the `jose`-provided method, or create your own instance.\nThe method is responsible for obtaining signature verification keys for a concrete token, and has the signature:\n\n`function(headerParameters: JWSHeaderParameters, input: FlattenedJWSInput): Promise\u003cKeyLike | Uint8Array\u003e | KeyLike | Uint8Array`\n\nThe easiest way is to use the method provided by the `jose` library. The method caches the result of the JWKS endpoint request\nin memory to limit sending requests to the server.\n\n```javascript\nconst jwksService = createRemoteJWKSet(new URL(settings.jwks_uri))\nconst midleware = secure(jwksService)\n\n```\n\n### Securing an endpoint\n\nTo secure an endpoint apply the `secure` middleware to it. Any endpoint with this middleware applied will require a valid\nJWT token sent in the `Authorization` header in the form `Bearer \u003ctoken_value\u003e`. The token, if valid, will be decoded\nand all its claims will be set in the request in a `claims` field.\n\nIf the token does not pass validation, a 403 response will be returned. If no JWT token is found in the request, a 401\nresponse will be returned. The response will have the `WWW-Authenticate` header set with detailed information on\nthe error (as specified in the [RFC 6750: The OAuth 2.0 Authorization Framework: Bearer Token Usage](https://tools.ietf.org/html/rfc6750)).\n\nIf you want the `WWW-Authenticate` to return a `realm` value, pass the middleware an `options` object with the `realm`\noption set.\n\n```javascript\nconst { secure } = require('express-oauth-jwt');\nrouter.use(secure(jwksService, { realm: 'my-realm' }));\n```\n\nThe `WWW-Authenticate` header in the error response will then might look like this:\n\n```curl\nWWW-Authenticate: Bearer realm=\"my-realm\", error=\"invalid_token\", error_description=\"...\"\n```\n\n### Authorizing the request based on scopes\n\nIn order to limit the request to given scope values pass the middleware an `options` object with a list of strings in the\n`scope` field:\n\n```javascript\nconst secure = require('express-oauth-jwt');\nrouter.use(secure(jwksService, { scope: [\"scope1\", \"scope2\"] }));\n```\n\n### Authorizing the request based on claims\n\nIn order to limit the request based on the presence or value of concrete claims, pass the middleware an `options` object\nwith a list of claims in the `claims` field. Each claim should be an object with at least the `name` field. Optionally\nyou can set the `value` field. If only the `name` field is set then the validator checks whether the claim\nexists in the token. If `value` is set as well, then the value of the claim in the token must also match.\n\n```javascript\nconst secure = require('express-oauth-jwt');\nrouter.use(secure(jwksService, { claims: [ { name: \"someClaim\", value: \"withValue\" } ] }));\n```\n\n## Using Opaque tokens\n\nThis middleware uses JSON Web Tokens, which can be easily decoded offline into a JSON object containing claims about\nthe user or client sending the request. But this is not always the case that JWT tokens are used for authorization.\nSometimes the Authorization Server will issue an opaque token, which is just an identifier of the user's data, and the\ndata itself is kept safely with the Authorization Server.\n\nIf you use opaque tokens for authorization then the token needs to be exchanged for data associated with it. It\ncannot be decoded, as the value of the token does not contain any data. In such situation, the best approach is to use the\nPhantom token approach - let your API gateway exchange the opaque token for a JWT. This way your service will always\nreceive a JWT which can be decoded with the approach shown here.\n\nYou can find out more on the Phantom token approach in the\n[Phantom Token Pattern](https://curity.io/resources/architect/api-security/phantom-token-pattern/) article.\n\nIf you're using Curity Identity Server you can learn how to enable Phantom tokens with the help of\n[this tutorial](https://curity.io/resources/operate/tutorials/integration/introspect-with-phantom-token/).\n\n## Access token claims in Request object\n\nThe `secure` middleware adds claims obtained from the access token into the Express request object, in the `claims`\nfield. You can access these claims in any other middleware which is next in chain and in the controllers.\n\n```javascript\nfunction getLibraryData(req, res) {\n    if (req.claims.myClaim == 'someValue') {\n        ...\n    }\n    ...\n}\n```\n\n## Questions and Support\n\nFor questions and support, contact Curity AB:\n\n\u003e Curity AB\n\u003e\n\u003e info@curity.io\n\u003e https://curity.io\n\nCopyright (C) 2020 Curity AB.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcurityio%2Fexpress-oauth-jwt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcurityio%2Fexpress-oauth-jwt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcurityio%2Fexpress-oauth-jwt/lists"}