Merge pull request #28506 from bergerhoffer/OSDOCS-1650

OSDOCS-1650: Adding docs for managing user oauth tokens

_topic_map.yml

@@ -572,6 +572,8 @@ Topics:
   File: configuring-internal-oauth
 - Name: Configuring OAuth clients
   File: configuring-oauth-clients
+- Name: Managing user-owned OAuth access tokens
+  File: managing-oauth-access-tokens
   Distros: openshift-enterprise,openshift-webscale,openshift-origin
 - Name: Understanding identity provider configuration
   File: understanding-identity-provider

authentication/managing-oauth-access-tokens.adoc

@@ -0,0 +1,17 @@
+[id="managing-oauth-access-tokens"]
+= Managing user-owned OAuth access tokens
+include::modules/common-attributes.adoc[]
+:context: managing-oauth-access-tokens
+
+toc::[]
+
+Users can review their own OAuth access tokens and delete any that are no longer needed.
+
+// Listing user-owned OAuth access tokens
+include::modules/oauth-list-tokens.adoc[leveloffset=+1]
+
+// Viewing the details of a user-owned OAuth access token
+include::modules/oauth-view-details-tokens.adoc[leveloffset=+1]
+
+// Deleting user-owned OAuth access tokens
+include::modules/oauth-delete-tokens.adoc[leveloffset=+1]

modules/oauth-delete-tokens.adoc

@@ -0,0 +1,25 @@
+// Module included in the following assemblies:
+//
+// * authentication/managing-oauth-access-tokens.adoc
+
+[id="oauth-delete-tokens_{context}"]
+= Deleting user-owned OAuth access tokens
+
+The `oc logout` command only invalidates the OAuth token for the active session. You can use the following procedure to delete any user-owned OAuth tokens that are no longer needed.
+
+Deleting an OAuth access token logs out the user from all sessions that use the token.
+
+.Procedure
+
+* Delete the user-owned OAuth access token:
++
+[source,terminal]
+----
+$ oc delete useroauthaccesstokens <token_name>
+----
++
+.Example output
+[source,terminal]
+----
+useroauthaccesstoken.oauth.openshift.io "<token_name>" deleted
+----

modules/oauth-list-tokens.adoc

@@ -0,0 +1,40 @@
+// Module included in the following assemblies:
+//
+// * authentication/managing-oauth-access-tokens.adoc
+
+[id="oauth-list-tokens_{context}"]
+= Listing user-owned OAuth access tokens
+
+You can list your user-owned OAuth access tokens. Token names are not sensitive and cannot be used to log in.
+
+.Procedure
+
+* List all user-owned OAuth access tokens:
++
+[source,terminal]
+----
+$ oc get useroauthaccesstokens
+----
++
+.Example output
+[source,terminal]
+----
+NAME       CLIENT NAME                    CREATED                EXPIRES                         REDIRECT URI                                                       SCOPES
+<token1>   openshift-challenging-client   2021-01-11T19:25:35Z   2021-01-12 19:25:35 +0000 UTC   https://oauth-openshift.apps.example.com/oauth/token/implicit      user:full
+<token2>   openshift-browser-client       2021-01-11T19:27:06Z   2021-01-12 19:27:06 +0000 UTC   https://oauth-openshift.apps.example.com/oauth/token/display       user:full
+<token3>   console                        2021-01-11T19:26:29Z   2021-01-12 19:26:29 +0000 UTC   https://console-openshift-console.apps.example.com/auth/callback   user:full
+----
+
+* List user-owned OAuth access tokens for a particular OAuth client:
++
+[source,terminal]
+----
+$ oc get useroauthaccesstokens --field-selector=clientName="console"
+----
++
+.Example output
+[source,terminal]
+----
+NAME       CLIENT NAME                    CREATED                EXPIRES                         REDIRECT URI                                                       SCOPES
+<token3>   console                        2021-01-11T19:26:29Z   2021-01-12 19:26:29 +0000 UTC   https://console-openshift-console.apps.example.com/auth/callback   user:full
+----

modules/oauth-view-details-tokens.adoc

@@ -0,0 +1,63 @@
+// Module included in the following assemblies:
+//
+// * authentication/managing-oauth-access-tokens.adoc
+
+[id="oauth-view-details-tokens_{context}"]
+= Viewing the details of a user-owned OAuth access token
+
+You can view the details of a user-owned OAuth access token.
+
+.Procedure
+
+* Describe the details of a user-owned OAuth access token:
++
+[source,terminal]
+----
+$ oc describe useroauthaccesstokens <token_name>
+----
++
+.Example output
+[source,terminal]
+----
+Name:                        <token_name> <1>
+Namespace:
+Labels:                      <none>
+Annotations:                 <none>
+API Version:                 oauth.openshift.io/v1
+Authorize Token:             sha256~Ksckkug-9Fg_RWn_AUysPoIg-_HqmFI9zUL_CgD8wr8
+Client Name:                 openshift-browser-client <2>
+Expires In:                  86400 <3>
+Inactivity Timeout Seconds:  317 <4>
+Kind:                        UserOAuthAccessToken
+Metadata:
+  Creation Timestamp:  2021-01-11T19:27:06Z
+  Managed Fields:
+    API Version:  oauth.openshift.io/v1
+    Fields Type:  FieldsV1
+    fieldsV1:
+      f:authorizeToken:
+      f:clientName:
+      f:expiresIn:
+      f:redirectURI:
+      f:scopes:
+      f:userName:
+      f:userUID:
+    Manager:         oauth-server
+    Operation:       Update
+    Time:            2021-01-11T19:27:06Z
+  Resource Version:  30535
+  Self Link:         /apis/oauth.openshift.io/v1/useroauthaccesstokens/<token_name>
+  UID:               f9d00b67-ab65-489b-8080-e427fa3c6181
+Redirect URI:        https://oauth-openshift.apps.example.com/oauth/token/display
+Scopes:
+  user:full <5>
+User Name:  <user_name> <6>
+User UID:   82356ab0-95f9-4fb3-9bc0-10f1d6a6a345
+Events:     <none>
+----
+<1> The token name, which is the sha256 hash of the token. Token names are not sensitive and cannot be used to log in.
+<2> The client name, which describes where the token originated from.
+<3> The value in seconds from the creation time before this token expires.
+<4> If there is a token inactivity timeout set for the OAuth server, this is the value in seconds from the creation time before this token can no longer be used.
+<5> The scopes for this token.
+<6> The user name associated with this token.