@auth0/auth0-react 1.12.0 → 1.12.1

package/README.md

@@ -1,31 +1,24 @@
-# @auth0/auth0-react
+![Auth0 SDK for React Single Page Applications](https://cdn.auth0.com/website/sdks/banners/auth0-react-banner.png)
 
-Auth0 SDK for React Single Page Applications (SPA).
-
-[![CircleCI](https://img.shields.io/circleci/build/github/auth0/auth0-react.svg?branch=master&style=flat)](https://circleci.com/gh/auth0/auth0-react)
-[![License](https://img.shields.io/:license-mit-blue.svg?style=flat)](https://opensource.org/licenses/MIT)
 [![npm](https://img.shields.io/npm/v/@auth0/auth0-react.svg?style=flat)](https://www.npmjs.com/package/@auth0/auth0-react)
 [![codecov](https://img.shields.io/codecov/c/github/auth0/auth0-react/master.svg?style=flat)](https://codecov.io/gh/auth0/auth0-react)
+![Downloads](https://img.shields.io/npm/dw/@auth0/auth0-react)
+[![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/auth0-react.svg?branch=master&style=flat)](https://circleci.com/gh/auth0/auth0-react)
 
-## Table of Contents
-
-- [Documentation](#documentation)
-- [Installation](#installation)
-- [Getting Started](#getting-started)
-- [Contributing](#contributing)
-- [Support + Feedback](#support--feedback)
-- [Troubleshooting](#troubleshooting)
-- [Frequently Asked Questions](#frequently-asked-questions)
-- [Vulnerability Reporting](#vulnerability-reporting)
-- [What is Auth0](#what-is-auth0)
-- [License](#license)
+📚 [Documentation](#documentation) - 🚀 [Getting Started](#getting-started) - 💻 [API Reference](#api-reference) - 💬 [Feedback](#feedback)
 
 ## Documentation
 
-- [API Reference](https://auth0.github.io/auth0-react/)
-- [Quickstart Guide](https://auth0.com/docs/quickstart/spa/react)
+- [Quickstart](https://auth0.com/docs/quickstart/spa/react) - our interactive guide for quickly adding login, logout and user information to a React app using Auth0.
+- [Sample App](https://github.com/auth0-samples/auth0-react-samples/tree/master/Sample-01) - a full-fledged React application integrated with Auth0.
+- [FAQs](https://github.com/auth0/auth0-react/blob/master/FAQ.md) - frequently asked questions about the auth0-react SDK.
+- [Examples](https://github.com/auth0/auth0-react/blob/master/EXAMPLES.md) - code samples for common React authentication scenario's.
+- [Docs site](https://www.auth0.com/docs) - explore our docs site and learn more about Auth0.
+
+## Getting started
 
-## Installation
+### Installation
 
 Using [npm](https://npmjs.org/)
 
@@ -39,7 +32,29 @@ Using [yarn](https://yarnpkg.com/)
 yarn add @auth0/auth0-react
 ```
 
-## Getting Started
+### Configure Auth0
+
+Create a **Single Page Application** in the [Auth0 Dashboard](https://manage.auth0.com/#/applications).
+
+> **If you're using an existing application**, verify that you have configured the following settings in your Single Page Application:
+>
+> - Click on the "Settings" tab of your application's page.
+> - Ensure that "Token Endpoint Authentication Method" under "Application Properties" is set to "None"
+> - Scroll down and click on the "Show Advanced Settings" link.
+> - Under "Advanced Settings", click on the "OAuth" tab.
+> - Ensure that "JsonWebToken Signature Algorithm" is set to `RS256` and that "OIDC Conformant" is enabled.
+
+Next, configure the following URLs for your application under the "Application URIs" section of the "Settings" page:
+
+- **Allowed Callback URLs**: `http://localhost:3000`
+- **Allowed Logout URLs**: `http://localhost:3000`
+- **Allowed Web Origins**: `http://localhost:3000`
+
+> These URLs should reflect the origins that your application is running on. **Allowed Callback URLs** may also include a path, depending on where you're handling the callback.
+
+Take note of the **Client ID** and **Domain** values under the "Basic Information" section. You'll need these values in the next step.
+
+### Configure the SDK
 
 Configure the SDK by wrapping your application in `Auth0Provider`:
 
@@ -70,14 +85,8 @@ import React from 'react';
 import { useAuth0 } from '@auth0/auth0-react';
 
 function App() {
-  const {
-    isLoading,
-    isAuthenticated,
-    error,
-    user,
-    loginWithRedirect,
-    logout,
-  } = useAuth0();
+  const { isLoading, isAuthenticated, error, user, loginWithRedirect, logout } =
+    useAuth0();
 
   if (isLoading) {
     return <div>Loading...</div>;
@@ -103,101 +112,21 @@ function App() {
 export default App;
 ```
 
-If you're using TypeScript, you can pass a type parameter to `useAuth0` to specify the type of `user`:
-
-```ts
-const { user } = useAuth0<{ name: string }>();
-
-user.name; // is a string
-```
-
-### Use with a Class Component
-
-Use the `withAuth0` higher order component to add the `auth0` property to Class components:
-
-```jsx
-import React, { Component } from 'react';
-import { withAuth0 } from '@auth0/auth0-react';
-
-class Profile extends Component {
-  render() {
-    // `this.props.auth0` has all the same properties as the `useAuth0` hook
-    const { user } = this.props.auth0;
-    return <div>Hello {user.name}</div>;
-  }
-}
-
-export default withAuth0(Profile);
-```
-
-### Protect a Route
-
-Protect a route component using the `withAuthenticationRequired` higher order component. Visits to this route when unauthenticated will redirect the user to the login page and back to this page after login:
+For more code samples on how to integrate **auth0-react** SDK in your **React** application, have a look at our [examples](https://github.com/auth0/auth0-react/blob/master/EXAMPLES.md).
 
-```jsx
-import React from 'react';
-import { withAuthenticationRequired } from '@auth0/auth0-react';
-
-const PrivateRoute = () => <div>Private</div>;
-
-export default withAuthenticationRequired(PrivateRoute, {
-  // Show a message while the user waits to be redirected to the login page.
-  onRedirecting: () => <div>Redirecting you to the login page...</div>,
-});
-```
+## API reference
 
-**Note** If you are using a custom router, you will need to supply the `Auth0Provider` with a custom `onRedirectCallback` method to perform the action that returns the user to the protected page. See examples for [react-router](https://github.com/auth0/auth0-react/blob/master/EXAMPLES.md#1-protecting-a-route-in-a-react-router-dom-app), [Gatsby](https://github.com/auth0/auth0-react/blob/master/EXAMPLES.md#2-protecting-a-route-in-a-gatsby-app) and [Next.js](https://github.com/auth0/auth0-react/blob/master/EXAMPLES.md#3-protecting-a-route-in-a-nextjs-app-in-spa-mode).
+Explore public API's available in auth0-react.
 
-### Call an API
+- [Auth0Provider](https://auth0.github.io/auth0-react/modules.html#Auth0Provider)
+- [Auth0ProviderOptions](https://auth0.github.io/auth0-react/interfaces/Auth0ProviderOptions.html)
+- [useAuth0](https://auth0.github.io/auth0-react/modules.html#useAuth0)
+- [withAuth0](https://auth0.github.io/auth0-react/modules.html#withAuth0)
+- [withAuthenticationRequired](https://auth0.github.io/auth0-react/modules.html#withAuthenticationRequired)
 
-Call a protected API with an Access Token:
-
-```jsx
-import React, { useEffect, useState } from 'react';
-import { useAuth0 } from '@auth0/auth0-react';
-
-const Posts = () => {
-  const { getAccessTokenSilently } = useAuth0();
-  const [posts, setPosts] = useState(null);
-
-  useEffect(() => {
-    (async () => {
-      try {
-        const token = await getAccessTokenSilently({
-          audience: 'https://api.example.com/',
-          scope: 'read:posts',
-        });
-        const response = await fetch('https://api.example.com/posts', {
-          headers: {
-            Authorization: `Bearer ${token}`,
-          },
-        });
-        setPosts(await response.json());
-      } catch (e) {
-        console.error(e);
-      }
-    })();
-  }, [getAccessTokenSilently]);
-
-  if (!posts) {
-    return <div>Loading...</div>;
-  }
+## Feedback
 
-  return (
-    <ul>
-      {posts.map((post, index) => {
-        return <li key={index}>{post}</li>;
-      })}
-    </ul>
-  );
-};
-
-export default Posts;
-```
-
-For a more detailed example see how to [create a `useApi` hook for accessing protected APIs with an access token](https://github.com/auth0/auth0-react/blob/master/EXAMPLES.md#4-create-a-useapi-hook-for-accessing-protected-apis-with-an-access-token).
-
-## Contributing
+### Contributing
 
 We appreciate feedback and contribution to this repo! Before you get started, please see the following:
 
@@ -205,35 +134,23 @@ We appreciate feedback and contribution to this repo! Before you get started, pl
 - [Auth0's code of conduct guidelines](https://github.com/auth0/open-source-template/blob/master/CODE-OF-CONDUCT.md)
 - [This repo's contribution guide](https://github.com/auth0/auth0-react/blob/master/CONTRIBUTING.md)
 
-## Support + Feedback
-
-For support or to provide feedback, please [raise an issue on our issue tracker](https://github.com/auth0/auth0-react/issues).
-
-## Troubleshooting
-
-For information on how to solve common problems, check out the [Troubleshooting](https://github.com/auth0/auth0-react/blob/master/TROUBLESHOOTING.md) guide
-
-## Frequently Asked Questions
-
-For a rundown of common issues you might encounter when using the SDK, please check out the [FAQ](https://github.com/auth0/auth0-react/blob/master/FAQ.md).
-
-## 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?
+### Raise an issue
 
-Auth0 helps you to easily:
+To provide feedback or report a bug, please [raise an issue on our issue tracker](https://github.com/auth0/auth0-react/issues).
 
-- 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
+### Vulnerability Reporting
 
-[Why Auth0?](https://auth0.com/why-auth0)
+Please do not report security vulnerabilities on the public GitHub issue tracker. The [Responsible Disclosure Program](https://auth0.com/responsible-disclosure-policy) details the procedure for disclosing security issues.
 
-## License
+---
 
-This project is licensed under the MIT license. See the [LICENSE](https://github.com/auth0/auth0-react/blob/master/LICENSE) file for more info.
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: light)" srcset="https://cdn.auth0.com/website/sdks/logos/auth0_light_mode.png"   width="150">
+    <source media="(prefers-color-scheme: dark)" srcset="https://cdn.auth0.com/website/sdks/logos/auth0_dark_mode.png" width="150">
+    <img alt="Auth0 Logo" src="https://cdn.auth0.com/website/sdks/logos/auth0_light_mode.png" width="150">
+  </picture>
+</p>
+<p align="center">Auth0 is an easy to implement, adaptable authentication and authorization platform. To learn more checkout <a href="https://auth0.com/why-auth0">Why Auth0?</a></p>
+<p align="center">
+This project is licensed under the MIT license. See the <a href="https://github.com/auth0/auth0-react/blob/master/LICENSE"> LICENSE</a> file for more info.</p>