Athenz OIDC Authentication Provider Support for AWS EKS Guide (AthenZ…

…#1754)

* Athenz OIDC Authentication Provider Support for AWS EKS Guide

Signed-off-by: Henry Avetisyan <[email protected]>

* update company name

Signed-off-by: Henry Avetisyan <[email protected]>

Co-authored-by: Henry Avetisyan <[email protected]>

README.md

@@ -96,6 +96,7 @@ credentials for configured AWS IAM roles.
     * [Private Key Store](docs/private_key_store.md)
     * [Certificate Signer](docs/cert_signer.md)
     * [Service Identity X.509 Certificate Support Requirements - Copper Argos](docs/copper_argos_dev.md)
+    * [OIDC Authentication Provider Support for AWS EKS](docs/oidc_aws_eks.md)
 * User Guide
     * [ZMS Client Utility](docs/zms_client.md)
     * [ZPU Utility](docs/setup_zpu.md)

docs/oidc_aws_eks.md

@@ -0,0 +1,107 @@
+# Athenz OIDC Authentication Provider Support for AWS EKS
+
+AWS EKS can be configured to use Athenz as OIDC Authentication Provider to authorize
+access to configured EKS clusters.
+
+## Athenz Configuration
+
+OIDC Spec requires that each client is uniquely identified within the OIDC Provider
+and has a redirect URI configuration property set. In the context of Athenz, the
+EKS cluster administrator first must create a unique service (e.g. `athenz.prod.eks`:
+service called `eks` in the domain `athenz.prod`)
+
+Once the service is created, it must be registered with its redirect URI.
+
+```
+$ zms-cli -d <domain-name> set-service-endpoint <service-name> <redirect-uri>
+```
+
+## AWS EKS Cluster Configuration
+
+In the AWS Console, select EKS service, then choose your cluster from the list.
+In the cluster view, select the `Configuratiion` tab and then the `Authentication`
+tab. Choose the `Associate Identity Provider` button. In the dialog box specify
+the following values (leave others blank):
+
+- Identity Provider Name: athenz
+- Issuer URL: `<athenz-zts-endpoint-uri> e.g. https://zts.athenz.io:8443/zts/v1`
+- Client ID: `<athenz-service-name> e.g. athenz.prod.eks`
+- Groups claim: groups
+- Username prefix: athenz
+- Groups prefix: athenz
+
+## AWS EKS Cluster Role Binding
+
+Next we need to set up and bind a role with subjects authenticated by
+the Athenz OIDC Provider. In this example, we'll use the `cluster-admin`
+role and allow any user in the `athenz.prod` domain `eks-cluster-admins`
+role to assume the capabilities authorized by the `cluster-admin` role.
+
+Create the following yaml called `cluster-group.yaml`.  It binds an ID token
+from Athenz provider having the groups claim of `eks-cluster-admins` to be
+authorized as cluster admins in EKS.
+
+```yaml
+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: Group
+      name: athenz:eks-cluster-admins
+```
+
+Use `kubectl` to apply it to your cluster.
+
+```
+$ kubectl apply -f cluster-group.yaml
+clusterrolebinding.rbac.authorization.k8s.io/oidc-cluster-admin created
+```
+
+Checkout the Kubernetes Guide for full details on Role/RoleBinding and 
+ClusterRole/ClusterRoleBinding authorization support in your cluster.
+
+## Athenz Role Configuration
+
+Make sure your Athenz domain associated with your ClientID identified
+service has the role referenced in the above configuration and the users
+who should be authorized as cluster administrators are members in that role.
+
+Based on our example above:
+
+```
+$ zms-cli -o yaml -d athenz.prod show-role eks-cluster-admins
+name: athenz.prod:role.eks-cluster-admins
+modified: "2022-01-21T22:17:59.291Z"
+rolemembers:
+- membername: user.john
+  active: true
+  approved: true
+```
+
+## OIDC ID Token Support
+
+Install the `zts-idtoken` utility to obtain OIDC ID Tokens from AWS
+ZTS instance and request an ID token from ZTS. The returned value from the `zts-idtoken`
+utility is the id token that we need to submit to AWS EKS. The utility assumes you are
+using X.509 key/cert to authenticate to the ZTS Server. The issued ID tokens are valid
+for 1 hour only.
+
+```
+$ zts-idtoken -zts <athenz-zts-endpoint-uri> -svc-key-file <service-key> -svc-cert-file <service-cert> -client-id athenz.prod.eks -nonce as324sdfa3 -scope "openid roles" -redirect-uri <redirect-uri>
+eyJraWQiOiJ6dHMuZWMudXM.....td2VzdC0yLjAiLCJhbGciOi
+```
+
+We can now use the id token as the value of the --token argument for `kubectl` to manage
+our AWS EKS cluster:
+
+```
+$ kubectl --token=eyJraWQiOiJ6dHMuZWMudXM.....td2VzdC0yLjAiLCJhbGciOi get pods -n sia
+NAME              READY   STATUS    RESTARTS   AGE
+sia-agent-cfl4n   1/1     Running   0          35d
+sia-agent-dwbhn   1/1     Running   0          35d
+```

mkdocs.yml

@@ -63,6 +63,7 @@ nav:
     - Athenz Service Identity X.509 Certificate for AWS EKS pods: service_x509_credentials_aws_eks.md
     - Athenz Service Identity X.509 Certificate for AWS Lambda functions: service_x509_credentials_aws_lambda.md
     - Obtaining OAuth2 Access Tokens from ZTS: zts_access_token_guide.md
+    - Athenz OIDC Authentication Provider Support for AWS EKS: oidc_aws_eks.md
 - AWS Setup:
     - AWS Temp Credentials: aws_temp_creds.md
     - Introduction: aws_athenz_setup.md

roadmap.md

@@ -1,5 +1,5 @@
 The following is the list of features that the Athenz team is working or
-planning to work on. At Verizon Media, we review our list every quarter
+planning to work on. At Yahoo, we review our list every quarter
 and decide which features will be implemented during that quarter. Additionally,
 we implement several smaller features as they're requested by our customers.
 
@@ -12,7 +12,7 @@ we implement several smaller features as they're requested by our customers.
 - Approve role memberships for non-admins through web ui
 - OAuth2 authorization well known metadata endpoint support
 
-- # Q4 2021
+# Q4 2021
 
 - Micro Segmentation: Service Identity based ACLs
 - Support publishing domain change events through an interface (Pulsar integration)