[SDK-3990] Add migration guide and EOL notice (#46)

MIGRATION_GUIDE.md

@@ -0,0 +1,150 @@
+# Migrating to express-oauth2-jwt-bearer
+
+Our recommended middleware for protecting Express APIs is now [express-oauth2-jwt-bearer](https://github.com/auth0/express-oauth2-jwt-bearer). This guide demonstrates how to migrate from `express-oauth2-bearer` to `express-oauth2-jwt-bearer`.
+
+## Basic setup
+
+### Before
+
+```bash
+# .env
+
+ISSUER_BASE_URL=https://YOUR_DOMAIN
+ALLOWED_AUDIENCES=https://api.yourapplication.com
+```
+
+```javascript
+const { auth } = require('express-oauth2-bearer');
+
+app.use(auth());
+```
+
+Or in your application code:
+
+```javascript
+const { auth } = require('express-oauth2-bearer');
+
+app.use(auth({
+ issuerBaseURL: 'https://tenant.auth0.com',
+ allowedAudiences: 'https://api.yourapplication.com'
+}));
+```
+
+### After
+
+```bash
+# .env
+
+ISSUER_BASE_URL=https://YOUR_ISSUER_DOMAIN
+AUDIENCE=https://my-api.com
+```
+
+```javascript
+const { auth } = require('express-oauth2-jwt-bearer');
+
+app.use(auth());
+```
+
+Or in your application code:
+
+```javascript
+const { auth } = require('express-oauth2-jwt-bearer');
+
+app.use(auth({
+ issuerBaseURL: 'https://YOUR_ISSUER_DOMAIN',
+ audience: 'https://my-api.com'
+}));
+```
+
+## JWTs signed with symmetric algorithms (eg HS256)
+
+### Before
+
+```javascript
+const { auth } = require('express-oauth2-bearer');
+
+app.use(auth({
+ issuerBaseURL: 'https://tenant.auth0.com',
+ allowedAudiences: 'https://api.yourapplication.com',
+ clientSecret: 'YOUR SECRET'
+}));
+```
+
+### After
+
+```javascript
+const { auth } = require('express-oauth2-jwt-bearer');
+
+app.use(auth({
+ issuer: 'https://YOUR_ISSUER_DOMAIN',
+ audience: 'https://my-api.com',
+ secret: 'YOUR SECRET',
+ tokenSigningAlg: 'HS256'
+}));
+```
+
+## Require scopes
+
+### Before
+
+```javascript
+const { auth, requiredScopes } = require('express-oauth2-bearer');
+
+app.use(auth());
+
+app.get('/products',
+ requiredScopes('read:products'),
+ (req, res) => {
+ res.sendStatus(200);
+ });
+```
+
+### After (same API)
+
+```javascript
+const { auth, requiredScopes } = require('express-oauth2-jwt-bearer');
+
+app.use(auth());
+
+app.get('/products',
+ requiredScopes('read:products'),
+ (req, res) => {
+ res.sendStatus(200);
+ });
+```
+
+## Inspect token
+
+### Before
+
+```javascript
+const { auth } = require('express-oauth2-bearer');
+
+app.use(auth());
+
+app.get('/products',
+ (req, res) => {
+ const auth = req.auth;
+ auth.claims; // The decoded JWT payload.
+ auth.token; // The raw JWT token.
+ res.sendStatus(200);
+ });
+```
+
+### After
+
+```javascript
+const { auth } = require('express-oauth2-jwt-bearer');
+
+app.use(auth());
+
+app.get('/products',
+ (req, res) => {
+ const auth = req.auth;
+ auth.header; // The decoded JWT header.
+ auth.payload; // The decoded JWT payload.
+ auth.token; // The raw JWT token.
+ res.sendStatus(200);
+ });
+ ```
+

README.md

@@ -1,4 +1,4 @@
-> **Please Note:** This repository is experimental and will be archived. 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 [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).
+> **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.