Credentials

Copied!
( [database] )

Description

The Credentials function provides the set of existing credential documents in the current database.

Credential documents are used to store the hashed password for a document. They are, most often, created implicitly when a document is created or updated with a top-level credentials object (that documents never store). Credential documents can also be created directly. See Credentials for details.

The Login or Identify functions use the hashed password stored in an identity document’s associated credential document in order to authenticate the identity document.

This function is useful for:

  • Listing currently existing credentials,

  • Creating credentials for already-existing documents,

  • Updating existing credentials (password update).

If you have a reference to a specific credential document, you can add custom fields to the credential document using Update or Replace.

When a credential document is created or updated, a BCrypt hash of the provided password is generated and stored. The original password is never stored on disk.

Parameters

Parameter Type Definition and Requirements

database

Reference

Optional - A Reference to a child database. If not specified, the current database is used.

Returns

A Set Reference for the set of existing credential documents.

Examples

  1. Create a credential

    The following query creates a credential document by specifying a credentials field while creating a document. Notice that the returned document no longer contains the credentials field:

    Copied!
    (
  (('users'), '3'),
  {
    data: {
      email: 'me@example.com',
    },
    credentials: {
      password: 'abc123',
    },
  }
)
    {
  ref: (("users"), "3"),
  ts: 1624310371040000,
  data: { email: 'me@example.com' }
}
    Query metrics:

    •    bytesIn:  164

    •   bytesOut:  176

    • computeOps:    1

    •    readOps:    0

    •   writeOps:    2

    •  readBytes:   93

    • writeBytes:  768

    •  queryTime: 57ms

    •    retries:    0

  2. List existing credentials

    The following query lists the References for any credentials (up to the pagination limit) in the current database, which includes the credential created in the first example:

    Copied!
    (
  (()),
  ('X', (('X')))
)
    {
  data: [
    {
      ref: ((), "1"),
      ts: 1624310372440000,
      instance: (("users"), "2"),
      hashed_password: '$2a$05$JeoMygtRUkhcYZL0q.v97.OHPnJ7884wKoHiBOHtlJZgSPKosBjpu'
    },
    {
      ref: ((), "302043912923513344"),
      ts: 1624310372440000,
      hashed_password: '$2a$05$rRJ29kORWsn77mkeNyaWWudl4MFgoJXtTsTyNiK.2YBgw3wTiWCm.',
      instance: (("users"), "1")
    },
    {
      ref: ((), "302043913015788032"),
      ts: 1624310372440000,
      hashed_password: '$2a$05$bZzDq3xKGsKCkIIeIo2RcedbOL0GLeBUnpdgGY7Xpi73LYdh61f46',
      instance: (("characters"), "181388642114077184")
    }
  ]
}
    Query metrics:

    •    bytesIn:   96

    •   bytesOut:  934

    • computeOps:    1

    •    readOps:   11

    •   writeOps:    0

    •  readBytes:  770

    • writeBytes:    0

    •  queryTime: 12ms

    •    retries:    0

    The following query lists the References for any credentials (up to the pagination limit) in a child database named "child_db":

    Copied!
    (
  ((('child_db'))),
  ('X', (('X')))
)
    { data: [] }
    Query metrics:

    •    bytesIn:  115

    •   bytesOut:   24

    • computeOps:    1

    •    readOps:    8

    •   writeOps:    0

    •  readBytes:  363

    • writeBytes:    0

    •  queryTime: 24ms

    •    retries:    0

  3. Update a credential (change password)

    There are two ways to update a credential.

    The following query updates the credential document by updating a document while specifying the credentials field:

    Copied!
    (
  (('users'), '2'),
  { credentials: { password: 'myNewPassword' } }
)
    {
  ref: (("users"), "2"),
  ts: 1624310378780000,
  data: { name: 'Bob User', email: 'bob@site.example.com' }
}
    Query metrics:

    •    bytesIn:  126

    •   bytesOut:  200

    • computeOps:    1

    •    readOps:    0

    •   writeOps:    2

    •  readBytes:  296

    • writeBytes:  332

    •  queryTime: 57ms

    •    retries:    0

    The following query demonstrates how to update a credential when you have a reference to the credential document itself:

    Copied!
    (
  ((), '1'),
  {
    current_password: 'abc123',
    password: 's3kret!',
  }
)
    {
  ref: ((), "1"),
  ts: 1624310381270000,
  instance: (("users"), "2"),
  hashed_password: '$2a$05$DoPPOepN4tx2arzvikDuKOEguR8EQLE0DULEc9LAiRWvzj3NPFH4i'
}
    Query metrics:

    •    bytesIn:  119

    •   bytesOut:  297

    • computeOps:    1

    •    readOps:    0

    •   writeOps:    1

    •  readBytes:  140

    • writeBytes:  230

    •  queryTime: 45ms

    •    retries:    0

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!