diff --git a/authentication/identity_providers/configuring-request-header-identity-provider.adoc b/authentication/identity_providers/configuring-request-header-identity-provider.adoc index daf3f8cd4764..60581fe9a63b 100644 --- a/authentication/identity_providers/configuring-request-header-identity-provider.adoc +++ b/authentication/identity_providers/configuring-request-header-identity-provider.adoc @@ -17,3 +17,15 @@ include::modules/identity-provider-config-map.adoc[leveloffset=+1] include::modules/identity-provider-request-header-CR.adoc[leveloffset=+1] include::modules/identity-provider-add.adoc[leveloffset=+1] + +[id="example-apache-auth-config-using-request-header"] +== Example Apache authentication configuration using request header + +This example configures an Apache authentication proxy for the {product-title} +using the request header identity provider. + +[discrete] +include::modules/identity-provider-apache-custom-proxy-configuration.adoc[leveloffset=+2] + +[discrete] +include::modules/identity-provider-configuring-apache-request-header.adoc[leveloffset=+2] diff --git a/modules/identity-provider-apache-custom-proxy-configuration.adoc b/modules/identity-provider-apache-custom-proxy-configuration.adoc new file mode 100644 index 000000000000..a72ab94ceaee --- /dev/null +++ b/modules/identity-provider-apache-custom-proxy-configuration.adoc @@ -0,0 +1,34 @@ +// Module included in the following assemblies: +// +// * authentication/identity_providers/configuring-request-header-identity-provider.adoc + +[id="identity-provider-apache-custom-proxy-configuration_{context}"] += Custom proxy configuration + +Using the `mod_auth_gssapi` module is a popular way to configure the Apache +authentication proxy using the request header identity provider; however, it is +not required. Other proxies can easily be used if the following requirements are +met: + +* Block the `X-Remote-User` header from client requests to prevent spoofing. +* Enforce client certificate authentication in the `RequestHeaderIdentityProvider` +configuration. +* Require the `X-Csrf-Token` header be set for all authentication requests using +the challenge flow. +* Make sure only the `/oauth/authorize` endpoint and its subpaths are proxied; +redirects must be rewritten to allow the backend server to send the client to +the correct location. +* The URL that proxies to `\https:///oauth/authorize` must end +with `/authorize` with no trailing slash. For example, `\https://proxy.example.com/login-proxy/authorize?...` +must proxy to `\https:///oauth/authorize?...`. ++ +* Subpaths of the URL that proxies to `\https:///oauth/authorize` +must proxy to subpaths of `\https:///oauth/authorize`. For +example, `\https://proxy.example.com/login-proxy/authorize/approve?...` must +proxy to `\https:///oauth/authorize/approve?...`. + +[NOTE] +==== +The `\https://` address is the Route to the OAuth server and +can be obtained by running `oc get route -n openshift-authentication`. +==== diff --git a/modules/identity-provider-configuring-apache-request-header.adoc b/modules/identity-provider-configuring-apache-request-header.adoc index 2eb77415cc16..d19b49a7944b 100644 --- a/modules/identity-provider-configuring-apache-request-header.adoc +++ b/modules/identity-provider-configuring-apache-request-header.adoc @@ -1,114 +1,49 @@ // Module included in the following assemblies: // -// * orphaned +// * authentication/identity_providers/configuring-request-header-identity-provider.adoc [id="identity-provider-configuring-apache-request-header_{context}"] = Configuring Apache authentication using request header -This example configures an authentication proxy on the same host as the master. -Having the proxy and master on the same host is merely a convenience and may not -be suitable for your environment. For example, if you were already -running a router -on the master, port 443 would not be available. - -It is also important to note that while this reference configuration uses -Apache's `mod_auth_gssapi`, it is by no means required and other proxies can -easily be used if the following requirements are met: - -1. Block the `X-Remote-User` header from client requests to prevent spoofing. -2. Enforce client certificate authentication in the `RequestHeaderIdentityProvider` configuration. -3. Require the `X-Csrf-Token` header be set for all authentication request using the challenge flow. -4. Only the `/oauth/authorize` endpoint and its subpaths should be proxied, -and redirects should not be rewritten to allow the backend server to send the client to the correct -location. -5. The URL that proxies to `\https:///oauth/authorize` must end with `/authorize` (with no trailing slash). For example: - * `\https://proxy.example.com/login-proxy/authorize?...` -> `\https:///oauth/authorize?...` -6. Subpaths of the URL that proxies to `\https:///oauth/authorize` must proxy to subpaths of `\https:///oauth/authorize`. For example: - * `\https://proxy.example.com/login-proxy/authorize/approve?...` -> `\https:///oauth/authorize/approve?...` - -. Obtain the `mod_auth_gssapi` module from the +This example uses the `mod_auth_gssapi` module to configure an Apache +authentication proxy using the request header identity provider. + +.Prerequisites + +* Obtain the `mod_auth_gssapi` module from the link:https://access.redhat.com/solutions/392003[Optional channel]. -Install the following packages: +You must have the following packages installed on your local machine: + ----- -# yum install -y httpd mod_ssl mod_session apr-util-openssl mod_auth_gssapi ----- +** `httpd` +** `mod_ssl` +** `mod_session` +** `apr-util-openssl` +** `mod_auth_gssapi` -. Generate a CA for validating requests that submit the trusted header. Use this CA -as the file name for `clientCA` in the identity provider configuration. +* Generate a CA for validating requests that submit the trusted header. Define +an {product-title} ConfigMap containing the CA. This is done by running: + ---- -# oc adm ca create-signer-cert \ - --cert='/etc/origin/master/proxyca.crt' \ - --key='/etc/origin/master/proxyca.key' \ - --name='openshift-proxy-signer@1432232228' \ - --serial='/etc/origin/master/proxyca.serial.txt' +$ oc create configmap ca-config-map --from-file=ca.crt=/path/to/ca -n openshift-config ---- + -[NOTE] -==== -The `oc adm ca create-signer-cert` command generates a certificate that is valid -for five years. This can be altered with the `--expire-days` option, but for -security reasons, it is recommended to not make it greater than this -value. +The CA must be stored in the `ca.crt` key of the ConfigMap. -// Run `oc adm` commands only from the first master listed in the Ansible host inventory file, -// by default *_/etc/ansible/hosts_*. -==== +* Generate a client certificate for the proxy. You can generate this certificate +by using any x509 certificate tooling. The client certificate must be signed by +the CA you generated for validating requests that submit the trusted header. -. Generate a client certificate for the proxy. You can generate this certificate -by using any x509 certificate tooling, including the `oc adm` CLI: -+ ----- -# oc adm create-api-client-config \ - --certificate-authority='/etc/origin/master/proxyca.crt' \ - --client-dir='/etc/origin/master/proxy' \ - --signer-cert='/etc/origin/master/proxyca.crt' \ - --signer-key='/etc/origin/master/proxyca.key' \ - --signer-serial='/etc/origin/master/proxyca.serial.txt' \ - --user='system:proxy' <1> - -# pushd /etc/origin/master -# cp master.server.crt /etc/pki/tls/certs/localhost.crt <2> -# cp master.server.key /etc/pki/tls/private/localhost.key -# cp ca.crt /etc/pki/CA/certs/ca.crt -# cat proxy/system\:proxy.crt \ - proxy/system\:proxy.key > \ - /etc/pki/tls/certs/authproxy.pem -# popd ----- -<1> The user name can be anything, however it is useful to give it a descriptive -name as it will appear in logs. -<2> When running the authentication proxy on a different host name than the -master, it is important to generate a certificate that matches the host name -instead of using the default master certificate as shown above. The value for -`masterPublicURL` in the *_/etc/origin/master/master-config.yaml_* file -must be included in the `X509v3 Subject Alternative Name` in the certificate -that is specified for `SSLCertificateFile`. If a new certificate needs to be -created, the `oc adm ca create-server-cert` command can be used. -+ -[NOTE] -==== -The `oc adm create-api-client-config` command generates a certificate that is -valid for two years. This can be altered with the `--expire-days` option, but -for security reasons, it is recommended to not make it greater than -this value. -Run `oc adm` commands only from the first master listed in the Ansible host inventory file, -by default *_/etc/ansible/hosts_*. -==== +* Create the Custom Resource (CR) for your identity providers. -[discrete] -===== Configuring Apache +.Procedure -This proxy does not have to reside on the same -host as the master. It uses a client certificate to connect to the master, which +This proxy uses a client certificate to connect to the OAuth server, which is configured to trust the `X-Remote-User` header. . Create the certificate for the Apache configuration. The certificate that you specify as the `SSLProxyMachineCertificateFile` parameter value is the proxy's -client cert that is used to authenticate the proxy to the server. It must use -`TLS Web Client Authentication` as the extended key type. - +client certificate that is used to authenticate the proxy to the server. It must +use `TLS Web Client Authentication` as the extended key type. . Create the Apache configuration. Use the following template to provide your required settings and values: @@ -148,23 +83,19 @@ LoadModule auth_gssapi_module modules/mod_auth_gssapi.so SSLProxyEngine on SSLProxyCACertificateFile /etc/pki/CA/certs/ca.crt - # It's critical to enforce client certificates on the Master. Otherwise - # requests could spoof the X-Remote-User header by accessing the Master's - # /oauth/authorize endpoint directly. + # It is critical to enforce client certificates. Otherwise, requests can + # spoof the X-Remote-User header by accessing the /oauth/authorize endpoint + # directly. SSLProxyMachineCertificateFile /etc/pki/tls/certs/authproxy.pem - # Send all requests to the console - RewriteEngine On - RewriteRule ^/console(.*)$ https://%{HTTP_HOST}:8443/console$1 [R,L] - - # In order to using the challenging-proxy an X-Csrf-Token must be present. + # To use the challenging-proxy, an X-Csrf-Token must be present. RewriteCond %{REQUEST_URI} ^/challenging-proxy RewriteCond %{HTTP:X-Csrf-Token} ^$ [NC] RewriteRule ^.* - [F,L] # Insert your backend server name/ip here. - ProxyPass https://[MASTER]:8443/oauth/authorize + ProxyPass https:///oauth/authorize AuthName "SSO Login" # For Kerberos AuthType GSSAPI @@ -173,21 +104,18 @@ LoadModule auth_gssapi_module modules/mod_auth_gssapi.so GssapiCredStore keytab:/etc/httpd/protected/auth-proxy.keytab # Enable the following if you want to allow users to fallback - # to password based authntication when they do not have a client - # configured to perform kerberos authentication + # to password based authentication when they do not have a client + # configured to perform kerberos authentication. GssapiBasicAuth On # For ldap: # AuthBasicProvider ldap # AuthLDAPURL "ldap://ldap.example.com:389/ou=People,dc=my-domain,dc=com?uid?sub?(objectClass=*)" - - # It's possible to remove the mod_auth_gssapi usage and replace it with - # something like mod_auth_mellon, which only supports the login flow. # Insert your backend server name/ip here. - ProxyPass https://[MASTER]:8443/oauth/authorize + ProxyPass https:///oauth/authorize AuthName "SSO Login" AuthType GSSAPI @@ -196,8 +124,8 @@ LoadModule auth_gssapi_module modules/mod_auth_gssapi.so GssapiCredStore keytab:/etc/httpd/protected/auth-proxy.keytab # Enable the following if you want to allow users to fallback - # to password based authntication when they do not have a client - # configured to perform kerberos authentication + # to password based authentication when they do not have a client + # configured to perform kerberos authentication. GssapiBasicAuth On ErrorDocument 401 /login.html @@ -207,102 +135,96 @@ LoadModule auth_gssapi_module modules/mod_auth_gssapi.so RequestHeader unset X-Remote-User ---- ++ +[NOTE] +==== +The `\https://` address is the Route to the OAuth server and +can be obtained by running `oc get route -n openshift-authentication`. +==== -[discrete] -[id="requestheader-master-ca-config_{context}"] -===== Configuring the master - -The `identityProviders` stanza in the -*_/etc/origin/master/master-config.yaml_* file must be updated as well: - ----- - identityProviders: - - name: requestheader - challenge: true - login: true - provider: - apiVersion: v1 - kind: RequestHeaderIdentityProvider - challengeURL: "https://[MASTER]/challenging-proxy/oauth/authorize?${query}" - loginURL: "https://[MASTER]/login-proxy/oauth/authorize?${query}" - clientCA: /etc/origin/master/proxyca.crt - headers: - - X-Remote-User ----- - -[discrete] -===== Restarting services - -Finally, restart the following services: - +. Update the `identityProviders` stanza in the Custom Resource (CR): ++ +[source,yaml] ---- -# systemctl restart httpd -# master-restart api -# master-restart controllers +identityProviders: + - name: requestheaderidp + type: RequestHeader + requestHeader: + challengeURL: "https:///challenging-proxy/oauth/authorize?${query}" + loginURL: "https:///login-proxy/oauth/authorize?${query}" + ca: + name: ca-config-map + clientCommonNames: + - my-auth-proxy + headers: + - X-Remote-User ---- -[discrete] -===== Verifying the configuration +. Verify the configuration. -. Test by bypassing the proxy. You should be able to request a token if you -supply the correct client certificate and header: +.. Confirm that you can bypass the proxy by requesting a token by supplying the +correct client certificate and header: + ---- # curl -L -k -H "X-Remote-User: joe" \ --cert /etc/pki/tls/certs/authproxy.pem \ - https://[MASTER]:8443/oauth/token/request + https:///oauth/token/request ---- -. If you do not supply the client certificate, the request should be denied: +.. Confirm that requests that do not supply the client certificate fail by +requesting a token without the certificate: + ---- # curl -L -k -H "X-Remote-User: joe" \ - https://[MASTER]:8443/oauth/token/request + https:///oauth/token/request ---- -. This should show a redirect to the configured `challengeURL` (with -additional query parameters): +.. Confirm that the `challengeURL` redirect is active: + ---- # curl -k -v -H 'X-Csrf-Token: 1' \ - '/oauth/authorize?client_id=openshift-challenging-client&response_type=token' + https:///oauth/authorize?client_id=openshift-challenging-client&response_type=token ---- ++ +Copy the `challengeURL` redirect to use in the next step. -. This should show a 401 response with a `WWW-Authenticate` basic challenge, a -negotiate challenge, or both challenges: +.. Run this command to show a 401 response with a `WWW-Authenticate` basic +challenge, a negotiate challenge, or both challenges: + ---- -# curl -k -v -H 'X-Csrf-Token: 1' \ - '' +# curl -k -v -H 'X-Csrf-Token: 1' \ + ---- -. Test logging in to the `oc` command line with and without using a Kerberos ticket: -.. If you generated a Kerberos ticket by using `kinit`, destroy it: +.. Test logging in to the OpenShift CLI (`oc`) with and without using a Kerberos +ticket: +... If you generated a Kerberos ticket by using `kinit`, destroy it: + ---- # kdestroy -c cache_name <1> ---- -<1> Provide the name of your Kerberos cache. -.. Log in to the `oc` command line by using your Kerberos credentials: ++ +<1> Make sure to provide the name of your Kerberos cache. +... Log in to the `oc` tool by using your Kerberos credentials: + ---- # oc login ---- + Enter your Kerberos user name and password at the prompt. -.. Log out of the `oc` command line: +... Log out of the `oc` tool: + ---- # oc logout ---- -.. Use your Kerberos credentials to get a ticket: +... Use your Kerberos credentials to get a ticket: + ---- # kinit ---- + Enter your Kerberos user name and password at the prompt. -.. Confirm that you can log in to the `oc` command line: +... Confirm that you can log in to the `oc` tool: + ---- # oc login