8.2.4. Authenticating Using Mutual SSL

Procedure 8.4. To Modify the Broker Proxy Configuration for Mutual SSL Authentication:

1. Edit the /etc/httpd/conf.d/000002_openshift_origin_broker_proxy.conf file on the broker host and add the following lines in the <VirtualHost *:443> block directly after the SSLProxyEngine directive, removing any other SSLCertificateFile, SSLCertificateKeyFile, and SSLCACertificateFile directives that may have previously been set:

   SSLOptions +StdEnvVars
   SSLCertificateFile path/to/SSL/certificate/file
   SSLCertificateKeyFile path/to/certificate/keyfile
   SSLCACertificateFile path/to/SSLCA/certificate/file
   SSLVerifyClient optional
   SSLVerifyDepth  2
   RequestHeader set X-Remote-User %{SSL_CLIENT_S_DN_CN}e env=SSL_CLIENT_S_DN_CN

   These directives serve the following functions for the SSL virtual host:
   • The SSLCertificateFile, SSLCertificateKeyFile, and SSLCACertificateFile directives are critical, because they set the paths to the certificates.
   • The SSLVerifyClient directive set to optional is also critical as it accommodates certain broker API calls that do not require authentication.
   • The SSLVerifyDepth directive can be changed based on the number of certificate authorities used to create the certificates.
   • The RequestHeader directive set to the above options allows a mostly standard broker proxy to turn the CN from the client certificate subject into an X_REMOTE_USER header that is trusted by the back-end broker. Importantly, ensure that the traffic between the SSL termination proxy and the broker application is trusted.
2. Restart the broker proxy:

   # service httpd restart

Procedure 8.5. To Modify the Broker Application Configuration for Mutual SSL Authentication:

1. Edit the /var/www/openshift/broker/httpd/conf.d/openshift-origin-auth-remote-user.conf file on the broker host to be exactly as shown:

   <Location /broker>
     # Broker handles auth tokens
     SetEnvIfNoCase Authorization Bearer passthrough
   
     # Console traffic will hit the local port.  mod_proxy will set this header automatically.
     SetEnvIf X-Forwarded-For "^$" passthrough=1
     # Turn the Trusted header into the Apache environment variable for the broker remote-user plugin
     SetEnvIf X-Remote-User "(..*)" REMOTE_USER=$1 passthrough=1
   
     # Old-style auth keys are POSTed as parameters. The deployment registration
     # and snapshot-save use this.
     BrowserMatchNoCase ^OpenShift passthrough
     # Older-style auth keys are POSTed in a header.  The Jenkins cartridge does
     # this.
     SetEnvIf broker_auth_key "^[A-Za-z0-9+/=]+$" passthrough=1
   
      Allow from env=passthrough
   
       # Allow the specific requests that can passthrough and then deny everything else.  The following requests can passthrough:
       #
       # * Use Bearer authentication
       # * Use Broker authentication tokens
       # * Originate from the trusted Console
      Order Allow,Deny
   </Location>
   
   # The following APIs do not require auth:
   #
   # /api
   # /environment
   # /cartridges
   # /quickstarts
   #
   # We want to match requests in the form of:
   #
   # /api
   # /api.json
   # /api/
   #
   # But not:
   #
   # /api_with_auth
   <LocationMatch ^/broker/rest/(api|environment|cartridges|quickstarts)(\.\w+|/?|/.*)$>
     <IfVersion >= 2.4>
       Require all granted
     </IfVersion>
     <IfVersion < 2.4>
       Allow from all
     </IfVersion>
   </LocationMatch>

2. Set the following in the /etc/openshift/plugins.d/openshift-origin-auth-remote-user.conf file:

   TRUSTED_HEADER="HTTP_X_REMOTE_USER"

3. Restart the broker service for the changes to take effect:

   # service openshift-broker restart

Procedure 8.6. To Modify the Management Console Configuration for Mutual SSL Authentication:

1. Edit the /var/www/openshift/console/httpd/conf.d/openshift-origin-auth-remote-user.conf file on the broker host and add the following:

   <Location /console>
       # The node->broker auth is handled in the Ruby code
       BrowserMatch Openshift passthrough
       Allow from env=passthrough
   
       # Turn the Console output header into the Apache environment variable for the broker remote-user plugin
       SetEnvIf X-Remote-User "(..*)" REMOTE_USER=$1
   
       Order Deny,Allow
   </Location>

2. Set the following in the /etc/openshift/console.conf file:

   REMOTE_USER_HEADER=HTTP_X_REMOTE_USER

3. Restart the Management Console service for the changes to take effect:

   # service openshift-console restart

Procedure 8.7. To Test the Mutual SSL Configuration:

1. Run the following command and ensure it returns successfully:

   # curl -k https://broker.example.com/broker/rest/api

2. Run the following command and ensure it returns with a 403 Forbidden status code:

   # curl -k https://broker.example.com/broker/rest/user

3. Run the following commands and ensure they return successfully:

   # curl --cert path/to/certificate/file --key path/to/certificate/keyfile --cacert path/to/SSLCA/certificate/file https://broker.example.com/broker/rest/api
   # curl --cert path/to/certificate/file --key path/to/certificate/keyfile --cacert path/to/SSLCA/certificate/file https://broker.example.com/broker/rest/user

   Note that the above commands may need to be altered with the --key option if your key and certificate are not located in the same PEM file. This option is used to specify the key location if it differs from your certificate file.