Skip to content

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.

Key Generation


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 ServiceToken identifying the service.
  • public key - ZMS/ZTS then use the public key to validate the ServiceToken generated by service agent.

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

Private Keys


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 generated 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 required.

Key Rotation


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 k component.

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 athenz with the key identifier 0 and the public key stored in the file storage_public.pem, run the following zms-cli command:

$ zms-cli -d athenz add-service storage 0 ./storage_public.pem