VESauth Client
VESauth can be used in conjunction with other uses of VES API, or as a standalone authentication service.
VESauth Client is a user agent that performs authentication on the behalf of a VES user.
The client can use
libVES.js or any other means of accessing the VES API.
Session-based VESauth
Create an instance of libVES.Auth from an unlocked instance of libVES. The associated VESauth token
pertains to the App Vault unlocked in the libVES instance.
VESauth = new libVES.Auth({VES: VES});
VES = new libVES({domain: "demo"});
VES.delegate().then(function() {
VESauth = new libVES.Auth({VES: VES});
});
Item-based VESauth
Create an instance of libVES.Auth from a Vault Item. The associated VESauth token
proves that the user has access to the Vault Item, and can only be used for low-security
access verification.
VESauth = new libVES.Auth({vaultItem: vaultItem});
vaultItem
libVES.VaultItem
An instance of Vault Item. The associated instance of libVES must be unlocked and must
have access to the item.
VES = new libVES({domain: "demo"});
VES.delegate().then(function() {
VESauth = new libVES.Auth({vaultItem: new libVES.VaultItem({domain: "demo", externalId: "myItem1"}, VES)});
});
getToken()
Get a VESauth token for a libVES.Auth instance. The token is to be securely passed to the Server to authenticate the Client.
Promise(String)
The VESauth token.
new libVES({domain: 'myDomain'}).delegate().then(function(VES) {
new libVES.Auth({VES: VES}).getToken().then(function(token) {
document.cookie = 'VESauth=' + token;
});
}).catch(function(error) {
window.alert(error);
});
getJSON(url)
Retrieve JSON content from a specified url. The request is authenticated with VESauth token,
generated for the libVES.Auth instance. The token is passed as an X-VES-Authorization: http header.
url
String
A url to retrieve JSON content from. The url may be appended with #path,
where path identifies a JSON sub-element in a filesystem style notation,
joined with "/"
Promise(object)
A parsed JSON object.
libVES.Error
libVES.Auth token generation failed, request failed, invalid response
new libVES({domain: 'myDomain'}).delegate().then(function(VES) {
new libVES.Auth({VES: VES}).getJSON('https://my.vesmail.email/ves.json#/apps/1/links/0').then(function(obj) {
console.log(obj);
});
}).catch(function(error) {
window.alert(error);
});
VESauth Server
VESauth Server can validate a VESauth token generated by a Client.
The server can use libVES.js through Node or browser, libVES.c,
or communicate with the VES REST API directly.
App Vault Authentication
Authenticate a user using a Session VESauth token.
// libVES.js
new libVES.Auth({domain: domain}).auth(token);
domain
String
VES domain specific to the authentication app.
token
String
A VESauth token generated by the Client.
// REST HTTP
// Example token = "vaultKey.123456.j9Ml0SIcr/MV4mK8J5ojTH4+PSzIoJn2OaOucSHkod63"
GET https://api.ves.host/v1/vaultKeys/123456?fields=externals,user(email) HTTP/1.0
Authorization: Bearer j9Ml0SIcr/MV4mK8J5ojTH4+PSzIoJn2OaOucSHkod63
// Response body:
{
"result": {
"id": 123456,
"externals": [
{
"domain": "myDomain",
"externalId": "user@acme.com"
}
],
"user": {
"id": 345678,
"email": "user@acme.com"
}
}
}
// Verify that "externals[0].domain" matches the expected VES domain
// Verify that "externals[0].externalId" is formatted as a valid email address
Access List Authentication
Authenticate a user against an Access List using a Session VESauth token.
// libVES.js
new libVES.Auth({vaultItem: acl}).auth(token);
acl
libVES.VaultItem
The access list Vault Item. Only the App Vaults the item is shared with will pass the authentication.
token
String
A VESauth token generated by the Client.
libVES.Error
Invalid token, bad parameters, network error, not on the access list
// REST HTTP
// Example token = "vaultKey.123456.j9Ml0SIcr/MV4mK8J5ojTH4+PSzIoJn2OaOucSHkod63"
// The Access List Vault Item ID can be retrieved using libVES when configuring the server
GET https://api.ves.host/v1/vaultItems/987654?fields=vaultEntries(vaultKey(externals)) HTTP/1.0
Authorization: Bearer j9Ml0SIcr/MV4mK8J5ojTH4+PSzIoJn2OaOucSHkod63
// Response body:
{
"result": {
"id": 987654,
"vaultEntries": [
{
"vaultKey": {
"id": 121212
}
},
{
"vaultKey": {
"id": 123456
"externals": [
{
"domain": "myDomain",
"externalId": "user@acme.com"
}
]
}
}
]
}
}
// Verify that for one of vaultEntries, vaultKey.id matches the id in the token
// Verify that for the matching vaultKey, externals[0].externalId id formatted as a valid email address
Access Verification
Verify that the Client that generated the VESauth Verify Token has access to a specific Vault Item.
The Verify Token does not expire unless the Vault Item content is updated.
Access Verification is a low security option, it cannot be used in place of Authentication,
neither does it return the identity of the VES user on whose behalf the token was created.
// libVES.js
new libVES.Auth({}).verify(token);
token
String
A VESauth token generated by the Client.
Promise(libVES.User)
The owner of the Vault Item (NOT necessarily the user who created the token).
libVES.Error
Invalid token, bad parameters, network error, item is not available
// REST HTTP
// Example token = "vaultItem.987654.~451QoNrvAbpjuGwZSOKkX4rW"
// The Access List Vault Item ID can be retrieved using libVES when configuring the server
GET https://api.ves.host/v1/vaultItems/987654?fields=file(creator) HTTP/1.0
Authorization: Bearer ~451QoNrvAbpjuGwZSOKkX4rW
// Response body:
{
"result": {
"id": 987654,
"file": {
"creator": {
"email": "user@acme.com"
}
}
}
}
// Verify that file.creator.email exists
