Credentials
Overview
The Credentials provider allows you to handle signing in with arbitrary credentials, such as a username and password, domain, or two factor authentication or hardware device (e.g. YubiKey U2F / FIDO).
It is intended to support use cases where you have an existing system you need to authenticate users against.
It comes with the constraint that users authenticated in this manner are not persisted in the database, and consequently that the Credentials provider can only be used if JSON Web Tokens are enabled for sessions.
note
The functionality provided for credentials based authentication is intentionally limited to discourage use of passwords due to the inherent security risks associated with them and the additional complexity associated with supporting usernames and passwords.
Example
The Credentials provider is specified like other providers, except that you need to define a handler for authorize()
that accepts credentials submitted via HTTP POST as input and returns either:
A
user
object, which indicates the credentials are valid.If you return an object it will be persisted to the JSON Web Token and the user will be signed in, unless a custom
signIn()
callback is configured that subsequently rejects it.Either
false
ornull
, which indicates failure.If you return
false
ornull
then an error will be displayed advising the user to check their details.Promise.Rejected()
with an Error or a URL.If you reject the promise with an Error, the user will be sent to the error page with the error message as a query parameter. If you reject the promise with a URL (a string), the user will be redirected to the URL.
See the callbacks documentation for more information on how to interact with the token.
Multiple providers
Example code
You can specify more than one credentials provider by specifying a unique id
for each one.
You can also use them in conjuction with other provider options.
As with all providers, the order you specify them is the order they are displayed on the sign in page.
Example UI
This example below shows a complex configuration is rendered by the built in sign in page.
You can also use a custom sign in page if you want to provide a custom user experience.