OSDOCS-16959-config-basic-auth CQA

authentication/identity_providers/configuring-basic-authentication-identity-provider.adoc

@@ -6,7 +6,8 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-Configure the `basic-authentication` identity provider for users to log in to {product-title} with credentials validated against a remote identity provider. Basic authentication is a generic back-end integration mechanism.
+[role="_abstract"]
+Configure the `basic-authentication` identity provider. Users can log in to {product-title} with credentials validated against a remote authentication service, without maintaining a separate user store in the cluster.
 
 include::modules/identity-provider-overview.adoc[leveloffset=+1]
 
@@ -22,7 +23,7 @@ include::modules/identity-provider-basic-authentication-CR.adoc[leveloffset=+1]
 [role="_additional-resources"]
 .Additional resources
 
-* See xref:../../authentication/understanding-identity-provider.adoc#identity-provider-parameters_understanding-identity-provider[Identity provider parameters] for information on parameters, such as `mappingMethod`, that are common to all identity providers.
+* xref:../../authentication/understanding-identity-provider.adoc#identity-provider-parameters_understanding-identity-provider[Identity provider parameters]
 
 include::modules/identity-provider-add.adoc[leveloffset=+1]
 

modules/example-apache-httpd-configuration.adoc

@@ -6,11 +6,11 @@
 [id="example-apache-httpd-configuration_{context}"]
 = Example Apache HTTPD configuration for basic identity providers
 
-The basic identify provider (IDP) configuration in {product-title} 4 requires
-that the IDP server respond with JSON for success and failures. You can use CGI
-scripting in Apache HTTPD to accomplish this. This section provides examples.
+[role="_abstract"]
+Review the example Apache HTTPD configuration when you need to set up a remote authentication server that returns JSON success and failure responses for basic identity providers in {product-title}.
 
 .Example `/etc/httpd/conf.d/login.conf`
+
 ----
 <VirtualHost *:443>
   # CGI Scripts in here
@@ -41,6 +41,7 @@ scripting in Apache HTTPD to accomplish this. This section provides examples.
 ----
 
 .Example `/var/www/cgi-bin/login.cgi`
+
 ----
 #!/bin/bash
 echo "Content-Type: application/json"
@@ -50,6 +51,7 @@ exit 0
 ----
 
 .Example `/var/www/cgi-bin/fail.cgi`
+
 ----
 #!/bin/bash
 echo "Content-Type: application/json"
@@ -58,16 +60,12 @@ echo '{"error": "Login failure"}'
 exit 0
 ----
 
+[id="example-apache-httpd-file-requirements_{context}"]
 == File requirements
 
-These are the requirements for the files you create on an Apache HTTPD web
-server:
+These are the requirements for the files you create on an Apache HTTPD web server:
 
 * `login.cgi` and `fail.cgi` must be executable (`chmod +x`).
-* `login.cgi` and `fail.cgi` must have proper SELinux contexts if SELinux is
-enabled: `restorecon -RFv /var/www/cgi-bin`, or ensure that the context is
-`httpd_sys_script_exec_t` using `ls -laZ`.
-* `login.cgi` is only executed if your user successfully logs in per `Require
-and Auth` directives.
-* `fail.cgi` is executed if the user fails to log in, resulting in an `HTTP 401`
-response.
+* `login.cgi` and `fail.cgi` must have proper SELinux contexts if SELinux is enabled: `restorecon -RFv /var/www/cgi-bin`, or ensure that the context is `httpd_sys_script_exec_t` using `ls -laZ`.
+* `login.cgi` is only executed if your user successfully logs in per `Require and Auth` directives.
+* `fail.cgi` is executed if the user fails to log in, resulting in an `HTTP 401` response.

modules/identity-provider-about-basic-authentication.adoc

@@ -6,39 +6,30 @@
 [id="identity-provider-about-basic-authentication_{context}"]
 = About basic authentication
 
-Basic authentication is a generic back-end integration mechanism that allows
-users to log in to {product-title} with credentials validated against a remote
-identity provider.
+[role="_abstract"]
+Review how basic authentication validates user credentials against a remote service over HTTP basic authentication. Use this integration when you need a flexible back-end for username and password login in {product-title}.
 
-Because basic authentication is generic, you can use this identity
-provider for advanced authentication configurations.
+Basic authentication is a generic back-end integration mechanism that allows users to log in to {product-title} with credentials validated against a remote identity provider.
+
+Because basic authentication is generic, you can use this identity provider for advanced authentication configurations.
 
 [IMPORTANT]
 ====
-Basic authentication must use an HTTPS connection to the remote server to
-prevent potential snooping of the user ID and password and man-in-the-middle
-attacks.
+Basic authentication must use an HTTPS connection to the remote server to prevent potential snooping of the user ID and password and man-in-the-middle attacks.
 ====
 
-With basic authentication configured, users send their user name
-and password to {product-title}, which then validates those credentials against
-a remote server by making a server-to-server request, passing the credentials as
-a basic authentication header. This requires users to send their credentials to
-{product-title} during login.
+With basic authentication configured, users send their user name and password to {product-title}, which then validates those credentials against a remote server by making a server-to-server request, passing the credentials as a basic authentication header. This requires users to send their credentials to {product-title} during login.
 
 [NOTE]
 ====
-This only works for user name/password login mechanisms, and {product-title} must
-be able to make network requests to the remote authentication server.
+This only works for user name/password login mechanisms, and {product-title} must be able to make network requests to the remote authentication server.
 ====
 
-User names and passwords are validated against a remote URL that is protected
-by basic authentication and returns JSON.
+User names and passwords are validated against a remote URL that is protected by basic authentication and returns JSON.
 
 A `401` response indicates failed authentication.
 
-A non-`200` status, or the presence of a non-empty "error" key, indicates an
-error:
+A non-`200` status, or the presence of a non-empty "error" key, indicates an error:
 
 [source,terminal]
 ----
@@ -49,9 +40,12 @@ A `200` status with a `sub` (subject) key indicates success:
 
 [source,terminal]
 ----
-{"sub":"userid"} <1>
+{"sub":"userid"}
 ----
-<1> The subject must be unique to the authenticated user and must not be able to
+
+where:
+
+`userid`:: Must be unique to the authenticated user and must not be able to
 be modified.
 
 A successful response can optionally provide additional data, such as:
@@ -70,12 +64,10 @@ A successful response can optionally provide additional data, such as:
 {"sub":"userid", "email":"user@example.com", ...}
 ----
 +
-* A preferred user name using the `preferred_username` key. This is useful when
-the unique, unchangeable subject is a database key or UID, and a more
-human-readable name exists. This is used as a hint when provisioning the
-{product-title} user for the authenticated identity. For example:
+* A preferred user name using the `preferred_username` key. This is useful when the unique, unchangeable subject is a database key or UID, and a more human-readable name exists. This is used as a hint when provisioning the {product-title} user for the authenticated identity. For example:
 +
 [source,terminal]
 ----
 {"sub":"014fbff9a07c", "preferred_username":"bob", ...}
 ----
+

modules/identity-provider-add.adoc

@@ -29,18 +29,18 @@ endif::[]
 [id="add-identity-provider_{context}"]
 = Adding an identity provider to your cluster
 
-After you install your cluster, add an identity provider to it so your
-users can authenticate.
+[role="_abstract"]
+Apply the identity provider custom resource (CR) to your cluster so users can authenticate with the configured identity provider.
 
 .Prerequisites
 
 * Create an {product-title} cluster.
-* Create the custom resource (CR) for your identity providers.
+* Create the CR for your identity providers.
 * You must be logged in as an administrator.
 
 .Procedure
 
-. Apply the defined CR:
+. Apply the defined CR by running the following command:
 +
 [source,terminal]
 ----
@@ -53,8 +53,7 @@ If a CR does not exist, `oc apply` creates a new CR and might trigger the follow
 ====
 
 ifndef::no-username-password-login[]
-. Log in to the cluster as a user from your identity provider, entering the
-password when prompted.
+. Log in to the cluster with credentials from the configured identity provider by running the following command. Enter the password when prompted:
 +
 [source,terminal]
 ----
@@ -70,7 +69,7 @@ As long as the `kubeadmin` user has been removed, the `oc login` command provide
 +
 You can also access this page from the web console by navigating to *(?) Help* -> *Command Line Tools* -> *Copy Login Command*.
 
-. Log in to the cluster, passing in the token to authenticate.
+. Log in to the cluster by running the following command and pass in the token to authenticate:
 +
 [source,terminal]
 ----
@@ -96,7 +95,7 @@ endif::oidc[]
 ====
 endif::no-username-password-login[]
 
-. Confirm that the user logged in successfully, and display the user name.
+. Confirm that the user logged in successfully and the username displays by running the following command:
 +
 [source,terminal]
 ----

modules/identity-provider-basic-authentication-CR.adoc

@@ -6,8 +6,8 @@
 [id="identity-provider-basic-authentication-CR_{context}"]
 = Sample basic authentication CR
 
-The following custom resource (CR) shows the parameters and acceptable values for a
-basic authentication identity provider.
+[role="_abstract"]
+Review the sample basic authentication `OAuth` custom resource (CR) to understand provider parameters and acceptable values before you configure the identity provider in your cluster.
 
 .Basic authentication CR
 
@@ -19,26 +19,27 @@ metadata:
   name: cluster
 spec:
   identityProviders:
-  - name: basicidp <1>
-    mappingMethod: claim <2>
+  - name: basicidp
+    mappingMethod: claim
     type: BasicAuth
     basicAuth:
-      url: https://www.example.com/remote-idp <3>
-      ca: <4>
+      url: https://www.example.com/remote-idp
+      ca:
         name: ca-config-map
-      tlsClientCert: <5>
+      tlsClientCert:
         name: client-cert-secret
-      tlsClientKey: <6>
+      tlsClientKey:
         name: client-key-secret
 ----
-<1> This provider name is prefixed to the returned user ID to form an identity
+
+where:
+
+`spec.identityProviders.name`:: Specifies that the provider name is prefixed to the returned user ID to form an identity
 name.
-<2> Controls how mappings are established between this provider's identities and `User` objects.
-<3> URL accepting credentials in Basic authentication headers.
-<4> Optional: Reference to an {product-title} `ConfigMap` object containing the
-PEM-encoded certificate authority bundle to use in validating server
+`spec.identityProviders.mappingMethod`:: Controls how mappings are established between the identities of this provider and `User` objects.
+`spec.identityProviders.basicAuth.url`:: URL accepting credentials in Basic authentication headers.
+`spec.identityProviders.basicAuth.ca`:: Optional: Reference to an {product-title} `ConfigMap` object containing the PEM-encoded certificate authority bundle to use in validating server
 certificates for the configured URL.
-<5> Optional: Reference to an {product-title} `Secret` object containing the client
-certificate to present when making requests to the configured URL.
-<6> Reference to an {product-title} `Secret` object containing the key for the
-client certificate. Required if `tlsClientCert` is specified.
+`spec.identityProviders.basicAuth.tlsClientCert`:: Optional: Reference to an {product-title} `Secret` object containing the client certificate to present when making requests to the configured URL.
+`spec.identityProviders.basicAuth.tlsClientKey`:: Reference to an {product-title} `Secret` object containing the key for the client certificate. Required if `tlsClientCert` is specified.
+

modules/identity-provider-basic-authentication-troubleshooting.adoc

@@ -6,30 +6,34 @@
 [id="identity-provider-basic-authentication-troubleshooting_{context}"]
 = Basic authentication troubleshooting
 
-The most common issue relates to network connectivity to the backend server. For
-simple debugging, run `curl` commands on the master. To test for a successful
-login, replace the `<user>` and `<password>` in the following example command
-with valid credentials. To test an invalid login, replace them with false
-credentials.
+[role="_abstract"]
+Troubleshoot basic authentication by testing backend connectivity and verifying JSON login responses when users cannot authenticate in {product-title}.
 
+The most common issue relates to network connectivity to the backend server. For simple debugging, run `curl` commands on a control plane node.
+
+.Procedure
+
+. To test successful and unsuccessful logins, replace the `<user>` and `<password>` in the following example command with valid or invalid credentials:
++
 [source,terminal]
 ----
 $ curl --cacert /path/to/ca.crt --cert /path/to/client.crt --key /path/to/client.key -u <user>:<password> -v https://www.example.com/remote-idp
 ----
 
-*Successful responses*
-
+. Review successful login responses.
++
 A `200` status with a `sub` (subject) key indicates success:
-
++
 [source,terminal]
 ----
 {"sub":"userid"}
 ----
-The subject must be unique to the authenticated user, and must not be able to
-be modified.
-
++
+The subject must be unique to the authenticated user, and must not be able to be modified.
++
 A successful response can optionally provide additional data, such as:
-
++
+--
 * A display name using the `name` key:
 +
 [source,terminal]
@@ -48,14 +52,14 @@ A successful response can optionally provide additional data, such as:
 ----
 {"sub":"014fbff9a07c", "preferred_username":"bob", ...}
 ----
+--
 +
-The `preferred_username` key is useful when
-the unique, unchangeable subject is a database key or UID, and a more
-human-readable name exists. This is used as a hint when provisioning the
-{product-title} user for the authenticated identity.
-
-*Failed responses*
+The `preferred_username` key is useful when the unique, unchangeable subject is a database key or UID, and a more human-readable name exists. This is used as a hint when provisioning the {product-title} user for the authenticated identity.
 
+. Review failed login responses.
++
+--
 - A `401` response indicates failed authentication.
 - A non-`200` status or the presence of a non-empty "error" key indicates an
 error: `{"error":"Error message"}`
+--

modules/identity-provider-config-map.adoc

@@ -15,9 +15,8 @@ endif::[]
 [id="identity-provider-creating-configmap_{context}"]
 = Creating a config map
 
-Identity providers use {product-title} `ConfigMap` objects in the `openshift-config`
-namespace to contain the certificate authority bundle. These are primarily
-used to contain certificate bundles needed by the identity provider.
+[role="_abstract"]
+Create a `ConfigMap` object in the `openshift-config` namespace to store the certificate authority bundle that identity providers use to validate secure connections to the remote authentication service.
 
 ifdef::github[]
 [NOTE]
@@ -28,9 +27,7 @@ endif::github[]
 
 .Procedure
 
-* Define an {product-title} `ConfigMap` object containing the
-certificate authority by using the following command. The certificate
-authority must be stored in the `ca.crt` key of the `ConfigMap` object.
+* Define an {product-title} `ConfigMap` object containing the certificate authority by using the following command. The certificate authority must be stored in the `ca.crt` key of the `ConfigMap` object.
 +
 [source,terminal]
 ----
@@ -39,7 +36,7 @@ $ oc create configmap ca-config-map --from-file=ca.crt=/path/to/ca -n openshift-
 +
 [TIP]
 ====
-You can alternatively apply the following YAML to create the config map:
+You can also apply the following YAML to create the config map:
 
 [source,yaml]
 ----

modules/identity-provider-secret-tls.adoc

@@ -7,11 +7,12 @@
 [id="identity-provider-creating-secret-tls_{context}"]
 = Creating the secret
 
-Identity providers use {product-title} `Secret` objects in the `openshift-config` namespace to contain the client secret, client certificates, and keys.
+[role="_abstract"]
+Create a TLS `Secret` object in the `openshift-config` namespace to store client certificates and keys that identity providers use for secure communication with the remote authentication service.
 
 .Procedure
 
-* Create a `Secret` object that contains the key and certificate by using the following command:
+* Create a `Secret` object that contains the key and certificate by running the following command:
 +
 [source,terminal]
 ----
@@ -20,7 +21,7 @@ $ oc create secret tls <secret_name> --key=key.pem --cert=cert.pem -n openshift-
 +
 [TIP]
 ====
-You can alternatively apply the following YAML to create the secret:
+You can also apply the following YAML to create the secret:
 
 [source,yaml]
 ----