Upbound Docs - OIDC authentication

OIDC authentication

Important

For more information about Upbound’s Space offerings, review What is Upbound.

You can configure a Space to integrate with an external Identity Provider, provided it implements the Open ID Connect (OIDC) protocol. This allows you to use an auth plugin, such as kubelogin.

Configure a Space for OIDC authentication

You can configure a Space to use OIDC auth with the structured authentication configuration at runtime.

AWS Cognito user pools
GCP Identity Platform
Microsoft Entra ID
Okta
Other Identity Providers, as long as they support OIDC

Tip

Consult your preferred Identity Provider’s documentation for setting up OIDC.

You must set the issuer URL (oidc-issuer-url) and client ID (oidc-client-id) values from the corresponding OIDC Identity Provider in the Space.

# Replace these with the values from your IdP.
export SPACES_OIDC_ISSUER_URL=issuer-url
export SPACES_OIDC_CLIENT_ID=client-id

During a Space install, you must create a ConfigMap with your certificate authority information. An example using Keycloak:

apiVersion: v1
kind: ConfigMap
metadata:
  name: structured-auth-config
  namespace: upbound-system
data:
  config.yaml: |-
    apiVersion: apiserver.config.k8s.io/v1alpha1
    kind: AuthenticationConfiguration
    jwt:
      - issuer:
          url: https://keycloak:8443/realms/master
          certificateAuthority: |-
            -----BEGIN CERTIFICATE-----
            MIIC6DCCAdCgAwIBAgIJAP2LaUhNPPgzMA0GCSqGSIb3DQEBCwUAMBMxETAPBgNV
            ...
            -----END CERTIFICATE-----
          audiences:
            - master-realm
          audienceMatchPolicy: MatchAny
        claimMappings:
          username:
            claim: "preferred_username"
            prefix: "keycloak:"
          groups:
            claim: "groups"
            prefix: ""
          extra:
            - key: 'upbound.io/aud'
              valueExpression: 'claims.aud'

Authenticate with a control plane

After you’ve installed a Space that’s configured to use OIDC auth, you need to fetch and convert the kubeconfig for the control plane. In a Space, the Space writes the connection details for a control plane to a secret in the Space. Fetch the kubeconfig from the secret. For example:

kubectl get secret kubeconfig-ctp1 -n default -o jsonpath='{.data.kubeconfig}' | base64 -d > /tmp/ctp1.yaml

Update the user details of the kubeconfig to use oidc-login. For example, below is a snippet of a kubeconfig which uses kubelogin.

users:
- name: acmeco-ctp1
  user:
    exec:
      apiVersion: client.authentication.k8s.io/v1beta1
      command: kubectl
      args:
      - oidc-login
      - get-token
      - --oidc-issuer-url=${SPACES_OIDC_ISSUER_URL}
      - --oidc-client-id=${SPACES_OIDC_CLIENT_ID}
      - --oidc-client-secret=${SPACES_OIDC_CLIENT_SECRET}

Now whenever a user attempts to interact directly with the control plane, they must have first authenticated with your Identity Provider.