From e746d344c9e5ac561bd3e479f281223b25ce2f4b Mon Sep 17 00:00:00 2001
From: Michael Taufen <mtaufen@users.noreply.github.com>
Date: Thu, 12 Mar 2020 13:18:39 -0700
Subject: [PATCH] ServiceAccountIssuerDiscovery: Add user facing documentation
 (#19328)

Extends the documentation on configuring service accounts to include
details on the ServiceAccountIssuerDiscovery feature.
---
 .../configure-service-account.md              | 62 ++++++++++++++++++-
 1 file changed, 60 insertions(+), 2 deletions(-)

diff --git a/content/en/docs/tasks/configure-pod-container/configure-service-account.md b/content/en/docs/tasks/configure-pod-container/configure-service-account.md
index f4917b36a9..a86ae91aca 100644
--- a/content/en/docs/tasks/configure-pod-container/configure-service-account.md
+++ b/content/en/docs/tasks/configure-pod-container/configure-service-account.md
@@ -299,9 +299,67 @@ token available to the pod at a configurable file path, and refresh the token as
 
 The application is responsible for reloading the token when it rotates. Periodic reloading (e.g. once every 5 minutes) is sufficient for most usecases.
 
+## Service Account Issuer Discovery
+
+{{< feature-state for_k8s_version="v1.18" state="alpha" >}}
+
+The Service Account Issuer Discovery feature is enabled by enabling the
+`ServiceAccountIssuerDiscovery` [feature gate](/docs/reference/command-line-tools-reference/feature)
+and then enabling the Service Account Token Projection feature as described
+[above](#service-account-token-volume-projection).
+
+{{< note >}}
+The issuer URL must comply with the
+[OIDC Discovery Spec](https://openid.net/specs/openid-connect-discovery-1_0.html). In
+practice, this means it must use the `https` scheme, and should serve an OpenID
+provider configuration at `{service-account-issuer}/.well-known/openid-configuration`.
+
+If the URL does not comply, the `ServiceAccountIssuerDiscovery` endpoints will
+not be registered, even if the feature is enabled.
+{{< /note >}}
+
+The Service Account Issuer Discovery feature enables federation of Kubernetes
+service account tokens issued by a cluster (the _identity provider_) with
+external systems (_relying parties_).
+
+When enabled, the Kubernetes API server provides an OpenID Provider
+Configuration document at `/.well-known/openid-configuration` and the associated
+JSON Web Key Set (JWKS) at `/openid/v1/jwks`. The OpenID Provider Configuration
+is sometimes referred to as the _discovery document_.
+
+When enabled, the cluster is also configured with a default RBAC ClusterRole
+called `system:service-account-issuer-discovery`. No role bindings are provided
+by default. Administrators may, for example, choose whether to bind the role to
+`system:authenticated` or `system:unauthenticated` depending on their security
+requirements and which external systems they intend to federate with.
+
+{{< note >}}
+The responses served at `/.well-known/openid-configuration` and
+`/openid/v1/jwks` are designed to be OIDC compatible, but not strictly OIDC
+compliant. Those documents contain only the parameters necessary to perform
+validation of Kubernetes service account tokens.
+{{< /note >}}
+
+The JWKS response contains public keys that a relying party can use to validate
+the Kubernetes service account tokens. Relying parties first query for the
+OpenID Provider Configuration, and use the `jwks_uri` field in the response to
+find the JWKS.
+
+In many cases, Kubernetes API servers are not available on the public internet,
+but public endpoints that serve cached responses from the API server can be made
+available by users or service providers. In these cases, it is possible to
+override the `jwks_uri` in the OpenID Provider Configuration so that it points
+to the public endpoint, rather than the API server's address, by passing the
+`--service-account-jwks-uri` flag to the API server. Like the issuer URL, the
+JWKS URI is required to use the `https` scheme.
 {{% /capture %}}
 
 {{% capture whatsnext %}}
-See also the
-[Cluster Admin Guide to Service Accounts](/docs/reference/access-authn-authz/service-accounts-admin/).
+
+See also:
+
+- [Cluster Admin Guide to Service Accounts](/docs/reference/access-authn-authz/service-accounts-admin/)
+- [Service Account Signing Key Retrieval KEP](https://github.com/kubernetes/enhancements/blob/master/keps/sig-auth/20190730-oidc-discovery.md)
+- [OIDC Discovery Spec](https://openid.net/specs/openid-connect-discovery-1_0.html)
+
 {{% /capture %}}