If you are running Emo locally, using the provided binaries, the default admin API key is
Before EmoDB can manage API keys it needs to be configured with a pair of reserved API keys:
- Administrator: This API key has full admin access to EmoDB.
- Replication: This API key is used to authenticate internal databus replication calls made by EmoDB between data centers.
To configure EmoDB with these keys follow the following steps:
Update the EmoDB
config.yamlwith temporary values for these keys:
auth: adminApiKey: "dummy" replicationApiKey: "dummy"
Choose two keys. The keys can be any valid string with no white space. For this example we’ll choose pebbles and bambam for the administration and replication keys respectively.
(Optional) Secure the keys. Run the following DropWizard command. If the cluster will be different than the one in
config.yamlthen specify a
clusteroption like in the examples below:
$ java -jar emodb-web-x.x.jar encrypt-configuration-api-key config.yaml --api-key pebbles --cluster local_cluster RS9uq2Ukyj5WDijFLvWc/L2YYz6/MugvyAUfRknzhgJNyqe94IPU1wNpMF5WmXRrT1qEUDmVYoDE9Ku7NPmLGg $ java -jar emodb-web-x.x.jar encrypt-configuration-api-key config.yaml --api-key bambam --cluster local_cluster h6jqPR3/sMoY59wwUZaaJTWobLzqyqQhN0zPX69F7JE29flOaJj0kYBKZDH+mZJGP7M87ZUOcP7JVf8l+tMkmA
config.yamlwith the actual values:
auth: adminApiKey: "RS9uq2Ukyj5WDijFLvWc/L2YYz6/MugvyAUfRknzhgJNyqe94IPU1wNpMF5WmXRrT1qEUDmVYoDE9Ku7NPmLGg" replicationApiKey: "h6jqPR3/sMoY59wwUZaaJTWobLzqyqQhN0zPX69F7JE29flOaJj0kYBKZDH+mZJGP7M87ZUOcP7JVf8l+tMkmA"
At this point pebbles has administrative access to EmoDB. From this point onward either pebbles or other API keys with administrative access can manage API keys.
Optionally Securing the Keys in config.yaml
As noted above securing the admin and replication API keys in
config.yaml is optional; EmoDB would work just as well were
pebbles and bambam written in plaintext. The risk in storing these keys in plaintext is that anyone on the EmoDB instance
with access to the configuration file can read the admin API key and therefore have full administrative access. Additionally, you likely
will have a system in place for deploying EmoDB and that system will require
config.yaml or some other dependency to contain
the API keys, such as a file in a Puppet module or a deployment package stored in S3, and each one of these introduces a new vulnerability
for your admin API key.
Having said that, be aware that the cryptographic strength of the encrypted API keys is pretty weak. With the current implementation decrypting the keys can be done with only your configuration file and the source code for encrypting and decrypting the keys. Therefore, encrypting the keys should be considered only a base level encryption to prevent casual viewers and resource crawlers from reading the configuration file’s API keys. You should still treat the encrypted API keys with the same level of protection as you would with any other sensitive credential.
If you choose you can configure EmoDB to allow anonymous access. An anonymous user has the roles explicitly defined
config.yaml. The permissions associated with those roles can be configured using the User Access Control API.
To enable anonymous access set the following attribute with the anonymous role(s) in your
auth: anonymousRoles: - list_of_roles
Anonymous access enables the following behavior:
- A client can explicitly authenticate as an anonymous user using the reserved API key “anonymous”.
- All REST calls with no API key provided are automatically authenticated as anonymous.