Login

Login( identity, param_object )
Login( identity, param_object )
Login( identity, param_object )
Login( identity, param_object )
login( identity, param_object )
Login( identity, param_object )

Description

The Login function creates an authentication token for the provided identity using the password provided in the param_object. The identity field can be a Reference for the identity document that should be authenticated, or a Set of References (where only the first Reference in the Set is authenticated).

If the identity document does not exist, or the provided password is incorrect, Login returns an error.

The authentication token secret for an authentication token can be used to connect to Fauna and execute queries in the database that has the identity. The permissions granted to the authentication token can be defined using Attribute-based access control (ABAC).

If the identity is not a member of at least one ABAC role, it has no privileges to read or write documents except its own identity document.

Parameters

Parameter Type Definition and Requirements

identity

The identity (reference to a document). When provided as a Set Reference, the first document reference in the set is used.

param_object

The param_object fields are described below.

param_object

Field Name Field Type Definition and Requirements

data

Optional - a document storing metadata about the token to be created.

password

The password to authenticate identity with.

ttl

Optional - A timestamp indicating the time-to-live for an authentication token, which is when the token should be removed. When a token is removed, the token ceases to exist (temporal queries cannot recover the token) and the associated secret can no longer be used to authenticate.

Removal is handled by a background task, so once a document (including collections, databases, indexes, keys, roles, and tokens) "expires" due to the setting in the ttl field, it could be some time (hours or days) before the removal occurs. There is no guarantee that removal occurs.

As of version 3.0.0, the ttl field is honored on read — an expired but not yet removed document behaves as if removal is complete. But, until removal is completed by background task processing, you can continue to access the history of the document, provided you have its reference, using the Events function.

Returns

Authentication status Return type Description

Success

An object with the authenticated Reference(s).

Failure

An error is returned.

Examples

try
{
    Value result = await client.Query(
        Login(
            Ref(Collection("characters"), "181388642114077184"),
            Obj("password", "abracadabra")
        )
    );
    Console.WriteLine(result);
}
catch (Exception e)
{
    Console.WriteLine($"ERROR: {e.Message}");
}
ObjectV(ref: RefV(id = "280491620815602176", collection = RefV(id = "tokens")),ts: LongV(1603756504750000),instance: RefV(id = "181388642114077184", collection = RefV(id = "characters", collection = RefV(id = "collections"))),secret: StringV(fnED5IGknTACAAPkgaNqIAIAx6peH_1tJ7X82fJ7bcOF6exEWYw))
result, err := client.Query(
	f.Login(
		f.Ref(f.Collection("characters"), "181388642114077184"),
		f.Obj{"password": "abracadabra"},
	))

if err != nil {
	fmt.Fprintln(os.Stderr, err)
} else {
	fmt.Println(result)
}
map[instance:{181388642114077184 0xc00008e3f0 0xc00008e3f0 <nil>} ref:{280481898848846336 0xc00008e240 0xc00008e240 <nil>} secret:fnED5HjNCtACAAPkeMygwAIA1rfQDqKRQAnHrDBoN1a_DgsbVMw ts:1603747233160000]
System.out.println(
    client.query(
        Login(
            Ref(Collection("characters"), Value("181388642114077184")),
            Obj("password", Value("abracadabra"))
        )
    ).get());
{ref: ref(id = "269701642908074496", collection = ref(id = "tokens")), ts: 1593466379950000, instance: ref(id = "181388642114077184", collection = ref(id = "characters", collection = ref(id = "collections"))), secret: "fnEDviw3HOACAAO-LDL9UAIAe6cFd6PJDjOcXLSnrSH2s6K97Fk"}
client.query(
  q.Login(
    q.Ref(q.Collection('characters'), '181388642114077184'),
    { password: 'abracadabra' },
  )
)
.then((ret) => console.log(ret))
.catch((err) => console.error(
  'Error: [%s] %s: %s',
  err.name,
  err.message,
  err.errors()[0].description,
))
{
  ref: Ref(Tokens(), "268283157930836480"),
  ts: 1592113607250000,
  instance: Ref(Collection("characters"), "181388642114077184"),
  secret: 'fnEDuSIcV7ACAAO5IhwXkAIAMQbrsrZaHs1cUWnligxyD5kUAPE'
}
result = client.query(
  q.login(
    q.ref(q.collection("characters"), "181388642114077184"),
    {"password": "abracadabra"}
  )
)
print(result)
{'ref': Ref(id=269168498780930560, collection=Ref(id=tokens)), 'ts': 1592957934080000, 'instance': Ref(id=181388642114077184, collection=Ref(id=characters, collection=Ref(id=collections))), 'secret': 'fnEDvEdS0pACAAO8R1KZUAIAswCZXMn3gnH_93FC7t_-eRUlqCU'}
Login(
  Ref(Collection('characters'), '181388642114077184'),
  { password: 'abracadabra' },
)
{
  ref: Ref(Tokens(), "302044012369412608"),
  ts: 1624310467030000,
  instance: Ref(Collection("characters"), "181388642114077184"),
  secret: 'fnEEMRNtz9ACAAQxE20rQAYAdf5rxVCUGicwNLCuiIB8CjHCqME'
}
Query metrics:
  •    bytesIn:  118

  •   bytesOut:  313

  • computeOps:    1

  •    readOps:    1

  •   writeOps:    1

  •  readBytes:  214

  • writeBytes:  414

  •  queryTime: 56ms

  •    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!