From 7c3e31a25fd282828af6fbc75c2e66a70b5f1ebc Mon Sep 17 00:00:00 2001 From: Ewan Harris Date: Tue, 25 Oct 2022 10:50:51 +0100 Subject: [PATCH] [SDK-3705] Redesign readme to match new style (#751) Co-authored-by: Frederik Prijck --- EXAMPLES.md | 69 +++++++++++++++++++ FAQ.md | 21 ++++++ README.md | 190 +++++++++++++++------------------------------------- 3 files changed, 143 insertions(+), 137 deletions(-) create mode 100644 EXAMPLES.md create mode 100644 FAQ.md diff --git a/EXAMPLES.md b/EXAMPLES.md new file mode 100644 index 000000000..da01a0fa8 --- /dev/null +++ b/EXAMPLES.md @@ -0,0 +1,69 @@ +# Examples + +## Automatic Management API Token Retrieval + +To **automatically** obtain a Management API token via the ManagementClient, you can specify the parameters `clientId`, `clientSecret` (use a Non Interactive Client) and optionally `scope`. +Behind the scenes the Client Credentials Grant is used to obtain the `access_token` and is by default cached for the duration of the returned `expires_in` value. + +```js +var ManagementClient = require('auth0').ManagementClient; +var auth0 = new ManagementClient({ + domain: '{YOUR_ACCOUNT}.auth0.com', + clientId: '{YOUR_NON_INTERACTIVE_CLIENT_ID}', + clientSecret: '{YOUR_NON_INTERACTIVE_CLIENT_SECRET}', + scope: 'read:users update:users', +}); +``` + +> Make sure your `clientId` is allowed to request tokens from Management API in [Auth0 Dashboard](https://manage.auth0.com/#/apis) + +### Obtaining Management API Token from Node.js backend + +To obtain a Management API token from your node backend, you can use Client Credentials Grant using your registered Auth0 Non Interactive Clients + +```js +var AuthenticationClient = require('auth0').AuthenticationClient; + +var auth0 = new AuthenticationClient({ + domain: '{YOUR_ACCOUNT}.auth0.com', + clientId: '{CLIENT_ID}', + clientSecret: '{CLIENT_SECRET}', +}); + +auth0.clientCredentialsGrant( + { + audience: 'https://{YOUR_ACCOUNT}.auth0.com/api/v2/', + scope: '{MANAGEMENT_API_SCOPES}', + }, + function (err, response) { + if (err) { + // Handle error. + } + console.log(response.access_token); + } +); +``` + +### Promises and callback support + +All methods can be used with promises or callbacks, when a callback argument is provided no promise will be returned. + +```js +// Using callbacks. +management.getUsers(function (err, users) { + if (err) { + // handle error. + } + console.log(users); +}); + +// Using promises. +management + .getUsers() + .then(function (users) { + console.log(users); + }) + .catch(function (err) { + // Handle error. + }); +``` diff --git a/FAQ.md b/FAQ.md new file mode 100644 index 000000000..6ac0ce2c2 --- /dev/null +++ b/FAQ.md @@ -0,0 +1,21 @@ +# Frequently Asked Questions + +Below are a number of questions or issues that have arisen from using the SDK. + +## Does this library have type definitions? + +The types for this library are currently maintained by the community at [Definitely Typed](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/auth0). The team is planning taking ownership of this library as discussed in https://github.com/auth0/node-auth0/issues/572. + +### Getting `Error: Can't resolve 'superagent-proxy'` when bundling with Webpack + +We have a dependency on `rest-facade` which `require`s but doesn't include `superagent-proxy`. This SDK doesn't support proxies, so this dependency is not required. To workaround this you can add the following to your `webpack.config.js`: + +``` +resolve: { + alias: { + 'superagent-proxy': false + } +} +``` + +Or install `superagent-proxy` yourself. diff --git a/README.md b/README.md index 203773333..7ac0875ea 100644 --- a/README.md +++ b/README.md @@ -1,31 +1,37 @@ -# node-auth0 +![Node.js client library for Auth0](https://cdn.auth0.com/website/sdks/banner/node-auth0-banner.png) -[![Build Status][circleci-image]][circleci-url] -[![NPM version][npm-image]][npm-url] -[![Coverage][codecov-image]][codecov-url] -[![License][license-image]][license-url] -[![Downloads][downloads-image]][downloads-url] -[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fauth0%2Fnode-auth0.svg?type=shield)](https://app.fossa.com/projects/git%2Bgithub.com%2Fauth0%2Fnode-auth0?ref=badge_shield) +![Release](https://img.shields.io/npm/v/auth0) +[![Codecov](https://img.shields.io/codecov/c/github/auth0/node-auth0)](https://codecov.io/gh/auth0/node-auth0) +![Downloads](https://img.shields.io/npm/dw/auth0) +[![License](https://img.shields.io/:license-mit-blue.svg?style=flat)](https://opensource.org/licenses/MIT) +![CircleCI](https://img.shields.io/circleci/build/github/auth0/node-auth0) -Node.js client library for the [Auth0](https://auth0.com) platform. +📚 [Documentation](#documentation) - 🚀 [Getting Started](#getting-started) - 💻 [API Reference](#api-reference) - 💬 [Feedback](#feedback) -## Installation +## Documentation -```bash -npm install auth0 -``` +- [FAQs](https://github.com/auth0/node-auth0/blob/master/FAQ.md) - frequently asked questions about node-auth0. +- [Docs Site](https://auth0.com/docs) - explore our docs site and learn more about Auth0 -## Documentation +## Getting Started -You can find this library documentation in this [page](https://auth0.github.io/node-auth0/). +### Requirements -For more information about [auth0](https://auth0.com) check our [documentation page](https://auth0.com/docs). +This library supports the following tooling versions: -## Node version support +- Node.js: `>=8.3.0` -This SDK is tested on the latest Node versions 8, 10, 12 and 14. +### Installation -## Authentication API Client +Using [npm](https://npmjs.org) in your project directory run the following command: + +```bash +npm install auth0 +``` + +### Configure the SDK + +#### Authentication API Client This client must be used to access Auth0's [Authentication API](https://auth0.com/docs/api/authentication). @@ -40,7 +46,9 @@ var auth0 = new AuthenticationClient({ }); ``` -## Management API Client +#### Management API Client + +> Note: When using the ManagementClient in a browser you should set `telemetry: false`. The Auth0 Management API is meant to be used by back-end servers or trusted parties performing administrative tasks. Generally speaking, anything that can be done through the Auth0 dashboard (and more) can also be done through this API. @@ -55,134 +63,42 @@ var management = new ManagementClient({ }); ``` -> Note: When using at browser you should use `telemetry: false`. - -To obtain **automatically** a Management API token via the ManagementClient, you can specify the parameters `clientId`, `clientSecret` (use a Non Interactive Client) and optionally `scope`. -Behind the scenes the Client Credentials Grant is used to obtain the `access_token` and is by default cached for the duration of the returned `expires_in` value. - -```js -var ManagementClient = require('auth0').ManagementClient; -var auth0 = new ManagementClient({ - domain: '{YOUR_ACCOUNT}.auth0.com', - clientId: '{YOUR_NON_INTERACTIVE_CLIENT_ID}', - clientSecret: '{YOUR_NON_INTERACTIVE_CLIENT_SECRET}', - scope: 'read:users update:users', -}); -``` - -> Make sure your ClientId is allowed to request tokens from Management API in [Auth0 Dashboard](https://manage.auth0.com/#/apis) - -To obtain a Management API token from your node backend, you can use Client Credentials Grant using your registered Auth0 Non Interactive Clients - -```js -var AuthenticationClient = require('auth0').AuthenticationClient; - -var auth0 = new AuthenticationClient({ - domain: '{YOUR_ACCOUNT}.auth0.com', - clientId: '{CLIENT_ID}', - clientSecret: '{CLIENT_SECRET}', -}); - -auth0.clientCredentialsGrant( - { - audience: 'https://{YOUR_ACCOUNT}.auth0.com/api/v2/', - scope: '{MANAGEMENT_API_SCOPES}', - }, - function (err, response) { - if (err) { - // Handle error. - } - console.log(response.access_token); - } -); -``` - -Also you can request a token when the user authenticates using any of our client side SDKs, e.g. [auth0.js](https://github.com/auth0/auth0.js). +For other examples see the [EXAMPLES.md](https://github.com/auth0/node-auth0/blob/master/EXAMPLES.md) document. -## Promises and callbacks +## API Reference -Be aware that all methods can be used with promises or callbacks. However, when a callback is provided no promise will be returned. +- [AuthenticationClient](https://auth0.github.io/node-auth0/AuthenticationClient.html) +- [ManagementClient](https://auth0.github.io/node-auth0/ManagementClient.html) -```js -// Using callbacks. -management.getUsers(function (err, users) { - if (err) { - // handle error. - } - console.log(users); -}); - -// Using promises. -management - .getUsers() - .then(function (users) { - console.log(users); - }) - .catch(function (err) { - // Handle error. - }); -``` +## Feedback -## Typescript +### Contributing -The types for this library are currently maintained by the community at [Definitely Typed](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/auth0). The team is planning taking ownership of this library as discussed in https://github.com/auth0/node-auth0/issues/572. After the team has taken ownership we will remove this net from the Readme. +We appreciate feedback and contribution to this repo! Before you get started, please see the following: -## Troubleshooting +- [Auth0's general contribution guidelines](https://github.com/auth0/open-source-template/blob/master/GENERAL-CONTRIBUTING.md) +- [Auth0's code of conduct guidelines](https://github.com/auth0/open-source-template/blob/master/CODE-OF-CONDUCT.md) -### Getting `Error: Can't resolve 'superagent-proxy'` when bundling with Webpack +### Raise an issue -We have a dependency on `rest-facade` which `require`s but doesn't include `superagent-proxy`. This SDK doesn't support proxies, so this dependency is not required. To workaround this you can add the following to your `webpack.config.js`: - -``` -resolve: { - alias: { - 'superagent-proxy': false - } -} -``` +To provide feedback or report a bug, please [raise an issue on our issue tracker](https://github.com/auth0/node-auth0/issues). -Or install `superagent-proxy` yourself. +### 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: - -- Add authentication with [multiple authentication sources](https://docs.auth0.com/identityproviders), either social like **Google, Facebook, Microsoft Account, LinkedIn, GitHub, Twitter, Box, Salesforce, amont others**, or enterprise identity systems like **Windows Azure AD, Google Apps, Active Directory, ADFS or any SAML Identity Provider**. -- Add authentication through more traditional **[username/password databases](https://docs.auth0.com/mysql-connection-tutorial)**. -- Add support for **[linking different user accounts](https://docs.auth0.com/link-accounts)** with the same user. -- Support for generating signed [Json Web Tokens](https://docs.auth0.com/jwt) to call your APIs and **flow the user identity** securely. -- Analytics of how, when and where users are logging in. -- Pull data from other sources and add it to the user profile, through [JavaScript rules](https://docs.auth0.com/rules). - -## Create a free Auth0 Account - -1. Go to [Auth0](https://auth0.com) and click "Try Auth0 for Free". -2. Use Google, GitHub or Microsoft Account to login. - -## Issue Reporting - -If you have found a bug or if you have a feature request, please report them at this repository issues section. 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. - -## Author - -[Auth0](https://auth0.com) - -## License - -This project is licensed under the MIT license. See the [LICENSE](LICENSE) file for more info. - - - -[npm-image]: https://img.shields.io/npm/v/auth0.svg?style=flat-square -[npm-url]: https://npmjs.org/package/auth0 -[circleci-image]: https://img.shields.io/circleci/project/github/auth0/node-auth0.svg?branch=master&style=flat-square -[circleci-url]: https://circleci.com/gh/auth0/node-auth0 -[codecov-image]: https://img.shields.io/codecov/c/github/auth0/node-auth0.svg?style=flat-square -[codecov-url]: https://codecov.io/github/auth0/node-auth0?branch=master -[license-image]: https://img.shields.io/npm/l/auth0.svg?style=flat-square -[license-url]: #license -[downloads-image]: https://img.shields.io/npm/dm/auth0.svg?style=flat-square -[downloads-url]: https://npmjs.org/package/auth0 - -[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fauth0%2Fnode-auth0.svg?type=large)](https://app.fossa.com/projects/git%2Bgithub.com%2Fauth0%2Fnode-auth0?ref=badge_large) +

+ + + + Auth0 Logo + +

+

+ Auth0 is an easy to implement, adaptable authentication and authorization platform. To learn more checkout Why Auth0? +

+

+ This project is licensed under the MIT license. See the LICENSE file for more info. +