[enterprise-4.18] [OSDOCS-12792]More Secure Auth Flows in ROSA CLIs

modules/ccs-gcp-customer-procedure-wif.adoc

@@ -39,24 +39,45 @@ Besides the required customer procedures listed in _Required customer procedure_
 
 . Install the link:https://console.redhat.com/openshift/downloads[OpenShift Cluster Manager API command-line interface (`ocm`)].
 +
-To use the OCM CLI, you must authenticate against your Red Hat {cluster-manager} account. This is accomplished with the {cluster-manager} API token.
-+
-You can obtain your token link:https://console.redhat.com/openshift/token/show[here].
 
-. To authenticate against your Red Hat {cluster-manager} account, run the following command:
-+
-[source,terminal]
-----
-$ ocm login --token <token> <1>
-----
-<1> Replace `<token>` with your {cluster-manager} API token.
-+
 [IMPORTANT]
 ====
 [subs="attributes+"]
 OpenShift Cluster Manager API command-line interface (`ocm`) is a Developer Preview feature only.
 For more information about the support scope of Red Hat Developer Preview features, see link:https://access.redhat.com/support/offerings/devpreview/[Developer Preview Support Scope].
 ====
++
+// To use the OCM CLI, you must authenticate against your Red Hat {cluster-manager} account. This is accomplished with the {cluster-manager} API token.
+// +
+// You can obtain your token link:https://console.redhat.com/openshift/token/show[here].
+
+. To authenticate against your Red Hat {cluster-manager} account, run one of the following commands.
+
+.. If your system supports a web-based browser, run the Red{nbsp}Hat single sign-on (SSO) authorization code command for secure authentication:
++
+.Syntax
+[source,terminal]
+----
+$ ocm login --use-auth-code
+----
++
+Running this command will redirect you to the Red Hat SSO login. Log in with your Red{nbsp}Hat login or email.
++
+.. If you are working with containers, remote hosts, and other environments without a web browser, run the Red{nbsp}Hat single sign-on (SSO) device code command for secure authentication:
+
++
+.Syntax
+[source,terminal]
+----
+$ ocm login --use-device-code
+----
+Running this command will redirect you to the Red{nbsp}Hat SSO login and provide a log in code.
+
++
+
+To switch accounts, logout from https://sso.redhat.com and run the `ocm logout` command in your terminal before attempting to login again.
+
++
 
 . Install the link:https://cloud.google.com/sdk/docs/install[gcloud CLI].
 +

modules/rosa-configure.adoc

@@ -10,22 +10,116 @@ Use the following commands to configure the {product-title} (ROSA) CLI, `rosa`.
 
 [id="rosa-login_{context}"]
 == 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.
+
+[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.
+====
+
+// 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.
+// ====
 
-Log in to your Red{nbsp}Hat account, saving the credentials to the `rosa` configuration file. You must provide a token when logging in. You can copy your token from link:https://console.redhat.com/openshift/token/rosa[the ROSA token page].
 
-The ROSA CLI (`rosa`) looks for a token in the following priority order:
+[id="rosa-login-sso_{context}"]
+=== login with single sign-on (SSO) authorization code
 
-. Command-line arguments
-. The `ROSA_TOKEN` environment variable
-. The `rosa` configuration file
-. Interactively from a command-line prompt
+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.
+
+[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:
+
++
 .Syntax
 [source,terminal]
 ----
-$ rosa login [arguments]
+$ 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.
++
+.Optional arguments inherited from parent commands
+[cols="30,70"]
+|===
+|Option |Definition
+
+|--help
+|Shows help for this command.
+
+|--debug
+|Enables debug mode.
+
+|===
++
+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.
+[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:
+
++
+.Syntax
+[source,terminal]
 ----
+$ rosa login --use-device-code
+----
++
+Running this command will redirect you to the Red Hat SSO login and provide a log in code.
++
+.Optional arguments inherited from parent commands
+[cols="30,70"]
+|===
+|Option |Definition
+
+|--help
+|Shows help for this command.
+
+|--debug
+|Enables debug mode.
+
+|===
++
+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-token_{context}"]
+=== login with an offline token
 
+Log in to your Red{nbsp}Hat account, saving the credentials to the `rosa` configuration file.
+
+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]
+====
+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:
++
+.Syntax
+[source,terminal]
+----
+$ rosa login [arguments]
+----
++
 .Arguments
 [cols="30,70"]
 |===
@@ -49,7 +143,7 @@ $ rosa login [arguments]
 |--token-url
 |The OpenID token URL (string). Default: `\https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token`
 |===
-
++
 .Optional arguments inherited from parent commands
 [cols="30,70"]
 |===