Many parameters within the API have an 'identity' field. For securing your application or game, this field is a JSON Web Token that is signed by either Adama or you. There is a weaker form of security using a special string prefixed by 'anonymous'; this allows developers to open up documents to the internet. Below is a table of the various forms of authentication supported by Adama.
|anonymous||an identity token of 'anonymous:$name' results in a principal of ($name, 'anonymous`).|
|adama||The platform has a global authentication mechanism for all adama developers. The principal is ($adamaUserId, 'adama'). The identity token is always secured by a ephemeral private key.|
|authority||In the spirt of allowing developers top bring their own authentication, an authority is a named and uploaded keystore with public keys. This allows you to secure your private key however you want. Click here for more information|
|document||A document is able to grant a web visitor a special principal that is tied to the document; this token is generated via a web response. Click here for more information|
An authority is a named keystore where public keys are stored in Adama.
Create an authority
You can create a keystore via the CLI tool.
java -jar ~/adama.jar authority create
This will return the name for your new keystore. For the remainder of this document, we will use
3LZXGH9PUOEH25GZYQ17IL7W713XLJ as the name.
Create the keystore
The tooling can create a keystore that contains an initial public key. The below command will create the keystore for the prior created authority.
java -jar adama.jar authority create-local \ --authority 3LZXGH9PUOEH25GZYQ17IL7W713XLJ \ --keystore my.keystore.json \ --private first.private.key.json
This will create two files within your working directory:
- my.keystore.json is a collection of public keys used by Adama to validate a private
- first.private.key.json is a private key used by your software to sign your users' id. This requires safe-keeping!
This keystore and private key were created entirely locally on your machine (for exceptional security), and now you upload only the keystore with:
Upload the keystore
With a keystore full of public keys, we can upload the keystore to Adama.
java -jar adama.jar authority set \ --authority 3LZXGH9PUOEH25GZYQ17IL7W713XLJ \ --keystore my.keystore.json
This will allow the users signed by that private key into Adama.
Sign an example identity
Consuming the private key will require some crypto libraries in some infrastructure that you manage, but we can get started by using the Adama tooling to create an identity today!
java -jar adama.jar authority sign \ --key first.private.key.json \ --agent user001
This will create a principal with agent
user001 and authority of
Adding another public key
Similar to create-local which initializes a keystore, we can generate and append a new public key and side-channel write the private key.
java -jar adama.jar authority append-local \ --authority 3LZXGH9PUOEH25GZYQ17IL7W713XLJ \ --keystore my.keystore.json --private second.private.key.json