Credentials

Credentials( [database] )
Credentials( )
ScopedCredentials( database )
Credentials( [database] )
Credentials( [database] )
credentials( [database] )
Credentials( [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.

A Reference to a child database.

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

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

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

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

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:

    try
{
    Value result = await client.Query(
        Create(
            Ref(Collection("users"), "3"),
            Obj(
                "data", Obj(
                    "email", "me@example.com"
                ),
                "credentials", Obj(
                    "password", "abc123"
                )
            )
        )
    );
    Console.WriteLine(result);
}
catch (Exception e)
{
    Console.WriteLine($"ERROR: {e.Message}");
}
    ObjectV(ref: RefV(id = "3", collection = RefV(id = "users", collection = RefV(id = "collections"))),ts: LongV(1603756198370000),data: ObjectV(email: StringV(me@example.com)))
    result, err := client.Query(
	f.Create(
		f.Ref(f.Collection("users"), "3"),
		f.Obj{
			"data": f.Obj{
				"email": "me@example.com" },
			"credentials": f.Obj{
				"password": "abc123" } }))

if err != nil {
	fmt.Fprintln(os.Stderr, err)
} else {
	fmt.Println(result)
}
    map[data:map[email:me@example.com] ref:{3 0xc0000bf710 0xc0000bf710 <nil>} ts:1603747139960000]
    System.out.println(
    client.query(
        Create(
            Ref(Collection("users"), Value(3)),
            Obj(
                "data", Obj(
                    "email", Value("me@example.com")
                ),
                "credentials", Obj(
                    "password", Value("abc123")
                )
            )
        )
    ).get());
    {ref: ref(id = "3", collection = ref(id = "users", collection = ref(id = "collections"))), ts: 1590015335330000, data: {email: "me@example.com"}}
    client.query(
  q.Create(
    q.Ref(q.Collection('users'), '3'),
    {
      data: {
        email: 'me@example.com',
      },
      credentials: {
        password: 'abc123',
      },
    }
  )
)
.then((ret) => console.log(ret))
.catch((err) => console.error(
  'Error: [%s] %s: %s',
  err.name,
  err.message,
  err.errors()[0].description,
))
    {
  ref: Ref(Collection("users"), "3"),
  ts: 1590014989740000,
  data: { email: 'me@example.com' }
}
    result = client.query(
  q.create(
    q.ref(q.collection("users"), "3"),
    {
      "data": {
        "email": "me@example.com",
      },
      "credentials": {
        "password": "abc123"
      }
    }
  )
)
print(result)
    {'ref': Ref(id=3, collection=Ref(id=users, collection=Ref(id=collections))), 'ts': 1590015699900000, 'data': {'email': 'me@example.com'}}
    Create(
  Ref(Collection('users'), '3'),
  {
    data: {
      email: 'me@example.com',
    },
    credentials: {
      password: 'abc123',
    },
  }
)
    {
  ref: Ref(Collection("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:

    try
{
    Value result = await client.Query(
        Map(
            Paginate(Credentials()),
            Lambda("X", Get(Var("X")))
        )
    );
    Console.WriteLine(result);
}
catch (Exception e)
{
    Console.WriteLine($"ERROR: {e.Message}");
}
    ObjectV(data: Arr(ObjectV(ref: RefV(id = "1", collection = RefV(id = "credentials")),ts: LongV(1603756199360000),instance: RefV(id = "2", collection = RefV(id = "users", collection = RefV(id = "collections"))),hashed_password: StringV($2a$05$hJdDKuTFYIkmVSFZcMKD6eGFQ0poVjDwORlLcwmXsGH4qwHY08TWq)), ObjectV(ref: RefV(id = "280491300341416448", collection = RefV(id = "credentials")),ts: LongV(1603756199120000),hashed_password: StringV($2a$05$dkesunx97SZGrTMCe4sgMeOCurm.AlaEys/waE1CfCyzkDtVnkUgq),instance: RefV(id = "1", collection = RefV(id = "users", collection = RefV(id = "collections")))), ObjectV(ref: RefV(id = "280491300342465024", collection = RefV(id = "credentials")),ts: LongV(1603756199120000),hashed_password: StringV($2a$05$V2Z.lSi0VZfJHpTFNmFEx.pCroUf3SlASvvcy.QY5rbIFmnim3gZe),instance: RefV(id = "181388642114077184", collection = RefV(id = "characters", collection = RefV(id = "collections"))))))
    result, err := client.Query(
	f.Map(
		f.Paginate(f.Credentials()),
		f.Lambda("X", f.Get(f.Var("X")))))

if err != nil {
	fmt.Fprintln(os.Stderr, err)
} else {
	fmt.Println(result)
}
    map[data:[map[hashed_password:$2a$05$lo1Uc1sqr/BJ4ieNClNRcOAYEH81ocq1osA/UDlz8wqan7UByNn6K instance:{2 0xc0000b7650 0xc0000b7650 <nil>} ref:{1 0xc0000b74a0 0xc0000b74a0 <nil>} ts:1603747140870000] map[hashed_password:$2a$05$pr/C3URfjEax73piLCNvleCc/qgVvF8to.T4OsH.mS9hFxzVZAp1C instance:{1 0xc00008e2a0 0xc00008e2a0 <nil>} ref:{280481801822011904 0xc0000b7770 0xc0000b7770 <nil>} ts:1603747140630000] map[hashed_password:$2a$05$E0jsZVARQFx38fZtgqWj/.s75qhB.rQ3WblydvH3FEbwTz.FgJcma instance:{181388642114077184 0xc00008e570 0xc00008e570 <nil>} ref:{280481801833546240 0xc00008e3c0 0xc00008e3c0 <nil>} ts:1603747140630000]]]
    System.out.println(
    client.query(
        Map(
            Paginate(Credentials()),
            Lambda("X", Get(Var("X")))
        )
    ).get());
    {data: [{ref: ref(id = "1", collection = ref(id = "credentials")), ts: 1601929884950000, instance: ref(id = "2", collection = ref(id = "users", collection = ref(id = "collections"))), hashed_password: "$2a$05$W5MswKg2Qn/2VIl5aSfgvuBv.w4l.eLki1ybjnxgtIwnPcV206OSK"}, {ref: ref(id = "278576270823916032", collection = ref(id = "credentials")), ts: 1601929884670000, hashed_password: "$2a$05$cL35Bbrbf0YThsjwvt2ml.mDBNE1X/rG8Wt2HwNvAzI3cMvS2blR6", instance: ref(id = "1", collection = ref(id = "users", collection = ref(id = "collections")))}, {ref: ref(id = "278576270851179008", collection = ref(id = "credentials")), ts: 1601929884670000, hashed_password: "$2a$05$iFxL6lFSsrks/1axcvg7meUidqv2VqYEnlT7pOvITPzqXH3SN5Z96", instance: ref(id = "181388642114077184", collection = ref(id = "characters", collection = ref(id = "collections")))}]}
    client.query(
  q.Map(
    q.Paginate(q.Credentials()),
    q.Lambda('X', q.Get(q.Var('X')))
  )
)
.then((ret) => console.log(ret))
.catch((err) => console.error(
  'Error: [%s] %s: %s',
  err.name,
  err.message,
  err.errors()[0].description,
))
    {
  data: [
    {
      ref: Ref(Credentials(), "1"),
      ts: 1601929730630000,
      instance: Ref(Collection("users"), "2"),
      hashed_password: '$2a$05$ChrufpV26Zwrgj/6LA/mlOk6CWWOMrw/hvv2z5mcKH2Ju99JnumXW'
    },
    {
      ref: Ref(Credentials(), "278576109013959168"),
      ts: 1601929730350000,
      hashed_password: '$2a$05$xQOb65pzQNzl2vEjkOwucO7PK/JIHmP65nSP3Kmn7LX.DDV6KnbdO',
      instance: Ref(Collection("users"), "1")
    },
    {
      ref: Ref(Credentials(), "278576109034930688"),
      ts: 1601929730350000,
      hashed_password: '$2a$05$E7jm9xLYIWGN1Dlv88p9SuAETxDq4sW0oxDMNUtkUrhMytxtIjSBi',
      instance: Ref(Collection("characters"), "181388642114077184")
    }
  ]
}
    result = client.query(
  q.map_(
    q.lambda_("X", q.get(q.var("X"))),
    q.paginate(q.credentials())
  )
)
print(result)
    {'data': [{'ref': Ref(id=1, collection=Ref(id=credentials)), 'ts': 1601929884950000, 'instance': Ref(id=2, collection=Ref(id=users, collection=Ref(id=collections))), 'hashed_password': '$2a$05$W5MswKg2Qn/2VIl5aSfgvuBv.w4l.eLki1ybjnxgtIwnPcV206OSK'}, {'ref': Ref(id=278576270823916032, collection=Ref(id=credentials)), 'ts': 1601929884670000, 'hashed_password': '$2a$05$cL35Bbrbf0YThsjwvt2ml.mDBNE1X/rG8Wt2HwNvAzI3cMvS2blR6', 'instance': Ref(id=1, collection=Ref(id=users, collection=Ref(id=collections)))}, {'ref': Ref(id=278576270851179008, collection=Ref(id=credentials)), 'ts': 1601929884670000, 'hashed_password': '$2a$05$iFxL6lFSsrks/1axcvg7meUidqv2VqYEnlT7pOvITPzqXH3SN5Z96', 'instance': Ref(id=181388642114077184, collection=Ref(id=characters, collection=Ref(id=collections)))}]}
    Map(
  Paginate(Credentials()),
  Lambda('X', Get(Var('X')))
)
    {
  data: [
    {
      ref: Ref(Credentials(), "1"),
      ts: 1624310372440000,
      instance: Ref(Collection("users"), "2"),
      hashed_password: '$2a$05$JeoMygtRUkhcYZL0q.v97.OHPnJ7884wKoHiBOHtlJZgSPKosBjpu'
    },
    {
      ref: Ref(Credentials(), "302043912923513344"),
      ts: 1624310372440000,
      hashed_password: '$2a$05$rRJ29kORWsn77mkeNyaWWudl4MFgoJXtTsTyNiK.2YBgw3wTiWCm.',
      instance: Ref(Collection("users"), "1")
    },
    {
      ref: Ref(Credentials(), "302043913015788032"),
      ts: 1624310372440000,
      hashed_password: '$2a$05$bZzDq3xKGsKCkIIeIo2RcedbOL0GLeBUnpdgGY7Xpi73LYdh61f46',
      instance: Ref(Collection("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":

    try
{
    Value result = await client.Query(
        Map(
            Paginate(Credentials(Database("child_db"))),
            Lambda("X", Get(Var("X")))
        )
    );
    Console.WriteLine(result);
}
catch (Exception e)
{
    Console.WriteLine($"ERROR: {e.Message}");
}
    ObjectV(data: Arr())
    result, err := client.Query(
	f.Map(
		f.Paginate(f.ScopedCredentials(f.Database("child_db"))),
		f.Lambda("X", f.Get(f.Var("X")))))

if err != nil {
	fmt.Fprintln(os.Stderr, err)
} else {
	fmt.Println(result)
}
    map[data:[]]
    System.out.println(
    client.query(
        Map(
            Paginate(Credentials(Database("child_db"))),
            Lambda("X", Get(Var("X")))
        )
    ).get());
    {data: []}
    client.query(
  q.Map(
    q.Paginate(q.Credentials(q.Database('child_db'))),
    q.Lambda('X', q.Get(q.Var('X')))
  )
)
.then((ret) => console.log(ret))
.catch((err) => console.error(
  'Error: [%s] %s: %s',
  err.name,
  err.message,
  err.errors()[0].description,
))
    { data: [] }
    result = client.query(
  q.map_(
    q.lambda_("X", q.get(q.var("X"))),
    q.paginate(q.credentials(q.database("child_db")))
  )
)
print(result)
    {'data': []}
    Map(
  Paginate(Credentials(Database('child_db'))),
  Lambda('X', Get(Var('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:

    try
{
    Value result = await client.Query(
        Update(
            Ref(Collection("users"), "2"),
            Obj("credentials", Obj("password", "myNewPassword"))
        )
    );
    Console.WriteLine(result);
}
catch (Exception e)
{
    Console.WriteLine($"ERROR: {e.Message}");
}
    ObjectV(ref: RefV(id = "2", collection = RefV(id = "users", collection = RefV(id = "collections"))),ts: LongV(1603756208270000),data: ObjectV(name: StringV(Bob User),email: StringV(bob@site.example.com)))
    result, err := client.Query(
	f.Update(
		f.Ref(f.Collection("users"), "2"),
		f.Obj{"credentials": f.Obj{"password": "myNewPassword"}}))

if err != nil {
	fmt.Fprintln(os.Stderr, err)
} else {
	fmt.Println(result)
}
    map[data:map[email:bob@site.example.com name:Bob User] ref:{2 0xc000156180 0xc000156180 <nil>} ts:1603747143310000]
    System.out.println(
    client.query(
        Update(
            Ref(Collection("users"), "2"),
            Obj("credentials", Obj("password", Value("myNewPassword")))
        )
    ).get());
    {ref: ref(id = "2", collection = ref(id = "users", collection = ref(id = "collections"))), ts: 1601931407470000, data: {name: "Bob User", email: "bob@site.example.com"}}
    client.query(
  q.Update(
    q.Ref(q.Collection('users'), '2'),
    { credentials: { password: 'myNewPassword' } }
  )
)
.then((ret) => console.log(ret))
.catch((err) => console.error(
  'Error: [%s] %s: %s',
  err.name,
  err.message,
  err.errors()[0].description,
))
    {
  ref: Ref(Collection("users"), "2"),
  ts: 1601931293490000,
  data: { name: 'Bob User', email: 'bob@site.example.com' }
}
    result = client.query(
  q.update(
    q.ref(q.collection("users"), "2"),
    {"credentials": {"password": "myNewPassword"}}
  )
)
print(result)
    {'ref': Ref(id=2, collection=Ref(id=users, collection=Ref(id=collections))), 'ts': 1601931860380000, 'data': {'name': 'Bob User', 'email': 'bob@site.example.com'}}
    Update(
  Ref(Collection('users'), '2'),
  { credentials: { password: 'myNewPassword' } }
)
    {
  ref: Ref(Collection("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:

    try
{
    Value result = await client.Query(
        Update(
            Ref(Credentials(), "1"),
            Obj(
                "current_password", "abc123",
                "password", "s3kret!"
            )
        )
    );
    Console.WriteLine(result);
}
catch (Exception e)
{
    Console.WriteLine($"ERROR: {e.Message}");
}
    ObjectV(ref: RefV(id = "1", collection = RefV(id = "credentials")),ts: LongV(1603756213160000),instance: RefV(id = "2", collection = RefV(id = "users", collection = RefV(id = "collections"))),hashed_password: StringV($2a$05$Mr1ByM81UbU0FjFAVMJtvOcaD6TfnlVks2o8couwCE7WZtQD5P0uC))
    result, err := client.Query(
	f.Update(
		f.Ref(f.Credentials(), "1"),
		f.Obj{
			"current_password": "abc123",
			"password": "s3kret!" }))

if err != nil {
	fmt.Fprintln(os.Stderr, err)
} else {
	fmt.Println(result)
}
    map[hashed_password:$2a$05$sq9yt4m.hJUSuNz/pcj5pu/OuxQ6p/NCPPT2KMtCaLjw8Gku6zj9q instance:{2 0xc00008f770 0xc00008f770 <nil>} ref:{1 0xc00008f5c0 0xc00008f5c0 <nil>} ts:1603747144970000]
    System.out.println(
    client.query(
        Update(
            Ref(Credentials(), "1"),
            Obj(
                "current_password", Value("abc123"),
                "password", Value("s3kret!")
            )
        )
    ).get());
    {ref: ref(id = "266082597906416137", collection = ref(id = "credentials")), ts: 1590022100100000, hashed_password: "$2a$05$kbMVi/ROL2yj/i1iifAx5uhupVeGnIFSCoeG66RKnMrNtbjmW5p3u", instance: ref(id = "2", collection = ref(id = "users", collection = ref(id = "collections")))}
    client.query(
  q.Update(
    q.Ref(q.Credentials(), '1'),
    {
      current_password: 'abc123',
      password: 's3kret!',
    }
  )
)
.then((ret) => console.log(ret))
.catch((err) => console.error(
  'Error: [%s] %s: %s',
  err.name,
  err.message,
  err.errors()[0].description,
))
    {
  ref: Ref(Credentials(), "266082597906416137"),
  ts: 1590022100100000,
  hashed_password: '$2a$05$kbMVi/ROL2yj/i1iifAx5uhupVeGnIFSCoeG66RKnMrNtbjmW5p3u',
  instance: Ref(Collection("users"), "2")
}
    result = client.query(
  q.update(
    q.ref(q.credentials(), "1"),
    {
      "current_password": "abc123",
      "password": "s3kret!"
    }
  )
)
print(result)
    {'ref': Ref(id=266082597906416137, collection=Ref(id=credentials)), 'ts': 1590022100100000, 'hashed_password': '$2a$05$kbMVi/ROL2yj/i1iifAx5uhupVeGnIFSCoeG66RKnMrNtbjmW5p3u', 'instance': Ref(id=2, collection=Ref(id=users, collection=Ref(id=collections)))}
    Update(
  Ref(Credentials(), '1'),
  {
    current_password: 'abc123',
    password: 's3kret!',
  }
)
    {
  ref: Ref(Credentials(), "1"),
  ts: 1624310381270000,
  instance: Ref(Collection("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!