OSDOCS-16969-config-keystone CQA

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

@@ -6,7 +6,8 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-Configure the `keystone` identity provider to integrate your {product-title} cluster with Keystone to enable shared authentication with an OpenStack Keystone v3 server configured to store users in an internal database. This configuration allows users to log in to {product-title} with their Keystone credentials.
+[role="_abstract"]
+Configure a Keystone identity provider to connect {product-title} to an OpenStack Keystone v3 server so users can sign in with Keystone credentials.
 
 include::modules/identity-provider-overview.adoc[leveloffset=+1]
 
@@ -22,6 +23,12 @@ include::modules/identity-provider-keystone-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]
+
+[role="_additional-resources"]
+[id="additional-resources-keystone_{context}"]
+== Additional resources
+
+* link:http://docs.openstack.org/developer/keystone/[Keystone]

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 OAuth custom resource to add an identity provider to your cluster so users can authenticate with external credentials instead of the default `kubeadmin` user.
 
 .Prerequisites
 
-* Create an {product-title} cluster.
-* Create the custom resource (CR) for your identity providers.
-* You must be logged in as an administrator.
+* An {product-title} cluster is installed.
+* The custom resource (CR) for your identity provider is defined.
+* You are 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 as a user from your identity provider by running the following command, which prompts for your user name and password:
 +
 [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, passing in the token to authenticate:
 +
 [source,terminal]
 ----
@@ -82,7 +81,7 @@ $ oc login --token=<token>
 ifdef::oidc[]
 If your OpenID Connect identity provider supports the resource owner password credentials (ROPC) grant flow, you can log in with a user name and password. You might need to take steps to enable the ROPC grant flow for your identity provider.
 
-After the OIDC identity provider is configured in {product-title}, you can log in by using the following command, which prompts for your user name and password:
+After the OIDC identity provider is configured in {product-title}, you can log in by running the following command, which prompts for your user name and password:
 
 [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 that the user name displays by running the following command:
 +
 [source,terminal]
 ----

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 in the `openshift-config` namespace to store the certificate authority bundle for your identity provider, so the OAuth custom resource can validate TLS connections to the authentication server.
 
 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 a `ConfigMap` object containing the certificate authority by running the following command. The certificate authority must be stored in the `ca.crt` key of the `ConfigMap` object.
 +
 [source,terminal]
 ----

modules/identity-provider-keystone-CR.adoc

@@ -6,10 +6,8 @@
 [id="identity-provider-keystone-CR_{context}"]
 = Sample Keystone CR
 
-The following custom resource (CR) shows the parameters and acceptable values for a
-Keystone identity provider.
-
-.Keystone CR
+[role="_abstract"]
+Use this sample OAuth custom resource to configure Keystone identity provider parameters, so you can apply the configuration with the correct domain, URL, certificate authority, and TLS client certificate settings.
 
 [source,yaml]
 ----
@@ -19,28 +17,26 @@ metadata:
   name: cluster
 spec:
   identityProviders:
-  - name: keystoneidp <1>
-    mappingMethod: claim <2>
+  - name: keystoneidp
+    mappingMethod: claim
     type: Keystone
     keystone:
-      domainName: default <3>
-      url: https://keystone.example.com:5000 <4>
-      ca: <5>
+      domainName: default
+      url: https://keystone.example.com:5000
+      ca:
         name: ca-config-map
-      tlsClientCert: <6>
+      tlsClientCert:
         name: client-cert-secret
-      tlsClientKey: <7>
+      tlsClientKey:
         name: client-key-secret
 ----
-<1> This provider name is prefixed to provider user names to form an identity name.
-<2> Controls how mappings are established between this provider's identities and `User` objects.
-<3> Keystone domain name. In Keystone, usernames are domain-specific. Only a single domain is supported.
-<4> The URL to use to connect to the Keystone server (required). This must
-use https.
-<5> 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.
-<6> Optional: Reference to an {product-title} `Secret` object containing the client
-certificate to present when making requests to the configured URL.
-<7> Reference to an {product-title} `Secret` object containing the key for the
-client certificate. Required if `tlsClientCert` is specified.
+
+where:
+
+`spec.identityProviders.name`:: This provider name is prefixed to provider user names to form an identity name.
+`spec.identityProviders.mappingMethod`:: Controls how mappings are established between identities from this provider and `User` objects.
+`spec.identityProviders.keystone.domainName`:: Keystone domain name. In Keystone, usernames are domain-specific. Only a single domain is supported.
+`spec.identityProviders.keystone.url`:: The URL to use to connect to the Keystone server (required). This must use `https`.
+`spec.identityProviders.keystone.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.
+`spec.identityProviders.keystone.tlsClientCert`:: Optional. Reference to an {product-title} `Secret` object containing the client certificate to present when making requests to the configured URL.
+`spec.identityProviders.keystone.tlsClientKey`:: Reference to an {product-title} `Secret` object containing the key for the client certificate. Required if `tlsClientCert` is specified.

modules/identity-provider-keystone-about.adoc

@@ -6,6 +6,7 @@
 [id="identity-provider-keystone-about_{context}"]
 = About Keystone authentication
 
-link:http://docs.openstack.org/developer/keystone/[Keystone] is an OpenStack project that provides identity, token, catalog, and policy services.
+[role="_abstract"]
+Allow users to sign in to {product-title} with Keystone credentials so authentication is shared with your OpenStack Keystone server. Map users by Keystone ID to reduce access risk when user names are reused.
 
-You can configure the integration with Keystone so that the new {product-title} users are based on either the Keystone user names or unique Keystone IDs. With both methods, users log in by entering their Keystone user name and password. Basing the {product-title} users on the Keystone ID is more secure because if you delete a Keystone user and create a new Keystone user with that user name, the new user might have access to the old user's resources.
+Map {product-title} users to Keystone user names or unique Keystone IDs. Users log in with their Keystone user name and password. Basing users on the Keystone ID is more secure. If you delete a Keystone user and create a new user with that user name, the new user might have access to resources of the deleted user.

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 Transport Layer Security (TLS) Secret in the `openshift-config` namespace to store the client certificate and key for your identity provider, so the OAuth custom resource can reference them without exposing sensitive values.
 
 .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]
 ----