Source code management and CI/CD systems are often on-site installations behind a firewall. Firewalls, and other security-related restrictions, do not allow requests to repositories from cloud-based third party systems. They also don't save access tokens with administrator permissions in any DevOps integration profile in a cloud installation of Targetprocess.
Watch the recording of our webinar “How to Define the Right DevOps Metrics” we hosted together with Icon Agility Services to learn how to define and collect the right metrics to see a full picture of your value streams, including DevOps.
We introduced a proxy service to overcome this, which allows you to keep an admin access token to the repository within its infrastructure, and all requests from Targetprocess will be directed to a proxy client instead of using direct access to repos. (Proxy client source code could be provided for review on request).
The proxy service is hosted on the Targetprocess side. When an Integration profile is marked as proxiable, all DevOps requests are directed to the proxy service, instead of being direct requests to the repository and CI/CD tools. The proxy service gets http requests and schedules them for processing. The proxy client runs within the repository infrastructure and pools requests from a proxy service. The proxy client executes requests to a client's tool, gets a response, and then submits the response back to the proxy service. When the proxy service receives a response, it sends it back to the Targetprocess DevOps service.
How to enable integrations proxying
To make the integration proxying option available we need an existing integration profile. If it's a new integration set up, first you'll need to fulfill the repo URL field and save the profile.
The personal access token becomes optional. It will be required later for a list of repositories/projects and can be added on the Targetprocess side as usual, OR in the proxy client on the repository side as a TOOL_SECRET parameter in docker run command.
When proxying is enabled, select Generate Proxy Client – it generates the CLIENT_ID and CLIENT_TOKEN, which are necessary to start a proxy client. The proxy client is distributed as a Docker image available at Dockerhub.
In fact, CLIENT_ID and CLIENT_TOKEN are credentials for client authorization. They are shown only once within the docker command, and won't be available again.
If you forget or lose this command (client_id and client_token), you will have to generate new client credentials, and start the command again to restart the proxy client in docker.
docker run -e CLIENT_ID=f82a6960-4a85-44b8-a611-f3c66203bd5f -e CLIENT_TOKEN=rBsh70IK7fd7jgd1OHsnCD60qXfsjrPLV5Hk5GrGYbp -e PROXY_URL=https://<your_account>.tpondemand.com/svc/proxy-service apptioinc/proxy-client
Proxy client configuration
The proxy client is configured via environment variables (they could be passed as -e parameters into docker run command):
- CLIENT_ID - Unique identifier of a proxy client. Generated in DevOps profile.
- CLIENT_TOKEN - Client token is generated for secure communication between proxy-client and proxy-service. Generated in DevOps profile.
- PROXY_URL - Url of the proxy-service. Could be built by following principle https://<your_account>/svc/proxy-service.
- TOOL_SECRET - (optional) Required when you do not want to enter your tool token into the DevOps profile. If specified, it also tells the proxy client to add DevOps tool token to every request. The way the proxy client will add the token to the request is configured with the TOOL_TYPE parameter.
- TOOL_TYPE - (optional) Required when you do not want to enter your tool token into the DevOps profile. Defines the way the proxy client adds the token to the request (Authorization header name, header value format etc.). Possible values: bitbucket, gitlab, github, azuredevops.
- TOOL_URL - (optional) Additional request validation option. If specified, it will allow the proxy client to execute requests starting with the value of TOOL_URL only.
- NODE_EXTRA_CA_CERTS – adds well-known extra certificates to Node.js
In closed environments, self-signed or privately signed certificates are commonly used, and rejected by Node.js since their root CAs are not known. Therefore DevOps Integrations do not work with self-signed certificates by default. So either there must be a certificate signed by CA or a trusted certificate added to the deployment environment.
As of Node.js 7.3.0 (and LTS versions 6.10.0 and 4.8.0), it is possible to add well-known extra certificates to Node.js with a NODE_EXTRA_CA_CERTS environment variable. It can be useful in the cloud environment or other deployment environments to add trusted certificates as a matter of policy (as opposed to explicit coding), or on personal machines, for example, adding CAs for proxy servers.
Download your root ca and mount it to the docker image as a volume during "docker run" execution. (For example, more on docker volumes herehttps://docs.docker.com/storage/volumes/). Then you can point to the certificate location within the docker image with NODE_EXTRA_CA_CERTS variable – when you run again docker command to start proxy client, add this variable with the path to a certificate within the docker container. It will look like
docker run -e CLIENT_ID=d693cbfb-6121238-4e38-afa9-1cbed5087dbe -e CLIENT_TOKEN=JKrYMV3FeZsnsadp8AdtysZra9N5vRdnCLYuit3QVv8 -e PROXY_URL=https://integrations.tpondemand.net/svc/proxy-service apptioinc/proxy-client:latest -e NODE_EXTRA_CA_CERTS=<path to your cert within container>