Setting up basicAuth with K8s Operator

[rubfcsilva]

Hey.
I'm having some issues deploying Apicurio schema registry with basic authentication enabled.

My manifest file looked like this initially (this is just the auth section)

spec:
  app:
    auth:
      basicAuth:
        cacheExpiration: 2h
        enabled: true
      enabled: true

This would raise the following error:

status:
  conditions:
    - lastTransitionTime: '2025-08-04T13:47:24Z'
      lastUpdateTime: '2025-08-05T12:02:05Z'
      message: >-
        Encountered 1 operator error(s):

        - NullPointerException: Cannot invoke
        "io.apicurio.registry.operator.api.v1.spec.auth.AuthTLSSpec.getTlsVerificationType()"
        because the return value of
        "io.apicurio.registry.operator.api.v1.spec.auth.AuthSpec.getTls()" is
        null
      reason: NullPointerException
      status: 'True'
      type: OperatorError

I then went ahead and created sort of a mock TLS config (even tho it seems like it is only required for OAuth authentication), and my config looked like this:

spec:
  app:
    auth:
      basicAuth:
        cacheExpiration: 2h
        enabled: true
      enabled: true
      tls:
        tlsVerificationType: NONE

The error would disappear, but instead of basic authentication, on the UI, I would get a Keycloak error.

The URL on browser looks something like

https://auth.apicur.io/auth/realms/apicurio-local/protocol/openid-connect/auth?client_id=default_client&redirect_uri ...

Is there any step or point I'm missing? I understand that using Keycloak is the recommended approach, but I would like to test the basic authentication method too.
Thanks

[EricWittmann]

Ah ok so there is a misconception about what that feature does! BASIC authentication is supported on the API only, not for the UI. When authentication is enabled, the UI will always use OAuth2/OIDC. But additionally you can enable BASIC auth which will allow you to use BASIC when making direct API calls to the backend. But the UI will always use OIDC (and thus Bearer Token auth when making backend calls).

There is no way to configure Registry so that the UI does some sort of basic, form based login.

For authentication in Registry to work at all, you will need to install an OIDC server like Keycloak (although any OIDC compliant solution should work).

[EricWittmann]

Here are some links to concrete examples or docs. Obviously I don't have anything for Dex, so I can't help on that specifically.

• Docker Compose - Registry + Keycloak (RBAC)
• OpenShift Deployment - Registry

And here is a configuration when using the Apicurio Registry v3 Operator with auth enabled:

apiVersion: registry.apicur.io/v1
kind: ApicurioRegistry3
metadata:
  name: $APPLICATION_NAME
spec:
  app:
    ingress:
      enabled: false
    auth:
      enabled: true
      appClientId: registry-client-api
      uiClientId: registry-client-ui
      authServerUrl: https://$KEYCLOAK_INGRESS_URL/realms/registry
      redirectUri: http://$UI_INGRESS_URL
      logoutUrl: http://$UI_INGRESS_URL
      basicAuth:
        enabled: true
        cacheExpiration: 25m
      tls:
        tlsVerificationType: none
      authz:
        enabled: true
        ownerOnlyEnabled: true
        adminOverride:
          enabled: true
    features:
      resourceDeleteEnabled: true
  ui:
    ingress:
      enabled: false
    env:
      - name: REGISTRY_API_URL
        value: https://$APP_INGRESS_URL/apis/registry/v3
---
apiVersion: route.openshift.io/v1
kind: Route
metadata:
  name: apicurio-registry-app
  annotations:
    kubernetes.io/tls-acme: "true"
  labels:
    app: $APPLICATION_NAME
spec:
  host: $APP_INGRESS_URL
  to:
    kind: Service
    name: registry-app-service
    weight: 100
  wildcardPolicy: None
  tls:
    termination: edge
    insecureEdgeTerminationPolicy: Redirect
---
apiVersion: route.openshift.io/v1
kind: Route
metadata:
  name: apicurio-registry-ui
  annotations:
    kubernetes.io/tls-acme: "true"
  labels:
    app: $APPLICATION_NAME
spec:
  host: $UI_INGRESS_URL
  to:
    kind: Service
    name: registry-ui-service
    weight: 100
  wildcardPolicy: None
  tls:
    termination: edge
    insecureEdgeTerminationPolicy: Redirect

I found a blog post about using Azure Entra ID but it's for Registry 2.4 so it might be more confusing than revealing. But if you disagree you can find it on the apicurio blog.

[EricWittmann]

Note: the operator example assumes Keycloak is already installed and running. But you get the idea hopefully. It also disables ingress and instead configures edge terminated SSL routes.

[EricWittmann]

Oh also - BASIC auth is supported by the REST API (if the feature is enabled, see the operator CR example). But we don't recommend it unless it's absolutely necessary. Some client tools ONLY support BASIC auth, so that's fine. But if your client can use OAuth that is preferred for performance reasons.

[rubfcsilva]

Hey @EricWittmann, long time no talk. :) Thanks to your reply, I was able to use Dex as the OIDC provider. However, I was not able to configure basic auth and OIDC at the same time. As per your reply it is possible to have human users login with OIDC and have API authentication with Basic Auth, right?

My config at the moment looks like this:

 auth:
    enabled: true
    anonymousReadsEnabled: false
    basicAuth:
      enabled: true
      cacheExpiration: 25m
    authz:
      enabled: true
      readAccessEnabled: true
      roles:
        admin: Viator-Data-Ops
    authServerUrl: https://dex.my-host.com
    redirectUri: https://apicurio-registry.my-host.com
    logoutUrl: https://apicurio-registry.my-host.com
    appClientId: apicurio-registry-api
    uiClientId: apicurio-registry
  env:
  - name: QUARKUS_LOG_LEVEL
    value: DEBUG
  - name: REGISTRY_LOG_LEVEL
    value: DEBUG
  - name: QUARKUS_PROFILE
    value: prod
  - name: QUARKUS_OIDC_ROLES_ROLE-CLAIM-PATH
    value: groups
  - name: QUARKUS_OIDC_TOKEN_PRINCIPAL-CLAIM
    value: name
  - name: APICURIO_AUTHN_OIDC_USERNAME-CLAIM
    value: name
  - name: APICURIO_UI_AUTH_OIDC_SCOPE
    value: openid profile email groups

I noticed that the predefined users only became available if set the environment variables

  - name: QUARKUS_SECURITY_USERS_EMBEDDED_PLAIN_TEXT
    value: "true"
  - name: QUARKUS_SECURITY_USERS_EMBEDDED_USERS_admin
    value: admin
  - name: QUARKUS_SECURITY_USERS_EMBEDDED_USERS_developer
    value: developer
  - name: QUARKUS_SECURITY_USERS_EMBEDDED_USERS_readonly
    value: readonly
  - name: QUARKUS_SECURITY_USERS_EMBEDDED_ROLES_admin
    value: sr-admin
  - name: QUARKUS_SECURITY_USERS_EMBEDDED_ROLES_developer
    value: sr-developer
  - name: QUARKUS_SECURITY_USERS_EMBEDDED_ROLES_readonly
    value: sr-readonly

I've run into an authentication conflict. When I apply these settings, Basic authentication works correctly, but it breaks the UI login that uses OIDC.

I'm trying to solve this through trial and error, but I don't fully understand the root cause of the issue. Based on my configuration, can you see anything that is obviously incorrect? Any insight you could provide would be greatly appreciated.

Note that I added some of Quarkus env variables because Apicurio was not using the groups claim as the claim to check if a user is an Admin, and also was using the sub claim as the username on the UI.

[EricWittmann]

Nice job getting Apicurio Registry working with Dex! But man are you swimming in uncharted waters now. :) I'll try to help though.

We have two BASIC auth features:

1. BASIC auth via server-side client credentials flow
2. BASIC auth via Quarkus plain text config

I know that (1) can be used concurrent with standard OIDC auth, as discussed. So I think you should be using this. I also know that (2) is not secure, is not for production, and should only be used for testing. I also believe that it is not compatible with OIDC - so I don't think you can use both of them at the same time (I could be wrong on this point).

So I think you want to ditch the QUARKUS_SECURITY_USERS_EMBEDDED_PLAIN_TEXT related stuff.

Now the tricky part about using BASIC authentication from (1), is that I'm not sure you can use the same users as you would use in the UI. I'm a little fuzzy on this area of the application. However, what I know is that it works by creating an OAuth client on the server and having that OAuth client authenticate to the configured OIDC server using the client credentials flow.

Researching how this works now - so the rest of this reply will be streamed based on what I discover. :) Apologies for the resulting ordering of the info.

You enable (1) by setting this property:

apicurio.authn.basic-client-credentials.enabled=true

If that property is enabled, and if the incoming REST request contains BASIC auth credentials, then this method will be called:

https://github.com/Apicurio/apicurio-registry/blob/main/app/src/main/java/io/apicurio/registry/auth/AppAuthenticationMechanism.java#L294-L308

That method does some caching of the auth (failure or successful token) but ultimately calls this method to perform the auth:

https://github.com/Apicurio/apicurio-registry/blob/main/app/src/main/java/io/apicurio/registry/auth/AppAuthenticationMechanism.java#L321-L338

That method create an OidcAuth object and delegates to it. Eventually this method is called:

https://github.com/Apicurio/apicurio-common-rest-client/blob/main/rest-client-common/src/main/java/io/apicurio/rest/client/auth/OidcAuth.java#L84-L113

As you can see from that code, it's doing a simple client-credentials flow OAuth grant. It's using the clientId and clientSecret. I think what this means is that you can use BASIC auth, but you must provide a clientId and clientSecret of a client in your OIDC provider. You cannot simply provide end user credentials.

Typically what you would do is create a new client in your OIDC provider for each "application" that you want to make BASIC authenticated calls to Registry.

I believe there may not be a way to use BASIC auth for an end user right now. If that is a requirement I would suggest opening a feature request github issue!!