Swimm OAuth Local Server
Does your organization restrict internet communication?
Our Enterprise Starter and Enterprise clients have two options for communicating with their Git hosting server:
- Whitelist our static IP address.
- Deploy Swimm's OAuth Local Server within your organization’s network.
1. Whitelist our static IP address.
Internet access restricted, but connected to the internet?
This is the easiest way to enable Swimm to communicate with your Git hosting server. Please reach out to the Swimm team for the static IP address to whitelist.
This solution does not apply for Bitbucket Datacenter and Gitlab Enterprise Server.
2. Swimm's OAuth Local Server
Git hosting not connected to internet?
Our OAuth Local server functions as a dedicated Docker container that operates within your local network. It acts as a conduit linking your Git hosting instance with the Swimm web application as part of the OAuth process.
Local OAuth explanation
Using OAuth with a on-prem Git hosting includes the following steps:
- Send a request to the Git hosting service from the client (Swimm WebApp - app.swimm.io).
- Get a temporary code from the Git hosting service.
- Use a backend instance to "convert" the temporary code into a token by sending a request back to the Git hosting service.
- Return the token to the client.
See visualization below:
Why do we need a “Swimm instance”?
All popular Git providers consider issuing a grant token as an operation that should occur on the backend for enhanced security. They enforce this by adding a CORS header to the API that creates tokens, which browsers respect, thereby preventing direct requests from being issued from the browser.
When behind a firewall or VPC/VPN
When the client is located within a protected network, it cannot receive requests from outside their environment (as highlighted in the flowchart). In the OAuth flow for Swimm - the web app, that opened in a browser within the customer’s environment, can make requests to the custom Git server. In contrast, the "Swimm instance" that resides outside the VPC/VPN cannot.
Installation guide
Step 1: Verify app
Verify OAuth App RedirectURL (callbackURL)
Please make sure that the redirect URL (callback URL) in the already-installed OAuth App is defined to be https://app.swimm.io/localGitProviderAuth
.
For more information on how to create an OAuth App for your Git hosting, please refer to the following instructions:
Step 2: Download image
Download the OAuth Local Server image
Pull the latest version of the OAuth Local Server image by running:
docker pull swimmio/onprem-agent:latest
Step 3: Deploy image
Deploy the OAuth Local Server image
Deploy the container inside your organization’s network with the following settings:
- The container is set to listen internally over the port
24605
. Please transfer HTTP(s) requests to this port. - Deploy the container with the environment variable of
ENTERPRISE_NAME
and set the value to be your company’s name.
Once the container is deployed, you can navigate to <your-deployment-url>
(for example: https://your-deployment-domain.a.run.app/) from a browser, and if the container was started successfully - you will get back an HTTP 200 response looking like this:
Make sure that the service will be accessible and be able to communicate with the developer’s browser, as well as the Git hosting server.
Step 4: Send information to Swimm
Share the deployment URL with Swimm
Please send the deployment URL
to the Swimm team to direct OAuth requests to your network's private instance for your workspace.