@envelop/auth0 3.4.0-alpha-26c4ae2.0 → 3.4.0

package/README.md

@@ -0,0 +1,113 @@
+## `@envelop/auth0`
+
+This plugin validates an JWT token created by [Auth0](https://auth0.com/), and injects the Auth0 user properties into your GraphQL context. With this plugin, you can implement authentication and authorization in a simple way.
+
+> The plugins is using [JWKS](https://auth0.com/docs/tokens/json-web-tokens/json-web-key-sets) standard in order to validate the token.
+
+## Getting Started
+
+We recommend using the [Adding Authentication with Auth0 guide](https://www.envelop.dev/docs/guides/adding-authentication-with-auth0) if this is your first time using this plugin!
+
+1. Sign up for [Auth0](https://auth0.com/), create a tenant based on your needs, and then create an Auth0 Application (https://auth0.com/docs/applications).
+2. Setup Auth0 client based on your client app. You should be able to login on your app, and get a JWT token from Auth0. Make sure to pass that token in your GraphQL requests sent to your server, using headers (for example: `Authorization: Bearer XYZ`). You can find more info here: https://auth0.com/docs/quickstart/spa
+3. From your tenant configuration screen, find your `audience` and `domain` configurations.
+4. Setup Envelop with that plugin:
+
+```ts
+import { envelop } from '@envelop/core';
+import { useAuth0 } from '@envelop/auth0';
+
+const getEnveloped = envelop({
+  plugins: [
+    // ... other plugins ...
+    useAuth0({
+      onError: e => { ... }, // In case of an error, you can override it and customize the error your client will get.
+      domain: 'YOUR_AUTH0_DOMAIN_HERE',
+      audience: 'YOUR_AUTH0_AUDIENCE_HERE',
+      headerName: 'authorization', // Name of the header
+      preventUnauthenticatedAccess: true, // If you need to have unauthenticated parts on your schema, make sure to disable that by setting it to `false` and the check it in your resolvers.
+      extendContextField: 'auth0', // The name of the field injected to your `context`
+      tokenType: 'Bearer', // Type of token to expect in the header
+    }),
+  ],
+});
+```
+
+5. Make sure to pass your request as part of the context building:
+
+```ts
+myHttpServer.on('request', async req => {
+  const { contextFactory } = getEnveloped({ req });
+  const contextValue = await contextFactory({ req }); // Make sure to pass it here
+});
+```
+
+> By default, this plugins looks for `req` or `request` properties in your base context. If you need to override it, please use `extractTokenFn` and you can customize it.
+
+6. You should now be able to validate user tokens, and if a user is valid, you can get the Auth0 user id (called `sub`) as part of your `context` during execution:
+
+```ts
+const myResolvers = {
+  Query: {
+    me: (root, args, context, info) => {
+      const auth0UserId = context.auth0.sub;
+    },
+  },
+};
+```
+
+### API Reference
+
+#### `jwksClientOptions`
+
+Pass this to customize the JWKS client creation. See: https://github.com/auth0/node-jwks-rsa
+
+> Setting this will override any other options defined by this plugin.
+
+#### `jwtDecodeOptions`
+
+Pass this to customize the JWT `decode` phase. See: https://www.npmjs.com/package/jws#jwsdecodesignature
+
+#### `jwtVerifyOptions`
+
+Pass this to customize the JWT `verify` phase. See: https://github.com/auth0/node-jsonwebtoken#jwtverifytoken-secretorpublickey-options-callback
+
+#### `onError(e: Error)`
+
+By default, this library will throw an error during context building if an error has happened.
+
+If you wish to customize the error, you can add `onError` callback and throw a custom error based on your needs.
+
+#### `preventUnauthenticatedAccess`
+
+By default, this library will prevent execution flow and throw an error in case of an authentication error.
+
+Setting this to `false` will lead to a `null` value in case of authentication issue (and `onError` will still get called).
+
+#### `domain`
+
+Specifies the Auth0 domain, please note that you need to specify that field with a protocol, for example: `my-domain.us.auth0.com`
+
+#### `audience`
+
+Specifies the Auth0 audience.
+
+#### `extractTokenFn(context: any)`
+
+If you wish to customize the token extraction from your HTTP request, override this function. It gets the `context` built so far as an argument, and you can extract your auth token based on your setup.
+
+#### `headerName` + `tokenType`
+
+If `extractTokenFn` is not set, the default behavior of this plugin is to look for `req` and `request` in the context, then look for `headers` and look for `authentication` header (you can customize it with `headerName`). Then, it validates that the token is of type `Bearer` (you can customize it with `tokenType` option).
+
+#### `extendContextField`
+
+The name of the field to inject to your `context`. When the user is valid, the decoded and verified payload of the JWT is injected. In most cases, the field that you need is `sub` (which refers to the internal Auth0 user identifier).
+
+You can read more about the token structure here: https://auth0.com/docs/tokens/json-web-tokens/json-web-token-structure
+
+By default, the `auth0` value is used.
+
+## Notes
+
+> Make sure to specify `audience` field in the client, otherwise you'll get an opaque token instead of a JWT token.

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@envelop/auth0",
-  "version": "3.4.0-alpha-26c4ae2.0",
+  "version": "3.4.0",
   "sideEffects": false,
   "peerDependencies": {
-    "@envelop/core": "2.4.0-alpha-26c4ae2.0",
+    "@envelop/core": "^2.4.0",
     "graphql": "^14.0.0 || ^15.0.0 || ^16.0.0"
   },
   "dependencies": {