Enterprise Service Cloud - Docs

Credentials

Access to the service is controlled using TLS certificates.

The certificates issued by the service are valid for 1 year and are signed using a self-signed Certificate Authority (CA). This CA is different from the one used by the Kafka brokers.

Certificate Renewal

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

An existing certificate cannot be renewed, instead a new user with a unique common name 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 Portal. In case the expiring certificate is not visible, please contact the ESC support.

Certificate Creation

Upon visiting the Administration section of the Portal and selecting Event Exposure from the menu, a new certificate can be created by providing the following information:

FieldMandatoryDescription
DescriptionNoFree text description of the certificate
EmailYesThe email to notify before certificate expiration
CSRYesThe user's certificate signing request
Consumer GroupYesThe 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 CSR with the following constraints:

  • Subject: must only contain the common name (CN) in the format: <prefix>-<tenant>-<free_text>, e.g. logs-orion-123-my-new-certificate where:
    • <prefix> is a service specific prefix
      • logs for Log Exposure
      • health for Health Exposure
      • lifecycle for Lifecycle Exposure
    • <tenant> is your tenant name, e.g. orion-123
    • <free_text> must match the 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 a CSR can be created simply by using the openssl command:

# if a private key is already available 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 no private key is available, a new one will be saved to 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 Portal accepts the plain text CSR, the API requires it as Base64-encoded text. To obtain this, run:

openssl base64 -A -in csr.pem

Consumer Group

Free-form name ([a-zA-Z0-9._-] up to 255 characters). This field is only used to control the Kafka consumer topology.

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

REST API

This is an information message

Warning

The recommended way of managing certificates is using the web UI of the Portal. However, the API can be accessed directly to automate these processes.

Please do not do the onboarding via the API, let the Portal or ESC Support do it.

Endpoints

ServiceEndpoint
Log Exposurehttps://les-api.prd.msg.entcloud.swisscom.com/api/v1
Health Exposurehttps://hes-api.prd.msg.entcloud.swisscom.com/api/v1
Lifecycle Exposurehttps://lces-api.prd.msg.entcloud.swisscom.com/api/v1

An example URL used for requests is https://api.private.cloud.swisscom.ch/events/v1/logs/tenants/orion-123/instances.

Authentication is done by passing a bearer token with your request.

Last Updated: