Merge pull request #97218 from openshift-cherrypick-robot/cherry-pick-95714-to-enterprise-4.19

[enterprise-4.19] [OSDOCS-15132]Improve the ROSA docs for secure auth flows (XCMSTRAT-600)

Author: mletalie

modules/rosa-configure.adoc

@@ -12,26 +12,38 @@ Use the following commands to configure the {product-title} (ROSA) CLI, `rosa`.
 == login
 There are several methods you can use to log into your Red{nbsp}Hat account using the {product-title} (ROSA) CLI (`rosa`). These methods are described in detail below.
 
+[id="rosa-login-sso_{context}"]
+=== Authenticating the ROSA CLI with Red Hat single sign-on
+
+You can log in to the ROSA CLI (`rosa`) with Red{nbsp}Hat single sign-on. Red{nbsp}Hat recommends using the `rosa` command line tool with Red{nbsp}Hat single sign-on, instead of using an offline authentication token.
+
+An offline authentication token is long-lived, stored on your operating system, and cannot be revoked. These factors increase overall security risks and the likelihood of unauthorized access to your account.
+
+Alternatively, authenticating with the Red{nbsp}Hat single sign-on method automatically sends your `rosa` instance a refresh token that is valid for 10 hours. This unique, temporary authorization code enhances security and reduces the risk of unauthorized access.
+
 [IMPORTANT]
 ====
-An offline authentication token is long-lived, stored on your operating system, and cannot be revoked. These factors increase overall security risks and the likelihood of unauthorized access to your account. Alternatively, the Red{nbsp}Hat secure browser-based single sign-on (SSO) method automatically sends your CLI instance a refresh token that is valid for 10 hours. Because this authorization code is unique and temporary, it is more secure and is the Red{nbsp}Hat recommended method of authentication.
+The method of authenticating using Red Hat single sign-on does not break any existing automations that rely on offline tokens. Red{nbsp}Hat recommends using link:https://console.redhat.com/iam/service-accounts[services accounts] for automation purposes. If you still need to use offline tokens for automation or other purposes, you can download the OpenShift Cluster Manager API token from the link:https://console.redhat.com/openshift/token[OpenShift Cluster Manager API Token] page.
 ====
 
-// Furthermore, offline authentication tokens are usually stored on your device by your operating system, which means other apps on your machine can access a token if the token is not properly secured. These offline tokens are long-lived and cannot be revoked. Users must copy and paste them manually which creates a security risk. Because of these factors, Red{nbsp}Hat recommends using the single sign-on method when logging into your account with the ROSA CLI (`rosa`). This method is more secure than logging in with an offline token.
-// ====
+Use one of the following methods of authentication:
 
+* If your system has a web browser, see the "Authenticating the ROSA CLI with a single sign-on authorization code" section to authenticate with Red Hat single sign-on.
 
-[id="rosa-login-sso_{context}"]
-=== login with single sign-on (SSO) authorization code
+* If you are working with containers, remote hosts, or other environments without a web browser, see the "Authenticating the ROSA CLI with a single sign-on device code" section to authenticate with Red Hat single sign-on.
 
-If your system supports a web-based browser, you can log in to the ROSA CLI (`rosa`) with a Red{nbsp}Hat single sign-on (SSO) authorization code.
+* To authenticate the ROSA CLI using an offline token, see the "Authenticating the ROSA CLI with an offline token" section.
 
 [NOTE]
 ====
 Single sign-on authorization is supported with ROSA CLI (`rosa`) version 1.2.36 or later.
 ====
 
-. To log into the ROSA CLI (`rosa`) with a Red{nbsp}Hat single sign-on authorization code, run the following command:
+[id="rosa-login-sso_auth{context}"]
+=== Authenticating the ROSA CLI with a single sign-on authorization code
+
+
+* To log in to the ROSA CLI (`rosa`) with a Red{nbsp}Hat single sign-on authorization code, run the following command:
 
 +
 .Syntax
@@ -40,7 +52,7 @@ Single sign-on authorization is supported with ROSA CLI (`rosa`) version 1.2.36
 $ rosa login --use-auth-code
 ----
 +
-Running this command will redirect you to the Red{nbsp}Hat SSO login. Log in with your Red{nbsp}Hat login or email.
+Running this command redirects you to the Red{nbsp}Hat single sign-on login. Log in with your Red{nbsp}Hat login or email.
 +
 .Optional arguments inherited from parent commands
 [cols="30,70"]
@@ -58,13 +70,13 @@ Running this command will redirect you to the Red{nbsp}Hat SSO login. Log in wit
 To switch accounts, logout from link:https://sso.redhat.com[https://sso.redhat.com] and run the `rosa logout` command in your terminal before attempting to login again.
 
 [id="rosa-login-sso-device_{context}"]
-=== login with a single sign-on device code
-If you are working with containers, remote hosts, and other environments without a web browser, you can use a Red{nbsp}Hat single sign-on (SSO) device code for secure authentication. To do this, you must use a second device that has a web browser to approve the login.
+=== Authenticating the ROSA CLI with a single sign-on device code
+If you are working with containers, remote hosts, and other environments without a web browser, you can use a Red{nbsp}Hat single sign-on device code for secure authentication. To do this, you must use a second device that has a web browser to approve the login.
 [NOTE]
 ====
 Single sign-on authorization is supported with ROSA CLI (`rosa`) version 1.2.36 or later.
 ====
-. To log in to ROSA CLI (`rosa`) with a Red Hat single sign-on device code, run the following command:
+* To log in to the ROSA CLI (`rosa`) with a Red Hat single sign-on device code, run the following command:
 
 +
 .Syntax
@@ -92,27 +104,22 @@ To switch accounts, logout from link:https://sso.redhat.com[https://sso.redhat.c
 
 
 [id="rosa-login-token_{context}"]
-=== login with an offline token
+=== Authenticating the ROSA CLI with an offline token
 
 Log in to your Red{nbsp}Hat account, saving the credentials to the `rosa` configuration file.
 
+[NOTE]
+====
 To use offline tokens for automation purposes, you can download the OpenShift Cluster Manager API token from the link:https://console.redhat.com/openshift/token/rosa[OpenShift Cluster Manager API Token] page.
-
 To use service accounts for automation purposes, see the link:https://console.redhat.com/iam/service-accounts[Service Accounts] page.
+====
 
-[NOTE]
+[IMPORTANT]
 ====
 Red{nbsp}Hat recommends using service accounts for automation purposes.
 ====
 
-// The ROSA CLI (`rosa`) looks for a token in the following priority order:
-
-// . Command-line arguments
-// . The `ROSA_TOKEN` environment variable
-// . The `rosa` configuration file
-// . Interactively from a command-line prompt
-
-. To log in to ROSA CLI (`rosa`) with a Red{nbsp}Hat offline token, run the following command:
+* To log in to ROSA CLI (`rosa`) with a Red{nbsp}Hat offline token, run the following command:
 +
 .Syntax
 [source,terminal]