+
+
+
+ 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. +
diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 000000000..d0763ec18 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,47 @@ +# Security Considerations + +## Cookies and Security + +All cookies will be set to `HttpOnly, SameSite=Lax` and will be set to `Secure` if the application's `AUTH0_BASE_URL` is `https`. + +The `HttpOnly` setting will make sure that client-side JavaScript is unable to access the cookie to reduce the attack surface of [XSS attacks](https://auth0.com/blog/developers-guide-to-common-vulnerabilities-and-how-to-prevent-them/#Cross-Site-Scripting--XSS-). + +The `SameSite=Lax` setting will help mitigate CSRF attacks. Learn more about SameSite by reading the ["Upcoming Browser Behavior Changes: What Developers Need to Know"](https://auth0.com/blog/browser-behavior-changes-what-developers-need-to-know/) blog post. + +## Caching and Security + +Many hosting providers will offer to cache your content at the edge in order to serve data to your users as fast as possible. For example Vercel will [cache your content on the Vercel Edge Network](https://vercel.com/docs/concepts/edge-network/caching) for all static content and Serverless Functions if you provide the necessary caching headers on your response. + +It's generally a bad idea to cache any response that requires authentication, even if the response's content appears safe to cache there may be other data in the response that isn't. + +This SDK offers a rolling session by default, which means that any response that reads the session will have a `Set-Cookie` header to update the cookie's expiry. Vercel and potentially other hosting providers include the `Set-Cookie` header in the cached response, so even if you think the response's content can be cached publicly, the responses `Set-Cookie` header cannot. + +Check your hosting provider's caching rules, but in general you should **never** cache responses that either require authentication or even touch the session to check authentication (eg when using `withApiAuthRequired`, `withPageAuthRequired` or even just `getSession` or `getAccessToken`). + +## Error Handling and Security + +The default server side error handler for the `/api/auth/*` routes prints the error message to screen, eg + +```js +try { + await handler(req, res); +} catch (error) { + res.status(error.status || 400).end(error.message); +} +``` + +Because the error can come from the OpenID Connect `error` query parameter we do some [basic escaping](https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html#rule-1-html-encode-before-inserting-untrusted-data-into-html-element-content) which makes sure the default error handler is safe from XSS. + +If you write your own error handler, you should **not** render the error `message`, or `error` and `error_description` properties without using a templating engine that will properly escape it for other HTML contexts first. + +## Comparison with the Auth0 React SDK + +We also provide an Auth0 React SDK, [auth0-react](https://github.com/auth0/auth0-react), which may be suitable for your Next.js application. + +The SPA security model used by `auth0-react` is different from the Web Application security model used by this SDK. In short, this SDK protects pages and API routes with a cookie session (see ["Cookies and Security"](#cookies-and-security)). A SPA library like `auth0-react` will store the user's ID Token and Access Token directly in the browser and use them to access external APIs directly. + +You should be aware of the security implications of both models. However, [auth0-react](https://github.com/auth0/auth0-react) may be more suitable for your needs if you meet any of the following scenarios: + +- You are using [Static HTML Export](https://nextjs.org/docs/advanced-features/static-html-export) with Next.js. +- You do not need to access user data during server-side rendering. +- You want to get the access token and call external API's directly from the frontend layer rather than using Next.js API Routes as a proxy to call external APIs diff --git a/TESTING.md b/TESTING.md new file mode 100644 index 000000000..78d2efcae --- /dev/null +++ b/TESTING.md @@ -0,0 +1,7 @@ +# Testing + +By default, the SDK creates and manages a singleton instance to run for the lifetime of the application. When testing your application, you may need to reset this instance, so its state does not leak between tests. + +If you're using Jest, we recommend using `jest.resetModules()` after each test. Alternatively, you can look at [creating your own instance of the SDK](https://github.com/auth0/open-source-template/blob/master/EXAMPLES.md#create-your-own-instance-of-the-sdk), so it can be recreated between tests. + +For end to end tests, have a look at how we use a [mock OIDC Provider](https://github.com/auth0/open-source-template/blob/master/scripts/oidc-provider.js). diff --git a/V2_MIGRATION_GUIDE.md b/V2_MIGRATION_GUIDE.md index bdcfdac74..e308eae59 100644 --- a/V2_MIGRATION_GUIDE.md +++ b/V2_MIGRATION_GUIDE.md @@ -2,15 +2,20 @@ Guide to migrating from `1.x` to `2.x` +- [Node 10 is no longer supported](#node-10-is-no-longer-supported) - [`getSession` now returns a `Promise`](#getsession-now-returns-a-promise) +- [Client methods and components are now exported under /client](#client-methods-and-components-are-now-exported-under-client) - [`updateSession` has been added](#updatesession-has-been-added) - [`getServerSidePropsWrapper` has been removed](#getserversidepropswrapper-has-been-removed) - [Profile API route no longer returns a 401](#profile-api-route-no-longer-returns-a-401) -- [The ID token is no longer stored by default](#the-id-token-is-no-longer-stored-by-default) - [Override default error handler](#override-default-error-handler) - [afterCallback can write to the response](#aftercallback-can-write-to-the-response) - [Configure default handlers](#configure-default-handlers) +## Node 10 is no longer supported + +Node 12 LTS and newer LTS releases are supported. + ## `getSession` now returns a `Promise` ### Before @@ -37,6 +42,92 @@ async function myApiRoute(req, res) { } ``` +## Client methods and components are now exported under /client + +All methods and components for the browser should now be accessed under `/client`. + +### Before + +```js +// pages/_app.js +import React from 'react'; +import { UserProvider } from '@auth0/nextjs-auth0'; + +export default function App({ Component, pageProps }) { + return ( +WARNING The message can contain user input and is only escaped using basic escaping for putting untrusted data + directly into the HTML body
+The 'error' parameter from the AS response + WARNING This can contain user input and is only escaped using basic escaping for putting untrusted data + directly into the HTML body
+The 'error_description' parameter from the AS response. + WARNING This can contain user input and is only escaped using basic escaping for putting untrusted data + directly into the HTML body
+
WARNING The message can contain user input and is only escaped using basic escaping for putting untrusted data + directly into the HTML body
+