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, which can be a Ref or a Set of refs, based on the password provided in param_object.

The authentication token’s secret can be used to connect to Fauna and execute queries within the database that contains identity. The permissions granted to the authentication token can be specified 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.

Parameters

Argument Type Definition and Requirements

identity

Ref or Set

The identity (reference to a document) or identities (set of refs to multiple documents) to authenticate.

param_object

Object

The param_object fields are described below.

param_object

Field Name Field Type Definition and Requirements

data

Object

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

password

String

The password to authenticate identity with.

ttl

Timestamp

Optional - A timestamp indicating the authentication token’s time-to-live, which is when the token should be removed. When a token is removed, the token’s existence ceases (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 actually occurs.

As of version 3.0.0, the ttl field is honored on read — a document that should have been removed behaves as if it has been removed. However, until removal actually occurs due to background task processing, you can continue to access the history of the document, provided you have its reference, via the Events function.

Returns

When authentication is successful, an object containing the authenticated Ref(s) is returned. When authentication fails, an error is returned.

Examples

client.Query(
    Login(
        Ref(Collection("characters"), "181388642114077184"),
        Obj("password", "abracadabra")
    )
);
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(181388642114077184L)),
            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', err))
{
  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'}
client.query(
  Login(
    Ref(Collection("characters"), "181388642114077184"),
    Obj("password" -> "abracadabra")))
{ref: ref(id = "270774096773513728", collection = ref(id = "tokens")), ts: 1594489151640000, instance: ref(id = "181388642114077184", collection = ref(id = "characters", collection = ref(id = "collections"))), secret: "fnEDwfubPJACAAPB-5Ru4AIAgnYlhCKrBBQ9EGB1Vs8VyL8H78U"}

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!