Tokens
Reference: Token |
---|
A token is a type of authentication secret used to provide identity-based access to a Fauna database.
You typically create and use tokens as part of a Fauna-based end-user authentication system.
Token system collection
Fauna stores tokens as documents in the Token
system collection. You can use
Token methods to access Token
collection documents in FQL.
See Token FQL docs |
---|
Identity documents
Each token is associated with an identity document that represents an end user,
system, or other identity. The identity document is distinct from the Token
document.
Any document in any user-defined collection can act as an identity document. For example:
// Example `Customer` collection document that acts
// as an identity document.
{
id: "<DOCUMENT_ID>",
coll: Customer,
ts: Time("2099-07-08T13:39:55.690Z"),
name: "Alice Appleseed",
email: "alice.appleseed@example.com",
address: {
street: "87856 Mendota Court",
city: "Washington",
state: "DC",
zipCode: "20220"
},
...
}
Multiple identity document collections
A common approach is to use different collections for different types of identity documents. This often makes role membership easier to manage.
For example, you can use the Customer
collection to store identity documents
for customer end users. In the same database, you can use the Manager
collection to store identity documents for manager end users.
Token roles
Fauna assigns user-defined roles to
tokens based on their identity document’s collection and the membership
property of the related role’s schema:
// Schema for the user-defined `customer` role.
role customer {
// Assign the `customer` role to tokens with
// identity documents in the `Customer` collection.
membership Customer
}
You can use membership to assign a token multiple roles. You can also use membership predicates to conditionally assign roles to tokens.
You can’t assign a built-in role to a token.
See Role membership. |
---|
Update a token’s roles
Fauna checks a token’s roles and related privileges at query time for every query.
To update a token’s roles or privileges, edit the membership and privileges for the related roles. Changes to roles and privileges take effect immediately and affect pre-existing tokens.
Check a token’s roles
You can use user-defined functions (UDFs) to check a token’s roles. See Check a secret’s user-defined roles.
Credentials
A credential associates an end-user password with an identity document.
Fauna stores credentials as documents in the Credential
system collection.
You can use Credential methods to
access Credential
collection documents in FQL.
See Credential FQL docs |
---|
Create and manage tokens
You create and manage tokens using FQL queries.
Fauna supports two methods for token creation:
-
Using a credential, which is useful for end-user authentication.
-
Without a credential, which is useful for servers, services, and other non-user identities.
Create a token with a credential
The following procedure outlines the steps for creating a token with a credential.
For clarity, the procedure outlines each step separately. In production, you’d typically bundle and encapsulate the steps in user-defined functions (UDFs). For an example, see Build an end-user authentication system.
-
If needed, create an identity document:
// Creates `Customer` collection document. // The collection contains identity documents for // customer end users. Customer.create({ email: "jdoe@example.com" })
-
Create a credential for the identity document:
// Declares a `customer` variable. // Uses the `Customer` collection's `byEmail()` index to // get `Customer` collection documents by `email` field value. // In the `Customer` collection, `email` field values are unique // so return the `first()` (and only) document. let customer = Customer.byEmail("jdoe@example.com").first() // Creates a credential for the previous `Customer` // identity document. In this example, the `password` is a // provided by the customer end user. Credential.create({ document: customer, password: "sekret" })
An identity document can only have one credential.
-
Call
credential.login()
to create a token using the credential and its password:let customer = Customer.byEmail("jdoe@example.com").first() // Uses `byDocument()` to get the credential for // the previous `Customer` identity document. let credential = Credentials.byDocument(customer) // Calls the `login()` with the credential's password. credential?.login("sekret"))
The returned
Token
document includes the token’ssecret
, which you can use to authenticate with Fauna. A token’s secret is shown once — when you create the token.{ id: "<DOCUMENT_ID>"", coll: Token, ts: Time("2099-07-08T14:34:15.520Z"), // Token's secret secret: "fn...", // `document` contains the token's identity document. document: Customer("<IDENTITY_DOCUMENT_ID>") }
-
If wanted, you can call
credential.login()
multiple times to create multiple tokens using the same credential.
Reference: credential.login() |
---|
Create a token without a credential
The following procedure outlines the steps for creating a token without a credential or related password.
-
If needed, create an identity document:
// Creates `Customer` collection document. // The collection contains identity documents for // customer end users. Customer.create({ email: "jdoe@example.com" })
-
Call
Token.create()
to create a token using the identity document:// Declares a `customer` variable. // Uses the `Customer` collection's `byEmail()` index to // get `Customer` collection documents by `email` field value. // In the `Customer` collection, `email` field values are unique // so return the `first()` (and only) document. let customer = Customer.byEmail("jdoe@example.com").first() // Creates a token for the previous `Customer` // identity document. Token.create({ document: customer })
The returned
Token
document includes the token’ssecret
, which you can use to authenticate with Fauna. A token’s secret is shown once — when you create the token.{ id: "<DOCUMENT_ID>"", coll: Token, ts: Time("2099-07-08T14:34:15.520Z"), // Token's secret secret: "fn...", // `document` contains the token's identity document. document: Customer("<IDENTITY_DOCUMENT_ID>") }
-
If wanted, you can call
Token.create()
multiple times to create multiple tokens using the same identity document.
Reference: Token.create() |
---|
Multiple requests
You can use the same token secret to authenticate multiple Fauna requests. A secret remains valid until it expires or is deleted.
Token expiration
A Token
document can include an optional ttl
(time-to-live) field that
contains the token’s expiration timestamp. You can set this ttl
when you
create a token using credential.login()
:
let customer = Customer.byEmail("alice.appleseed@example.com").first()
let credential = Credentials.byDocument(customer)
// Set the token's `ttl` to 60 minutes from the current time at
// query. The token's secret expires at its `ttl`.
credential?.login("fauna-demo", Time.now().add(60, "minutes")))
{
id: "<TOKEN_DOCUMENT_ID>"",
coll: Token,
ts: Time("2099-07-08T14:34:15.520Z"),
ttl: Time("2099-07-06T19:28:51.499944Z"),
secret: "fn...",
document: Customer("<IDENTITY_DOCUMENT_ID>")
}
You can also set ttl
using Token
methods:
Token.byId("<TOKEN_DOCUMENT_ID>")?.update({
// Set the token's `ttl`.
ttl: Time.now().add(60, "minutes")
})
After the ttl
timestamp passes, Fauna permanently deletes the token and its
secret. You can’t use an expired token’s secret to authenticate requests.
A Token
document without a ttl
does not expire and persists until deleted.
Access end-user data in a query
If you use a token secret to authenticate a FQL query, you can access the
token’s identity document or Token
document in the query.
You can use ABAC to dynamically grant roles and privileges based on attributes of these documents.
Access a token’s identity document
Use Query.identity()
to get the identity
document for a query’s authentication token:
Query.identity()
{
id: "<DOCUMENT_ID>",
coll: Customer,
ts: Time("2099-06-21T18:39:00.735Z"),
name: "Alice Appleseed",
email: "alice.appleseed@example.com",
...
}
Reference: Query.identity() |
---|
Access a token document
Use Query.token()
to get the Token
document
for a query’s authentication token:
Query.token()
{
id: "<DOCUMENT_ID>",
coll: Token,
ts: Time("2099-07-06T19:11:13.570Z"),
document: Customer.byId("<IDENTITY_DOCUMENT_ID>")
}
Reference: Query.token() |
---|
Is this article helpful?
Tell Fauna how the article can be improved:
Visit Fauna's forums
or email docs@fauna.com
Thank you for your feedback!