Generic OIDC

This section pertains to Redpanda Console in a self-hosted deployment, and this feature requires an Enterprise license. To upgrade, contact Redpanda sales.

If you would like to integrate an OpenID Connect (OIDC) compatible identity provider that is not yet natively supported in Console, you can configure the generic OIDC provider. To do so, create an OAuth application in your identity provider and then provide this application’s credentials in the configuration:

Application type: Web application
Authorized redirect URI: https://console.<your-company>.com/login/callbacks/oidc. Replace <your-company>.com with your company’s domain name.

The redirect URI is based on the assumption that you host Redpanda Console so it is accessible from https://console.<your-company>.com.

Edit the console configuration file

Edit the console configuration file associated with your deployment method and incorporate the details from your client application. For example, Kubernetes deployments use the values.yaml file. Linux deployments use the redpanda-console-config.yaml file, which is in /etc/redpanda.

login:
  enabled: true

  # jwtSecret is the secret key you must use to sign and encrypt the JSON
  # web token used to store user sessions. This secret key is
  # critical for the security of Redpanda Console's authentication and
  # authorization system. Use a long, complex key with a combination of
  # numbers, letters, and special characters. The minimum number of
  # characters is 10, but Redpanda recommends using more than 32
  # characters. For additional security, use a different secret key for
  # each environment. jwtSecret can be securely generated with the following
  # command: LC_ALL=C tr -dc '[:alnum:]' < /dev/random | head -c32
  #
  # If you update this secret key, any users who are
  # already logged in to Redpanda Console will be logged out and will have
  # to log in again.
  jwtSecret: ""

  oidc:
    # Whether or not the OIDC provider should be initialized
    enabled: true

    # OAuth application client id
    clientId: ""

    # OAuth application client secret
    clientSecret: ""

    # IssuerUrl is the identity provider's URL; for example, https://accounts.google.com.
    # Console will send a GET request to `${issuerUrl}/.well-known/openid-configuration`
    # and the `issuer` returned in the response has to match this issuer url.
    issuerUrl: ""

    # IssuerTLS is the TLS configuration used by the HTTP client to send requests
	  # to the IssuerURL. If you don't set any certificate paths, the IssuerTLS defaults to
    # the system cert pool.
    issuerTls:
      caFilepath:
      certFilepath:
      keyFilepath:

    # DisplayName is the name that shall be shown on the login page for this identity provider
    displayName: ""

    # UserIdentifyingClaimKey is a relevant property if you want to use a specific claim key
    # to identify users in the role binding. A claim key is part of the identity provider's
    # issued access token payload.
    # By default, we will use the 'sub' claim key, which usually resolves to the unique ID
    # within the identity provider. The value of this claim is compared against what you
    # use in the roleBindings for the `name` property.
    userIdentifyingClaimKey: "sub"

The userIdentifyingClaimKey can only be used for claims that have a string value. You cannot use it for the groups claim in AzureAD, for example, because the claim value is a string array.

Define role-bindings

After you set up the OIDC login configuration, you can bind users to roles. Below is a sample role binding:

roleBindings:
  - metadata:
      name: Developers
    subjects:
        # Kind must always be set to `user` for the OIDC provider, as the claims always belong to
        # an individual user.  This is also true if you match a claim against a group.
      - kind: user
        provider: OIDC
        # Name must match the value of your configured claim key
        name: joe@yourcompany.com
    roleName: editor

Troubleshooting

Used claim key did not exist in user’s id token

If the claim key in a role binding does not exist in the ID token, Redpanda Console prints an error message in the backend to assist you with this. The error message contains the claim key that Redpanda Console tried to look up, as well as all existing claim keys for this specific user.

Here is an example error message:

{
  "level": "error",
  "msg": "the specified user identifying claim does not exist for the user that has logged in",
  "found_claim_keys": ["oid", "aud", "sub"],
  "used_claim_key": "uid"
}

Find your claim keys and values

If you are unsure about which claim keys and values that your identity provider attached to your ID token, you can extract them from the JSON web token that is sent to your browser as a cookie. Because the claim values may be sensitive, Redpanda Console never logs them in the backend.

Open the Redpanda Console login page. Don’t click the OIDC login button yet.
Open your browser’s developer tools and inspect the network requests.
If your browser has the option to preserve logs, enable it. Without this option enabled, some browsers such as Google Chrome truncate the network request logs after a redirection.
Click the OIDC login button and authenticate with your identity provider.
Search the network requests in your browser’s developer tools for a request that starts with the relative path /auth/callbacks/oidc?code=.
Copy the value of the jwt cookie in the set-cookie header. The value of that cookie is an encrypted and compressed JSON web token.
Send the JSON web token to Redpanda Console to decode.

  curl -sL -X POST 'https://your-console-url.com/admin/session-token/decode' \
  -H 'Content-Type: application/json' \
  --data-raw '{
      "token": "<your-token>"
  }'

The response is a JSON object, which includes your token in the oAuthToken.access_token field.