Manage Event Exposure

The onboarding and credential management of Event Exposure services are available under the Certificates menu on the top of the ESC Portal.

The menu is only visible for those, who hold the required administrator roles.

Administrator roles

Credential management is only available for the users that have the corresponding vRA custom user role. The tenant manager can assign this role either directly to users or via Custom Groups that have this role.

This is an information message

Please Note

• Managing Health Exposure requires the Health Exposure Administrator role.
• Managing Log Exposure requires the Log Exposure Administrator role.

Managing the user roles is possible using the vRA Portal, which can be opened from the top right corner of the ESC Portal.

This is an information message

Please Note

• Users that have obtained a certificate can further authenticate to the Kafka topics until the certificate expires or is deleted, even if their user role has been revoked since.
• Users that are granted permission to the service can consume all events published in the Kafka topic for the entire tenant.

Onboarding/offboarding

Upon first opening the Certificates menu on the top of the ESC Portal, the onboarding to the service is done automatically.

Currently there is no self-service offboarding process defined. If this is required, please contact the ESC support.

Certificate management

User Certificate Creation

Access to the service is controlled using TLS certificates.

The certificates issued by the service are valid for 1 year and are signed by the Log Exposure Certificate Authority (CA), which in turn is signed by the Swisscom Datacenter CA.

New certificates can be created on the Certificates menu on the top of the ESC Portal by providing the following information:

Field	Mandatory	Description
Description	No	Free text description of the certificate
Email	Yes	The email to notify before certificate expiration
CSR	Yes	The user's certificate signing request
Consumer Group	Yes	The Kafka consumer group

Email:

The email is used by the service for certificate expiration notifications (see the Certificate Renewal section). Hence, it is recommended that this is a team mailbox or the email of a distribution list.

Certificate Signing Request(CSR):

The user must provide a certificate signing request (CSR) with the following constraints:

• Subject: must only contain the common name (CN) in the format: <prefix>-<tenant>-<your_free_text>. E.g. logs-orion-123-my-new-certificate where:
  • <prefix> is a service specific prefix
    • health for Health Exposure
    • logs for Log Exposure
  • <tenant> is your tenant name, e.g. orion-123
  • <your_free_text> is a free-text matching the following regular expression: [a-z0-9-]*[a-z0-9]. E.g. my-new-certificate
• Key Usage: if any is provided, the list must include TLS Web Client Authentication (clientAuth)

The examples below show how you can create a CSR simply using the openssl command:

# if you already have a private key saved in the private_key.pem file
openssl req -new -key private_key.pem -out csr.pem -subj "/CN=logs-orion-123-my-user-certificate"

# if you don't have a private key and you want to generate one in the private_key.pem
openssl req -newkey rsa:3072 -keyout private_key.pem -out csr.pem -subj "/CN=logs-orion-123-my-user-certificate"

While the ESC Portal will directly accept the plain text CSR, the API requires it as Base64-encoded text. To obtain this, run:

openssl base64 -A -in csr.pem

Consumer Group:

This field allows you to control the Kafka consumer topology.

• Using different consumer groups, the consumers would consume the same Kafka topic in parallel, each one receiving all the events.
• Having a shared consumer group shared between multiple certificates, the corresponding consumers will compete for the same events in a topic and each event will reach only one of the consumers.

Certificate Renewal

Starting 90 days before the expiration date (1 year after creation), an email notification will be sent weekly to the email address used during certificate creation.

An existing certificate cannot be renewed, instead a new one has to be created by following the instructions in the Certificate Creation section.

To stop the weekly expiration notification, delete the expiring certificate using the ESC Portal. If you can't see your existing certificate, please contact the ESC support to have this certificate removed and the notification stopped.