Install token broker proxy

Learn how to install a token broker proxy in your environment. The token broker proxy acts as the bridge between mutual Transport Layer Security (mTLS) based authentication and OAuth2 for clients running in constrained environments. You register your token broker in Snow Atlas, and either install the token broker proxy as a Windows service on your Windows server, or use Helm charts to install a container with the token broker proxy in your environment.

You must install this service in your environment to be able to use the Snow Atlas browser extension for SaaS. For more information, see Browser extension.

Prerequisites

There are several requirements to set up the token broker proxy.

Create a token broker registration

Before you install the token broker proxy service, you must create a token broker registration in Snow Atlas. For more information, see Create token broker registrations.

Install as a Windows service

No specific requrements.

Install using Helm

To install the token broker proxy using Helm charts, you require the following:

• Helm 3 or later on your local machine

• kubectl version 1.25 or later

• Kubernetes cluster version 1.23 or later

• TCP port 443 must be allowed for outbound connections

note

Refer to Helm's version support policy to ensure that you are using compatible versions of Helm and Kubernetes.

Parameters required

You require the following parameters for the steps to configure the token broker proxy service for installation as a Windows service or using Helm charts.

Parameter	Description for Windows	Description for Helm
-clientid	The client ID that you receive when you add a Token broker registration in Snow Atlas. For more information, see Create token broker registrations. Value required in the installation command in Step 3 of Procedure to install as a Windows service.	The client ID that you receive when you add a Token broker registration in Snow Atlas. For more information, see Create token broker registrations. Value required in the secrets file that you add to your cluster in Step 2 of Procedure to install using Helm.
-clientsecret	The Secret key that you receive when you add a Token broker registration in Snow Atlas. For more information, see Create token broker registrations. Value required in the installation command in Step 3 of Procedure to install as a Windows service.	The Secret key that you receive when you add a Token broker registration in Snow Atlas. For more information, see Create token broker registrations. Value required in the secrets file that you add to your cluster in Step 2 of Procedure to install using Helm.
-clientca	The thumbprint of the client CA certificate. Value required in the installation command in Step 3 of Procedure to install as a Windows service.	The client certificate chain used to validate the client certificate. Value required in the secrets file that you add to your cluster in Step 2 of Procedure to install using Helm.
-servercert	The thumbprint of the Transport Layer Security (TLS) certificate and intermediate certificates. Value required in the installation command in Step 3 of Procedure to install as a Windows service.	The filepath to the Transport Layer Security (TLS) certificate and intermediate certificates. Value required in the secrets file that you add to your cluster in Step 2 of Procedure to install using Helm.
-signingcert	The thumbprint of the JSON Web Token (JWT) signing certificate required to sign the token. Value required in the installation command in Step 3 of Procedure to install as a Windows service.	The filepath to the JSON Web Token (JWT) signing certificate required to sign the token. Value required in the secrets file that you add to your cluster in Step 2 of Procedure to install using Helm.
-platformurl	The URL for your Snow Atlas instance. You can find this URL in the Snow Atlas settings menu, on the Licenses and usage page. You require the value for the API URL on the General information tab. For further information, see General information. Value required in the installation command in Step 3 of Procedure to install as a Windows service.	The URL for your Snow Atlas instance. You can find this URL in the Snow Atlas settings menu, on the Licenses and usage page. You require the value for the API URL on the General information tab. For further information, see General information. Value required in the values.yaml file in Step 4 of Procedure to install using Helm.
-brokerport	The port for the token broker proxy in your environment. Value required in the installation command in Step 3 of Procedure to install as a Windows service.	The port for the token broker proxy in your environment. Value required in the values.yaml file in Step 4 of Procedure to install using Helm.
-brokerhost	The hostname for the token broker proxy in your environment. Value required in the installation command in Step 3 of Procedure to install as a Windows service.	The hostname for the token broker proxy in your environment. Value required in the values.yaml file in Step 4 of Procedure to install using Helm.
-clientdiscriminator	The client discriminator determines from which field the email address is extracted. If you want the email address to be extracted from the OU or CN fields, add this parameter and the value in the installation command in Step 3 of Procedure to install as a Windows service.	The client discriminator determines from which field the email address is extracted. If you want the email address to be extracted from the OU or CN fields, add this parameter and the value in the values.yaml file in Step 4 of Procedure to install using Helm.

Procedure to install as a Windows service

note

This installation procedure and Windows service is in beta.

Ensure that you have all of the prerequisites required to install the token broker proxy. For more information, see Prerequisites.

The iam-tokenbroker-proxy-win64.exe file is provided in Token broker proxy for SaaS browser extension on Snow Globe. You must sign in to Snow Globe to access this article. The token broker proxy is installed and run as a Windows service on your Windows server. This service obtains a token that is used to communicate with Snow Atlas APIs.

1. Convert your PEM certificates to PFX with the following commands:

   openssl pkcs12 -export -out ./certs/server.pfx -inkey ./certs/server.key -in ./certs/server.crt -password pass:
   openssl pkcs12 -export -out ./certs/signingcert.pfx -inkey ./certs/signingcert.pem -in ./certs/signingcert.pem -password pass:

2. Import the PFX into the Windows certificate store under LocalMachine with the following commands:

   Import-Certificate -FilePath .\certs\ca.crt -CertStoreLocation Cert:\LocalMachine\Root
   Import-PfxCertificate -FilePath .\certs\server.pfx -CertStoreLocation Cert:\LocalMachine\My
   Import-PfxCertificate -FilePath .\certs\signingcert.pfx -CertStoreLocation Cert:\LocalMachine\My

3. Install the application on your Windows server with the following command, using the values defined in Parameters required. The --clientdiscriminator=[client-discriminator] row in the command is optional.

   ./iam-tokenbroker-proxy.exe `
   --clientid=[client_id] `
   --clientsecret=[client_secret] `
   --servercert=[server_certificate_thumbprint] `
   --clientca=[client_certificate_thumbprint] `
   --platformurl=[platform_url] `
   --signingcert=[signing_certificate_thumbprint] `
   --brokerport=[port_number] `
   --brokerhost=[host_name] `
   --clientdiscriminator=[client-discriminator] `
   install
   note

   To manage the Windows service, run the application with the install or remove commands. All output from the running Windows service will be added to the Windows EventLog.

4. Set the service to always run, to ensure that data is sent regularly to Snow Atlas.

After you install your token broker proxy, to configure the browser extension, see Configure browser extensions.

Procedure to install using Helm

Ensure that you have all of the prerequisites required to install the token broker proxy. For more information, see Prerequisites.

The snowsoftware-tokenbroker-proxy Helm chart is provided in github.com/SnowSoftware/helm-charts and installs the token broker proxy in your cluster. This service obtains a token that is used to communicate with Snow Atlas APIs.

1. Add the repository https://snowsoftwareglobal.github.io/helm-charts to your Helm chart repositories:

   helm repo add snowsoftware https://snowsoftwareglobal.github.io/helm-charts
   helm repo update

2. To provide the certificates and client credentials required for the token broker proxy on your cluster, use a secrets management tool. For example, if you use Kubernetes Secrets, create a secrets.yaml file as shown below. For Kubernetes Secrets, the values that you enter must be base64 encoded.

   apiVersion: v1
   kind: Secret
   metadata:
     name: snowsoftware-tokenbroker-proxy-secrets
   type: Opaque
   data:
     clientid: <base64-encoded client id>
     clientsecret: <base64-encoded client secret>
     clientca: <base64-encoded client CA>
     servercert: <base64-encoded server cert>
     signingcert: <base64-encoded signing cert>

3. Apply the secrets to your cluster. For example, if you use Kubernetes Secrets:

   kubectl apply -f secret.yaml

4. To provide the service with the platform URL, broker port and broker host, create a values.yaml file as shown below. If you want the email address to be extracted from the OU or CN fields, set this in values.yaml file as well.

   tokenbrokerProxy:
     platformurl: "<snow atlas identity provider URL>"
     brokerport: "<port>" # default
     brokerhost: "<host>" # default
     clientdiscriminator: <client discriminator> # supported values: "emailAddress", "OU", "CN"   

5. Install the token broker proxy with the latest version and provide the values.yaml file that you create in Step 3:

   helm install snowsoftware-tokenbroker-proxy snowsoftware/snowsoftware-tokenbroker-proxy -f values.yaml

After your install your token broker proxy, to configure the browser extension, see Configure browser extensions.

Snow Software does not own the third party trademarks, software, products, or tools (collectively, the "Third Party Products") referenced herein. Third Party Product updates, including user interface updates, may not be reflected in this content.