Chapter 5. Securing Apicurio Registry deployments

Procedure

1. In the OpenShift web console, click Installed Operators and Red Hat Single Sign-On Operator, and then the Keycloak tab.

2. Click Create Keycloak to provision a new Red Hat Single Sign-On instance for securing a Apicurio Registry deployment. You can use the default value, for example:

   apiVersion: keycloak.org/v1alpha1
   kind: Keycloak
   metadata:
     name: example-keycloak
     labels:
       app: sso
   spec:
     instances: 1
     externalAccess:
       enabled: True
     podDisruptionBudget:
       enabled: True

3. Wait until the instance has been created, and click Networking and then Routes to access the new route for the keycloak instance.
4. Click the Location URL and copy the displayed URL value for later use when deploying Apicurio Registry.

5. Click Installed Operators and Red Hat Single Sign-On Operator, and click the Keycloak Realm tab, and then Create Keycloak Realm to create a registry example realm:

   apiVersion: keycloak.org/v1alpha1
   kind: KeycloakRealm
   metadata:
     name: registry-keycloakrealm
     labels:
       app: sso
   spec:
     instanceSelector:
       matchLabels:
         app: sso
     realm:
       displayName: Registry
       enabled: true
       id: registry
       realm: registry
       sslRequired: none
       roles:
         realm:
           - name: sr-admin
           - name: sr-developer
           - name: sr-readonly
       clients:
         - clientId: registry-client-ui
           implicitFlowEnabled: true
           redirectUris:
             - '*'
           standardFlowEnabled: true
           webOrigins:
             - '*'
           publicClient: true
         - clientId: registry-client-api
           implicitFlowEnabled: true
           redirectUris:
             - '*'
           standardFlowEnabled: true
           webOrigins:
             - '*'
           publicClient: true
       users:
         - credentials:
             - temporary: false
               type: password
               value: changeme
           enabled: true
           realmRoles:
             - sr-admin
           username: registry-admin
         - credentials:
             - temporary: false
               type: password
               value: changeme
           enabled: true
           realmRoles:
             - sr-developer
           username: registry-developer
         - credentials:
             - temporary: false
               type: password
               value: changeme
           enabled: true
           realmRoles:
             - sr-readonly
           username: registry-user

   Important

   You must customize this KeycloakRealm resource with values suitable for your environment if you are deploying to production. You can also create and manage realms using the Red Hat Single Sign-On web console.

6. If your cluster does not have a valid HTTPS certificate configured, you can create the following HTTP Service and Ingress resources as a temporary workaround:

   1. Click Networking and then Services, and click Create Service using the following example:

      apiVersion: v1
      kind: Service
      metadata:
        name: keycloak-http
        labels:
          app: keycloak
      spec:
        ports:
          - name: keycloak-http
            protocol: TCP
            port: 8080
            targetPort: 8080
        selector:
          app: keycloak
          component: keycloak
        type: ClusterIP
        sessionAffinity: None
      status:
        loadBalancer: {}

   2. Click Networking and then Ingresses, and click Create Ingress using the following example::

      apiVersion: networking.k8s.io/v1
      kind: Ingress
      metadata:
        name: keycloak-http
        labels:
          app: keycloak
      spec:
        rules:
          - host: KEYCLOAK_HTTP_HOST
            http:
              paths:
                - path: /
                  pathType: ImplementationSpecific
                  backend:
                    service:
                      name: keycloak-http
                      port:
                        number: 8080

      Modify the host value to create a route accessible for the Apicurio Registry user, and use it instead of the HTTPS route created by Red Hat Single Sign-On Operator.

7. Click the Apicurio Registry Operator, and on the ApicurioRegistry tab, click Create ApicurioRegistry, using the following example, but replace your values in the keycloak section.

   apiVersion: registry.apicur.io/v1
   kind: ApicurioRegistry
   metadata:
     name: example-apicurioregistry-kafkasql-keycloak
   spec:
     configuration:
       security:
         keycloak:
           url: "http://keycloak-http-<namespace>.apps.<cluster host>"
           # ^ Required
           # Use an HTTP URL in development.
           realm: "registry"
           # apiClientId: "registry-client-api"
           # ^ Optional (default value)
           # uiClientId: "registry-client-ui"
           # ^ Optional (default value)
       persistence: 'kafkasql'
       kafkasql:
         bootstrapServers: '<my-cluster>-kafka-bootstrap.<my-namespace>.svc:9092'

Procedure

1. In the Red Hat Single Sign-On Admin Console, create a Red Hat Single Sign-On realm for Apicurio Registry. By default, Apicurio Registry expects a realm name of registry. For details on creating realms, see the the Red Hat Single Sign-On user documentation.

2. Create a Red Hat Single Sign-On 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.

     Note

     If you are using Red Hat Single Sign-On service accounts, the client Access Type must be confidential instead of bearer-only.

3. Create a Red Hat Single Sign-On 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 Red Hat Single Sign-On:

   Table 5.2. Configuration for Apicurio Registry authentication with Red Hat Single Sign-On

   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 Red Hat Single Sign-On.	String	false
   KEYCLOAK_URL	The URL of the Red Hat Single Sign-On authentication server. For example, http://localhost:8080.	String	-
   KEYCLOAK_REALM	The Red Hat Single Sign-On 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

   Tip

   For an example of setting environment variables on OpenShift, see Section 6.1, “Configuring Apicurio Registry health checks on OpenShift”.

5. Set the following option to true to enable Apicurio Registry user roles in Red Hat Single Sign-On:

   Table 5.3. 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 Red Hat Single Sign-On realm:

   Table 5.4. 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 5.5. Configuration for owner-only authorization

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

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/

     Important

     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.6. 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 5.7. 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

   Note

   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.

Procedure

1. Generate a keystore with a self-signed certificate. You can skip this step if you are using your own certificates.

   openssl req -newkey rsa:2048 -new -nodes -x509 -days 3650 -keyout tls.key -out tls.crt

2. Create a new secret to hold the certificate and the private key.

   1. In the left navigation menu of the OpenShift web console, click Workloads > Secrets > Create Key/Value Secret.
   2. Use the following values:
      Name: https-cert-secret
      Key 1: tls.key
      Value 1: tls.key (uploaded file)
      Key 2: tls.crt
      Value 2: tls.crt (uploaded file)

   or create the secret using the following command:

   oc create secret generic https-cert-secret --from-file=tls.key --from-file=tls.crt

3. Edit the spec.configuration.security.https section of the ApicurioRegistry CR for your Apicurio Registry deployment, for example:

   apiVersion: registry.apicur.io/v1
   kind: ApicurioRegistry
   metadata:
     name: example-apicurioregistry
   spec:
     configuration:
       # ...
       security:
         https:
           secretName: https-cert-secret

4. Verify that the connection is working:

   1. Connect into a pod on the cluster using SSH (you can use the Apicurio Registry pod):

      oc rsh example-apicurioregistry-deployment-6f788db977-2wzpw

   2. Find the cluster IP of the Apicurio Registry pod from the Service resource (see the Location column in the web console). Afterwards, execute a test request (we are using self-signed certificate, so an insecure flag is required):

      curl -k https://172.30.230.78:8443/health

Procedure

1. Add a second Route in addition to the HTTP route created by the Apicurio Registry Operator. For example:

   kind: Route
   apiVersion: route.openshift.io/v1
   metadata:
     [...]
     labels:
       app: example-apicurioregistry
       [...]
   spec:
     host: example-apicurioregistry-default.apps.example.com
     to:
       kind: Service
       name: example-apicurioregistry-service-9whd7
       weight: 100
     port:
       targetPort: 8080
     tls:
       termination: edge
       insecureEdgeTerminationPolicy: Redirect
     wildcardPolicy: None

   Note

   Make sure the insecureEdgeTerminationPolicy: Redirect configuration property is set.

   If you do not specify a certificate, OpenShift will use a default. Alternatively, you can generate a custom self-signed certificate using the following commands:

   openssl genrsa 2048 > tls.key &&
   openssl req -new -x509 -nodes -sha256 -days 365 -key tls.key -out tls.crt

   Then create a route using the OpenShift CLI:

   oc create route edge \
     --service=example-apicurioregistry-service-9whd7 \
     --cert=tls.crt --key=tls.key \
     --hostname=example-apicurioregistry-default.apps.example.com \
     --insecure-policy=Redirect \
     -n default