Setting up authentication for the on-premises gateway

With BMC Helix Single Sign-On (SSO), BMC Helix Intelligent Integrations on-premises gateway users are required to present credentials to authenticate themselves.

Perform the following tasks to set up the authentication for the BMC Helix Intelligent Integrations on-premises gateway:

1. Register the OAuth client (on-premises gateway).
   Perform one of the following tasks to register the client depending on whether BMC Helix SSO is running in your on-premises environment or the BMC Helix environment:
   • On-premises environment: Perform the steps in Task 1.
   • BMC Helix SaaS environment: Contact the BMC Support team.
2. Update the BMC Helix SSO configuration for Auth Proxy. 

Before you begin

• Ensure that you have the TenantAdmin role with BMC Helix SSO SaaS administrator credentials.
• On the server <FQDN>:<portNumber>, where the II on-premises gateway is installed, the firewall should allow:
  • outbound data transmissions from the II server to the ADE platform.
  • inbound data transmissions from the ADE platform to the II server. 

Task 1: To register the OAuth client

1. Create a tenant administrator account for BMC Helix SSO:
   1. Log on to the BMC Helix SSO Admin Console as a SaaS administrator.
   2. Click Tenant and from the list of tenants, select a tenant.
   3. Click the pin icon to switch to the BMC Helix SSO Admin Console of the selected tenant.
   4. On the navigation panel, click the Admin User tab.
      The list of administrator users is displayed.
   5. (Optional) Click Add Admin User.
      On the Add Admin User page enter the following information and click Save:
      
      • Login: Enter a name of the BMC Helix SSO administrator.
      • Password: Create a password for the tenant administrator account.
      • Confirm Password: Confirm the password for the tenant administrator account.
        The tenant administrator account is added and is available in List of Admin Users.
2. Register the OAuth client:
   1. Log on to the BMC Helix SSO Admin Console as a tenant administrator by using the credentials you created in step1(f).
   2. Click OAuth2. 
   3. On the OAuth2 and OpenID Configuration page, click the Clients tab.
   4. Click Register Client.
   5. Enter a name for the OAuth client.
   6. Ensure that the Enabled check box is selected to enable the client for authorization. 
   7. Click Add Redirect URI, and then add the URI in the following format to which the authorization code is sent after an /authorize request succeeds. The client side must support the URI.
      https://<hostName>:<portNumber>/swpui/auth/code/callback
      In the URL:
      
      • Replace <hostName> with the fully-qualified domain name of the server where the on-premises gateway is installed.
      • Replace <portNumber> with a custom port if you are using a port other than the default of 443. 
   8. Select the openid (Scope used for OpenID connect) check box to enable the OAuth client to use the OpenID Connect protocol.

   9. Click Save.
      The following information is automatically generated when you register the client:

      Client ID	Registers the client identifier issued to the client by BMC Helix SSO server during the registration process. You can view this information when you select the registered client.
      Client Secret	Shows the client secret (private key) only after you click Save. The private key is used to sign the JWT, which contains the client authorization. This JWT is different from the one containing the end-user credentials that is used in the JWT assertion grant type.

   10. Save the Client ID and Client Secret values in a file somewhere because these values will not be displayed again.
   11. Log out of the BMC Helix SSO admin console.
3. Add a realm and configure authentication for the realm:
   1. Log on to the BMC Helix SSO console as a SaaS administrator.
   2. Click the edit icon corresponding to the realm of the tenant.
   3. In Application Domain(s), enter the fully-qualified domain name of the server where the on-premises gateway is installed.
   4. Click Save.

Task 2: To update the BMC Helix SSO configuration for Auth Proxy

1. Log on to the server where the on-premises gateway is installed as a tenant administrator.
2. Navigate to the <IIGATEWAY_INSTALL_DIR>/hii/conf/authproxy directory and open the external.conf file with a text editor.
3. Update the file:
   • Search for the rsso_external_url and rsso_internal_url parameters and replace {RSSO_URL} with the OpenID Connect Issuer URL.
   • Search for the target_host parameter and replace {RSSO_TARGET_HOST} with swp-ui.
   • Search for the client_id parameter and replace {RSSO_CLIENT_ID} with the Client ID that you saved in a file while registering the OAuth client.
   • Search for the client_secret parameter and replace {RSSO_CLIENT_SECRET} with the Client Secret that you saved in a file while registering the OAuth client.
4. Save the file.