Configuring Apicurio Registry security options

This chapter explains how to set configuration options for Apicurio Registry security. For example, this includes authentication in Keycloak or Microsoft Azure Active Directory and role-based authorization in Apicurio Registry.

For a list of all available configuration options, see Apicurio Registry configuration reference.

Configuring Apicurio Registry authentication and authorization with Keycloak

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

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

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

  • Keycloak is installed and running. For more details, see the Keycloak user documentation.

  • Apicurio Registry is installed and running.

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 details on creating realms, see the Keycloak user documentation.

  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 with Keycloak
    Environment variable Description Type Default

    AUTH_ENABLED

    Enables authentication for Apicurio 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 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-liveness-readiness-probes_registry].

  5. Set the following option to true to enable Apicurio Registry user roles in Keycloak:

    Table 2. Configuration for Apicurio 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 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-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 Apicurio 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

Configuring Apicurio Registry authentication and authorization with Microsoft Azure Active Directory

This section explains how to manually configure authentication and authorization options for Apicurio Registry and Microsoft Azure Active Directory (Azure AD).

The Apicurio Registry web console and core REST API support authentication in Azure AD based on OpenID Connect (OIDC) and the OAuth Authorization Code Flow. Apicurio Registry provides role-based authorization for default admin, write, and read-only user roles. Apicurio Registry authentication and authorization settings are disabled by default.

To secure Apicurio Registry with Azure AD, you require a valid directory in Azure AD with specific configuration. This involves registering the Apicurio Registry application in the Azure AD portal with recommended settings and configuring environment variables in Apicurio Registry.

Prerequisites
Procedure

  1. Log in to the Azure AD portal using your email address or GitHub account.

  2. In the navigation menu, select Manage > App registrations > New registration, and complete the following settings:

    • Name: Enter your application name. For example: apicurio-registry-example

    • Supported account types: Click Accounts in any organizational directory.

    • Redirect URI: Select Single-page application from the list, and enter your Apicurio Registry web console application host. For example: https://test-registry.com/ui/

      You must register your Apicurio Registry application host as a Redirect URI. When logging in, users are redirected from Apicurio Registry to Azure AD for authentication, and you want to send them back to your application afterwards. Azure AD does not allow any redirect URLs that are not registered.

  3. Click Register. You can view your app registration details by selecting Manage > App registrations > apicurio-registry-example.

  4. Select Manage > Authentication and ensure that the application is configured with your redirect URLs and tokens as follows:

    • Redirect URIs: For example: https://test-registry.com/ui/

    • Implicit grant and hybrid flows: Click ID tokens (used for implicit and hybrid flows)

  5. Select Azure AD > Admin > App registrations > Your app > Application (client) ID. For example: 123456a7-b8c9-012d-e3f4-5fg67h8i901

  6. Select Azure AD > Admin > App registrations > Your app > Directory (tenant) ID. For example: https://login.microsoftonline.com/1a2bc34d-567e-89f1-g0hi-1j2kl3m4no56/v2.0

  7. In Apicurio Registry, configure the following environment variables with your Azure AD settings:

    Table 5. Configuration for Azure AD settings in Apicurio Registry
    Environment variable Description Setting

    KEYCLOAK_API_CLIENT_ID

    The client application ID for the Apicurio Registry REST API

    Your Azure AD Application (client) ID obtained in step 5. For example: 123456a7-b8c9-012d-e3f4-5fg67h8i901

    REGISTRY_OIDC_UI_CLIENT_ID

    The client application ID for the Apicurio Registry web console.

    Your Azure AD Application (client) ID obtained in step 5. For example: 123456a7-b8c9-012d-e3f4-5fg67h8i901

    REGISTRY_AUTH_URL_CONFIGURED

    The URL for authentication in Azure AD.

    Your Azure AD Application (tenant) ID obtained in step 6. For example: https://login.microsoftonline.com/1a2bc34d-567e-89f1-g0hi-1j2kl3m4no56/v2.0.

  8. In Apicurio Registry, configure the following environment variables for Apicurio Registry-specific settings:

    Table 6. Configuration for Apicurio Registry-specific settings
    Environment variable Description Setting

    REGISTRY_AUTH_ENABLED

    Enables authentication for Apicurio Registry.

    true

    REGISTRY_UI_AUTH_TYPE

    The Apicurio Registry authentication type.

    oidc

    CORS_ALLOWED_ORIGINS

    The host for your Apicurio Registry deployment for cross-origin resource sharing (CORS).

    For example: https://test-registry.com

    REGISTRY_OIDC_UI_REDIRECT_URL

    The host for your Apicurio Registry web console.

    For example: https://test-registry.com/ui

    ROLE_BASED_AUTHZ_ENABLED

    Enables role-based authorization in Apicurio Registry.

    true

    QUARKUS_OIDC_ROLES_ROLE_CLAIM_PATH

    The name of the claim in which Azure AD stores roles.

    roles
    When you enable roles in Apicurio Registry, you must also create the same roles in Azure AD as application roles. The default roles expected by Apicurio Registry are sr-admin, sr-developer, and sr-readonly.
Additional resources

Apicurio Registry authentication and authorization configuration options

Apicurio Registry provides authentication options for OpenID Connect with Keycloak and HTTP basic authentication.

Apicurio Registry provides authorization options for role-based and content-based approaches:

  • Role-based authorization for default admin, write, and read-only user roles.

  • Content-based authorization for schema or API artifacts, where only the owner of the artifacts or artifact group can update or delete artifacts.

All authentication and authorization options in Apicurio Registry are disabled by default. Before enabling any of these options, you must first set the AUTH_ENABLED option to true.

This chapter provides details on the following configuration options:

Apicurio Registry authentication by using OpenID Connect with Keycloak

You can set the following environment variables to configure authentication for the Apicurio Registry web console and API with Keycloak:

Table 7. Configuration for Apicurio Registry authentication with Keycloak
Environment variable Description Type Default

AUTH_ENABLED

Enables authentication for Apicurio 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 Apicurio Registry REST API.

String

registry-api

KEYCLOAK_UI_CLIENT_ID

The client ID for the Apicurio Registry web console.

String

apicurio-registry

Apicurio Registry authentication by using HTTP basic

By default, Apicurio Registry supports authentication by using OpenID Connect. Users or API clients must obtain an access token to make authenticated calls to the Apicurio Registry REST API. However, because some tools do not support OpenID Connect, you can also configure Apicurio Registry to support HTTP basic authentication by setting the following configuration options to true:

Table 8. Configuration for Apicurio Registry HTTP basic authentication
Environment variable Java system property Type Default value

AUTH_ENABLED

registry.auth.enabled

Boolean

false

CLIENT_CREDENTIALS_BASIC_AUTH_ENABLED

registry.auth.basic-auth-client-credentials.enabled

Boolean

false

Apicurio Registry HTTP basic client credentials cache expiry

You can also configure the HTTP basic client credentials cache expiry time. By default, when using HTTP basic authentication, Apicurio Registry caches JWT tokens, and does not issue a new token when there is no need. You can configure the cache expiry time for JWT tokens, which is set to 10 mins by default.

When using Keycloak, it is best to set this configuration to your Keycloak JWT expiry time minus one minute. For example, if you have the expiry time set to 5 mins in Keycloak, you should set the following configuration option to 4 mins:

Table 9. Configuration for HTTP basic client credentials cache expiry
Environment variable Java system property Type Default value

CLIENT_CREDENTIALS_BASIC_CACHE_EXPIRATION

registry.auth.basic-auth-client-credentials.cache-expiration

Integer

10

Apicurio Registry role-based authorization

You can set the following options to true to enable role-based authorization in Apicurio Registry:

Table 10. Configuration for Apicurio Registry role-based authorization
Environment variable Java system property Type Default value

AUTH_ENABLED

registry.auth.enabled

Boolean

false

ROLE_BASED_AUTHZ_ENABLED

registry.auth.role-based-authorization

Boolean

false

You can then configure role-based authorization to use roles included in the user’s authentication token (for example, granted when authenticating by using Keycloak), or to use role mappings managed internally by Apicurio Registry.

Use roles assigned in Keycloak

To enable using roles assigned by Keycloak, set the following environment variables:

Table 11. Configuration for Apicurio Registry role-based authorization by using Keycloak
Environment variable Description Type Default

ROLE_BASED_AUTHZ_SOURCE

When set to token, user roles are taken from the authentication token.

String

token

REGISTRY_AUTH_ROLES_ADMIN

The name of the role that indicates a user is an admin.

String

sr-admin

REGISTRY_AUTH_ROLES_DEVELOPER

The name of the role that indicates a user is a developer.

String

sr-developer

REGISTRY_AUTH_ROLES_READONLY

The name of the role that indicates a user has read-only access.

String

sr-readonly

When Apicurio Registry is configured to use roles from Keycloak, you must assign Apicurio Registry users to at least one of the following user roles in Keycloak. However, you can configure different user role names by using the environment variables in Configuration for Apicurio Registry role-based authorization by using Keycloak.

Table 12. Apicurio Registry roles for authentication and authorization
Role name Read artifacts Write artifacts Global rules Description

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 and import/export. This role can configure artifact-specific rules only.

sr-readonly

Yes

No

No

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

Manage roles directly in Apicurio Registry

To enable using roles managed internally by Apicurio Registry, set the following environment variable:

Table 13. Configuration for Apicurio Registry role-based authorization by using internal role mappings
Environment variable Description Type Default

ROLE_BASED_AUTHZ_SOURCE

When set to application, user roles are managed internally by Apicurio Registry.

String

token

When using internally managed role mappings, users can be assigned a role by using the /admin/roleMappings endpoint in the Apicurio Registry REST API. For more details, see Apicurio Registry REST API documentation.

Users can be granted exactly one role: ADMIN, DEVELOPER, or READ_ONLY. Only users with admin privileges can grant access to other users.

Apicurio Registry admin-override configuration

Because there are no default admin users in Apicurio Registry, it is usually helpful to configure another way for users to be identified as admins. You can configure this admin-override feature by using the following environment variables:

Table 14. Configuration for Apicurio Registry admin-override
Environment variable Description Type Default

REGISTRY_AUTH_ADMIN_OVERRIDE_ENABLED

Enables the admin-override feature.

String

false

REGISTRY_AUTH_ADMIN_OVERRIDE_FROM

Where to look for admin-override information. Only token is currently supported.

String

token

REGISTRY_AUTH_ADMIN_OVERRIDE_TYPE

The type of information used to determine if a user is an admin. Values depend on the value of the FROM variable, for example, role or claim when FROM is token.

String

role

REGISTRY_AUTH_ADMIN_OVERRIDE_ROLE

The name of the role that indicates a user is an admin.

String

sr-admin

REGISTRY_AUTH_ADMIN_OVERRIDE_CLAIM

The name of a JWT token claim to use for determining admin-override.

String

org-admin

REGISTRY_AUTH_ADMIN_OVERRIDE_CLAIM_VALUE

The value that the JWT token claim indicated by the CLAIM variable must be for the user to be granted admin-override.

String

true

For example, you can use this admin-override feature to assign the sr-admin role to a single user in Keycloak, which grants that user the admin role. That user can then use the /admin/roleMappings REST API (or associated UI) to grant roles to additional users (including additional admins).

Apicurio Registry owner-only authorization

You can set the following options to true to enable owner-only authorization for updates to artifacts or artifact groups in Apicurio Registry:

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

AUTH_ENABLED

registry.auth.enabled

Boolean

false

REGISTRY_AUTH_OBAC_ENABLED

registry.auth.owner-only-authorization

Boolean

false

REGISTRY_AUTH_OBAC_LIMIT_GROUP_ACCESS

registry.auth.owner-only-authorization.limit-group-access

Boolean

false

When owner-only authorization is enabled, only the user who created an artifact can modify or delete that artifact.

When owner-only authorization and group owner-only authorization are both enabled, only the user who created an artifact group has write access to that artifact group, for example, to add or remove artifacts in that group.

Apicurio Registry authenticated read access

When the authenticated read access option is enabled, Apicurio Registry grants at least read-only access to requests from any authenticated user in the same organization, regardless of their user role.

To enable authenticated read access, you must first enable role-based authorization, and then ensure that the following options are set to true:

Table 16. Configuration for authenticated read access
Environment variable Java system property Type Default value

AUTH_ENABLED

registry.auth.enabled

Boolean

false

REGISTRY_AUTH_AUTHENTICATED_READS_ENABLED

registry.auth.authenticated-read-access.enabled

Boolean

false

For more details, see Apicurio Registry role-based authorization.

Apicurio Registry anonymous read-only access

In addition to the two main types of authorization (role-based and owner-based authorization), Apicurio Registry supports an anonymous read-only access option.

To allow anonymous users, such as REST API calls with no authentication credentials, to make read-only calls to the REST API, set the following options to true:

Table 17. Configuration for anonymous read-only access
Environment variable Java system property Type Default value

AUTH_ENABLED

registry.auth.enabled

Boolean

false

REGISTRY_AUTH_ANONYMOUS_READ_ACCESS_ENABLED

registry.auth.anonymous-read-access.enabled

Boolean

false
Additional resources