kubelogin/docs/setup.md

Kubernetes OpenID Connection authentication

This document guides how to set up the Kubernetes OpenID Connect (OIDC) authentication. Let's see the following steps:

1. Set up the OIDC provider
2. Verify authentication
3. Bind a role
4. Set up the Kubernetes API server
5. Set up the kubeconfig
6. Verify cluster access

1. Set up the OIDC provider

Google Identity Platform

You can log in with a Google account.

Open Google APIs Console and create an OAuth client with the following setting:

• Application Type: Other

Check the client ID and secret. Replace the following variables in the later sections.

Variable	Value
ISSUER_URL	https://accounts.google.com
YOUR_CLIENT_ID	xxx.apps.googleusercontent.com
YOUR_CLIENT_SECRET	random string

Keycloak

You can log in with a user of Keycloak. Make sure you have an administrator role of the Keycloak realm.

Open the Keycloak and create an OIDC client as follows:

• Client ID: YOUR_CLIENT_ID
• Valid Redirect URLs:
  • http://localhost:8000
  • http://localhost:18000 (used if the port 8000 is already in use)
• Issuer URL: https://keycloak.example.com/auth/realms/YOUR_REALM

You can associate client roles by adding the following mapper:

• Name: groups
• Mapper Type: User Client Role
• Client ID: YOUR_CLIENT_ID
• Client Role prefix: kubernetes:
• Token Claim Name: groups
• Add to ID token: on

For example, if you have the admin role of the client, you will get a JWT with the claim {"groups": ["kubernetes:admin"]}.

Replace the following variables in the later sections.

Variable	Value
ISSUER_URL	https://keycloak.example.com/auth/realms/YOUR_REALM
YOUR_CLIENT_ID	YOUR_CLIENT_ID
YOUR_CLIENT_SECRET	random string

Dex with GitHub

You can log in with a GitHub account.

Open GitHub OAuth Apps and create an application with the following setting:

• Application name: (any)
• Homepage URL: https://dex.example.com
• Authorization callback URL: https://dex.example.com/callback

Deploy the dex with the following config:

issuer: https://dex.example.com
connectors:
- type: github
  id: github
  name: GitHub
  config:
    clientID: YOUR_GITHUB_CLIENT_ID
    clientSecret: YOUR_GITHUB_CLIENT_SECRET
    redirectURI: https://dex.example.com/callback
staticClients:
- id: YOUR_CLIENT_ID
  name: Kubernetes
  redirectURIs:
  - http://localhost:8000
  - http://localhost:18000
  secret: YOUR_DEX_CLIENT_SECRET

Replace the following variables in the later sections.

Variable	Value
ISSUER_URL	https://dex.example.com
YOUR_CLIENT_ID	YOUR_CLIENT_ID
YOUR_CLIENT_SECRET	YOUR_DEX_CLIENT_SECRET

Okta

You can log in with an Okta user.

Open your Okta organization and create an application with the following options:

• Login redirect URIs:
  • http://localhost:8000
  • http://localhost:18000 (used if the port 8000 is already in use)
• Grant type allowed: Authorization Code

Replace the following variables in the later sections.

Variable	Value
ISSUER_URL	https://YOUR_ORGANIZATION.okta.com
YOUR_CLIENT_ID	random string
YOUR_CLIENT_SECRET	random string

2. Verify authentication

Run the following command:

kubectl oidc-login setup \
  --oidc-issuer-url=ISSUER_URL \
  --oidc-client-id=YOUR_CLIENT_ID \
  --oidc-client-secret=YOUR_CLIENT_SECRET

It will open the browser and you can log in to the provider. Then it will show the instruction.

3. Bind a role

Bind the cluster-admin role to you. Apply the following manifest:

kind: ClusterRoleBinding
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: oidc-cluster-admin
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: cluster-admin
subjects:
- kind: User
  name: ISSUER_URL#YOUR_SUBJECT

kubectl apply -f oidc-cluster-admin.yaml

As well as you can create a custom role and bind it.

4. Set up the Kubernetes API server

Add the following options to the kube-apiserver:

--oidc-issuer-url=ISSUER_URL
--oidc-client-id=YOUR_CLIENT_ID

See OpenID Connect Tokens for details.

If you are using kops, run kops edit cluster and append the following settings:

spec:
  kubeAPIServer:
    oidcIssuerURL: ISSUER_URL
    oidcClientID: YOUR_CLIENT_ID

5. Set up the kubeconfig

Add the following user to the kubeconfig:

users:
- name: google
  user:
    exec:
      apiVersion: client.authentication.k8s.io/v1beta1
      command: kubectl
      args:
      - oidc-login
      - get-token
      - --oidc-issuer-url=ISSUER_URL
      - --oidc-client-id=YOUR_CLIENT_ID
      - --oidc-client-secret=YOUR_CLIENT_SECRET

You can share the kubeconfig to your team members for on-boarding.

6. Verify cluster access

Make sure you can access the Kubernetes cluster.

% kubectl get nodes
Open http://localhost:8000 for authentication
You got a valid token until 2019-05-16 22:03:13 +0900 JST
NAME                                    STATUS    ROLES     AGE       VERSION
ip-1-2-3-4.us-west-2.compute.internal   Ready     node      21d       v1.9.6
ip-1-2-3-5.us-west-2.compute.internal   Ready     node      20d       v1.9.6