Skip to main content
Version: 1.19

Configure OIDC

important

This guide is only applicable for administrators who've deployed self-hosted Spaces. For general RBAC in Upbound, read Upbound RBAC.

Upbound uses the Kubernetes Structured Authentication Configuration to validate OIDC tokens sent to the API. Upbound stores this configuration as a ConfigMap and authenticates with the Upbound router component during installation with Helm.

This guide walks you through how to create and apply an authentication configuration to validate Upbound with an external identity provider. Each section focuses on a specific part of the configuration file.

Creating the AuthenticationConfiguration file​

First, create a file called config.yaml with an AuthenticationConfiguration kind. The AuthenticationConfiguration is the initial authentication structure necessary for Upbound to communicate with your chosen identity provider.

apiVersion: apiserver.config.k8s.io/v1beta1
kind: AuthenticationConfiguration
jwt:
- issuer:
url: oidc-issuer-url
audiences:
- oidc-client-id
claimMappings: # optional
username:
claim: oidc-username-claim
prefix: oidc-username-prefix
groups:
claim: oidc-groups-claim
prefix: oidc-groups-prefix

For detailed configuration options, including the CEL-based token validation, review the feature documentation.

The AuthenticationConfiguration allows you to configure multiple JWT authenticators as separate issuers.

Configure an issuer​

The jwt array requires an issuer specification and typically contains:

  • A username claim mapping
  • A groups claim mapping Optionally, the configuration may also include:
  • A set of claim validation rules
  • A set of user validation rules

The issuer URL must be unique across all configured authenticators.

issuer:
url: https://example.com
discoveryUrl: https://discovery.example.com/.well-known/openid-configuration
certificateAuthority: |-
<Inline CA Certificate>
audiences:
- client-id-a
- client-id-b
audienceMatchPolicy: MatchAny

By default, the authenticator assumes the OIDC Discovery URL is {issuer.url}/.well-known/openid-configuration. Most identity providers follow this structure, and you can omit the discoveryUrl field. To use a separate discovery service, specify the full path to the discovery endpoint in this field.

If the CA for the Issuer isn't public, provide the PEM encoded CA for the Discovery URL.

At least one of the audiences entries must match the aud claim in the JWT. For OIDC tokens, this is the Client ID of the application attempting to access the Upbound API. Having multiple values set allows the same configuration to apply to multiple client applications, for example the kubectl CLI and an Internal Developer Portal.

If you specify multiple audiences , audienceMatchPolicy must equal MatchAny.

Configure claimMappings​

Username claim mapping​

By default, the authenticator uses the sub claim as the user name. To override this, either:

  • specify both claim and prefix. Use a non-empty prefix, such as oidc:. or
  • specify a CEL expression to calculate the user name.
claimMappings:
username:
claim: "sub"
prefix: "keycloak:"
# <or>
expression: '"oidc:" + claims.username'

If the username expression uses claims.email, the configuration must also reference claims.email_verified, for example in a claim validation rule:

claimMappings:
username:
expression: '"oidc:" + claims.email'
claimValidationRules:
- expression: 'claims.email_verified == true'
message: email address must be verified

If your identity provider doesn't send email_verified, use claims.?email_verified.orValue(true) == true instead.

Groups claim mapping​

By default, this configuration doesn't map groups, unless you either:

  • specify both claim and prefix. Use a non-empty prefix, such as oidc:. or
  • specify a CEL expression that returns a string or list of strings.
claimMappings:
groups:
claim: "groups"
prefix: "oidc:"
# <or>
expression: 'claims.roles.split(",").map(r, "oidc:" + r)'
warning

Always prefix usernames and groups, so that names from your identity provider can't collide with names that Spaces or Kubernetes reserve.

Use list claims in CEL expressions​

CEL treats every claim as type any, which macros such as map, filter, all, and exists don't accept. Wrap the claim in dyn() first:

claimMappings:
groups:
expression: 'has(claims.groups) ? dyn(claims.groups).map(g, "oidc:" + g) : []'

The has() check handles tokens without a groups claim.

Validation rules​

Validation rules are CEL expressions that must all be true for authentication to succeed. Review the documentation for all options.

Upbound recommends a prefix on every username and group, and a rule that requires it. The rule still holds if someone later changes a mapping, for example to an expression that forgets the prefix:

claimMappings:
username:
claim: "sub"
prefix: "oidc:"
groups:
claim: "groups"
prefix: "oidc:"
userValidationRules:
- expression: "user.username.startsWith('oidc:')"
message: "username must start with oidc:"
- expression: "user.groups.all(g, g.startsWith('oidc:'))"
message: "groups must start with oidc:"

Use the prefixed names in your RBAC bindings, for example oidc:ctp-admins.

Reserved names​

Spaces rejects a token if its username or any of its groups starts with system: or upbound:, or if its username is kubernetes-admin. The user gets a 401 Unauthorized error, and the router logs which rule failed.

To enforce this in your own configuration as well, for example when you can't require a prefix, add these rules:

userValidationRules:
- expression: "!user.username.startsWith('system:') && !user.username.startsWith('upbound:')"
message: username can't use a reserved prefix
- expression: "user.groups.all(g, !g.startsWith('system:') && !g.startsWith('upbound:'))"
message: groups can't use a reserved prefix

Add a prefix to an existing configuration​

A new or changed prefix renames your users and groups, for example ctp-admins becomes oidc:ctp-admins. Update the subjects of your bindings at the same time, or users lose the access they grant:

  • ClusterRoleBindings and RoleBindings in the host cluster
  • RBAC inside your control planes

Required claims​

To interact with Space and ControlPlane APIs, users must have the upbound.io/aud claim set to one of the following:

Upbound.io AudienceNotes
[]No Access to Space-level or ControlPlane APIs
['upbound:spaces:api']This Identity is only for Space-level APIs
['upbound:spaces:controlplanes']This Identity is only for ControlPlane APIs
['upbound:spaces:api', 'upbound:spaces:controlplanes']This Identity is for both Space-level and ControlPlane APIs

You can set this claim in two ways:

  • In the identity provider mapped in the ID token.
  • Inject in the authenticator with the jwt.claimMappings.extra array.

For example:

apiVersion: apiserver.config.k8s.io/v1beta1
kind: AuthenticationConfiguration
jwt:
- issuer:
url: https://keycloak:8443/realms/master
certificateAuthority: |-
<ca bytes inline>
audiences:
- master-realm
audienceMatchPolicy: MatchAny
claimMappings:
username:
claim: "preferred_username"
prefix: "keycloak:"
groups:
claim: "groups"
prefix: "keycloak:"
extra:
- key: 'upbound.io/aud'
valueExpression: "['upbound:spaces:controlplanes', 'upbound:spaces:api']"

Install the AuthenticationConfiguration​

Once you create an AuthenticationConfiguration file, specify this file as a ConfigMap in the host cluster for the Upbound Space.

kubectl create configmap <configmap name> -n upbound-system --from-file=config.yaml=./path/to/config.yaml

To enable OIDC authentication and disable Upbound IAM when installing the Space, reference the configuration and pass an empty value to the Upbound IAM issuer parameter:

up space init --token-file="${SPACES_TOKEN_PATH}" "v${SPACES_VERSION}" \
...
--set "authentication.structuredConfig=<configmap name>" \
--set "router.controlPlane.extraArgs[0]=--upbound-iam-issuer-url="

Update the AuthenticationConfiguration​

Update the ConfigMap to change the configuration. The router applies it without a restart, usually within a few minutes:

kubectl create configmap <configmap name> -n upbound-system --from-file=config.yaml=./path/to/config.yaml \
--dry-run=client -o yaml | kubectl apply -f -

Starting in Spaces v1.19, Spaces rejects a configuration the router can't apply, with the field that failed and a hint for common mistakes. It also warns when a username or groups claim mapping sets prefix: "". While spaces-controller is unavailable, changes to the ConfigMap fail.

If the router reads an invalid configuration, for example one created before you installed Spaces, it keeps its last valid configuration, or starts without OIDC authentication. Other authentication methods keep working. In earlier versions, the router doesn't start with an invalid configuration. Check the router logs for errors:

kubectl logs -n upbound-system deployment/spaces-router -c router-control-plane | grep -i "authentication config"

Configure RBAC​

In this scenario, the external identity provider handles authentication, but permissions for Spaces and ControlPlane APIs use standard RBAC objects.

Spaces APIs​

The Spaces APIs include:

- apiGroups:
- spaces.upbound.io
resources:
- controlplanes
- sharedexternalsecrets
- sharedsecretstores
- backups
- backupschedules
- sharedbackups
- sharedbackupconfigs
- sharedbackupschedules
- apiGroups:
- observability.spaces.upbound.io
resources:
- sharedtelemetryconfigs

ControlPlane APIs​

Crossplane specifies three roles for a ControlPlane: admin, editor, and viewer. These map to the verbs admin, edit, and view on the controlplanes/k8s resource in the spaces.upbound.io API group.

Control access​

The groups claim in the AuthenticationConfiguration allows you to control resource access when you create a ClusterRoleBinding. A ClusterRole defines the role parameters and a ClusterRoleBinding subject.

The example below allows admin permissions for all ControlPlanes to members of the ctp-admins group, which the Keycloak example above maps to keycloak:ctp-admins:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
name: allow-ctp-admin
rules:
- apiGroups:
- spaces.upbound.io
resources:
- controlplanes/k8s
verbs:
- admin

ctp-admins ClusterRoleBinding

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
name: allow-ctp-admin
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: ClusterRole
name: allow-ctp-admin
subjects:
- apiGroup: rbac.authorization.k8s.io
kind: Group
name: keycloak:ctp-admins