Apicurio Studio

Configuring your Apicurio Registry deployment

Configuring Apicurio Registry authentication and authorization with Keycloak

This section explains how to manually configure authentication and authorization options for Apicurio Registry using Keycloak.

Alternatively, for details on how to configure these settings automatically, see the Apicurio Registry Operator documentation.

You can enable authentication for the Apicurio Registry web console and core REST API using Keycloak based on OAuth using OpenID Connect (OIDC). The same Keycloak realm and users are federated across the Apicurio Registry web console and core REST API using OpenID Connect so that you only require one set of credentials.

Apicurio Registry provides role-based authorization for default admin, write, and read-only user roles. Apicurio Registry also provides content-based authorization at the schema or API level, where only the creator of the registry artifact can update or delete it. Apicurio Registry authentication and authorization settings are disabled by default.

Prerequisites
Procedure
  1. In the Keycloak Admin Console, create a Keycloak realm for Apicurio Registry. By default, Apicurio Registry expects a realm name of registry. For more details on creating realms, see Getting Started with Keycloak.

  2. Create a Keycloak client for the Apicurio Registry API. By default, Apicurio Registry expects the following settings:

    • Client ID: registry-api

    • Client Protocol: openid-connect

    • Access Type: bearer-only

      You can use the defaults for the other client settings.

      If you are using Keycloak service accounts, the client Access Type must be confidential instead of bearer-only.
  3. Create a Keycloak client for the Apicurio Registry web console. By default, Apicurio Registry expects the following settings:

    • Client ID: apicurio-registry

    • Client Protocol: openid-connect

    • Access Type: public

    • Valid Redirect URLs: http://my-registry-url:8080/*

    • Web Origins: +

      You can use the defaults for the other client settings.

  4. In your Apicurio Registry deployment on OpenShift, set the following Apicurio Registry environment variables to configure authentication using Keycloak:

    Table 1. Configuration for Apicurio Registry authentication
    Environment variable Description Type Default

    AUTH_ENABLED

    If set to true, the environment variables that follow are required.

    String

    false

    KEYCLOAK_URL

    The URL of the Keycloak authentication server to use. Must end with /auth.

    String

    None

    KEYCLOAK_REALM

    The Keycloak realm used for authentication.

    String

    registry

    KEYCLOAK_API_CLIENT_ID

    The client ID for the Apicurio Registry REST API.

    String

    registry-api

    KEYCLOAK_UI_CLIENT_ID

    The client ID for the Apicurio Registry web console.

    String

    apicurio-registry

    For an example of setting environment variables on OpenShift, see Configuring Apicurio Registry health checks on OpenShift.
  5. Set the following option to true to enable Apicurio Registry user roles in Keycloak:

    Table 2. Configuration for Apicurio Registry user roles
    Environment variable Java system property Type Default value

    ROLES_ENABLED

    registry.auth.roles.enabled

    Boolean

    false

  6. When Apicurio Registry user roles are enabled, you must assign Apicurio Registry users to at least one of the following default user roles in your Keycloak realm:

    Table 3. Default user roles for registry authentication and authorization
    Role Read artifacts Write artifacts Global rules Summary

    sr-admin

    Yes

    Yes

    Yes

    Full access to all create, read, update, and delete operations.

    sr-developer

    Yes

    Yes

    No

    Access to create, read, update, and delete operations, except configuring global rules. This role can configure artifact rules.

    sr-readonly

    Yes

    No

    No

    Access to read and search operations only. This role cannot configure any rules.

  7. Set the following to true to enable owner-only authorization for updates to schema and API artifacts in Apicurio Registry:

    Table 4. Configuration for owner-only authorization
    Environment variable Java system property Type Default value

    REGISTRY_AUTH_OWNER_ONLY_AUTHORIZATION

    registry.auth.owner-only-authorization

    Boolean

    false

Additional resources

Configuring Apicurio Registry logging

You can set Apicurio Registry logging configuration at runtime. Apicurio Registry provides a REST endpoint to set the log level for specific loggers for finer grained logging. This section explains how to view and set Apicurio Registry log levels at runtime using the Apicurio Registry /admin REST API.

Prerequisites
  • Get the URL to access your Apicurio Registry instance, or get your Apicurio Registry route if you have Apicurio Registry deployed on OpenShift. This simple example uses a URL of localhost:8080.

Procedure
  1. Use this curl command to obtain the current log level for the logger io.apicurio.registry.storage:

    $ curl -i localhost:8080/apis/registry/v2/admin/loggers/io.apicurio.registry.storage
    HTTP/1.1 200 OK
    [...]
    Content-Type: application/json
    {"name":"io.apicurio.registry.storage","level":"INFO"}
  2. Use this curl command to change the log level for the logger io.apicurio.registry.storage to DEBUG:

    $ curl -X PUT -i -H "Content-Type: application/json" --data '{"level":"DEBUG"}' localhost:8080/apis/registry/v2/admin/loggers/io.apicurio.registry.storage
    HTTP/1.1 200 OK
    [...]
    Content-Type: application/json
    {"name":"io.apicurio.registry.storage","level":"DEBUG"}
  3. Use this curl command to revert the log level for the logger io.apicurio.registry.storage to its default value:

    $ curl -X DELETE -i localhost:8080/apis/registry/v2/admin/loggers/io.apicurio.registry.storage
    HTTP/1.1 200 OK
    [...]
    Content-Type: application/json
    {"name":"io.apicurio.registry.storage","level":"INFO"}

Configuring Apicurio Registry event sourcing

You can configure Apicurio Registry to send events when changes are made to the registry. For example, Apicurio Registry can trigger events when schema and API artifacts are created, updated, deleted, and so on. You can configure Apicurio Registry to send events to your applications and to third-party integrations in this way.

There are different protocols available for transporting the events. The currently implemented protocols are HTTP and Apache Kafka. However, regardless of the protocol, the events are sent using the CNCF CloudEvents specification.

All of the event types are defined in io.apicurio.registry.events.dto.RegistryEventType. For example, the event types include:

  • io.apicurio.registry.artifact-created

  • io.apicurio.registry.artifact-updated

  • io.apicurio.registry.artifact-rule-created

  • io.apicurio.registry.global-rule-created

You can configure cloud events in Apicurio Registry using Java system properties or equivalent environment variables.

Prerequisites
  • You must have an application that you want to send Apicurio Registry cloud events to. For example, this can be a custom application or a third-party application.

Configuring Apicurio Registry event sourcing using HTTP

The example in this section shows a custom application running at http://my-app-host:8888/events.

Procedure
  1. When using the HTTP protocol, set your Apicurio Registry configuration to send events to a your application as follows:

    • registry.events.sink.my-custom-consumer=http://my-app-host:8888/events

  2. If required, you can configure multiple event consumers as follows:

    • registry.events.sink.my-custom-consumer=http://my-app-host:8888/events

    • registry.events.sink.other-consumer=http://my-consumer.com/events

Configuring Apicurio Registry event sourcing using Apache Kafka

The example in this section shows a Kafka topic named my-registry-events running on my-kafka-host:9092.

Procedure
  1. When using the Kafka protocol, set your Kafka topic as follows:

    • registry.events.kafka.topic=my-registry-events

  2. You can set the configuration for the Kafka producer using the KAFKA_BOOTSTRAP_SERVERS environment variable:

    • KAFKA_BOOTSTRAP_SERVERS=my-kafka-host:9092

      Alternatively, you can set the properties for the kafka producer using the registry.events.kafka.config prefix, for example: registry.events.kafka.config.bootstrap.servers=my-kafka-host:9092

  3. If required, you can also set the Kafka topic partition to use to produce events:

    • registry.events.kafka.topic-partition=1

Additional resources

Configuring Apicurio Registry health checks on OpenShift

You can configure optional environment variables for liveness and readiness probes to monitor the health of the Apicurio Registry server on OpenShift:

  • Liveness probes test if the application can make progress. If the application cannot make progress, OpenShift automatically restarts the failing Pod.

  • Readiness probes test if the application is ready to process requests. If the application is not ready, it can become overwhelmed by requests, and OpenShift stops sending requests for the time that the probe fails. If other Pods are OK, they continue to receive requests.

The default values of the liveness and readiness environment variables are designed for most cases and should only be changed if required by your environment. Any changes to the defaults depend on your hardware, network, and amount of data stored. These values should be kept as low as possible to avoid unnecessary overhead.
Prerequisites
  • You must have an OpenShift cluster with cluster administrator access.

  • You must have already installed Apicurio Registry on OpenShift.

  • You must have already installed and configured your chosen Apicurio Registry storage in Strimzi or PostgreSQL.

Procedure
  1. In the OpenShift Container Platform web console, log in using an account with cluster administrator privileges.

  2. Click Installed Operators > Apicurio Registry.

  3. On the ApicurioRegistry tab, click the Operator custom resource for your deployment, for example, example-apicurioregistry.

  4. In the main overview page, find the Deployment Name section and the corresponding DeploymentConfig name for your Apicurio Registry deployment, for example, example-apicurioregistry.

  5. In the left navigation menu, click Workloads > Deployment Configs, and select your DeploymentConfig name.

  6. Click the Environment tab, and enter your environment variables in the Single values env section, for example:

    • NAME: LIVENESS_STATUS_RESET

    • VALUE: 350

  7. Click Save at the bottom.

    Alternatively, you can perform these steps using the OpenShift oc command. For more details, see the OpenShift CLI documentation.

Environment variables for Apicurio Registry health checks

This section describes the available environment variables for Apicurio Registry health checks on OpenShift. These include liveness and readiness probes to monitor the health of the Apicurio Registry server on OpenShift. For an example procedure, see Configuring Apicurio Registry health checks on OpenShift.

The following environment variables are provided for reference only. The default values are designed for most cases and should only be changed if required by your environment. Any changes to the defaults depend on your hardware, network, and amount of data stored. These values should be kept as low as possible to avoid unnecessary overhead.

Liveness environment variables

Table 5. Environment variables for Apicurio Registry liveness probes
Name Description Type Default

LIVENESS_ERROR_THRESHOLD

Number of liveness issues or errors that can occur before the liveness probe fails.

Integer

1

LIVENESS_COUNTER_RESET

Period in which the threshold number of errors must occur. For example, if this value is 60 and the threshold is 1, the check fails after two errors occur in 1 minute

Seconds

60

LIVENESS_STATUS_RESET

Number of seconds that must elapse without any more errors for the liveness probe to reset to OK status.

Seconds

300

LIVENESS_ERRORS_IGNORED

Comma-separated list of ignored liveness exceptions.

String

io.grpc.StatusRuntimeException,org.apache.kafka.streams.errors.InvalidStateStoreException

Because OpenShift automatically restarts a Pod that fails a liveness check, the liveness settings, unlike readiness settings, do not directly affect behavior of Apicurio Registry on OpenShift.

Readiness environment variables

Table 6. Environment variables for Apicurio Registry readiness probes
Name Description Type Default

READINESS_ERROR_THRESHOLD

Number of readiness issues or errors that can occur before the readiness probe fails.

Integer

1

READINESS_COUNTER_RESET

Period in which the threshold number of errors must occur. For example, if this value is 60 and the threshold is 1, the check fails after two errors occur in 1 minute.

Seconds

60

READINESS_STATUS_RESET

Number of seconds that must elapse without any more errors for the liveness probe to reset to OK status. In this case, this means how long the Pod stays not ready, until it returns to normal operation.

Seconds

300

READINESS_TIMEOUT

Readiness tracks the timeout of two operations:

  • How long it takes for storage requests to complete

  • How long it takes for HTTP REST API requests to return a response

If these operations take more time than the configured timeout, this is counted as a readiness issue or error. This value controls the timeouts for both operations.

Seconds

5