Merge pull request openshift#3151 from ahardin-rh/enj-3092

Add OAuth discovery and SA annotations docs

Author: ahardin-rh

architecture/additional_concepts/authentication.adoc

@@ -137,7 +137,7 @@ It then determines what user that identity maps to, creates an access token for
 that user, and returns the token for use.
 
 [[oauth-clients]]
-*OAuth Clients*
+=== OAuth Clients
 
 Every request for an OAuth token must specify the OAuth client that will
 receive and use the token. The following OAuth clients are automatically created
@@ -182,7 +182,7 @@ grantMethod: prompt <4>
 ====
 
 [[service-accounts-as-oauth-clients]]
-*Service Accounts as OAuth Clients*
+=== Service Accounts as OAuth Clients
 
 A
 xref:../../admin_guide/service_accounts.adoc#admin-guide-service-accounts[service
@@ -194,27 +194,153 @@ service account's own namespace:
 
 * `user:info`
 * `user:check-access`
-* `role:<any role>:<serviceaccount namespace>`
-* `role:<any role>:<serviceaccount namespace>:!`
+* `role:<any_role>:<serviceaccount_namespace>`
+* `role:<any_role>:<serviceaccount_namespace>:!`
 
 When using a service account as an OAuth client:
 
-* `client_id` is `system:serviceaccount:<serviceaccount namespace>:<serviceaccount name>`.
+* `client_id` is `system:serviceaccount:<serviceaccount_namespace>:<serviceaccount_name>`.
 * `client_secret` can be any of the API tokens for that service account. For example:
 +
 ----
-$ oc sa get-token <serviceaccount name>
+$ oc sa get-token <serviceaccount_name>
 ----
 
-* `redirect_uri` must match an annotation on the service account that has the
-prefix `serviceaccounts.openshift.io/oauth-redirecturi`. For example,
-`serviceaccounts.openshift.io/oauth-redirecturi.one`.
 * To get `WWW-Authenticate` challenges, set an
 `serviceaccounts.openshift.io/oauth-want-challenges` annotation on the service
 account to *true*.
 
+* `redirect_uri` must match an annotation on the service account.
+xref:redirect-uris-for-service-accounts[Redirect URIs for Service Accounts as
+OAuth Clients] provides more information.
+
+[[redirect-uris-for-service-accounts]]
+==== Redirect URIs for Service Accounts as OAuth Clients
+
+Annotation keys must have the prefix
+`serviceaccounts.openshift.io/oauth-redirecturi.` or
+`serviceaccounts.openshift.io/oauth-redirectreference.` such as:
+
+----
+serviceaccounts.openshift.io/oauth-redirecturi.<name>
+----
+
+In its simplest form, the annotation can be used to directly specify valid
+redirect URIs. For example:
+
+----
+"serviceaccounts.openshift.io/oauth-redirecturi.first":  "https://example.com"
+"serviceaccounts.openshift.io/oauth-redirecturi.second": "https://other.com"
+----
+
+The `first` and `second` postfixes in the above example are used to separate the
+two valid redirect URIs.
+
+In more complex configurations, static redirect URIs may not be enough. For
+example, perhaps you want all ingresses for a route to be considered valid. This
+is where dynamic redirect URIs via the
+`serviceaccounts.openshift.io/oauth-redirectreference.` prefix come into play.
+
+For example:
+
+----
+"serviceaccounts.openshift.io/oauth-redirectreference.first": "{\"kind\":\"OAuthRedirectReference\",\"apiVersion\":\"v1\",\"reference\":{\"kind\":\"Route\",\"name\":\"jenkins\"}}"
+----
+
+Since the value for this annotation contains serialized JSON data, it is easier
+to see in an expanded format:
+
+----
+
+{
+  "kind": "OAuthRedirectReference",
+  "apiVersion": "v1",
+  "reference": {
+    "kind": "Route",
+    "name": "jenkins"
+  }
+}
+
+----
+
+Now you can see that an `OAuthRedirectReference` allows us to reference the
+route named `jenkins`. Thus, all ingresses for that route will now be considered
+valid.  The full specification for an `OAuthRedirectReference` is:
+
+----
+
+{
+  "kind": "OAuthRedirectReference",
+  "apiVersion": "v1",
+  "reference": {
+    "kind": ..., <1>
+    "name": ..., <2>
+    "group": ... <3>
+  }
+}
+
+----
+
+<1> `kind` refers to the type of the object being referenced. Currently, only `route` is supported.
+<2> `name` refers to the name of the object. The object must be in the same namespace as the service account.
+<3> `group` refers to the group of the object. Leave this blank, as the group for a route is the empty string.
+
+Both annotation prefixes can be combined to override the data provided by the
+reference object. For example:
+
+----
+"serviceaccounts.openshift.io/oauth-redirecturi.first":  "custompath"
+"serviceaccounts.openshift.io/oauth-redirectreference.first": "{\"kind\":\"OAuthRedirectReference\",\"apiVersion\":\"v1\",\"reference\":{\"kind\":\"Route\",\"name\":\"jenkins\"}}"
+----
+
+The `first` postfix is used to tie the annotations together. Assuming that the
+`jenkins` route had an ingress of *_\https://example.com_*, now
+*_\https://example.com/custompath_* is considered valid, but
+*_\https://example.com_* is not.  The format for partially supplying override
+data is as follows:
+
+[cols="4a,8a",options="header"]
+|===
+|Type | Syntax
+|Scheme| "https://"
+|Hostname| "//website.com"
+|Port| "//:8000"
+|Path| "examplepath"
+|===
+
+[NOTE]
+====
+Specifying a host name override will replace the host name data from the
+referenced object, which is not likely to be desired behavior.
+====
+
+Any combination of the above syntax can be combined using the following format:
+
+`<scheme:>//<hostname><:port>/<path>`
+
+The same object can be referenced more than once for more flexibility:
+
+----
+"serviceaccounts.openshift.io/oauth-redirecturi.first":  "custompath"
+"serviceaccounts.openshift.io/oauth-redirectreference.first": "{\"kind\":\"OAuthRedirectReference\",\"apiVersion\":\"v1\",\"reference\":{\"kind\":\"Route\",\"name\":\"jenkins\"}}"
+"serviceaccounts.openshift.io/oauth-redirecturi.second":  "//:8000"
+"serviceaccounts.openshift.io/oauth-redirectreference.second": "{\"kind\":\"OAuthRedirectReference\",\"apiVersion\":\"v1\",\"reference\":{\"kind\":\"Route\",\"name\":\"jenkins\"}}"
+----
+
+Assuming that the route named `jenkins` has an ingress of
+*_\https://example.com_*, then both *_\https://example.com:8000_* and
+*_\https://example.com/custompath_* are considered valid.
+
+Static and dynamic annotations can be used at the same time to achieve the
+desired behavior:
+
+----
+"serviceaccounts.openshift.io/oauth-redirectreference.first": "{\"kind\":\"OAuthRedirectReference\",\"apiVersion\":\"v1\",\"reference\":{\"kind\":\"Route\",\"name\":\"jenkins\"}}"
+"serviceaccounts.openshift.io/oauth-redirecturi.second": "https://other.com"
+----
+
 [[integrations]]
-*Integrations*
+=== Integrations
 
 All requests for OAuth tokens involve a request to `_<master>_/oauth/authorize`.
 Most authentication integrations place an authenticating proxy in front of this
@@ -248,8 +374,78 @@ WWW-Authenticate challenges, users can visit `_<master>_/oauth/token/request`
 using a browser to obtain an access token manually.
 ====
 
+[[oauth-server-metadata]]
+=== OAuth Server Metadata
+
+Applications running in {product-title} may need to discover information about
+the built-in OAuth server. For example, they may need to discover what the
+address of the `<master>` server is without manual configuration.  To aid in
+this, {product-title} implements the IETF
+link:https://tools.ietf.org/html/draft-ietf-oauth-discovery-04[OAuth 2.0
+Authorization Server Metadata] draft specification.
+
+Thus, any application running inside the cluster can issue a `GET` request to
+*_\https://openshift.default.svc/.well-known/oauth-authorization-server_* to fetch
+the following information:
+
+----
+{
+  "issuer": "https://<master>", <1>
+  "authorization_endpoint": "https://<master>/oauth/authorize", <2>
+  "token_endpoint": "https://<master>/oauth/token", <3>
+  "scopes_supported": [ <4>
+    "user:full",
+    "user:info",
+    "user:check-access",
+    "user:list-scoped-projects",
+    "user:list-projects"
+  ],
+  "response_types_supported": [ <5>
+    "code",
+    "token"
+  ],
+  "grant_types_supported": [ <6>
+    "authorization_code",
+    "implicit"
+  ],
+  "code_challenge_methods_supported": [ <7>
+    "plain",
+    "S256"
+  ]
+}
+----
+<1> The authorization server's issuer identifier, which is a URL that uses the
+`https` scheme and has no query or fragment components. This is the location
+where `.well-known` link:https://tools.ietf.org/html/rfc5785[RFC 5785] resources
+containing information about the authorization server are published.
+<2> URL of the authorization server's authorization endpoint. See
+link:https://tools.ietf.org/html/rfc6749[RFC 6749].
+<3> URL of the authorization server's token endpoint. See
+link:https://tools.ietf.org/html/rfc6749[RFC 6749].
+<4> JSON array containing a list of the OAuth 2.0
+link:https://tools.ietf.org/html/rfc6749[RFC 6749] scope values that this
+authorization server supports. Note that not all supported scope values are
+advertised.
+<5> JSON array containing a list of the OAuth 2.0 `response_type` values that this
+authorization server supports. The array values used are the same as those used
+with the `response_types` parameter defined by "OAuth 2.0 Dynamic Client
+Registration Protocol" in link:https://tools.ietf.org/html/rfc7591[RFC 7591].
+<6> JSON array containing a list of the OAuth 2.0 grant type values that this
+authorization server supports. The array values used are the same as those used
+with the `grant_types` parameter defined by *OAuth 2.0 Dynamic Client
+Registration Protocol* in link:https://tools.ietf.org/html/rfc7591[RFC 7591].
+<7> JSON array containing a list of PKCE
+link:https://tools.ietf.org/html/rfc7636[RFC 7636] code challenge methods
+supported by this authorization server. Code challenge method values are used in
+the `code_challenge_method` parameter defined in
+link:https://tools.ietf.org/html/rfc7636#section-4.3[Section 4.3 of RFC 7636].
+The valid code challenge method values are those registered in the IANA *PKCE
+Code Challenge Methods* registry.  See
+link:http://www.iana.org/assignments/oauth-parameters[IANA OAuth Parameters].
+
+
 [[obtaining-oauth-tokens]]
-*Obtaining OAuth Tokens*
+=== Obtaining OAuth Tokens
 
 The OAuth server supports standard
 link:https://tools.ietf.org/html/rfc6749#section-4.1[authorization code grant]

using_images/other_images/jenkins.adoc

@@ -65,8 +65,9 @@ You can manage Jenkins authentication in two ways:
 [[jenkins-openshift-oauth-authentication]]
 ==== {product-title} OAuth authentication
 
-OAuth authentication is activated by configuring the `*Configure Global
-Security*` panel in the Jenkins UI, or by setting the `*OPENSHIFT_ENABLE_OAUTH*`
+xref:../../architecture/additional_concepts/authentication.adoc#oauth[OAuth
+authentication] is activated by configuring the `*Configure Global Security*`
+panel in the Jenkins UI, or by setting the `*OPENSHIFT_ENABLE_OAUTH*`
 environment variable on the Jenkins `*Deployment Config*` to anything other than
 `false`. This activates the OpenShift Login plug-in, which retrieves the
 configuration information from pod data or by interacting with the
@@ -76,12 +77,12 @@ Valid user and password combinations are controlled by your identity provider.
 For example, if `Allow All` is the default identity provider, you can provide
 any non-empty string for both the user name and password. If you have
 administrator privileges in the project Jenkins is running in, you will have
-administrative privileges within Jenkins. 
+administrative privileges within Jenkins.
 
 Valid users are automatically added to the Jenkins authorization matrix at log
 in, dictated by the permissions within the Jenkins authorization matrix
 associated with the user. Users authenticated against {product-title} OAuth are
-added to the Jenkins authorization matrix on their first successful log in. 
+added to the Jenkins authorization matrix on their first successful log in.
 
 The `admin` role maps to the set of permissions traditionally associated with
 the `admin` user in the {product-title} Jenkins image:
@@ -399,4 +400,3 @@ Jenkins job] that is pre-configured in the Jenkins image utilizes the
 plug-in for creating CI/CD flows for {product-title} in Jenkins.
 
 See the https://github.com/openshift/jenkins-plugin/[the plug-in's README] for a detailed description of what is available.
-