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).

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")));
{
  "ref": { "@ref": "tokens/181388643175236096" },
  "class": { "@ref": "tokens" },
  "ts": 1509244540264619,
  "document": { "@ref": "classes/characters/181388642114077184" },
  "secret": "fnEChGwCisACAAKEbAFuUAIAwIxOcffRgoJm7EgUt_zlmiPOze4"
}
curl https://db.fauna.com/ \
    -u fnAChGwBcAACAO70ziE0cfROosNJHdgBmJU1PgpL: \
    -d '{
          "login": { "@ref": "classes/characters/181388642114077184" },
          "params": { "object": { "password": "abracadabra" } }
        }'
HTTP/1.1 201 Created
{
  "resource": {
    "ref": { "@ref": "tokens/181388643175236096" },
    "class": { "@ref": "tokens" },
    "ts": 1509244540264619,
    "document": { "@ref": "classes/characters/181388642114077184" },
    "secret": "fnEChGwCisACAAKEbAFuUAIAwIxOcffRgoJm7EgUt_zlmiPOze4"
  }
}
result, _ := client.Query(
    f.Login(
        f.RefCollection(f.Collection("characters"), "181388642114077184"),
        f.Obj{"password": "abracadabra"},
    ),
)

fmt.Println(result)
map[ref:{181388643175236096 0xc4202b3440 <nil>} ts:1509244540264619 document:{181388642114077184 0xc4202b36c0 <nil>} secret:fnEChGwCisACAAKEbAFuUAIAwIxOcffRgoJm7EgUt_zlmiPOze4]
System.out.println(
       client.query(
           Login(
             Ref(Collection("characters"), Value(181388642114077184L)),
             Obj("password", Value("abracadabra")))
       ).get());
{
  ref: ref(id = "210072853209416192", collection = ref(id = "tokens")),
  ts: 1536599934671870,
  document: ref(id = "181388642114077184", collection = ref(id = "characters", collection = ref(id = "collections"))),
  secret: "fnEC6lQloIACAALqVCVT8AIAtHiABBu-jZoAKERviRRl5bjZNBQ"
}
client.query(
  q.Login(
    q.Ref(q.Collection('characters'), '181388642114077184'),
    { password: 'abracadabra' },
  )
)
.then((ret) => console.log(ret))
{ ref: Ref(id=181388643175236096, collection=Ref(id=tokens)),
  ts: 1527279532953934,
  document:
   Ref(id=181388642114077184, collection=Ref(id=characters, collection=Ref(id=collections))),
  secret: 'fnECx5uE8OACAQLCZP7uQAIBF3rvpXoJEzfIrNXEL21PUpib9AE' }
client.query(
  q.login(
    q.ref(q.collection("characters"), "181388642114077184"),
    {"password": "abracadabra"}
  ))
{
  "ref": { "@ref": "tokens/181388643175236096" },
  "class": { "@ref": "tokens" },
  "ts": 1509244540264619,
  "document": { "@ref": "classes/characters/181388642114077184" },
  "secret": "fnEChGwCisACAAKEbAFuUAIAwIxOcffRgoJm7EgUt_zlmiPOze4"
}
client.query(
  Login(
    Ref(Collection("characters"), "181388642114077184"),
    Obj("password" -> "abracadabra")))
{
  "ref": { "@ref": "tokens/181388643175236096" },
  "class": { "@ref": "tokens" },
  "ts": 1509244540264619,
  "document": { "@ref": "classes/characters/181388642114077184" },
  "secret": "fnEChGwCisACAAKEbAFuUAIAwIxOcffRgoJm7EgUt_zlmiPOze4"
}

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!