proc-configuring-registry-security-keycloak.adoc

Configuring {registry} authentication and authorization with {keycloak}

This section explains how to manually configure authentication and authorization options for {registry} and {keycloak}.

Note	Alternatively, for details on how to configure these settings automatically,

The {registry} web console and core REST API support authentication in {keycloak} based on OAuth and OpenID Connect (OIDC). The same {keycloak} realm and users are federated across the {registry} web console and core REST API using OpenID Connect so that you only require one set of credentials.

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

Prerequisites

• {keycloak} is installed and running. For more details, see the

• {registry} is installed and running.

Procedure

1. In the {keycloak} Admin Console, create a {keycloak} realm for {registry}. By default, {registry} expects a realm name of registry. For details on creating realms, see the

2. Create a {keycloak} client for the {registry} API. By default, {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.

     Note	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 {registry} web console. By default, {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 {registry} deployment on OpenShift, set the following {registry} environment variables to configure authentication using {keycloak}:

   Table 1. Configuration for {registry} authentication with {keycloak}

   Environment variable	Description	Type	Default
   AUTH_ENABLED	Enables authentication for {registry}. When set to true, the environment variables that follow are required for authentication using {keycloak}.	String	false
   KEYCLOAK_URL	The URL of the {keycloak} authentication server. For example, http://localhost:8080.	String	-
   KEYCLOAK_REALM	The {keycloak} realm for authentication. For example, registry.	String	-
   KEYCLOAK_API_CLIENT_ID	The client ID for the {registry} REST API.	String	registry-api
   KEYCLOAK_UI_CLIENT_ID	The client ID for the {registry} web console.	String	apicurio-registry

   Tip	For an example of setting environment variables on OpenShift, see [configuring-liveness-readiness-probes_{context}].

5. Set the following option to true to enable {registry} user roles in {keycloak}:

   Table 2. Configuration for {registry} role-based authorization

   Environment variable	Java system property	Type	Default value
   ROLE_BASED_AUTHZ_ENABLED	registry.auth.role-based-authorization	Boolean	false

6. When {registry} user roles are enabled, you must assign {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-specific 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 {registry}:

   Table 4. Configuration for owner-only authorization

   Environment variable	Java system property	Type	Default value
   REGISTRY_AUTH_OBAC_ENABLED	registry.auth.owner-only-authorization	Boolean	false

Additional resources

• For details on configuring non-default user role names, see [registry-security-settings_{context}].

• For an open source example application and Keycloak realm, see Docker Compose example of Apicurio Registry with Keycloak.

• For details on how to use {keycloak} in a production environment, see