From 8b05fa679d8ee20de79644ab7682cc3a93c828f3 Mon Sep 17 00:00:00 2001 From: Andrea Hoffer Date: Tue, 8 Sep 2020 14:58:29 -0400 Subject: [PATCH] OSDOCS-1172: Adding docs for token inactivity timeout --- _topic_map.yml | 2 + .../configuring-internal-oauth.adoc | 2 +- authentication/configuring-oauth-clients.adoc | 20 ++++ ...ring-token-inactivity-timeout-clients.adoc | 57 +++++++++++ ...-configuring-token-inactivity-timeout.adoc | 97 +++++++++++++++++++ modules/oauth-default-clients.adoc | 31 ++++++ modules/oauth-register-additional-client.adoc | 12 +-- modules/oauth-token-requests.adoc | 27 +++--- 8 files changed, 227 insertions(+), 21 deletions(-) create mode 100644 authentication/configuring-oauth-clients.adoc create mode 100644 modules/oauth-configuring-token-inactivity-timeout-clients.adoc create mode 100644 modules/oauth-configuring-token-inactivity-timeout.adoc create mode 100644 modules/oauth-default-clients.adoc diff --git a/_topic_map.yml b/_topic_map.yml index d18a218c13..982f845b4c 100644 --- a/_topic_map.yml +++ b/_topic_map.yml @@ -458,6 +458,8 @@ Topics: Distros: openshift-dedicated - Name: Configuring the internal OAuth server File: configuring-internal-oauth +- Name: Configuring OAuth clients + File: configuring-oauth-clients Distros: openshift-enterprise,openshift-webscale,openshift-origin - Name: Understanding identity provider configuration File: understanding-identity-provider diff --git a/authentication/configuring-internal-oauth.adoc b/authentication/configuring-internal-oauth.adoc index efb676b242..2a9dca4fc0 100644 --- a/authentication/configuring-internal-oauth.adoc +++ b/authentication/configuring-internal-oauth.adoc @@ -18,7 +18,7 @@ include::modules/oauth-internal-options.adoc[leveloffset=+1] include::modules/oauth-configuring-internal-oauth.adoc[leveloffset=+1] -include::modules/oauth-register-additional-client.adoc[leveloffset=+1] +include::modules/oauth-configuring-token-inactivity-timeout.adoc[leveloffset=+1] include::modules/oauth-server-metadata.adoc[leveloffset=+1] diff --git a/authentication/configuring-oauth-clients.adoc b/authentication/configuring-oauth-clients.adoc new file mode 100644 index 0000000000..027ba7aa5f --- /dev/null +++ b/authentication/configuring-oauth-clients.adoc @@ -0,0 +1,20 @@ +[id="configuring-oauth-clients"] += Configuring OAuth clients +include::modules/common-attributes.adoc[] +:context: configuring-oauth-clients +toc::[] + +Several OAuth clients are created by default in {product-title}. You can also register and configure additional OAuth clients. + +// Default OAuth clients +include::modules/oauth-default-clients.adoc[leveloffset=+1] + +// Register an additional OAuth client +include::modules/oauth-register-additional-client.adoc[leveloffset=+1] + +// Configuring token inactivity timeout for OAuth clients +include::modules/oauth-configuring-token-inactivity-timeout-clients.adoc[leveloffset=+1] + +== Additional resources + +* xref:../rest_api/oauth_apis/oauthclient-oauth-openshift-io-v1.adoc#oauthclient-oauth-openshift-io-v1[OAuthClient [oauth.openshift.io/v1]] diff --git a/modules/oauth-configuring-token-inactivity-timeout-clients.adoc b/modules/oauth-configuring-token-inactivity-timeout-clients.adoc new file mode 100644 index 0000000000..17274ef478 --- /dev/null +++ b/modules/oauth-configuring-token-inactivity-timeout-clients.adoc @@ -0,0 +1,57 @@ +// Module included in the following assemblies: +// +// * authentication/configuring-oauth-clients.adoc + +[id="oauth-token-inactivity-timeout_{context}"] += Configuring token inactivity timeout for an OAuth client + +You can configure OAuth clients to expire OAuth tokens after a set period of inactivity. By default, no token inactivity timeout is set. + +[NOTE] +==== +If the token inactivity timeout is also configured in the internal OAuth server configuration, the timeout that is set in the OAuth client overrides that value. +==== + +.Prerequisites + +* You have access to the cluster as a user with the `cluster-admin` role. +* You have configured an identity provider (IDP). + +.Procedure + +. Update the OAuth client configuration to set a token inactivity timeout. + +.. Edit the OAuth client configuration: ++ +[source,terminal] +---- +$ oc edit oauthclient <1> +---- +<1> Replace `` with the OAuth client to configure, for example, `console`. ++ +Add the `accessTokenInactivityTimeoutSeconds` field and set your timeout value: ++ +[source,yaml] +---- +apiVersion: oauth.openshift.io/v1 +grantMethod: auto +kind: OAuthClient +metadata: +... +accessTokenInactivityTimeoutSeconds: 600 <1> +---- +<1> The minimum allowed timeout value in seconds is `300`. + +.. Save the file to apply the changes. + +. Verify that the token inactivity timeout was successfully set. + +.. Log in to the cluster with an identity from your IDP. Be sure to use the OAuth client that you just configured. + +.. Perform an action and verify that it was successful. + +.. Wait longer than the configured timeout without using the identity. In this procedure's example, wait longer than 600 seconds. + +.. Try to perform an action from the same identity's session. ++ +This attempt should fail because the token should have expired due to inactivity longer than the configured timeout. diff --git a/modules/oauth-configuring-token-inactivity-timeout.adoc b/modules/oauth-configuring-token-inactivity-timeout.adoc new file mode 100644 index 0000000000..010d186970 --- /dev/null +++ b/modules/oauth-configuring-token-inactivity-timeout.adoc @@ -0,0 +1,97 @@ +// Module included in the following assemblies: +// +// * authentication/understanding-internal-oauth.adoc + +[id="oauth-token-inactivity-timeout_{context}"] += Configuring token inactivity timeout for the internal OAuth server + +You can configure OAuth tokens to expire after a set period of inactivity. By default, no token inactivity timeout is set. + +[NOTE] +==== +If the token inactivity timeout is also configured in your OAuth client, that value overrides the timeout that is set in the internal OAuth server configuration. +==== + +.Prerequisites + +* You have access to the cluster as a user with the `cluster-admin` role. +* You have configured an identity provider (IDP). + +.Procedure + +. Update the OAuth configuration to set a token inactivity timeout. + +.. Edit the OAuth configuration: ++ +[source,terminal] +---- +$ oc edit oauth cluster +---- ++ +Add the `spec.tokenConfig.accessTokenInactivityTimeout` field and set your timeout value: ++ +[source,yaml] +---- +apiVersion: config.openshift.io/v1 +kind: OAuth +metadata: +... +spec: + tokenConfig: + accessTokenInactivityTimeout: 400s <1> +---- +<1> Set a value with the appropriate units, for example `400s` for 400 seconds, or `30m` for 30 minutes. The minimum allowed timeout value is `300s`. + +.. Save the file to apply the changes. + +. Check that the OAuth server Pods have restarted: ++ +[source,terminal] +---- +$ oc get clusteroperators authentication +---- ++ +Do not continue to the next step until `PROGRESSING` is listed as `False`, as shown in the following output: ++ +.Example output +[source,terminal] +---- +NAME VERSION AVAILABLE PROGRESSING DEGRADED SINCE +authentication 4.6.0 True False False 145m +---- + +. Check that a new revision of the Kubernetes API server Pods has rolled out. This will take several minutes. ++ +[source,terminal] +---- +$ oc get clusteroperators kube-apiserver +---- ++ +Do not continue to the next step until `PROGRESSING` is listed as `False`, as shown in the following output: ++ +.Example output +[source,terminal] +---- +NAME VERSION AVAILABLE PROGRESSING DEGRADED SINCE +kube-apiserver 4.6.0 True False False 145m +---- ++ +If `PROGRESSING` is showing `True`, wait a few minutes and try again. + +. Verify that the token inactivity timeout was successfully set. + +.. Log in to the cluster with an identity from your IDP. + +.. Execute a command and verify that it was successful. + +.. Wait longer than the configured timeout without using the identity. In this procedure's example, wait longer than 400 seconds. + +.. Try to execute a command from the same identity's session. ++ +This command should fail because the token should have expired due to inactivity longer than the configured timeout. ++ +.Example output +[source,terminal] +---- +error: You must be logged in to the server (Unauthorized) +---- diff --git a/modules/oauth-default-clients.adoc b/modules/oauth-default-clients.adoc new file mode 100644 index 0000000000..33a59aa055 --- /dev/null +++ b/modules/oauth-default-clients.adoc @@ -0,0 +1,31 @@ +// Module included in the following assemblies: +// +// * authentication/configuring-oauth-clients.adoc + +[id="oauth-default-clients_{context}"] += Default OAuth clients + +The following OAuth clients are automatically created when starting the {product-title} API: + +[cols="2,3",options="header"] +|=== + +|OAuth client |Usage + +|`openshift-browser-client` +|Requests tokens at `/oauth/token/request` with a user-agent that can handle interactive logins. ^[1]^ + +|`openshift-challenging-client` +|Requests tokens with a user-agent that can handle `WWW-Authenticate` challenges. + +|=== +[.small] +-- +1. `` refers to the namespace route. This is found by +running the following command: ++ +[source,terminal] +---- +$ oc get route oauth-openshift -n openshift-authentication -o json | jq .spec.host +---- +-- diff --git a/modules/oauth-register-additional-client.adoc b/modules/oauth-register-additional-client.adoc index eab1693723..2013f26b17 100644 --- a/modules/oauth-register-additional-client.adoc +++ b/modules/oauth-register-additional-client.adoc @@ -1,9 +1,9 @@ // Module included in the following assemblies: // -// * authentication/configuring-internal-oauth.adoc +// * authentication/configuring-oauth-clients.adoc [id="oauth-register-additional-client_{context}"] -= Register an additional OAuth client += Registering an additional OAuth client If you need an additional OAuth client to manage authentication for your {product-title} cluster, you can register one. @@ -26,12 +26,12 @@ grantMethod: prompt <4> ') ---- <1> The `name` of the OAuth client is used as the `client_id` parameter when -making requests to `__/oauth/authorize` and -`__/oauth/token`. +making requests to `/oauth/authorize` and +`/oauth/token`. <2> The `secret` is used as the `client_secret` parameter when making requests -to `__/oauth/token`. +to `/oauth/token`. <3> The `redirect_uri` parameter specified in requests to -`__/oauth/authorize` and `__/oauth/token` +`/oauth/authorize` and `/oauth/token` must be equal to or prefixed by one of the URIs listed in the `redirectURIs` parameter value. <4> The `grantMethod` is used to determine what action to take when this diff --git a/modules/oauth-token-requests.adoc b/modules/oauth-token-requests.adoc index 79bf9634fa..491f34d369 100644 --- a/modules/oauth-token-requests.adoc +++ b/modules/oauth-token-requests.adoc @@ -12,38 +12,37 @@ created when starting the {product-title} API: [options="header"] |=== -|OAuth Client |Usage +|OAuth client |Usage |`openshift-browser-client` -|Requests tokens at `__/oauth/token/request` with a user-agent that can handle interactive logins. +|Requests tokens at `/oauth/token/request` with a user-agent that can handle interactive logins. ^[1]^ |`openshift-challenging-client` |Requests tokens with a user-agent that can handle `WWW-Authenticate` challenges. |=== - -[NOTE] -==== -__ refers to the namespace's route. This is found by -running the following command. - +[.small] +-- +1. `` refers to the namespace route. This is found by +running the following command: ++ [source,terminal] ---- -oc get route oauth-openshift -n openshift-authentication -o json | jq .spec.host +$ oc get route oauth-openshift -n openshift-authentication -o json | jq .spec.host ---- -==== +-- All requests for OAuth tokens involve a request to -`__/oauth/authorize`. Most authentication integrations place an +`/oauth/authorize`. Most authentication integrations place an authenticating proxy in front of this endpoint, or configure {product-title} to validate credentials against a backing identity provider. -Requests to `__/oauth/authorize` can come from user-agents that +Requests to `/oauth/authorize` can come from user-agents that cannot display interactive login pages, such as the CLI. Therefore, {product-title} supports authenticating using a `WWW-Authenticate` challenge in addition to interactive login flows. If an authenticating proxy is placed in front of the -`__/oauth/authorize` endpoint, it sends unauthenticated, +`/oauth/authorize` endpoint, it sends unauthenticated, non-browser user-agents `WWW-Authenticate` challenges rather than displaying an interactive login page or redirecting to an interactive login flow. @@ -60,5 +59,5 @@ If the authenticating proxy cannot support `WWW-Authenticate` challenges, or if {product-title} is configured to use an identity provider that does not support WWW-Authenticate challenges, you must use a browser to manually obtain a token from -`__/oauth/token/request`. +`/oauth/token/request`. ====