Log in and log out

This tutorial shows you how to log in to associated users with a token, and how to log out by deleting the token.

Log in

The way to tell Fauna that access to an identity document requires a password is by associating the identity with a credential. A document can have only one associated credential.

As a setup to this tutorial, your CoffeeStore database should have a People collection. If it doesn’t, you can recreate the collection as described in advanced/security/user-roles.adoc#people-data.

  1. Open the CoffeeStore database in the Fauna Shell.

  2. In the Fauna Shell, select the Admin Built-in Role.

  3. The login process in the following steps uses user email and password credentials. Find the first People document that includes an email:

    People.firstWhere(.email != null)
    {
  id: "370723013175279650",
  coll: People,
  ts: Time("2023-07-20T15:21:59.220Z"),
  name: "Janine Labrune",
  email: "jlabrune@gmail.com",
  address: {
    street: "67, rue des Cinquante Otages",
    city: "Nantes",
    country: "France",
    zip: "44000"
  },
  status: "active"
}

    Note the id field value, which is needed for the next step.

  4. Create a Credential for the document, including the required password:

    Credential.create({
  document: People.byId("370723013175279650"),
  password: "sekret"
})
    {
  id: "371153420791316514",
  coll: Credential,
  ts: Time("2023-07-24T17:05:34.890Z"),
  document: People.byId("370723013175279650")
}

    The People document is associated with the credential. The credential never displays the password.

    If you lose or forget your password, you can call Credential.update() to set a new password.

  5. Create a token using the login() method of the credentials object. The credential includes the document password.

    Credentials.byId("371153420791316514")!.login("sekret")
    {
  id: "371153519651061794",
  coll: Token,
  ts: Time("2023-07-24T17:07:09.170Z"),
  secret: "fnEFJpoo3_AAIgUiXlNNgAAi7f_DzBJ_4i_Y3fJHlD_KYwtEGfc",
  document: People.byId("370723013175279650")
}

    The login returns a token.

    A Token document can be associated with only one database, such that access to a parent database doesn’t grant access to its children.

    A token persists until it is deleted or expires. You can set the ttl field to define an expiration time if you want.

    You typically create a token when you use a key for authentication.

    This is the only time Fauna displays the secret and it can’t be recovered if it is discarded or lost. Make sure to copy and save the secret to a password manager or other safe location.

Log out

To log out, delete the login token. The Query.token() method gives you the current session token.

  1. In the Fauna Shell, select Secret and enter your token secret.

    Subsequent queries you enter use this secret.

  2. Verify that you are in the session with the correct token:

    Query.token()
    {
  id: "371287435110252578",
  coll: Token,
  ts: Time("2023-07-26T04:35:40.910Z"),
  document: People.byId("371264255805095970")
}

    Because you are using the token secret, Fauna knows your identity and allows you to make queries on your identity documents.

  3. To log out, delete the token:

    Query.token()!.delete()
    Token.byId("371287435110252578") /* permission denied */

  4. Verify that the query fails because the secret is no longer valid:

    People.all()
    Invalid secret

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!