Add more details on authn and authz settings for AWS (#1721)

content/docs/aws/authentication.md

@@ -1,45 +1,55 @@
 +++
-title = "Authentication and TLS Support"
-description = "Add TLS and authentication with your custom domain"
+title = "Authentication and Authorization"
+description = "Authentication and authorization support for Kubeflow in AWS"
 weight = 90
 +++
 
-This section shows the how to add TLS support and create a user pool to authenticate users with your custom domain in Amazon Web Services (AWS).
+This section shows the how to setup Kubeflow with authentication and authorization support in Amazon Web Services (AWS).
 
 
+## Manifest
+
+In order to simply your setups, we highly recommend you to use this manifest.
+{{% config-uri-aws-cognito %}}
+
 ## Traffic Flow
 External Traffic → [ Ingress → Istio ingress gateway → Istio virtual services ]
 
 When you generate and apply kubernetes resources, an ingress is created to manage external traffic to Kubernetes services. The AWS Appliction Load Balancer(ALB) Ingress Controller will provision an Application Load balancer for that ingress. By default, TLS and authentication are not enabled at creation time.
 
-In Kubeflow 0.6 release, community already move from [Ambassador](https://www.getambassador.io/) to [Istio](https://istio.io/) to manage internal traffic. In AWS solution, TLS, authentication,can be done at the ALB and and authorization can be done at Istio layer.
-
+Kubeflow uses [Istio](https://istio.io/) to manage internal traffic. In AWS solution, TLS, authentication can be done at the ALB and and authorization can be done at Istio layer.
 
 ## Enable TLS and Authentication
 
 Right now, certificates for ALB public DNS names are not supported. Instead, you must  prepare a custom domain. You can register your domain in Route53 or any domain provider such as [GoDaddy.com](https://www.godaddy.com/).
 
 [AWS Certificate Manager](https://aws.amazon.com/certificate-manager/) is a service that lets you easily provision, manage, and deploy public and private Secure Sockets Layer/Transport Layer Security (SSL/TLS) certificates for use with AWS services and your internal connected resources.
 
-To get TLS support from the ALB Ingress Controller, you need to follow [this tutorial](https://docs.aws.amazon.com/acm/latest/userguide/gs-acm-request-public.html) to request a certificate in AWS Certificate Manager. After successful validation, you will get a certificate ARN to use with the ALB Ingress Controller.
+To get TLS support from the ALB Ingress Controller, you need to follow [this tutorial](https://docs.aws.amazon.com/acm/latest/userguide/gs-acm-request-public.html) to request a certificate in AWS Certificate Manager. After successful validation, you will get a `certificate ARN` to use with the ALB Ingress Controller.
+
+> Note: Even you need to create a `certificate ARN`, we don't necessarily need a custom domain unless you want to use it, you can still use ALB ingress hostname to visit kubeflow central dashboard.
 
 <img src="/docs/images/aws/cognito-certarn.png"
   alt="Cognito Certificate ARN"
   class="mt-3 mb-3 border border-info rounded">
 
 [AWS Cognito](https://aws.amazon.com/cognito/) lets you add user sign-up, sign-in, and access control to your web and mobile apps quickly and easily. Amazon Cognito scales to millions of users and supports sign-in with social identity providers, such as Facebook, Google, and Amazon, and enterprise identity providers via SAML 2.0.
 
-<img src="/docs/images/aws/cognito-appclient.png"
+In order to authenticate and manage users for Kubeflow, let's create a user pool. You can follow instructions below.
+
+<img src="/docs/images/aws/cognito-alb-domain.png"
   alt="Cognito Application Client Setting"
   class="mt-3 mb-3 border border-info rounded">
 
+For the callback URLs field, if you don't want to use custom domain, you can use ALB hostname for testing. You will see some `Not Secure` warning in browser because ALB hostname doesn't match with domain name in your ACM certificate. It's still functionally working. We will use ALB and please check [section](/docs/aws/custom-domain) to setup custom domain.
+
 <img src="/docs/images/aws/cognito-domain.png"
   alt="Cognito Domain Name"
   class="mt-3 mb-3 border border-info rounded">
 
-In order to authenticate and manage users for Kubeflow, let's create a user pool. You can follow these instructions here. Once a user pool created, we will have a `UserPoolId`, a Cognito Domain name, and a Cognito Pool Arn.
+Once a user pool created, we will have a `UserPoolId`, a Cognito Domain name, and a Cognito Pool Arn.
 
-Before you `generate all -V`, please update Cognito spec in your Kubeflow
+Before you `kfctl apply -V -f ${CONFIG_FILE}`, please update Cognito spec in your Kubeflow
 configuration file at `${CONFIG_FILE}`, so that it looks like this:
 
 ```
@@ -52,25 +62,57 @@ plugins:
             cognitoAppClientId: xxxxxbxxxxxx
             cognitoUserPoolDomain: your-user-pool
             certArn: arn:aws:acm:us-west-2:xxxxx:certificate/xxxxxxxxxxxxx-xxxx
-        roles:
-          - eksctl-kubeflow-aws-nodegroup-ng-a2-NodeInstanceRole-xxxxx
-        region: us-west-2
+      ....
 ```
 
 After you finish the TLS and Authentication configuration, then you can run `kfctl apply -V -f ${CONFIG_FILE}`.
 
-After your ingress DNS is ready, you need to create a `CNAME` in your DNS records.
+After a while, your ALB will be ready, you can get ALB hostname by running follow command.
 
-<img src="/docs/images/aws/custom-domain-cname.png"
-  alt="Custom Domain CNAME"
+```
+kubectl get ingress istio-ingress -n istio-system
+NAME            HOSTS   ADDRESS                                                                  PORTS   AGE
+istio-ingress   *       a743484b-istiosystem-istio-2af2-1092604728.us-west-2.elb.amazonaws.com   80      4h9m
+```
+
+Update your callback URLs.
+<img src="/docs/images/aws/cognito-alb-domain.png"
+  alt="Cognito Application Client Setting"
   class="mt-3 mb-3 border border-info rounded">
 
-Then you can visit `https://www.shanjiaxin.com`, which is a custom domain we use in this case, it will redirect you to an authentication page. We added a user `kubeflow-test-user` in the Cognito setting and we can use this user for the login service.
+
+Then you can visit kubeflow dahsboard using your ALB hostname.
 
 <img src="/docs/images/aws/authentication.png"
   alt="Cognito Authentication pop-up"
   class="mt-3 mb-3 border border-info rounded">
 
-<img src="/docs/images/aws/kubeflow-main-page.png"
-  alt="Kubeflow main page"
-  class="mt-3 mb-3 border border-info rounded">
+
+## Enable Authorization
+
+[kfctl_aws_cognito.yaml](https://github.com/kubeflow/manifests/blob/master/kfdef/kfctl_aws_cognito.yaml) by default set `clusterRbacConfig` to `ON` which enables istio RBAC for all services. When user create Kubeflow Profile like below, besides `kubeflow-user` namespace, an istio `ServiceRole` and `ServiceRoleBinding` will be created for RBAC.
+
+```yaml
+apiVersion: kubeflow.org/v1
+kind: Profile
+metadata:
+  name: kubeflow-user
+spec:
+  owner:
+    kind: User
+    name: kubeflow-user@amazon.com
+```
+
+The `ServiceRole` `ns-access-istio` is created and it allows user to access all the services in that namespace. `ServiceRoleBinding` `owner-binding-istio` define subject like beflow. Only request with header `kubeflow-userid: kubeflow@amazon.com` can have pass istio RBAC and visit the service
+
+```yaml
+subjects:
+  - properties:
+      request.headers[kubeflow-userid]: kubeflow-user@amazon.com
+```
+
+After ALB load balancer authenticates a user successfully, it sends the user claims received from the IdP to the target. The load balancer signs the user claim so that applications can verify the signature and verify that the claims were sent by the load balancer. Applications that require the full user claims can use any standard JWT library to verify the JWT tokens.
+
+Header `x-amzn-oidc-data` stores user claims, in JSON web tokens (JWT) format. In order to create a `kubeflow-userid` header, we create [aws-istio-authz-adaptor](https://github.com/kubeflow/manifests/tree/master/aws/aws-istio-authz-adaptor) which is an isito [route directive adpater](https://istio.io/docs/tasks/policy-enforcement/control-headers/). It modifies traffic metadata using operation templates on the request and response headers. In this case, we decode JWT token `x-amzn-oidc-data` and retrieve user claim, then append a new header to user's requests.
+
+Check [Enable multi-user authorization for AWS](https://github.com/kubeflow/kubeflow/issues/4761) for more technical details.

content/docs/aws/custom-domain.md

@@ -0,0 +1,37 @@
++++
+title = "Custom Domain"
+description = "Use a custom domain for Kubeflow on AWS"
+weight = 90
++++
+
+## Prerequisite
+
+Before you configure custom domain, you must have read [this section](/docs/aws/authentication) to understand ALB with Cognito or OIDC setup.
+
+## Using Custom Domain
+
+In the Cognito App client setting page, use `https://{YOUR_DOMAIN_NAME}/oauth2/idresponse` in the callback URLs. The rest steps are exact same as the steps in [this section](/docs/aws/authentication)
+
+<img src="/docs/images/aws/cognito-appclient.png"
+  alt="Cognito Application Client Setting"
+  class="mt-3 mb-3 border border-info rounded">
+
+After your ingress DNS is ready, you can get ALB hostname by running follow command.
+
+```
+kubectl get ingress istio-ingress -n istio-system
+NAME            HOSTS   ADDRESS                                                                  PORTS   AGE
+istio-ingress   *       a743484b-istiosystem-istio-2af2-1092604728.us-west-2.elb.amazonaws.com   80      4h9m
+```
+
+Go to your domain vendor, create a `CNAME` in your DNS records and point to this ALB host name.
+
+<img src="/docs/images/aws/custom-domain-cname.png"
+  alt="Custom Domain CNAME"
+  class="mt-3 mb-3 border border-info rounded">
+
+Then you can visit `https://www.shanjiaxin.com`, which is a custom domain we use in this case, it will redirect you to an authentication page. We added a user `kubeflow-test-user` in the Cognito setting and we can use this user for the login service.
+
+<img src="/docs/images/aws/kubeflow-main-page.png"
+  alt="Kubeflow main page"
+  class="mt-3 mb-3 border border-info rounded">

content/docs/aws/customizing-aws.md

@@ -34,7 +34,7 @@ metadata:
   # AWS_CLUSTER_NAME and AWS_REGION will override `name` and `region` here.
   name: kubeflow-example
   region: us-west-2
-  version: '1.13'
+  version: '1.14'
 # If your region has multiple availability zones, you can specify 3 of them.
 #availabilityZones: ["us-west-2b", "us-west-2c", "us-west-2d"]
 

content/docs/aws/deploy/install-kubeflow.md

@@ -169,7 +169,7 @@ configuration before deploying Kubeflow:
 
     *Important!!!* By default, these scripts create an AWS Application Load Balancer for Kubeflow that is open to public. This is good for development testing and for short term use, but we do not recommend that you use this configuration for production workloads.
 
-    To secure your installation, Follow the [instructions](/docs/aws/authentication) to add authentication.
+    To secure your installation, Follow the [instructions](/docs/aws/authentication) to add authentication and authorization.
 
 
 1. Wait for all the resources to become ready in the `kubeflow` namespace.