Registering ZMS Service Identity
Once a domain has been registered in Athenz, the administrator will register service identities that are specified in domain roles and policy assertions. The latter can reference those roles having access to specified resources.
Before you can register the service identity, you'll need to generate keys. We'll cover how to create the keys and register the service identity next.
The registration process requires the domain administrator to generate a private/public RSA key pair (recommended to be at least 2048 bit) for the service. Athenz also supports EC keys.
The following are the keys and the services that use those keys:
- private key - The service agent uses the private key to generate a
ServiceTokenidentifying the service.
- public key - ZMS/ZTS then use the public key to validate the
ServiceTokengenerated by service agent.
openssl command-line utility is used to generate the key pair:
$ openssl genrsa -out service_private.pem 2048 $ openssl rsa -in service_private.pem -pubout > service_public.pem
The zms-cli client utility requires that the public key have an extension of .pem.
The private key file must be installed on all hosts where the client service will be running.
Each key pair has a key identifier that will be included in the
ServiceTokens (NToken) as the value of the
k component. If
the service’s private key has been compromised or the service has a policy
to periodically rotate the keys, the service administrator will generate
a new key pair, remove the public key with the old identifier, and
register a new public key with a different key identifier. Typically, a
service would start with "0" as its first identifier and increment when
If the service’s private key has been compromised or the service has a policy to periodically rotate the keys, the service administrator will generate a new key pair, remove the public key with identifier 0 and register a new public key with a different key identifier as shown below:
$ zms-cli -d <domain> delete-public-key <service> 0 $ zms-cli -d <domain> add-public-key <service> 1 new_service_public.pem
As mentioned above, the key identifier is included in generated Service
Tokens as the value of the
Service Identity Registration
To create a service identity object in ZMS with the generated public key:
$ zms-cli -d <domain> add-service <service> <key-id> <service_public.pem>
For example, to register the service "storage" in the domain
with the key identifier
0 and the public key stored in the file
run the following
$ zms-cli -d athenz add-service storage 0 ./storage_public.pem