Skip to content

Commit

Permalink
Merge branch 'next' into feat/use-session-required
Browse files Browse the repository at this point in the history
  • Loading branch information
@balazsorban44
balazsorban44 authored Jul 5, 2021
2 parents 05f6955 + 53e5e37 commit 40f9b25
Show file tree
Hide file tree
Showing 12 changed files with 2,486 additions and 2,264 deletions.
189 changes: 168 additions & 21 deletions www/docs/faq.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,13 +15,24 @@ It is not commercial software and is not associated with a commercial organizati

## Compatibility

### What databases does NextAuth.js support?
<details>
<summary>
<h3 style={{display:"inline-block"}}>What databases does NextAuth.js support?</h3>
</summary>
<p>

You can use NextAuth.js with MySQL, MariaDB, Postgres, MongoDB and SQLite or without a database. (See also: [Databases](/configuration/databases))

You can use also NextAuth.js with any database using a custom database adapter, or by using a custom credentials authentication provider - e.g. to support signing in with a username and password stored in an existing database.

### What authentication services does NextAuth.js support?
</p>
</details>

<details>
<summary>
<h3 style={{display:"inline-block"}}>What authentication services does NextAuth.js support?</h3>
</summary>
<p>

<p>NextAuth.js includes built-in support for signing in with&nbsp;
{Object.values(require("../providers.json")).sort().join(", ")}.
Expand All @@ -32,15 +43,29 @@ NextAuth.js also supports email for passwordless sign in, which is useful for ac

You can also use a custom based provider to support signing in with a username and password stored in an external database and/or using two factor authentication.

### Does NextAuth.js support signing in with a username and password?
</p>
</details>

<details>
<summary>
<h3 style={{display:"inline-block"}}>Does NextAuth.js support signing in with a username and password?</h3>
</summary>
<p>

NextAuth.js is designed to avoid the need to store passwords for user accounts.

If you have an existing database of usernames and passwords, you can use a custom credentials provider to allow signing in with a username and password stored in an existing database.

_If you use a custom credentials provider user accounts will not be persisted in a database by NextAuth.js (even if one is configured). The option to use JSON Web Tokens for session tokens (which allow sign in without using a session database) must be enabled to use a custom credentials provider._

### Can I use NextAuth.js with a website that does not use Next.js?
</p>
</details>

<details>
<summary>
<h3 style={{display:"inline-block"}}>Can I use NextAuth.js with a website that does not use Next.js?</h3>
</summary>
<p>

NextAuth.js is designed for use with Next.js and Serverless.

Expand All @@ -50,63 +75,126 @@ If you use NextAuth.js on a website with a different subdomain then the rest of

NextAuth.js does not currently support automatically signing into sites on different top level domains (e.g. `www.example.com` vs `www.example.org`) using a single session.

### Can I use NextAuth.js with React Native?
</p>
</details>

<details>
<summary>
<h3 style={{display:"inline-block"}}>Can I use NextAuth.js with React Native?</h3>
</summary>
<p>

NextAuth.js is designed as a secure, confidential client and implements a server side authentication flow.

It is not intended to be used in native applications on desktop or mobile applications, which typically implement public clients (e.g. with client / secrets embedded in the application).

### Is NextAuth.js supporting TypeScript?
</p>
</details>

<details>
<summary>
<h3 style={{display:"inline-block"}}>Is NextAuth.js supporting TypeScript?</h3>
</summary>
<p>

Yes! Check out the [TypeScript docs](/getting-started/typescript)

</p>
</details>

---

## Databases

### What databases are supported by NextAuth.js?
<details>
<summary>
<h3 style={{display:"inline-block"}}>What databases are supported by NextAuth.js?</h3>
</summary>
<p>

NextAuth.js can be used with MySQL, Postgres, MongoDB, SQLite and compatible databases (e.g. MariaDB, Amazon Aurora, Amazon DocumentDB…) or with no database.

It also provides an Adapter API which allows you to connect it to any database.

### What does NextAuth.js use databases for?
</p>
</details>

<details>
<summary>
<h3 style={{display:"inline-block"}}>What does NextAuth.js use databases for?</h3>
</summary>
<p>

Databases in NextAuth.js are used for persisting users, OAuth accounts, email sign in tokens and sessions.

Specifying a database is optional if you don't need to persist user data or support email sign in. If you don't specify a database then JSON Web Tokens will be enabled for session storage and used to store session data.

If you are using a database with NextAuth.js, you can still explicitly enable JSON Web Tokens for sessions (instead of using database sessions).

### Should I use a database?
</p>
</details>

<details>
<summary>
<h3 style={{display:"inline-block"}}>Should I use a database?</h3>
</summary>
<p>

- Using NextAuth.js without a database works well for internal tools - where you need to control who is able to sign in, but when you do not need to create user accounts for them in your application.

- Using NextAuth.js with a database is usually a better approach for a consumer facing application where you need to persist accounts (e.g. for billing, to contact customers, etc).

### What database should I use?
</p>
</details>

<details>
<summary>
<h3 style={{display:"inline-block"}}>What database should I use?</h3>
</summary>
<p>

Managed database solutions for MySQL, Postgres and MongoDB (and compatible databases) are well supported from cloud providers such as Amazon, Google, Microsoft and Atlas.

If you are deploying directly to a particular cloud platform you may also want to consider serverless database offerings they have (e.g. [Amazon Aurora Serverless on AWS](https://aws.amazon.com/rds/aurora/serverless/)).

</p>
</details>

---

## Security

### I think I've found a security problem, what should I do?
<details>
<summary>
<h3 style={{display:"inline-block"}}>I think I've found a security problem, what should I do?</h3>
</summary>
<p>

Less serious or edge case issues (e.g. queries about compatibility with optional RFC specifications) can be raised as public issues on GitHub.

If you discover what you think may be a potentially serious security problem, please contact a core team member via a private channel (e.g. via email to me@iaincollins.com) or raise a public issue requesting someone get in touch with you via whatever means you prefer for more details.

### What is the disclosure policy for NextAuth.js?
</p>
</details>

<details>
<summary>
<h3 style={{display:"inline-block"}}>What is the disclosure policy for NextAuth.js?</h3>
</summary>
<p>

We practice responsible disclosure.

If you contact us regarding a potentially serious issue, we will endeavor to get back to you within 72 hours and to publish a fix within 30 days. We will responsibly disclose the issue (and credit you with your consent) once a fix to resolve the issue has been released - or after 90 days, which ever is sooner.

### How do I get Refresh Tokens and Access Tokens for an OAuth account?
</p>
</details>

<details>
<summary>
<h3 style={{display:"inline-block"}}>How do I get Refresh Tokens and Access Tokens for an OAuth account?</h3>
</summary>
<p>

NextAuth.js provides a solution for authentication, session management and user account creation.

Expand All @@ -119,7 +207,14 @@ You can then look them up from the database or persist them to the JSON Web Toke

Note: NextAuth.js does not currently handle Access Token rotation for OAuth providers for you, however you can check out [this tutorial](/tutorials/refresh-token-rotation) if you want to implement it.

### When I sign in with another account with the same email address, why are accounts not linked automatically?
</p>
</details>

<details>
<summary>
<h3 style={{display:"inline-block"}}>When I sign in with another account with the same email address, why are accounts not linked automatically?</h3>
</summary>
<p>

Automatic account linking on sign in is not secure between arbitrary providers - with the exception of allowing users to sign in via an email addresses as a fallback (as they must verify their email address as part of the flow).

Expand All @@ -137,19 +232,33 @@ Automatic account linking is not a planned feature of NextAuth.js, however there

Providing support for secure account linking and unlinking of additional providers - which can only be done if a user is already signed in already - was originally a feature in v1.x but has not been present since v2.0, is planned to return in a future release.

</p>
</details>

---

## Feature Requests

### Why doesn't NextAuth.js support [a particular feature]?
<details>
<summary>
<h3 style={{display:"inline-block"}}>Why doesn't NextAuth.js support [a particular feature]?</h3>
</summary>
<p>

NextAuth.js is an open source project built by individual contributors who are volunteers writing code and providing support in their spare time.

If you would like NextAuth.js to support a particular feature, the best way to help make it happen is to raise a feature request describing the feature and offer to work with other contributors to develop and test it.

If you are not able to develop a feature yourself, you can offer to sponsor someone to work on it.

### I disagree with a design decision, how can I change your mind?
</p>
</details>

<details>
<summary>
<h3 style={{display:"inline-block"}}>I disagree with a design decision, how can I change your mind?</h3>
</summary>
<p>

Product design decisions on NextAuth.js are made by core team members.

Expand All @@ -159,11 +268,18 @@ Requests that provide the detail requested in the template and follow the format

Ultimately if your request is not accepted or is not actively in development, you are always free to fork the project under the terms of the ISC License.

</p>
</details>

---

## JSON Web Tokens

### Does NextAuth.js use JSON Web Tokens?
<details>
<summary>
<h3 style={{display:"inline-block"}}>Does NextAuth.js use JSON Web Tokens?</h3>
</summary>
<p>

NextAuth.js supports both database session tokens and JWT session tokens.

Expand All @@ -172,7 +288,14 @@ NextAuth.js supports both database session tokens and JWT session tokens.

You can also choose to use JSON Web Tokens as session tokens with using a database, by explicitly setting the `session: { jwt: true }` option.

### What are the advantages of JSON Web Tokens?
</p>
</details>

<details>
<summary>
<h3 style={{display:"inline-block"}}>What are the advantages of JSON Web Tokens?</h3>
</summary>
<p>

JSON Web Tokens can be used for session tokens, but are also used for lots of other things, such as sending signed objects between services in authentication flows.

Expand All @@ -184,7 +307,14 @@ JSON Web Tokens can be used for session tokens, but are also used for lots of ot

- You can use JWT to securely store information you do not mind the client knowing even without encryption, as the JWT is stored in a server-readable-only-token so data in the JWT is not accessible to third party JavaScript running on your site.

### What are the disadvantages of JSON Web Tokens?
</p>
</details>

<details>
<summary>
<h3 style={{display:"inline-block"}}>What are the disadvantages of JSON Web Tokens?</h3>
</summary>
<p>

- You cannot as easily expire a JSON Web Token - doing so requires maintaining a server side blocklist of invalid tokens (at least until they expire) and checking every token against the list every time a token is presented.

Expand All @@ -206,7 +336,14 @@ JSON Web Tokens can be used for session tokens, but are also used for lots of ot

If using JSON Web Token you should at least specify a secret and ideally configure public/private keys.

### Are JSON Web Tokens secure?
</p>
</details>

<details>
<summary>
<h3 style={{display:"inline-block"}}>Are JSON Web Tokens secure?</h3>
</summary>
<p>

By default tokens are signed (JWS) but not encrypted (JWE), as encryption adds additional overhead and reduces the amount of space available to store data (total cookie size for a domain is limited to 4KB).

Expand All @@ -220,7 +357,14 @@ NextAuth.js will generate keys for you, but this will generate a warning at star

Using explicit public/private keys for signing is strongly recommended.

### What signing and encryption standards does NextAuth.js support?
</p>
</details>

<details>
<summary>
<h3 style={{display:"inline-block"}}>What signing and encryption standards does NextAuth.js support?</h3>
</summary>
<p>

NextAuth.js includes a largely complete implementation of JSON Object Signing and Encryption (JOSE):

Expand All @@ -235,3 +379,6 @@ This incorporates support for:
- [RFC 7638 - JSON Web Key Thumbprint](https://tools.ietf.org/html/rfc7638)
- [RFC 7787 - JSON JWS Unencoded Payload Option](https://tools.ietf.org/html/rfc7797)
- [RFC 8037 - CFRG Elliptic Curve ECDH and Signatures](https://tools.ietf.org/html/rfc8037)

</p>
</details>
Loading

0 comments on commit 40f9b25

Please sign in to comment.