Update AWS Route53 documentation to better explain the authentication…

… options

Signed-off-by: Richard Wall <[email protected]>

content/docs/configuration/acme/dns01/route53.md

@@ -12,14 +12,15 @@ how cert-manager handles DNS01 challenges.
 > (AWS) and that you already have a hosted zone in Route53.
 >
 > 📖 Read
-> [Tutorial: Deploy cert-manager on Amazon Elastic Kubernetes (EKS) and use Let's Encrypt to sign a certificate for an HTTPS website](../../../tutorials/getting-started-aws-letsencrypt/README.md),
-> which contains end-to-end instructions for those who are new to cert-manager and AWS.
+> [Deploy cert-manager on AWS Elastic Kubernetes Service (EKS) and use Let's Encrypt to sign a certificate for an HTTPS website](../../../tutorials/getting-started-aws-letsencrypt/README.md),
+> a tutorial which explains how to create an EKS cluster, install cert-manager, and configuring ACME ClusterIssuer using Route53 for DNS-01 challenges..
 
-## Set up an IAM Role
+## Set up an IAM Policy
 
-cert-manager needs to be able to add records to Route53 in order to solve the
-DNS01 challenge. To enable this, create a IAM policy with the following
-permissions:
+cert-manager needs permission to add TXT records to your Route53 zone in order to solve the DNS01 challenge.
+It needs permission to delete the TXT records, after the challenge succeeds or fails.
+It also needs permission to list the hosted zones, unless you use the `hostedZoneID` field.
+To enable this, create an IAM policy with the following permissions in the AWS account of the Route53 zone:
 
 ```json
 {
@@ -47,24 +48,54 @@ permissions:
 }
 ```
 
-> Note: The `route53:ListHostedZonesByName` statement can be removed if you
+> ℹ️ The `route53:ListHostedZonesByName` statement can be removed if you
 > specify the (optional) `hostedZoneID`. You can further tighten the policy by
 > limiting the hosted zone that cert-manager has access to (e.g.
 > `arn:aws:route53:::hostedzone/DIKER8JEXAMPLE`).
+>
+> 📖 Read about [actions supported by Amazon Route 53](https://docs.aws.amazon.com/Route53/latest/APIReference/API_Operations_Amazon_Route_53.html),
+> in the [Amazon Route 53 API Reference](https://docs.aws.amazon.com/Route53/latest/APIReference/Welcome.html).
 
 ## Credentials
 
-You have two options for the set up - either create a user or a role and attach
-that policy from above.  Using a role is considered best practice because you do
-not have to store permanent credentials in a secret.
+[Requests to the Route53 API must be signed using an access key ID and a secret access key](https://docs.aws.amazon.com/Route53/latest/APIReference/requests-authentication.html),
+and there are several mechanisms for cert-manager to get the access key ID and secret access key,
+some of which are now considered legacy.
+
+The various mechanisms are described below:
+
+### IAM Roles for Service Accounts (IRSA) with dedicated Kubernetes ServiceAccount resources
+
+cert-manager authenticates to Route53 using temporary credentials obtained from STS,
+by exchanging a temporary Kubernetes ServiceAccount token for a temporary AWS access key.
+
+| ✔️ Advantages                           | ✖️ Disadvantages                                            |
+|----------------------------------------|------------------------------------------------------------|
+| uses short-lived credentials           | Additional RBAC required                                   |
+| No key rotation necessary              | Additional ServiceAccount required                         |
+| No Kubernetes Secrets                  | AWS Identity Provider                                      |
+| Works best with cloud managed clusters | Kubernetes cluster requires public OIDC discovery document |
+
+This mechanism works as follows:
+
+1. cert-manager connects to the Kubernetes API server and requests a [Kubernetes service account token](https://kubernetes.io/docs/concepts/security/service-accounts/#authenticating-credentials)
+1. Kubernetes API server returns a [signed JWT]().
+1. cert-manager connects to [AWS Security Token Service (STS)](https://docs.aws.amazon.com/STS/latest/APIReference/welcome.html)
+   invoking the [AssumeRoleWithWebIdentity Action](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html),
+   supplying the Kubernetes signed JWT and the Role ARN specified in the ClusterIssuer (or Issuer).
+1. STS returns a [Temporary security credential](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html)
+   (a short lived AWS access key).
+1. cert-manager connects to [AWS Route53](https://docs.aws.amazon.com/Route53/latest/APIReference/API_Operations.html)
+   invoking various actions to create TXT records to satisfy the ACME challenge.
+   It [signs the requests](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-signing.html) using the short lived access key.
 
-cert-manager supports two ways of specifying credentials:
+1. IAM Roles for Service Accounts (IRSA).
+1. (Legacy) IAM User with Access Key
+1. explicit by providing an `accessKeyID` or an `accessKeyIDSecretRef`, and a `secretAccessKeySecretRef`
+- or implicit (using [metadata service](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html)
+  or [environment variables or credentials file](https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/configuring-sdk.html#specifying-credentials).
 
-- explicit by providing an `accessKeyID` or an `accessKeyIDSecretRef`, and a `secretAccessKeySecretRef`
-- or implicit (using [metadata
-  service](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html)
-  or [environment variables or credentials
-  file](https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/configuring-sdk.html#specifying-credentials).
+### IAM Roles for Service Accounts (IRSA) with mounted
 
 cert-manager also supports specifying a `role` to enable cross-account access
 and/or limit the access of cert-manager. Integration with