Key Outcomes#

• Self-service user login: Developers authenticate directly using their single sign-on (SSO) credentials via a browser window.
• Short-lived sessions: User access automatically expires after 8 hours, eliminating static long-lived credentials.
• Role-Based Access Control (RBAC): Permissions are dynamically mapped based on Keycloak user groups.
• Stateless kubeconfig: Distribute a single, static kubeconfig template that contains zero credentials or secrets.

How Pinniped Kubeconfig Works#

Traditional kubeconfig files contain embedded client certificates or static tokens. Pinniped changes this paradigm entirely:

• Credential-less configuration: The generated kubeconfig file contains no user credentials, certificates, or tokens.
• Safe distribution: The exact same kubeconfig file can be safely stored in public or team internal Git repositories.
• Browser-based flow: When a user executes kubectl, the Pinniped CLI plugin opens a local browser window to authenticate with Keycloak. Upon successful login, short-lived credentials are cached locally.

1.1 Create the OIDC Client#

1. Log in to your Keycloak Admin Console and select your realm (<REALM_NAME>).
2. Navigate to Clients → click Create client.
3. Configure the client parameters:

Note: In Part 3, once the Pinniped Supervisor endpoint is configured, you must return here and add https://<PINNIPED_SUPERVISOR_URL>/* to Valid redirect URIs. Failing to do so will result in an Invalid parameter: redirect_uri error during browser authentication.

1.2 Add the Group Mapper#

To enforce Kubernetes RBAC based on Keycloak user groups, the JWT token issued by Keycloak must contain a groups claim.

1. Under the kubernetes client, open the Client scopes tab.
2. Select the dedicated scope (e.g., kubernetes-dedicated).
3. Click Add mapper → By configuration → Group Membership.
4. Set the following fields:

Important: groups here is a Token Claim Name, not an OIDC scope name. If you attempt a manual OAuth request with -d "scope=openid groups", Keycloak will reject it with invalid_scope. Always request scope=openid — the groups claim will automatically be included in the token payload once this mapper is enabled.

You can verify the supported scopes on your realm endpoint:

1
curl -s https://<KEYCLOAK_URL>/realms/<REALM_NAME>/.well-known/openid-configuration | jq '.scopes_supported'

1.3 Create Groups and Assign Users#

1. In Keycloak sidebar, go to Groups and create:
   • dev-team
   • ops-team
   • qa-team
2. Go to Users, select a user, open the Groups tab, and click Join Group to assign them to their respective team.

1.4 Test User Setup Checklist#

When creating test users in Keycloak, ensure all required user details are configured. Incomplete profiles will cause authentication failures:

Tip: If Keycloak returns Account is not fully set up despite meeting all criteria above, reset the user password manually under Credentials → Set password.

1.5 Optional: Test Token Generation via Direct Access Grants#

Direct Access Grants (password grant type) are disabled by default in modern Keycloak versions for security reasons. To temporarily test token issuance via curl:

1. Open Client kubernetes → Settings → Capability config → enable Direct access grants → Save.
2. Execute the token request:

1
curl -s -X POST \
2
  https://<KEYCLOAK_URL>/realms/<REALM_NAME>/protocol/openid-connect/token \
3
  -d "client_id=kubernetes" \
4
  -d "username=<USER_EMAIL>" \
5
  -d "password=<PASSWORD>" \
6
  -d "grant_type=password" \
7
  -d "scope=openid" \
8
  | jq -r '.id_token' \
9
  | cut -d. -f2 \
10
  | base64 -d 2>/dev/null \
11
  | jq .

Verify that the groups array is present in the decoded token payload:

1
{
2
  "email": "dev-user@example.com",
3
  "email_verified": true,
4
  "groups": ["dev-team"],
5
  "iss": "https://sso.example.com/realms/internal"
6
}

Security Note: Disable Direct access grants after testing. Production authorization always uses the standard Authorization Code Flow via browser.

1.6 Configure 8-Hour Session Lifespan#

In Keycloak Admin Console, open Realm Settings → Sessions tab:

Next, select the Tokens tab:

When Keycloak’s refresh token expires after 8 hours, Pinniped automatically prompts the user to re-authenticate via their browser on the next kubectl command execution.

2.1 Install cert-manager#

1
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/latest/download/cert-manager.yaml
2

3
# Monitor deployment status until all pods are Ready
4
kubectl get pods -n cert-manager --watch

2.2 Define ClusterIssuer and Certificate#

Create cert-manager-pinniped.yaml:

1
apiVersion: cert-manager.io/v1
2
kind: ClusterIssuer
3
metadata:
4
  name: letsencrypt-prod
5
spec:
6
  acme:
7
    server: https://acme-v02.api.letsencrypt.org/directory
8
    email: <YOUR_EMAIL>
9
    privateKeySecretRef:
10
      name: letsencrypt-prod-key
11
    solvers:
12
      - http01:
13
          ingress:
14
            ingressClassName: traefik
15

16
---
17
apiVersion: cert-manager.io/v1
18
kind: Certificate
19
metadata:
20
  name: pinniped-tls
21
  namespace: pinniped-supervisor
22
spec:
23
  secretName: pinniped-tls-cert
24
  issuerRef:
25
    name: letsencrypt-prod
26
    kind: ClusterIssuer
27
  dnsNames:
28
    - <PINNIPED_SUPERVISOR_URL>

Apply the configuration:

1
kubectl apply -f cert-manager-pinniped.yaml
2

3
# Verify Certificate status (Wait for READY: True)
4
kubectl get certificate pinniped-tls -n pinniped-supervisor --watch

3.1 Install Pinniped Supervisor#

1
kubectl apply -f https://get.pinniped.dev/latest/install-pinniped-supervisor.yaml
2

3
# Verify pods
4
kubectl get pods -n pinniped-supervisor

3.2 Expose Supervisor via Traefik (TLS Passthrough)#

Because Pinniped Supervisor directly handles sensitive credential exchanges, it requires TLS Passthrough to perform end-to-end TLS termination directly inside the pod rather than at the Ingress controller layer.

1. Create a ClusterIP Service for the Supervisor:

1
apiVersion: v1
2
kind: Service
3
metadata:
4
  name: pinniped-supervisor
5
  namespace: pinniped-supervisor
6
spec:
7
  type: ClusterIP
8
  selector:
9
    app: pinniped-supervisor
10
  ports:
11
    - protocol: TCP
12
      port: 443
13
      targetPort: 8443

2. Create a Traefik IngressRouteTCP with passthrough: true:

1
apiVersion: traefik.io/v1alpha1
2
kind: IngressRouteTCP
3
metadata:
4
  name: pinniped-supervisor
5
  namespace: pinniped-supervisor
6
spec:
7
  entryPoints:
8
    - websecure
9
  routes:
10
    - match: HostSNI(`<PINNIPED_SUPERVISOR_URL>`)
11
      services:
12
        - name: pinniped-supervisor
13
          port: 443
14
  tls:
15
    passthrough: true

Apply both manifests:

1
kubectl apply -f pinniped-supervisor-service.yaml
2
kubectl apply -f pinniped-supervisor-ingressroute.yaml

3.3 Configure OIDCIdentityProvider#

Create the custom OIDCIdentityProvider resource to link Pinniped Supervisor to Keycloak:

1
apiVersion: idp.supervisor.pinniped.dev/v1alpha1
2
kind: OIDCIdentityProvider
3
metadata:
4
  name: keycloak-idp
5
  namespace: pinniped-supervisor
6
spec:
7
  issuer: https://<KEYCLOAK_URL>/realms/<REALM_NAME>
8
  authorizationConfig:
9
    additionalScopes:
10
      - email
11
    allowPasswordGrant: false
12
  claims:
13
    username: email
14
    groups: groups
15
  client:
16
    secretName: keycloak-client-secret

Note: Do not add groups to additionalScopes. Requesting groups as an OIDC scope will trigger an invalid_scope error from Keycloak.

Now, create the corresponding client secret. Pinniped requires a custom secret type secrets.pinniped.dev/oidc-client:

1
apiVersion: v1
2
kind: Secret
3
metadata:
4
  name: keycloak-client-secret
5
  namespace: pinniped-supervisor
6
type: secrets.pinniped.dev/oidc-client
7
stringData:
8
  clientID: kubernetes
9
  clientSecret: ""

Caution: Do not use kubectl create secret generic. Generic secrets have type Opaque, which will cause Pinniped to throw the error referenced Secret has wrong type "Opaque". Always apply via YAML with type: secrets.pinniped.dev/oidc-client.

Verify IdP health:

1
kubectl describe OIDCIdentityProvider keycloak-idp -n pinniped-supervisor
2
# Look for: Phase: Ready

If status remains in Phase: Error, restart the Supervisor deployment to reload secrets:

1
kubectl rollout restart deployment/pinniped-supervisor -n pinniped-supervisor

3.4 Configure FederationDomain#

The FederationDomain exposes the public OIDC issuer endpoint of the Supervisor, using the TLS certificate generated by cert-manager:

1
apiVersion: config.supervisor.pinniped.dev/v1alpha1
2
kind: FederationDomain
3
metadata:
4
  name: kubernetes-federation
5
  namespace: pinniped-supervisor
6
spec:
7
  issuer: https://<PINNIPED_SUPERVISOR_URL>/kubernetes-federation
8
  tls:
9
    secretName: pinniped-tls-cert
10
  identityProviders:
11
    - displayName: "Keycloak SSO"
12
      objectRef:
13
        apiGroup: idp.supervisor.pinniped.dev
14
        kind: OIDCIdentityProvider
15
        name: keycloak-idp
16
      transforms:
17
        expressions:
18
          - type: username/v1
19
            expression: '"keycloak:" + username'
20
          - type: groups/v1
21
            expression: 'groups.map(g, "keycloak:" + g)'

Verify FederationDomain status:

1
kubectl describe FederationDomain kubernetes-federation -n pinniped-supervisor | grep "Phase\|Message"
2
# Expected output: Phase: Ready

Remember to update Keycloak client settings (Part 1.1) by adding https://<PINNIPED_SUPERVISOR_URL>/* to the client’s Valid redirect URIs.

4.1 Install Concierge#

Deploy the Pinniped Concierge agent on the target Kubernetes cluster:

1
kubectl apply -f https://get.pinniped.dev/latest/install-pinniped-concierge.yaml

4.2 Configure JWTAuthenticator#

The Concierge uses a JWTAuthenticator to validate authentication tokens issued by the Supervisor.

Extract the active TLS Certificate Authority bundle from pinniped-tls-cert:

1
LE_CA=$(kubectl get secret pinniped-tls-cert \
2
  -n pinniped-supervisor \
3
  -o jsonpath='{.data.tls\.crt}')

Apply the JWTAuthenticator resource:

1
kubectl apply -f - <<EOF
2
apiVersion: authentication.concierge.pinniped.dev/v1alpha1
3
kind: JWTAuthenticator
4
metadata:
5
  name: supervisor-jwt-authenticator
6
  namespace: pinniped-concierge
7
spec:
8
  issuer: https://<PINNIPED_SUPERVISOR_URL>/kubernetes-federation
9
  audience: https://<K8S_API_URL>
10
  tls:
11
    certificateAuthorityData: ${LE_CA}
12
EOF

Verify Authenticator status:

1
kubectl describe JWTAuthenticator supervisor-jwt-authenticator -n pinniped-concierge | grep "Phase\|Message"
2
# Expected output: Phase: Ready

5.1 Install Pinniped CLI#

Install the pinniped CLI on your workstation:

1
# macOS via Homebrew
2
brew install pinniped-cli
3

4
# Linux Binary
5
curl -Lo pinniped https://get.pinniped.dev/latest/pinniped-cli-linux-amd64
6
chmod +x pinniped
7
sudo mv pinniped /usr/local/bin/pinniped

5.2 Generate Kubeconfig File#

As an administrator, generate the static kubeconfig template:

1
pinniped get kubeconfig \
2
  --kubeconfig ~/.kube/config \
3
  > kubeconfig-production.yaml

Note: In Pinniped CLI v0.47.0+, the --pinniped-namespace flag was deprecated in favor of automatic discovery.

This kubeconfig-production.yaml file contains no user secrets. Upload it to your team’s internal documentation site or repository.

5.3 Workstation Setup for Developers#

Developers set up cluster access on their machines in two steps:

1
# 1. Download generic kubeconfig from internal docs
2
curl -O https://internal-docs.example.com/kubernetes/kubeconfig-production.yaml
3

4
# 2. Install Pinniped CLI
5
brew install pinniped-cli

Path Troubleshooting: The generated kubeconfig invokes /usr/local/bin/pinniped. On Apple Silicon Macs, Homebrew installs binaries under /opt/homebrew/bin/pinniped. Create a symbolic link to prevent exec: fork/exec /usr/local/bin/pinniped: no such file or directory:

1
sudo ln -s $(which pinniped) /usr/local/bin/pinniped

5.4 First-Time Login Experience#

When a developer runs kubectl using the Pinniped kubeconfig:

1
export KUBECONFIG=./kubeconfig-production.yaml
2
kubectl get pod -n dev

1. Pinniped automatically launches the system web browser pointing to Keycloak SSO.
2. The user enters their Keycloak credentials.
3. The browser displays “Login Succeeded”.
4. Control returns to the terminal, and kubectl executes seamlessly.

5.5 Daily Session Flow#

1
Morning (08:00):
2
  kubectl get pods ──▶ Browser opens ──▶ User authenticates
3
  └── Session active for 8 hours ✅
4

5
Afternoon (12:00):
6
  kubectl get pods ──▶ Seamless background token refresh ✅
7

8
End of Shift / Next Day (After 8 Hours):
9
  kubectl get pods ──▶ Refresh token expired
10
  └── Browser opens automatically for standard re-login ✅

To manually clear session credentials (e.g., when testing different users or groups):

1
# Linux
2
rm -rf ~/.config/pinniped/sessions.yaml
3

4
# macOS
5
rm -rf ~/Library/Application\ Support/pinniped/sessions.yaml

7.1 Verify Active User Identity#

Run kubectl auth whoami to verify how the API server perceives your authenticated identity and groups:

1
$ kubectl auth whoami
2
ATTRIBUTE                                           VALUE
3
Username                                            keycloak:dev-user@example.com
4
Groups                                              [keycloak:dev-team system:authenticated]
5
Extra: authentication.kubernetes.io/credential-id   [X509SHA256=e5cfbbef0c518879defcaa995b2a4e578522c68d691d1ae9f910e759b5b7c5b7]

7.2 Access Control Verification#

Test resource listing under allowed versus restricted namespaces:

1
$ kubectl get pod -n dev
2
NAME            READY   STATUS    RESTARTS   AGE
3
demo-backend    1/1     Running   0          9h
4
demo-database   1/1     Running   0          9h
5
demo-frontend   1/1     Running   0          9h

1
$ kubectl get pod -n prod
2
Error from server (Forbidden): pods is forbidden: User "keycloak:dev-user@example.com" cannot list resource "pods" in API group "" in the namespace "prod"

1
$ kubectl auth can-i create deployments -n prod
2
no