Configuring Auth Proxy for deployment with BMC Helix SSO

Before you begin

You must have Auth Proxy deployed in the Docker container. 

Task 1: To set up Auth Proxy for the BMC Helix SSO server

1. Register the Auth Proxy server as an Open ID Client on the BMC Helix SSO server.
2. (Optional) Configure Access Token Timeout. Default = 1 hour.
3. Specify OpenID Connect Issuer URL that must correspond to the current FQDN of the BMC Helix SSO tenant.
4. Generate the JSON Web Key.  
   For information about how to perform these steps, see Configuring OAuth 2.0.

Task 2: To create a configuration file for Auth Proxy

1. Create the external.conf file that can be mounted into the AuthProxy container during the startup.

2. Copy the following content into the external.conf file.

   helix_sso_external_url= "<External URL of the BMC Helix SSO server that corresponds to the current FQDN of the BMC Helix SSO tenant>"
   helix_sso_internal_url= "<Internal URL of the BMC Helix SSO server that corresponds to the current FQDN of the BMC Helix SSO tenant>"
   
   number_of_retries= <Any numeric value> /* If not specified, 2 is applied by default  */
   
   token_status_cache_timeout= <Any numeric value measured in seconds> /* If not specified, 180 is applied by default */
   token_synchronization_timeout = 10
   
   http_auth_header
     {
      name = "helix_sso_uid"
     }
   proxies =
   [
     {
      listen = <Incoming listening port of the first application>
      target_host = <Host of the first application>
      target_port = <Target port of the first application>
      excluded_url_patterns = [".*\\.jpg", "/app/healthcheck/"]
      logout_url = "<Path to logout resources of the target application>"
      cookie = {
        secure = true /* true by default */
        same_site = true /* true by default */
        same_site_mode = "STRICT" /* STRICT by default/
       }
     }
     {
       listen = <Incoming listening port of the second application>
       target_host = <Host of the second application>
       target_port = <Target port of the second application>
       excluded_url_patterns =[".*\\.jpg"]
       logout_url ="/sample/agentless_logout.jsp"
     }
   ]
   oidc_client_id= "<Open ID Client ID generated by the BMC Helix SSO server>"
   oidc_client_secret= "<Open ID Client secret generated by the BMC Helix SSO server>"
   redis = {
   url = ""
   cluster = true
   channel = "channel"
   password = ""
   }
   

   Warning

   Important

   • redis.uri is required for automatically extending OAuth 2.0 user sessions by enabling refresh tokens.
   • Use redis.password if the Redis server is not protected with password.
   • redis.channel is required for Configuring BMC Helix SSO to support immediate logout from all applications.
   • If you want to use the Redis server in cluster mode, use the following Redis server configuration property from the code block:
     redis.cluster=true
   • In your configuration file, if you use the Redis server properties from the code block and the following properties, the properties from the code block take precedence:
     redis_url=" "
     redis_channel="..."
     redis_password="..."

3. To enable the liveness health probe for Auth Proxy, add the following code to the external.conf file and update the values for your container:

   internal_stat_server = {
   listen = <listeningPort>
   liveness_endpoint = "/healthcheck"
   worker_io_threads = 2
   worker_task_core_threads = 8
   worker_task_max_threads = 8
   }

   Warning

   Important

   • Auth Proxy does not start if the listening port is the same as any other proxy port.
   • Liveness health probe is not enabled if the <listeningPort> is set to 0.

   The default liveness endpoint is /healthcheck, and you can view the status of Auth Proxy by using the following command in a tool like Postman:
   localhost:<listeningPort>/healthcheck
   The return value of Status Code is 200 OK if Auth Proxy is running. 

4. To replace HTTP 307 and HTTP 302 Temporary Redirect responses with an HTTP 401 Unauthorized response with a special header, add the following values in the external.conf file:

   rsso_ajax_request_support = true
   rsso_ajax_request_header_identifier = "X-RSSO-AJAX-REQUEST"

5. Adjust all values in the angle brackets in the external.conf file, and save it.

   Warning

   Important

   The external.conf file contains sensitive information. BMC recommends protecting it with restrictive permissions on the filesystem.

Task 3: To enable configuration for the Auth Proxy server 

On the server with Auth Proxy container, run the following command to publish the configuration set in the external.conf file on the Auth Proxy server:

Here, <aus-harboreg-01.bmc.com/rsso/authproxy:RSSO_Auth_Proxy_96> is the Auth Proxy docker image from the last Drop.

Task 4: To disable the BMC Helix SSO agent for applications that use Auth Proxy

For applications that you configured to communicate with the BMC Helix SSO server via Auth Proxy, disable the BMC Helix SSO agent if these applications are already integrated with the BMC Helix SSO server.

For each application specified in the external.conf file that uses the BMC Helix SSO agent, apply the following configuration in the rsso-agent.properties file:

On the Auth Proxy side, apply the following configuration for every proxy section:

Task 5: To add response headers

You can add headers for 302, 307, and 401 HTTP responses.

To add a header, perform the following steps:

1. In the external.conf file, add the following code and update the values:

   response_headers = [
   {
   name = "",
   value = ""
   }
   ]

Where to go from here

After you have performed steps described in this topic, set up authentication on the BMC Helix SSO server.  For more information, see Setting up end user authentication.