From 675f8ee195ef6d4dc61eb144d8abd696d1cc2a22 Mon Sep 17 00:00:00 2001 From: William Gabor Date: Thu, 23 Jul 2026 15:52:53 -0400 Subject: [PATCH] OSDOCS-16959-config-basic-auth CQA --- ...asic-authentication-identity-provider.adoc | 5 ++- .../example-apache-httpd-configuration.adoc | 22 +++++----- ...y-provider-about-basic-authentication.adoc | 42 ++++++++----------- modules/identity-provider-add.adoc | 15 ++++--- ...tity-provider-basic-authentication-CR.adoc | 35 ++++++++-------- ...-basic-authentication-troubleshooting.adoc | 40 ++++++++++-------- modules/identity-provider-config-map.adoc | 11 ++--- modules/identity-provider-secret-tls.adoc | 7 ++-- 8 files changed, 85 insertions(+), 92 deletions(-) diff --git a/authentication/identity_providers/configuring-basic-authentication-identity-provider.adoc b/authentication/identity_providers/configuring-basic-authentication-identity-provider.adoc index 70691f0be455..9b9b47c80e46 100644 --- a/authentication/identity_providers/configuring-basic-authentication-identity-provider.adoc +++ b/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] diff --git a/modules/example-apache-httpd-configuration.adoc b/modules/example-apache-httpd-configuration.adoc index 24ecad4b5353..8e0ba7e05f53 100644 --- a/modules/example-apache-httpd-configuration.adoc +++ b/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` + ---- # 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. diff --git a/modules/identity-provider-about-basic-authentication.adoc b/modules/identity-provider-about-basic-authentication.adoc index 417edb7591e9..218caa3138c7 100644 --- a/modules/identity-provider-about-basic-authentication.adoc +++ b/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", ...} ---- + diff --git a/modules/identity-provider-add.adoc b/modules/identity-provider-add.adoc index d6a460a966cc..b263cffbb5de 100644 --- a/modules/identity-provider-add.adoc +++ b/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] ---- diff --git a/modules/identity-provider-basic-authentication-CR.adoc b/modules/identity-provider-basic-authentication-CR.adoc index dbd8126a7285..1e99dfb982d7 100644 --- a/modules/identity-provider-basic-authentication-CR.adoc +++ b/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. + diff --git a/modules/identity-provider-basic-authentication-troubleshooting.adoc b/modules/identity-provider-basic-authentication-troubleshooting.adoc index 2364aedea873..fbf59eb0b0b4 100644 --- a/modules/identity-provider-basic-authentication-troubleshooting.adoc +++ b/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 `` and `` 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 `` and `` 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 : -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"}` +-- diff --git a/modules/identity-provider-config-map.adoc b/modules/identity-provider-config-map.adoc index e403dd031eac..88bd3391cf02 100644 --- a/modules/identity-provider-config-map.adoc +++ b/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] ---- diff --git a/modules/identity-provider-secret-tls.adoc b/modules/identity-provider-secret-tls.adoc index 85259addf132..1f12de781d32 100644 --- a/modules/identity-provider-secret-tls.adoc +++ b/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 --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] ----