diff --git a/Documentation/connectors/kubelogin-activedirectory.md b/Documentation/connectors/kubelogin-activedirectory.md new file mode 100644 index 00000000..e6a922f0 --- /dev/null +++ b/Documentation/connectors/kubelogin-activedirectory.md @@ -0,0 +1,129 @@ +# Integration kubelogin and Active Directory + +## Overview + +kubelogin is helper tool for kubernetes and oidc integration. +It makes easy to login Open ID Provider. +This document describes how dex work with kubelogin and Active Directory. + +examples/config-ad-kubelogin.yaml is sample configuration to integrate Active Directory and kubelogin. + +## Precondition + +1. Active Directory +You should have Active Directory or LDAP has Active Directory compatible schema such as samba ad. +You may have user objects and group objects in AD. Please ensure TLS is enabled. + +2. Install kubelogin +Download kubelogin from https://github.com/int128/kubelogin/releases. +Install it to your terminal. + +## Getting started + +### Generate certificate and private key + +Create OpenSSL conf req.conf as follow: + +``` +[req] +req_extensions = v3_req +distinguished_name = req_distinguished_name + +[req_distinguished_name] + +[ v3_req ] +basicConstraints = CA:FALSE +keyUsage = nonRepudiation, digitalSignature, keyEncipherment +subjectAltName = @alt_names + +[alt_names] +DNS.1 = dex.example.com +``` + +Please replace dex.example.com to your favorit hostname. +Generate certificate and private key by following command. + +``` +$ openssl req -new -x509 -sha256 -days 3650 -newkey rsa:4096 -extensions v3_req -out openid-ca.pem -keyout openid-key.pem -config req.cnf -subj "/CN=kube-ca" -nodes +$ ls openid* +openid-ca.pem openid-key.pem +``` + +### Modify dex config + +Modify following host, bindDN and bindPW in examples/config-ad-kubelogin.yaml. + +``` +connectors: +- type: ldap + name: OpenLDAP + id: ldap + config: + host: ldap.example.com:636 + + # No TLS for this setup. + insecureNoSSL: false + insecureSkipVerify: true + + # This would normally be a read-only user. + bindDN: cn=Administrator,cn=users,dc=example,dc=com + bindPW: admin0! +``` + +### Run dex + +``` +$ bin/dex serve examples/config-ad-kubelogin.yaml +``` + +### Configure kubernetes with oidc + +Copy openid-ca.pem to /etc/ssl/certs/openid-ca.pem on master node. + +Use the following flags to point your API server(s) at dex. `dex.example.com` should be replaced by whatever DNS name or IP address dex is running under. + +``` +--oidc-issuer-url=https://dex.example.com:32000/dex +--oidc-client-id=kubernetes +--oidc-ca-file=/etc/ssl/certs/openid-ca.pem +--oidc-username-claim=email +--oidc-groups-claim=groups +``` + +Then restart API server(s). + + +See https://kubernetes.io/docs/reference/access-authn-authz/authentication/ for more detail. + +### kubelogin + +Create context for dex authentication: + +``` +$ kubectl config set-context oidc-ctx --cluster=cluster.local --user=test +$ kubectl config set-credentials test + --auth-provider=oidc \ + --auth-provider-arg=idp-issuer-url=https://dex.example.com:32000/dex \ + --auth-provider-arg=client-id=kubernetes \ + --auth-provider-arg=client-secret=ZXhhbXBsZS1hcHAtc2VjcmV0 \ + --auth-provider-arg=idp-certificate-authority-data=$(base64 -w 0 openid-ca.pem) \ + "--auth-provider-arg=extra-scopes=offline_access openid profile email group" +$ kubectl config use-context oidc-ctx +``` + +Please confirm idp-issuer-url, cleint-id, client-secret and idp-certificate-authority-data value is same as config-ad-kubelogin.yaml's value. + +Then run kubelogin: + +``` +$ kubelogin +``` + +Access http://localhost:8000 by web browser and login with your AD account(eg. test@example.com) and password. +After login and grant, you have following token in ~/.kube/config: + +``` + id-token: eyJhbGciOiJSUzICuU4dCcilDDWlw2lfr8mg... + refresh-token: ChlxY2EzeGhKEB4492EzecdKJOElECK... +``` +