Credentials

Credentials( )
Credentials( )
Credentials( )
Credentials( )
credentials( )
credentials
Credentials( )
Credentials( )

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

None.

Returns

A SetRef 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:

    Value result = await client.Query(
      Create(
        Ref(Collection("users"), "2"),
        Obj(
          "data", Obj(
            "email", "me@example.com"
          ),
          "credentials", Obj(
            "password", "abc123"
          )
        )
      )
    );
    result, err := client.Query(
      f.Create(
        f.Ref(f.Collection("users"), "2"),
        f.Obj{
          "data": f.Obj{
            "email": "me@example.com" },
          "credentials": f.Obj{
            "password": "abc123" } }))
    
    if (err != nil) {
      fmt.Println(err)
    } else {
      fmt.Println(result)
    }
    System.out.println(
        client.query(
            Create(
                Ref(Collection("users"), Value(2)),
                Obj(
                    "data", Obj(
                        "email", Value("me@example.com")
                    ),
                    "credentials", Obj(
                        "password", Value("abc123")
                    )
                )
            )
        ).get());
    client.query(
      q.Create(
        q.Ref(q.Collection('users'), '2'),
        {
          data: {
            email: 'me@example.com',
          },
          credentials: {
            password: 'abc123'
          }
        }
      )
    )
    .then((ret) => console.log(ret))
    print(client.query(
      q.create(
        q.ref(q.collection("users"), "2"),
        {
          "data": {
            "email": "me@example.com",
          },
          "credentials": {
            "password": "abc123"
          }
        }
      )
    ))
    Not available in this language yet.
    println(Await.result(
      client.query(
        Create(
          Ref(Collection("users"), "2"),
          Obj(
            "data" -> Obj(
              "email" -> "me@example.com"
            ),
            "credentials" -> Obj(
              "password" -> "abc123"
            )
          )
        )
      ),
      5.seconds
    ))
    Not available in this language yet.
    ObjectV(ref: RefV(id = "2", collection = RefV(id = "users", collection = RefV(id = "collections"))),ts: LongV(1590016088500000),data: ObjectV(email: StringV(me@example.com)))
    map[data:map[email:me@example.com] ref:{2 0xc00008e480 0xc00008e480 <nil>} ts:1590015933070000]
    {ref: ref(id = "2", collection = ref(id = "users", collection = ref(id = "collections"))), ts: 1590015335330000, data: {email: "me@example.com"}}
    {
      ref: Ref(Collection("users"), "2"),
      ts: 1590014989740000,
      data: { email: 'me@example.com' }
    }
    {'ref': Ref(id=2, collection=Ref(id=users, collection=Ref(id=collections))), 'ts': 1590015699900000, 'data': {'email': 'me@example.com'}}
    {ref: ref(id = "2", collection = ref(id = "users", collection = ref(id = "collections"))), ts: 1590015539770000, data: {email: "me@example.com"}}
  2. List existing credentials

    The following query lists any existing credentials, which includes the credential created in the first example:

    Value result = await client.Query(
      Map(
        Paginate(Credentials()),
        Lambda("X", Get(Var("X")))
      )
    );
    result, err := client.Query(
      f.Map(
        f.Paginate(f.Credentials()),
        f.Lambda("X", f.Get(f.Var("X")))))
    
    if (err != nil) {
      fmt.Println(err)
    } else {
      fmt.Println(result)
    }
    System.out.println(
        client.query(
            Map(
                Paginate(Credentials()),
                Lambda("X", Get(Var("X")))
            )
        ).get());
    client.query(
      q.Map(
        q.Paginate(q.Credentials()),
        q.Lambda("X", q.Get(q.Var("X")))
      )
    )
    .then((ret) => console.log(ret))
    print(client.query(
      q.map_(
        q.lambda_("X", q.get(q.var("X"))),
        q.paginate(q.credentials())
      )
    ))
    Not available in this language yet.
    println(Await.result(
      client.query(
        Map(
          Paginate(Credentials()),
          Lambda("X", Get(Var("X")))
        )
      ),
      5.seconds
    ))
    Not available in this language yet.
    ObjectV(data: Arr(ObjectV(ref: RefV(id = "266082597906416137", collection = RefV(id = "credentials")),ts: LongV(1590016088500000),hashed_password: StringV($2a$05$pHnEDsQ7n5nb734z3W9/n.I5ksS53ScVVuxOgyjN2FQDsHYiKXXWm),instance: RefV(id = "2", collection = RefV(id = "users", collection = RefV(id = "collections"))))))
    map[data:[map[hashed_password:$2a$05$pHnEDsQ7n5nb734z3W9/n.I5ksS53ScVVuxOgyjN2FQDsHYiKXXWm instance:{2 0xc00008e600 0xc00008e600 <nil>} ref:{266082597906416137 0xc00008e450 0xc00008e450 <nil>} ts:1590016088500000]]]
    {data: [{ref: ref(id = "266082597906416137", collection = ref(id = "credentials")), ts: 1590016088500000, hashed_password: "$2a$05$pHnEDsQ7n5nb734z3W9/n.I5ksS53ScVVuxOgyjN2FQDsHYiKXXWm", instance: ref(id = "2", collection = ref(id = "users", collection = ref(id = "collections")))}]}
    {
      data: [
        {
          ref: Ref(Credentials(), "266082597906416137"),
          ts: 1590016088500000,
          hashed_password: '$2a$05$pHnEDsQ7n5nb734z3W9/n.I5ksS53ScVVuxOgyjN2FQDsHYiKXXWm',
          instance: Ref(Collection("users"), "2")
        }
      ]
    }
    {'data': [{'ref': Ref(id=266082597906416137, collection=Ref(id=credentials)), 'ts': 1590016088500000, 'hashed_password': '$2a$05$pHnEDsQ7n5nb734z3W9/n.I5ksS53ScVVuxOgyjN2FQDsHYiKXXWm', 'instance': Ref(id=2, collection=Ref(id=users, collection=Ref(id=collections)))}]}
    {data: [{ref: ref(id = "266082597906416137", collection = ref(id = "credentials")), ts: 1590016088500000, hashed_password: "$2a$05$pHnEDsQ7n5nb734z3W9/n.I5ksS53ScVVuxOgyjN2FQDsHYiKXXWm", instance: ref(id = "2", collection = ref(id = "users", collection = ref(id = "collections")))}]}
  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:

    Value result = await client.Query(
        Update(
            Ref(Collection("users"), "2"),
            Obj("credentials", Obj("password", "myNewPassword"))
        )
    );
    result, err := client.Query(
    	f.Update(
    		f.Ref(f.Collection("users"), "2"),
    		f.Obj{"credentials": f.Obj{"password": "myNewPassword"}}))
    
    if (err != nil) {
    	fmt.Println(err)
    } else {
    	fmt.Println(result)
    }
    System.out.println(
        client.query(
            Update(
                Ref(Collection("users"), "2"),
                Obj("credentials", Obj("password", Value("myNewPassword")))
            )
        ).get());
    client.query(
      q.Update(
        q.Ref(q.Collection('users'), '2'),
        { credentials: { password: 'myNewPassword' } }
      )
    )
    .then((ret) => console.log(ret))
    .catch((err) => console.log('Error:', err))
    print(client.query(
      q.update(
        q.ref(q.collection("users"), "2"),
        { "credentials": { "password": "myNewPassword" } }
      )
    ))
    Not available in this language yet.
    println(Await.result(
        client.query(
            Update(
                Ref(Collection("users"), "2"),
                Obj("credentials" -> Obj("password" -> "myNewPassword"))
            )
        ),
        5.seconds
    ))
    Not available in this language yet.
    ObjectV(ref: RefV(id = "2", collection = RefV(id = "users", collection = RefV(id = "collections"))),ts: LongV(1595955526310000),data: ObjectV(email: StringV(me@example.com)))
    Obj{"data": Obj{"email": "me@example.com"}, "ref": RefV{ID: "2", Collection: &RefV{ID: "users", Collection: &RefV{ID: "collections"}}}, "ts": 1595955409035000}
    {ref: ref(id = "2", collection = ref(id = "users", collection = ref(id = "collections"))), ts: 1595954885910000, data: {email: "me@example.com"}}
    {
      ref: Ref(Collection("users"), "2"),
      ts: 1595954762893000,
      data: { email: 'me@example.com' }
    }
    {'ref': Ref(id=2, collection=Ref(id=users, collection=Ref(id=collections))), 'ts': 1595955273875000, 'data': {'email': 'me@example.com'}}
    {ref: ref(id = "2", collection = ref(id = "users", collection = ref(id = "collections"))), ts: 1595955143260000, data: {email: "me@example.com"}}

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

    Value result = await client.Query(
      Update(
        Ref(Credentials(), "266082597906416137"),
        Obj(
          "current_password", "abc123",
          "password", "s3kret!"
        )
      )
    );
    result, err := client.Query(
      f.Update(
        f.Ref(f.Credentials(), "266082597906416137"),
        f.Obj{
          "current_password": "abc123",
          "password": "s3kret!" }))
    
    if (err != nil) {
      fmt.Println(err)
    } else {
      fmt.Println(result)
    }
    System.out.println(
        client.query(
            Update(
                Ref(Credentials(), "266082597906416137"),
                Obj(
                    "current_password", Value("abc123"),
                    "password", Value("s3kret!")
                )
            )
        ).get());
    client.query(
      q.Update(
        q.Ref(q.Credentials(), '266082597906416137'),
        {
          current_password: 'abc123',
          password: 's3kret!'
        }
      )
    )
    .then((ret) => console.log(ret))
    print(client.query(
      q.update(
        q.ref(q.credentials(), "266082597906416137"),
        {
          "current_password": "abc123",
          "password": "s3kret!"
        }
      )
    ))
    Not available in this language yet.
    println(Await.result(
      client.query(
        Update(
          Ref(Credentials(), "266082597906416137"),
          Obj(
            "current_password" -> "abc123",
            "password" -> "s3kret!"
          )
        )
      ),
      5.seconds
    ))
    Not available in this language yet.
    ObjectV(ref: RefV(id = "266082597906416137", collection = RefV(id = "credentials")),ts: LongV(1590022100100000),hashed_password: StringV($2a$05$kbMVi/ROL2yj/i1iifAx5uhupVeGnIFSCoeG66RKnMrNtbjmW5p3u),instance: RefV(id = "2", collection = RefV(id = "users", collection = RefV(id = "collections"))))
    map[hashed_password:$2a$05$kbMVi/ROL2yj/i1iifAx5uhupVeGnIFSCoeG66RKnMrNtbjmW5p3u instance:{2 0xc00008e870 0xc00008e870 <nil>} ref:{266082597906416137 0xc00008e5a0 0xc00008e5a0 <nil>} ts:1590022100100000]
    {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")))}
    {
      ref: Ref(Credentials(), "266082597906416137"),
      ts: 1590022100100000,
      hashed_password: '$2a$05$kbMVi/ROL2yj/i1iifAx5uhupVeGnIFSCoeG66RKnMrNtbjmW5p3u',
      instance: Ref(Collection("users"), "2")
    }
    {'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)))}
    {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")))}

Was this article helpful?

We're sorry to hear that.
Tell us how we can improve!
Visit Fauna's Discourse forums or email docs@fauna.com

Thank you for your feedback!