https://github.com/auth0/express-oauth2-bearer
Experimental Middleware for express.js to validate access tokens.
https://github.com/auth0/express-oauth2-bearer
dx-sdk
Last synced: 9 months ago
JSON representation
Experimental Middleware for express.js to validate access tokens.
- Host: GitHub
- URL: https://github.com/auth0/express-oauth2-bearer
- Owner: auth0
- License: mit
- Archived: true
- Created: 2018-11-26T14:13:44.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2023-07-19T05:14:20.000Z (almost 3 years ago)
- Last Synced: 2024-09-28T23:05:52.875Z (over 1 year ago)
- Topics: dx-sdk
- Language: JavaScript
- Homepage:
- Size: 202 KB
- Stars: 40
- Watchers: 13
- Forks: 12
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
> **Please Note:** This repository is experimental and will reach end-of-life on **June 30, 2023**. To protect Express.js APIs with JWT Bearer Tokens, we recommend [express-oauth2-jwt-bearer](https://github.com/auth0/node-oauth2-jwt-bearer/tree/main/packages/express-oauth2-jwt-bearer). See the [Migration Guide](./MIGRATION_GUIDE.md) and the [blog post](https://auth0.com/blog/introducing-oauth2-express-sdk-protecting-api-with-jwt/#What-s-Happening-to--express-jwt----express-jwt-authz---and--jwks-rsa-) for more details).
Authentication middleware for Express.js that validates access tokens following [RFC 6750](https://tools.ietf.org/html/rfc6750). The purpose of this library is to protect OAuth 2.0 resources.
## Table of Contents
[](https://app.fossa.com/projects/git%2Bgithub.com%2Fauth0%2Fexpress-oauth2-bearer?ref=badge_shield)
- [Installation](#installation)
- [Getting Started](#getting-started)
- [Contributing](#contributing)
- [Support + Feedback](#support--feedback)
- [Vulnerability Reporting](#vulnerability-reporting)
- [What is Auth0](#what-is-auth0)
- [License](#license)
## Installation
This library is installed with [npm](https://npmjs.org/package/express-oauth2-bearer):
```
npm i express-oauth2-bearer --save
```
## Getting Started
The library needs the following values to authroize requests:
- **Issuer Base URL**: The base URL of the authorization server. If you're using Auth0, this is your tenant **Domain** pre-pended with `https://` (like `https://tenant.auth0.com`) found on the **Settings** tab for your Application in the [Auth0 dashboard](https://manage.auth0.com).
- **Allowed Audiences**: Audience identifier (or multiple separated by a comma) allowed for the access token. If you're using Auth0, this is the **Identifier** found on the **Settings** tab for your API in the [Auth0 dashboard](https://manage.auth0.com/#/apis).
These can be configured in a `.env` file in the root of your application:
```text
# .env
ISSUER_BASE_URL=https://YOUR_DOMAIN
ALLOWED_AUDIENCES=https://api.yourapplication.com
```
... or in your application code:
```js
const { auth } = require('express-oauth2-bearer');
app.use(auth({
issuerBaseURL: 'https://tenant.auth0.com',
allowedAudiences: 'https://api.yourapplication.com'
}));
```
The OpenID strategy is the default strategy for token validation. With the configuration values set in the `.env` file, the following code will restrict requests to all proceeding routes to ones that have a valid access token with the `https://api.yourapplication.com` audience and the `read:products` scope:
```javascript
const { auth, requiredScopes } = require('express-oauth2-bearer');
app.use(auth());
app.get('/products',
requiredScopes('read:products'),
(req, res) => {
console.dir(req.auth.claims);
res.sendStatus(200);
});
```
If access tokens are not expected to be signed like OpenID Connect ID tokens, add the `auth` middleware with a callback to validate as follows:
```javascript
const { auth, requiredScopes } = require('express-oauth2-bearer');
const validateAccesToken = async (token) => {
const token = await db.tokens.find(token);
if (token.expired) { return; }
return token;
};
app.use(auth(validateAcessToken)));
app.get('/products',
requiredScopes('read:products'),
(req, res) => {
console.dir(req.auth.claims);
res.sendStatus(200);
});
```
### API Documentation:
`auth()` accepts an asynchronous function receiving an access token and returning a set of claims.
`requiredScopes()` accepts either a string or an array of strings.
`strategies.openid` accepts the following parameters:
| Name | Default | Description |
|---------------------|------------------------------------|----------------------------------------------------------------------|
| issuerBaseURL | `env.ISSUER_BASE_URL` | URL for the token issuer. |
| allowedAudiences | `env.ALLOWED_AUDIENCES.split(',')` | Allowed audiences for the token. |
| clockTolerance | `5` | Clock tolerance in seconds for token verification, aka leeway. |
| clientSecret | `env.CLIENT_SECRET` | Client secret, required for tokens signed with symmetric algorithms. |
## Contributing
We appreciate feedback and contribution to this repo! Before you get started, please see the following:
- [Auth0's general contribution guidelines](https://github.com/auth0/.github/blob/master/CONTRIBUTING.md)
- [Auth0's code of conduct guidelines](https://github.com/auth0/open-source-template/blob/master/CODE-OF-CONDUCT.md)
Contributions can be made to this library through PRs to fix issues, improve documentation or add features. Please fork this repo, create a well-named branch, and submit a PR with a complete template filled out.
Code changes in PRs should be accompanied by tests covering the changed or added functionality. Tests can be run for this library with:
```bash
npm install
npm test
```
When you're ready to push your changes, please run the lint command first:
```bash
npm run lint
```
## Support + Feedback
Please use the [Issues queue](https://github.com/auth0/express-oauth2-bearer/issues) in this repo for questions and feedback.
## Vulnerability Reporting
Please do not report security vulnerabilities on the public GitHub issue tracker. The [Responsible Disclosure Program](https://auth0.com/whitehat) details the procedure for disclosing security issues.
## What is Auth0?
Auth0 helps you to easily:
- implement authentication with multiple identity providers, including social (e.g., Google, Facebook, Microsoft, LinkedIn, GitHub, Twitter, etc), or enterprise (e.g., Windows Azure AD, Google Apps, Active Directory, ADFS, SAML, etc.)
- log in users with username/password databases, passwordless, or multi-factor authentication
- link multiple user accounts together
- generate signed JSON Web Tokens to authorize your API calls and flow the user identity securely
- access demographics and analytics detailing how, when, and where users are logging in
- enrich user profiles from other data sources using customizable JavaScript rules
[Why Auth0?](https://auth0.com/why-auth0)
## License
This project is licensed under the MIT license. See the [LICENSE](LICENSE) file for more info.
[](https://app.fossa.com/projects/git%2Bgithub.com%2Fauth0%2Fexpress-oauth2-bearer?ref=badge_large)