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:

    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', err))
    {
      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'}}
    try {
      println(Await.result(
      client.query(
        Create(
          Ref(Collection("users"), "3"),
          Obj(
            "data" -> Obj(
              "email" -> "me@example.com"
            ),
            "credentials" -> Obj(
              "password" -> "abc123"
            )
          )
        )
      ),
      5.seconds
    ))} catch {
      case unknown: Throwable => println("Error: " + unknown.getMessage())
    }
    {ref: ref(id = "3", 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:

    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', err))
    {
      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)))}]}
    try {
      println(Await.result(
      client.query(
        Map(
          Paginate(Credentials()),
          Lambda("X", Get(Var("X")))
        )
      ),
      5.seconds
    ))} catch {
      case unknown: Throwable => println("Error: " + unknown.getMessage())
    }
    {data: [{ref: ref(id = "1", collection = ref(id = "credentials")), ts: 1601929944400000, instance: ref(id = "2", collection = ref(id = "users", collection = ref(id = "collections"))), hashed_password: "$2a$05$ApB0tP/3HazP4ie2/7JzpuY6M0u2mdc9ctwkJwCUPcOxflw4CiViS"}, {ref: ref(id = "278576333135544832", collection = ref(id = "credentials")), ts: 1601929944090000, hashed_password: "$2a$05$hwyLOsFFmwOEjATa57BBD.07QcoOj7gQuC1ktl8quBcdioS7bUVTa", instance: ref(id = "1", collection = ref(id = "users", collection = ref(id = "collections")))}, {ref: ref(id = "278576333157564928", collection = ref(id = "credentials")), ts: 1601929944090000, hashed_password: "$2a$05$912BctCr.uT82ZedCa65kOcfkqfxUn6wuZ6vQnlkgD8rpZ0Y5NBFC", instance: ref(id = "181388642114077184", collection = ref(id = "characters", 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:

    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', err))
    {
      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'}}
    try {
      println(Await.result(
        client.query(
            Update(
                Ref(Collection("users"), "2"),
                Obj("credentials" -> Obj("password" -> "myNewPassword"))
            )
        ),
        5.seconds
    ))} catch {
      case unknown: Throwable => println("Error: " + unknown.getMessage())
    }
    {ref: ref(id = "2", collection = ref(id = "users", collection = ref(id = "collections"))), ts: 1601931432610000, data: {name: "Bob User", email: "bob@site.example.com"}}

    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', err))
    {
      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)))}
    try {
      println(Await.result(
      client.query(
        Update(
          Ref(Credentials(), "1"),
          Obj(
            "current_password" -> "abc123",
            "password" -> "s3kret!"
          )
        )
      ),
      5.seconds
    ))} catch {
      case unknown: Throwable => println("Error: " + unknown.getMessage())
    }
    {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!