Keeper Automator Service
Automatic device approval service for SSO Connect Cloud environments
Overview
The Keeper Automator is a self-hosted service which performs cryptographic operations including device approvals, team approvals and team user assignments.
Once Automator is running, users can seamlessly access Keeper on a new (not previously approved) device after a successful authentication with your identity provider, without any further approval steps. Without the Automator service, users and admins can still perform manual device approvals through Push Approval methods.
Keeper Automator is a lightweight service that can be deployed in your cloud or on-prem environment.
Why is this needed?
Keeper SSO Connect provides seamless authentication into the Keeper vault using your identity provider. Normally a user must a approve their new device, or an Admin can approve a new device for a user. The Automator service is totally optional, created for Admins who want to remove any friction associated with device approvals.
To preserve Zero Knowledge and automate the transfer of the Encrypted Data Key (EDK) to the user's device, a service must be run which is operated by the Enterprise (instead of hosted by Keeper). The service can be run several different ways, either in the cloud or self-hosted.
An in-depth explanation of SSO Connect encryption model is documented here.
Installation Options
Depending on your environment, select from one of the following installation methods. The Azure Container App, Azure App Services, AWS Elastic Container Service and Google Cloud with GCP Cloud Run are the best choices if you use one of these cloud services.
Installation Method: Azure Container App
Installation Method: Azure App Services
Installation Method: Azure App Gateway
Installation Method: AWS Elastic Container Service
Installation Method: AWS Elastic Container Service with KSM
Installation Method: Google Cloud with GCP Cloud Run
Installation Method: Standalone Java
Installation Method: Docker
Installation Method: Docker Compose
Installation Method: Kubernetes
Installation Method: Windows Service
Automator Security
Using the Automator service creates a frictionless experience for users, however it requires that you have fully secured your identity provider.
Please refer to our Recommended Security Settings guide to securing your Keeper environment.
Version 17.0 Overview
Instructions for upgrading your Automator instance to v17.0
Overview
Version v17.0+ incorporated several new features:
Team Approvals (Team Creation)
Team User Approvals (Assigning Users to Teams)
All settings can be configured as environment variables
Support for simplified Azure Container App deployment
Support for simplified AWS ECS Service deployment
HSTS is enabled for improved HTTPS security
IP address filtering for device approval and team approval
Optional rate limiting for all APIs
Optional filtering by email domain
Optional binding to specific network IPs
Team User approvals
Teams and users who are provisioned through SCIM can be immediately processed by the Automator service (instead of waiting for the admin to login to the console).
To activate this new feature:
Update your Automator container or .zip file to the latest version
Use the
automator editcommand in Keeper Commander to instruct the service to perform device approvals and also perform Team User approvals:
Example:
Team Approvals
When team creation is requested by the identity provider via SCIM messaging, the request is not fully processed until someone can generate an encryption key (to preserve Zero Knowledge). This is normally processed when an admin logs into the Keeper Admin Console.
When team approvals is activated on the Keeper Automator service, teams are now created automatically when any assigned user from the team logs in successfully to the Keeper Vault. Therefore, teams will not appear in the environment until at least one user from that team logs into their vault.
All settings can be configured as environment variables
This makes configuration easier when installing Automator in Azure Containers or other Docker-like containers where access to the settings file is difficult.
In Docker, Azure Containers, or other environments that use the docker-compose.yml file, you can set environment variables in the docker compose file, for example:
After editing the docker-compose.yml file, you will need to rebuild the container if the environment variables have changed. Just restarting the container will not incorporate the changes.
Advanced Features
See this page for all of the new and advanced features / settings for the Automator service.
Ingress Requirements
Ingres configuration for Keeper Automator
Keeper Automator can be deployed many different ways - on prem, cloud or serverless.
Data Flow Diagram
Network Firewall Setup
In your firewall inbound traffic rules, set one of following rulesets:
For US Data Center Customers:
Inbound TCP port 443 from
54.208.20.102/32Inbound TCP port 443 from
34.203.159.189/32
US / GovCloud Data Center Customers:
Inbound TCP port 443 from
18.252.135.74/32Inbound TCP port 443 from
18.253.212.59/32
For EU / Dublin Data Center Customers:
Inbound TCP port 443 from
52.210.163.45/32Inbound TCP port 443 from
54.246.185.95/32
For AU / Sydney Data Center Customers:
Inbound TCP port 443 from
3.106.40.41/32Inbound TCP port 443 from
54.206.208.132/32
For CA / Canada Data Center Customers:
Inbound TCP port 443 from
35.182.216.11/32Inbound TCP port 443 from
15.223.136.134/32
For JP / Tokyo Data Center Customers:
Inbound TCP port 443 from
54.150.11.204/32Inbound TCP port 443 from
52.68.53.105/32
Make sure to create a rule for each IP address listed based on your Keeper geographic data center region.
Azure Container App
Simple Deployment with Azure Container App
Overview
This guide provides step-by-step instructions to publish Keeper Automator to the Azure Container App service. This provides a simple and straightforward way to host the Automator service in the cloud.
(1) Create an Automator Config key
Open a command line interface and generate a 256-bit AES key in URL-encoded format using one of the methods below, depending on your operating system:
Generate a Key
Save the resulting value produced by this command for Step (3).
(2) Create a Container Registry
If you do not already have a container registry, you must create one and configure as you see fit. Example below.
(3) Create a Container App
From Azure, create a new Container App.
Select or create a new Resource Group
Set the Container App Name to "keeperautomator" or whatever you prefer
Select "Container Image" as the Deployment Source
Select the region where you would like the service hosted
Create a new Apps Environment or select an existing environment
Click
Next : Container >
(4) Setup Container Details
In the "Container" step, make the following selections:
Uncheck the "Use quickstart image"
Select "Docker Hub or other registries"
Select "Public"
Select Registry login server as
docker.ioSet the Image and tag as
keeper/automator:latestSkip to "Container resource allocation"
For CPU and Memory, 0.5 CPU cores and 1Gi memory is sufficient, but this can be updated based on your volume of new device logins.
Create an environment variable called
AUTOMATOR_CONFIG_KEYwith the value from Step 1 above of the setup guide.Create an environment variable called
AUTOMATOR_PORTwith the value of8089Create an environment variable called
SSL_MODEwith the value ofnoneClick "Next : Ingress >"
(5) Ingress Setup
On the Ingress setup screen, select the following:
EnableIngressIngress traffic
Accepting traffic from anywhere(we'll modify this in a later step)Ingress type
HTTPTarget port set to
8089
(6) Create Container App
Click "Review + Create" and then click "Create"
After a few minutes, the container app will be created and automatically start up.
Clicking on "Go to Resource" will take you to the container environment.
(7) Customize the Ingress Setup
To restrict communications to the Keeper Automator service, click on the "Ingress" link on the left side of the screen under the "Network" section
Click on "Ingress"
Select "Allow traffic from IPs configured below, deny all other traffic"
Click "Add" to add two of Keeper's IPs and any of your IPs required for testing the service. Ingress Requirements information: Located Here
Click Save
(8) Set Scaling
Select Application > Scale and set min and max replicas to 1
Click "Save as a new revision"
(9) Create Volume
Select Application > Volumes and click "+ Add"
Add a Ephemeral Storage and name it as you wish and click "Add"
Then click "Save as a new revision"
(10) Set up Health Probes and Volume Mount
Navigate to the "Application > Revisions and Replicas" section"
Click on "Create new revision"
Click on Application > Revisions and replicas an observe a new revision being activated
Next, click on the "Container" tab
Click on the container image name link, in this case "keeperautomator" at the bottom
Navigate to Health Probes and enter the following under each section:
Under "Liveness probes":
Enable liveness probes
Transport:
HTTPPath:
/healthPort:
8089Initial delay seconds:
5Period seconds:
30
Under "Startup probes":
Enable startup probes
Transport:
HTTPPath:
/healthPort:
8089Initial delay seconds:
5Period seconds:
30
Under "Volume Mounts" tab:
Select "+ Add"
Select the volume you created in a previous step and Add Mount Path as
/usr/mybin/config
Finish the configuration
Click on
SaveThen click on
Createto build the new configurationAfter a few minutes, the new containers should start up
(11) Retrieve the Application URL
Wait until the revision is done activating.
From the Overview section of the Container App, on the right side is the "Application URL" that was assigned. Copy this and use this Application URL in the next step.
For example, https://craigautomator1.xyx-1234.azurecontainerapps.io
(12) Login to Keeper Commander
Keeper Commander is required to perform the final step of Automator configuration. This can be run from anywhere, it does not need to be installed on the server.
On your workstation or server, install Keeper Commander CLI. The installation instructions including binary installers are here:
https://docs.keeper.io/secrets-manager/commander-cli/commander-installation-setup
After Commander is installed, launch Keeper Commander, or from an existing terminal you can type keeper shell to open the session, then login using the login command. In order to set up Automator, you must login as a Keeper Administrator, or an Admin with the ability to manage the SSO node.
(13) Create the Automator
Create the Automator using a series of commands, starting with automator create with your node name.
The Node Name (in this case "Azure Cloud") comes from the Admin Console UI as seen below.
The output of the command will display the Automator settings, including metadata from the identity provider.
Note that the "URL" is not populated yet. This is the Application URL from Step 8.
Run the "automator edit" command as displayed below, which sets the URL and also sets up the skills (team, team_for_user and device).
Next we exchange keys: The enterprise private key encrypted with the Automator public key is provided to Automator:
Initialize the Automator with the new configuration
Enable the service
At this point, the configuration is complete.
For external health checks, you can use the below URL:
https://<server>/health
Example curl command:
Testing the User Experience
Now that Keeper Automator is deployed, you can test the end-user experience. No prompts for approval will be required after the user authenticates with the SSO identity provider.
The easiest way to test is to open an incognito mode window to the Keeper Web Vault and login with SSO Cloud. You will not be prompted for device approval.
Advanced
Azure Container Apps have many advanced capabilities that are beyond the scope of this documentation. A few of the capabilities are provided below.
Scaling with Multiple Containers
If you would like to have multiple containers running the Keeper Automator service:
Click on "Scale and replicas"
Click "Edit and deploy"
Click on the "Scale" tab
Select the min and max number of containers. The minimum should be at least 1.
Click Create
After a minute, the new version will deploy
Run
automator setup xxxmultiple times (one for each container)Run
automator init xxxmultiple times (one for each container)
Logging
The Keeper Automator logs can be viewed and monitored using the "Console" or "Log stream" section.
For example, to tail the log file of a running Automator service:
Click on Console
Select "/bin/sh"
Click Connect
At the prompt, type:
tail -f logs/keeper-automator.log
Advanced Settings
Environment variables can be passed into the Container to turn on/off features of the runtime environment. The variables with their description can be found at the Advanced Settings page.
Azure App Services
Deployment with Azure App Services
Overview
This guide provides step-by-step instructions to instantiate Keeper Automator as a Web App within Azure App Services. For environments such as GCC High and DoD, this service is available for hosting the Automator.
(1) Create an Automator Config key
Open a command line interface and generate a 256-bit AES key in URL-encoded format using one of the methods below, depending on your operating system:
Generate a Key
Save the resulting value produced by this command for Step (6).
(2) Create a App Services Web App
From the Azure portal, create a new Web App by selecting App Services in the search bar and then selecting Create + Web App
Select or create a new Resource Group
Set the Instance Name
Set Publish to "Docker Container"
Set Operating System to "Linux"
Select the region where you would like the service hosted
Select your Linux Plan or create a new plan. Pricing plan at a minimum should be Premium V3 P0V3, but will also be dependent on the end user environment
Proceed to the
Dockersection
(3) Setup Docker Container Details
In the "Docker" step, make the following selections:
Options: "Single Container"
Image Service: "Docker Hub"
Access Type: "Public"
Image and tag:
keeper/automator:latestProceed to the
Monitoringsection
(4) Setup WebApp Monitoring
Select "Enable Application Insights": Yes
Select or create a new Application Insights workspace
Proceed to the
Review + createsection
(5) Create WebApp
Click "Review + Create" and then click "Create"
After a few minutes, the web app will be created and automatically start up.
Clicking on "Go to Resource" will take you to the container environment.
Make note of the Default domain value. This will be needed to setup and initialize the Automator service
(6) Configure the WebApp
Go to the Configuration section and select "New application setting"
Or your environment variables settings may be in a different section of the UI under Environment variables.
Add the following application settings:
Create the below environment variables with their respective values:
AUTOMATOR_CONFIG_KEY -> "value from Step 1 above of the setup guide"
AUTOMATOR_PORT -> 8089
SSL_MODE -> none
WEBSITES_PORT -> 8089
Click Apply
(7) Set up Diagnostics
Select Diagnostic settings and then select "+ Add diagnostic setting"
Give the diagnostic setting a name.
Select "App Service Console logs"
Select "App Service Application logs"
Select "Send to Log Analytics workspace"
Select or setup a new Log Analytics workspace
(8) Set up Logs
Select Logs from the main menu. Click the "X" to close the Queries window.
To see the Docker deployment and startup logs: AppServicePlatformLogs
To see the application error logs: AppServiceConsoleLogs
(9) Set up App Service logs
Select App Service Logs from the main menu under the Monitoring section. Then select File System under Application logging and set a retention per user's preference
Click Save
(10) View Log stream
Select Log Stream from the main menu under the Overview section to verify the Automator service is connected and logging correctly
(11) Configure Health Check
Select Health check from the main menu under the Monitoring section. Then Enable the health check function and set the Path value to "/health". Click Save to save the configuration, and Save again to confirm changes.
(12) Configure Access Restrictions
In the Networking section you can setup simple access rules or configure Azure Front Door.
Select Networking from the main menu and click on "Enabled with no access restrictions"
Under Access Restrictions, select "Enabled from select virtual networks and IP addresses" and "Allow" unmatched rule action. Click +Add to add inbound access rules.
Under Add Rule, add the inbound firewall rules. You should restrict traffic to the Keeper published IP addresses marked as "Network Firewall Setup" for your respective region per the page below
Ingress RequirementsClick Add Rule
Click Save to save the configurations
(13) Login to Keeper Commander
Keeper Commander is required to perform the final step of Automator configuration. This can be run from anywhere, it does not need to be installed on the server.
On your workstation or server, install Keeper Commander CLI. The installation instructions including binary installers are here:
https://docs.keeper.io/secrets-manager/commander-cli/commander-installation-setup
After Commander is installed, launch Keeper Commander, or from an existing terminal you can type keeper shell to open the session, then login using the login command. In order to set up Automator, you must login as a Keeper Administrator, or an Admin with the ability to manage the SSO node.
(14) Create the Automator
Create the Automator using a series of commands, starting with automator create
The Node Name (in this case "Azure Cloud") comes from the Admin Console UI as seen below.
The output of the command will display the Automator settings, including metadata from the identity provider.
Note that the "URL" is not populated yet. This is the Default Domain value from Step 5.
Run the "automator edit" command as displayed below, which sets the URL and also sets up the skills (team, team_for_user and device).
Next we exchange keys: The enterprise private key encrypted with the Automator public key is provided to Automator:
Initialize the Automator with the new configuration
Enable the service
At this point, the configuration is complete.
For external health checks, you can use the below URL:
https://<server>/health
Example curl command:
Testing the User Experience
Now that Keeper Automator is deployed, you can test the end-user experience. No prompts for approval will be required after the user authenticates with the SSO identity provider.
The easiest way to test is to open an incognito mode window to the Keeper Web Vault and login with SSO Cloud. You will not be prompted for device approval.
Loading...
AWS Elastic Container Service
Running Keeper Automator with the AWS ECS (Fargate) service
Overview
This example demonstrates how to launch the Keeper Automator service in Amazon ECS in the most simple way, with as few dependencies as needed.
Requirements:
A managed SSL certificate via the AWS
(1) Create an Automator Config key
Generate a 256-bit AES key in URL-encoded format using one of the methods below, depending on your operating system:
Mac/Linux
Windows
Save this value for the environmental variables set in the task definition.
(2) Create a VPC
If your VPC does not exist, a basic VPC with multiple subnets, a route table and internet gateway must be set up. In this example, there are 3 subnets in the VPC with an internet gateway as seen in the resource map below:
(3) Create CloudWatch Log Group
If you would like to capture logs (recommended), Go to CloudWatch > Create log group
Name the log group "automator-logs".
(4) Create an Execution IAM Role
Go to IAM > Create role
Select AWS service
Then search for Elastic Container Service and select it.
Select "Elastic Container Service Task" and click Next
Add the "AmazonECSTaskExecution" policy to the role and click Next
Assign the name "ECSTaskWritetoLogs" and then create the role.
Make note of the ARN for this Role, as it will be used in the next steps.
In this example, it is arn:aws:iam::373699066757:role/ECSTaskWritetoLogs
(5) Create a Security Group for ECS
Go to EC2 > Security Groups and click on "Create security group"
Depending on what region your Keeper tenant is hosted, you need to create inbound rules that allow https port 443 from the Keeper cloud. The list of IPs for each tenant location is located below. In the example below, this is the US data center.
We also recommend adding your workstation's external IP address for testing and troubleshooting.
Assign a name like "MyAutomatorService" and then click "Create".
US
54.208.20.102/32
34.203.159.189/32
US GovCloud
18.252.135.74/32
18.253.212.59/32
EU
52.210.163.45/32
54.246.185.95/32
AU
3.106.40.41/32
54.206.208.132/32
CA
35.182.216.11/32
15.223.136.134/32
JP
54.150.11.204/32
52.68.53.105/32
(6) Add the Security Group to the list of inbound rules
After saving the security group, edit the inbound rules again. This time, make the following additions:
Add HTTP port 8089 with the Source set to the security group. This allows traffic from the ALB to the container inside the network and for processing health checks.
(7) Create Elastic Container Service Cluster
Navigate to the Amazon Elastic Container Service.
Select "Create cluster" and assign the cluster name and VPC. In this example we are using the default "AWS Fargate (serverless)" infrastructure option.
The Default namespace can be called "automator"
The "Infrastructure" is set to AWS Fargate (serverless)
Click Create
(8) Create ECS Task Definition
In your favorite text editor, copy the below JSON task definition file and save it.
Important: Make the following changes to the JSON file:
Change the XXX (REPLACE THIS) XXX on line 24 to the secret key created in Step 1 above.
Replace lines 37-39 with the name and location of the log group from Step 3
Change the XXX on line 44 for the role ID as specific to your AWS role (from Step 4, e.g. 373699066757)
Next, go to Elastic Container Service > Task definitions > Create Task from JSON
Remove the existing JSON and copy-paste the modified JSON file into the box, then click Create.
This task definition can be modified according to your instance CPU/Memory requirements.
(9) Upload SSL Cert to AWS Certificate Manager
In order for an application load balancer in AWS to serve requests for Automator, the SSL certificate must be managed by the AWS Certificate Manager. You can either import or create a certificate that is managed by AWS.
From AWS console, open the "Certificate Manager"
Click on Request
Request a public certificate and click Next
Enter the domain name for the automator service, e.g. automator.lurey.com
Select your preferred validation method and key algorithm
Click Request
Click on the certificate request from the list of certs
If you use Route53 to manage the domain, you can click on the certificate and then select "Create Records in Route53" to instantly validate the domain and create the certificate. If you use a different DNS provider, you need to create the CNAME record as indicated on the screen.
Once create the CNAME record, the domain will validate within a few minutes.
This certificate will be referenced in Step 11 when creating the application load balancer.
(10) Create a Target Group
Go to EC2 > Target Groups and click Create target group
Select "IP Addresses" as the target type
Enter the Target group name of "automatortargetgroup" or whatever you prefer
Select HTTP Protocol with Port 8089
Select the VPC which contains the ECS cluster
Select HTTP1
Under Health checks, select the Health check protocol "HTTP"
Type
/healthas the Health check pathExpand the "Advanced health check settings"
Select Override and then enter port 8089
Click Next
Don't select any targets yet, just click Create target group
(11) Create Application Load Balancer (ALB)
Go to EC2 > Load balancers > Create load balancer
Select Application Load Balancer > Create
Assign name such as "automatornalb" or whatever you prefer
Scheme is "Internet-facing"
IP address type: IPv4
In the Network Mapping section, select the VPC and the subnets which will host the ECS service.
In the Security groups, select "MyAutomatorService" as created in Step 4.
In the Listeners and routing section, select HTTPS port 443 and in the target group select the Target group as created in the prior step (automatortargetgroup).
In the Secure listener settings, select the SSL certificate "from ACM" that was uploaded to the AWS Certificate Manager in Step 9.
Click Create load balancer
(12) Create ECS Service
Go to Elastic Container Service > Task definitions > Select the task created in Step 8.
From this Task definition, click on Deploy > Create Service
Select Existing cluster of "automator"
Assign Service name of "automatorservice" or whatever name you prefer
For the number of Desired tasks, set this to 1 for now. After configuration is complete, you can increase to the number of tasks you would like to have running.
Under Networking, select the VPC, subnets and replace the existing security group with the ECS security group created in Step 4. In this case, it is called "MyAutomatorService".
For Public IP, turn this ON.
Under Load balancing, select Load balancer type "Application Load Balancer"
Use an existing load balancer and select "automatoralb" created in Step 11.
Use an existing listener, and select the 443:HTTPS listener
Use an existing target group, and select the Target Group from Step 10
Set the Health check path to "/health"
Set the Health check protocol to "HTTP"
Click Create
After a few minutes, the service should start up.
(13) Update DNS
Assuming that the DNS name is hosted and managed by Route53:
Go to Route53 > Create or Edit record
Create an A-record
Set as "Alias"
Route traffic to "Alias to Application and Classic Load Balancer"
Select AWS Region
Select the "automatoralb" Application Load Balancer
Select "Simple Routing"
Select "Save"
The next step is to configure Automator using Keeper Commander while only having one task running.
(14) Install Keeper Commander
At this point, the service is running but it is not able to communicate with Keeper yet.
On your workstation, server or any computer, install the Keeper Commander CLI. This is just used for initial setup. The installation instructions including binary installers are here:
Installing Keeper Commander
After Commander is installed, you can type keeper shell to open the session, then login using the login command. In order to set up Automator, you must login as a Keeper Administrator, or an Admin with the ability to manage the SSO node.
(15) Initialize with Commander
Login to Keeper Commander and activate the Automator using a series of commands, starting with automator create
The Node Name (in this case "Azure Cloud") comes from the Admin Console UI as seen below.
The output of the command will display the Automator settings, including metadata from the identity provider.
Run the "automator edit" command as displayed below, which sets the URL and also sets up the skills (team, team_for_user and device).
Next we exchange keys: The enterprise private key encrypted with the Automator public key is provided to Automator:
Initialize the Automator with the new configuration
Enable the service
At this point, the configuration is complete.
For automated health checks, you can use the below URL:
https://<server>/health
Example curl command:
In this example setup, the load balancer will be forwarding /health checks to the target instances over HTTP port 8089.
(16) Testing the User Experience
Now that Keeper Automator is deployed with a single task running, you can test the end-user experience. No prompts for approval will be required after the user authenticates with the SSO identity provider.
The easiest way to test is to open an incognito mode window to the Keeper Web Vault and login with SSO Cloud. You will not be prompted for device approval.
Assuming that the approval worked, you can now increase the number of tasks running.
(17) Update Task Definition (Optional)
The Keeper Automator service can run quite well on a single container without any issue due to the low number of requests that it processes. However if you would like to have multiple containers running, please follow the below steps:
Click on the "automatorservice" from the ECS services screen
Click on "Update service"
Select the checkbox on "Force new deployment"
Ensure that the latest task revision is selected
Set the Desired Tasks to the number of containers you would like running
Click "Update"
After a few minutes, the new containers will deploy. Wait until all containers are active.
Launch Keeper Commander (or it might still be open)
For every container, the automator setup, automator init and automator enable must be executed.
For example, if there are 3 containers running:
Logging and Monitoring
The Automator logs can be searched and monitored in the "Logs" tab of the ECS service, or in CloudWatch.
AWS Elastic Container Service with KSM (Advanced)
Running Keeper Automator with the AWS ECS (Fargate) service and Keeper Secrets Manager for secret storage
Overview
This example demonstrates how to launch the Keeper Automator service in Amazon ECS with Fargate, while also demonstrating the use of Keeper Secrets Manager for retrieving the secret configuration for the published Docker container.
Keeper Setup
Since this deployment requires the use of Keeper Secrets Manager, this section reviews the steps needed to set up your Keeper vault and the SSL certificate for publishing the Automator service.
(1) SSL Certificate
Create an SSL Certificate as described from this page
When this step is completed, you will have two files: ssl-certificate.pfx and ssl-certificate-password.txt
(2) Create Shared Folder
Create a Shared Folder in your vault. This folder will not be shared to anyone except the secrets manager application.
(3) Add File Attachments
Create a record in the Shared Folder, and make note of the Record UID. Upload the SSL certificate and SSL certificate password files to a Keeper record in the shared folder.
(4) Add Automator Property File
Upload a new file called keeper.properties which contains the following content:
The notable line here is the disable_sni_check=true which is necessary when running the Automator service under a managed load balancer.
Your shared folder and record should look something like this:
(5) Create KSM Application
Create a Keeper Secrets Manager ("KSM") application in your vault. If you are not familiar with secrets manager, follow this guide. The name of this application is "Automator" but the name does not matter.
(6) Attach the KSM application to the shared folder
Edit the Shared Folder and add the Automator application to this folder.
(7) Create a KSM Device Configuration
Open the secrets manager application, click on "Devices" tab and click "Add Device". Select a base64 configuration. Download and save this configuration for use in the ECS task definition.
AWS Setup
(1) Create a VPC
If your VPC does not exist, a basic VPC with multiple subnets, a route table and internet gateway must be set up. In this example, there are 3 subnets in the VPC with an internet gateway as seen in the resource map below:
(2) Create CloudWatch Log Group
Go to CloudWatch > Create log group
Name the log group "automator-logs".
(3) Create an Execution IAM Role
Go to IAM > Create role
Select AWS service
Then search for Elastic Container Service and select it.
Select "Elastic Container Service Task" and click Next
Add the "AmazonECSTaskExecution" policy to the role and click Next
Assign the name "ECSTaskWritetoLogs" and then create the role.
Make note of the ARN for this Role, as it will be used in the next steps.
In this example, it is arn:aws:iam::373699066757:role/ECSTaskWritetoLogs
(4) Create a Security Group for ECS
Go to EC2 > Security Groups and click on "Create security group"
Depending on what region your Keeper tenant is hosted, you need to create inbound rules that allow https port 443. The list of IPs for each tenant location is on this page. In the example below, this is the US data center.
We also recommend adding your workstation's external IP address for testing and troubleshooting.
Assign a name like "MyAutomatorService" and then click "Create".
After saving the security group, edit the inbound rules again. This time, add HTTPS port 443 and select the security group in the drop-down. This will allow the load balancer to monitor health status and distribute traffic.
(5) Create Security Group for EFS
We'll create another security group that controls NFS access to EFS from the cluster.
Go to EC2 > Security Groups and click on "Create security group"
Set a name such as "MyAutomatorEFS".
Select Type of "NFS" and then select Custom and then the security group that was created in the prior step for the ECS cluster. Click "Create security group".
Note the security group ID for the next step. In this case, it is sgr-089fea5e4738f3898
(6) Create two Elastic File System volumes
At present, the Automator service needs access to two different folders. In this example setup, we are creating one volume to store the SSL certificate and SSL passphrase files. The second volume stores the property file for the Automator service. These 3 files are in your Keeper record.
Go to AWS > Elastic File System and click Create file system
Call it "automator_config" and click Create
Again, go to Elastic File System and click Create file system. Call this one automator_settings and click Create.
Note the File system IDs displayed. These IDs (e.g. fs-xxx) will be used in the ECS task definition.
After a minute, the 2 filesystems will be available. Click on each one and then select the "Network" tab then click on "Manage".
Change the security group for each subnet to the one created in the above step (e.g. "MyAutomatorEFS") and click Save. Make this network change to both filesystems that were created.
(7) Create Elastic Container Service Cluster
Navigate to the Amazon Elastic Container Service.
Select "Create cluster" and assign the cluster name and VPC. In this example we are using the default "AWS Fargate (serverless)" infrastructure option.
The Default namespace can be called "automator"
The "Infrastructure" is set to AWS Fargate (serverless)
Click Create
(8) Create ECS Task Definition
In your favorite text editor, copy the below JSON task definition file and save it.
Make the following changes to the JSON file:
Change the XXXCONFIGXXX value to a base64 config from Keeper Secrets Manager created in the beginning of this guide
Change the 3 instances of "XXXXX" to the Record UID containing the SSL certificate, SSL certificate password and settings file in your vault shared folder which KSM is accessing.
Change the two File system IDs (fs-XXX) to yours from the above steps
Change the XXX for the role ID as specific to your AWS role
Change the eu-west-1 value in two spots to the region of your ECS service
Next, go to Elastic Container Service > Task definitions > Create Task from JSON
Remove the existing JSON and copy-paste the contents of the JSON file above into the box, then click Create.
This task definition can be modified according to your instance CPU/Memory requirements.
(9) Upload SSL Cert to AWS Certificate Manager
In order for an application load balancer in AWS to serve requests for Automator, the SSL certificate must be managed by the AWS Certificate Manager.
Go to AWS Certificate Manager and Click on Import
On your workstation, we need to convert the SSL certificate (.pfx) file to a PEM-encoded certificate body, PEM-encoded private key and PEM-encoded certificate chain.
Since you already have the .pfx file, this can be done using the below openssl commands:
Download the ssl-certificate.pfx file and the certificate password locally to your workstation and enter the below commands:
Generate the PEM-encoded certificate body
Generate the PEM-encoded private key
Generate the PEM-encoded certificate chain
Copy the contents of the 3 files into the screen, e.g.
(10) Create a Target Group
Go to EC2 > Target Groups and click Create target group
Select "IP Addresses" as the target type
Enter the Target group name of "automatortargetgroup" or whatever you prefer
Select HTTPS Protocol with Port 443
Select the VPC which contains the ECS cluster
Select HTTP1
Under Health checks, select the Health check protocol "HTTPS"
Type
/healthas the Health check pathClick Next
Don't select any targets yet, just click Create target group
(11) Create Application Load Balancer (ALB)
Go to EC2 > Load balancers > Create load balancer
Select Application Load Balancer > Create
Assign name such as "automatornalb" or whatever you prefer
Scheme is "Internet-facing"
IP address type: IPv4
In the Network Mapping section, select the VPC and the subnets which will host the ECS service.
In the Security groups, select "MyAutomatorService" as created in Step 4.
In the Listeners and routing section, select HTTPS port 443 and in the target group select the Target group as created in the prior step (automatortargetgroup).
In the Secure listener settings, select the SSL certificate "from ACM" that was uploaded to the AWS Certificate Manager in Step 9.
Click Create load balancer
(12) Create ECS Service
Go to Elastic Container Service > Task definitions > Select the task created in Step 8.
From this Task definition, click on Deploy > Create Service
Select Existing cluster of "automator"
Assign Service name of "automatorservice" or whatever name you prefer
Important: For the number of Desired tasks, set this to 1 for right now. After configuration, we will increase to the number of tasks you would like to have running.
Under Networking, select the VPC, subnets and replace the existing security group with the ECS security group created in Step 4. In this case, it is called "MyAutomatorService".
For Public IP, turn this ON.
Under Load balancing, select Load balancer type "Application Load Balancer"
Use an existing load balancer and select "automatoralb" created in Step 11.
Use an existing listener, and select the 443:HTTPS listener
Use an existing target group, and select the Target Group from Step 10
Click Create
After a few minutes, the service should start up.
(13) Update DNS
Assuming that the DNS name is hosted and managed by Route53:
Go to Route53 > Create or Edit record
Create an A-record
Set as "Alias"
Route traffic to "Alias to Application and Classic Load Balancer"
Select AWS Region
Select the "automatoralb" Application Load Balancer
Select "Simple Routing"
Select "Save"
The next step is to configure Automator using Keeper Commander while only having one task running.
(14) Install Keeper Commander
At this point, the service is running but it is not able to communicate with Keeper yet.
On your workstation, server or any computer, install the Keeper Commander CLI. This is just used for initial setup. The installation instructions including binary installers are here:
Installing Keeper Commander
After Commander is installed, you can type keeper shell to open the session, then login using the login command. In order to set up Automator, you must login as a Keeper Administrator, or an Admin with the ability to manage the SSO node.
(15) Initialize with Commander
Login to Keeper Commander and activate the Automator using a series of commands, starting with automator create
The Node Name (in this case "Azure Cloud") comes from the Admin Console UI as seen below.
The output of the command will display the Automator settings, including metadata from the identity provider.
Run the "automator edit" command as displayed below, which sets the URL and also sets up the skills (team, team_for_user and device).
Next we exchange keys: The enterprise private key encrypted with the Automator public key is provided to Automator:
Initialize the Automator with the new configuration
Enable the service
At this point, the configuration is complete.
For automated health checks, you can use the below URL:
https://<server>/health
Example curl command:
In this example setup, the load balancer will be sending health checks to the target instances.
(16) Testing the User Experience
Now that Keeper Automator is deployed with a single task running, you can test the end-user experience. No prompts for approval will be required after the user authenticates with the SSO identity provider.
The easiest way to test is to open an incognito mode window to the Keeper Web Vault and login with SSO Cloud. You will not be prompted for device approval.
Assuming that the approval worked, you can now increase the number of tasks running.
(17) Update Task Definition
From the ECS screen, open the automator service and click "Update Service". Then set the number of tasks that you would like to have running.
Logging and Monitoring
The Automator logs can be searched and monitored in the "Logs" tab of the ECS service, or in CloudWatch.
Java on Linux
Keeper Automator sample implementation using standalone Java service
This guide provides step-by-step instructions to publish Keeper Automator on any Linux instance that can run Docker.
Standalone Java Service
(1) Install Java
In preparation of the service, ensure that at least Java 17 is installed. In a standard Amazon AWS Linux 2 instance, the Amazon Corretto Java 17 SDK can be installed using the below command:
To check which version is running, type:
(2) Install the Service
From the Automator instance, download and unzip the Keeper Automator service:
(3) Create the config folder
If the folder does not exist, create the a "config" folder in the extracted location.
(4) Copy the .pfx and password file
Upload the .pfx file created in the Create Certificate page to the Automator's config/ folder and make sure the filename is called ssl-certificate.pfx.
For example, using scp:
If your ssl-certificate.pfx file is protected by a passphrase, you also need to create a file called ssl-certificate-password.txt and place it into the docker container:
For example:
(5) Edit Service Settings
The file called keeper.properties located in the settings/ folder is used to manage the advanced configuration parameters of the service. Common parameters that may need to be edited include:
automator_host
automator_port
ssl_certificate
See the advanced settings page for details on each parameter.
(6) Start the Service
From the Automator instance, start the service using java -jar. In this example below, it is run in the background using nohup.
On Windows command line or powershell, the command must be executed exactly per below:
(7) Check Service Status
Confirm the service is running through a web browser (note that port 443 must be opened from whatever device you are testing) In this case, the URL is: https://<server>/health
This URL can also be used for automated health checks.
Example:
Now that the service is running, you need to integrate the Automator into your environment using Keeper Commander.
Final Configuration with Commander
Keeper Commander is required to perform the final step of Automator configuration. This can be run from anywhere, it does not need to be installed on the server.
On your workstation or server, install Keeper Commander CLI. The installation instructions including binary installers are here:
https://docs.keeper.io/secrets-manager/commander-cli/commander-installation-setup
After Commander is installed, you can type keeper shell to open the session, then login using the login command. In order to set up Automator, you must login as a Keeper Administrator, or an Admin with the ability to manage the SSO node.
Login to Keeper Commander and activate the Automator using a series of commands, starting with automator create
The Node Name (in this case "Azure Cloud") comes from the Admin Console UI as seen below.
The output of the command will display the Automator settings, including metadata from the identity provider.
Run the "automator edit" command as displayed below, which sets the URL and also sets up the skills (team, team_for_user and device).
Next we exchange keys: The enterprise private key encrypted with the Automator public key is provided to Automator:
Next, send other IdP metadata to the Automator:
Enable the Automator service
At this point, the configuration is complete.
For environments using AD FS ...
When activating Keeper Automator with AD FS as the identity provider, users will not be able to login until you update the Keeper certificate using the instructions below:
Login to the Keeper Admin Console
Go to Admin > SSO Node > Provisioning and then view the SSO Cloud configuration.
Click on "Export SP Cert".
In the AD FS Management Console select the Keeper Cloud SSO Relying Party Trust properties.
On the "Encryption" tab, replace the old certificate with this new cert.
On the "Signature" tab, Add/Replace the new SP certificate with this new cert.
Securing the Service
We recommend restricting network access to the service. Please see the Ingress Requirements section for a list of IP addresses to allow.
Testing the User Experience
Now that Keeper Automator is deployed, you can test the end-user experience. No prompts for approval will be required after the user authenticates with the SSO identity provider.
The easiest way to test is to open an incognito mode window to the Keeper Web Vault and login with SSO Cloud. You will not be prompted for device approval.
Service Restart
When you stop/start the Keeper Automator service, or if you restart the server, you may need to use Keeper Commander to re-initialize the service endpoint.
Troubleshooting
Service not starting
Please check the Keeper Automator logs. This usually describes the issue. On Linux, the logs are located in the install directory.
Users always getting prompted for approval
When you reconfigure the Keeper Automator service, you may need to use Keeper Commander to re-initialize the service endpoint. (Keeper Commander documentation is linked here).
The commands required on Keeper Commander to re-initialize your Automator instance are below:
Docker on Linux
How to deploy Keeper Automator in a simple docker environment
Docker on Linux
This guide provides step-by-step instructions to publish Keeper Automator on any Linux instance that can run Docker.
Setup
(1) Install Docker
If you don't have Docker installed, set it up per the instructions on your platform. For example, if you use the yum package installer:
Start the Docker service if it's not running
Then configure the service to start automatically
To allow non-root users to run Docker (and if this meets your security requirements), run this command:
(2) Pull the Automator image
Use the docker pull command to get the latest Keeper Automator image.
(3) Start the service
Use the command below to start the service. This example below is listening to port 443.
(4) Update the certificate
Inside the docker container, create a "config" folder.
Copy the ssl-certificate.pfx file created in the Certificate Guide into the container.
If your .pfx file is protected by a passphrase, you also need to create a file called ssl-certificate-password.txt
...and place it into the docker container:
Make sure that the ssl_mode parameter in the keeper.properties file within the container is set to certificate.
(5) Restart the container with the SSL cert
Now that the certificate is installed, restart the Docker container:
(6) Install Keeper Commander
At this point, the service is running but it is not able to communicate with Keeper yet.
On your workstation, server or any computer, install the Keeper Commander CLI. The installation instructions including binary installers are here:
Installing Keeper Commander
After Commander is installed, you can type keeper shell to open the session, then login using the login command. In order to set up Automator, you must login as a Keeper Administrator, or an Admin with the ability to manage the SSO node.
(7) Initialize with Commander
Login to Keeper Commander and activate the Automator using a series of commands, starting with automator create
The Node Name (in this case "Azure Cloud") comes from the Admin Console UI as seen below.
The output of the command will display the Automator settings, including metadata from the identity provider.
Note that the "URL" is not populated yet. This is the public URL which the Keeper backend will communicate with. For example, automator.mycompany.com.
Run the "automator edit" command as displayed below, which sets the URL and also sets up the skills (team, team_for_user and device).
Next we exchange keys: The enterprise private key encrypted with the Automator public key is provided to Automator:
Initialize the Automator with the new configuration
Enable the service
At this point, the configuration is complete.
For automated health checks, you can use the below URL:
https://<server>/health
Example:
For environments using AD FS ...
When activating Keeper Automator with AD FS as the identity provider, users will not be able to login until you update the Keeper certificate using the instructions below:
Login to the Keeper Admin Console
Go to Admin > SSO Node > Provisioning and then view the SSO Cloud configuration.
Click on "Export SP Cert".
In the AD FS Management Console select the Keeper Cloud SSO Relying Party Trust properties.
On the "Encryption" tab, replace the old certificate with this new cert.
On the "Signature" tab, Add/Replace the new SP certificate with this new cert.
Securing the Service
We recommend restricting network access to the service. Please see the Ingress Requirements page for a list of IP addresses to allow.
Testing the User Experience
Now that Keeper Automator is deployed, you can test the end-user experience. No prompts for approval will be required after the user authenticates with the SSO identity provider.
The easiest way to test is to open an incognito mode window to the Keeper Web Vault and login with SSO Cloud. You will not be prompted for device approval.
Service Restart
When you stop/start the Keeper Automator service, the Docker service will automatically retain state.
Upgrading the Container
When a new version of Keeper Automator is available, you can update your Automator service by repeating steps 2-7 above.
For example:
Then, run the Keeper Commander commands:
Troubleshooting
Service not starting
Please check the Keeper Automator logs. This usually describes the issue. In the Docker environment, you can tail the log file using this command:
Connecting to the container to check the log file is possible using the below command:
Docker Compose
Installation of Keeper Automator using the Docker Compose method
This guide provides step-by-step instructions to publish Keeper Automator on any Linux instance that can run Docker and Docker Compose.
Docker Compose benefits over standard Docker:
Data is preserved between container updates
Future updates are simple to install and maintain
Instructions for installing Automator using the Docker Compose method are below.
(1) Install Docker and Docker Compose
Instructions for installing Docker and Docker Compose vary by platform. Please refer to the official documentation below:
https://docs.docker.com/compose/install/
On Linux, a quick guide to installing Docker and Docker Compose:
Note: On Linux you may use docker-compose instead of docker compose.
After installing, you may still need to start the Docker service, if it's not running.
Then configure the service to start automatically
To allow non-root users to run Docker (and if this meets your security requirements), run this command:
(2) Create docker-compose.yml file
Save the snippet below as the file docker-compose.yml on your server, in the location where you will be executing docker compose commands.
(3) Install the Container and Start it up
(4) Copy the SSL Certificate and password file created from Custom SSL Certificate page
(5) Restart the service with the new cert
(6) Install Keeper Commander
At this point, the service is running but it is not able to communicate with Keeper yet.
On your workstation, server or any computer, install the Keeper Commander CLI. This is just used for initial setup. The installation instructions including binary installers are here:
Installing Keeper Commander
After Commander is installed, you can type keeper shell to open the session, then login using the login command. In order to set up Automator, you must login as a Keeper Administrator, or an Admin with the ability to manage the SSO node.
(7) Initialize with Commander
Login to Keeper Commander and activate the Automator using a series of commands, starting with automator create
The Node Name (in this case "Azure Cloud") comes from the Admin Console UI as seen below.
The output of the command will display the Automator settings, including metadata from the identity provider.
Note that the "URL" is not populated yet. Edit the URL with the FQDN you selected.
Run the "automator edit" command as displayed below, which sets the URL and also sets up the skills (team, team_for_user and device).
Next we exchange keys: The enterprise private key encrypted with the Automator public key is provided to Automator:
Initialize the Automator with the new configuration
Enable the service
At this point, the configuration is complete.
For automated health checks, you can use the below URL:
https://<server>/health
Example:
Monitoring Logs
The Automator logs can be monitored by using the Docker Compose command:
For environments using AD FS ...
When activating Keeper Automator with AD FS as the identity provider, users will not be able to login until you update the Keeper certificate using the instructions below:
Login to the Keeper Admin Console
Go to Admin > SSO Node > Provisioning and then view the SSO Cloud configuration.
Click on "Export SP Cert".
In the AD FS Management Console select the Keeper Cloud SSO Relying Party Trust properties.
On the "Encryption" tab, replace the old certificate with this new cert.
On the "Signature" tab, Add/Replace the new SP certificate with this new cert.
Securing the Service
We recommend restricting network access to the service. Please see the Ingress Requirements section for a list of IP addresses to allow.
Updating
When a new version of Automator is available, updating the container is the only requirement.
Testing the User Experience
Now that Keeper Automator is deployed, you can test the end-user experience. No prompts for approval will be required after the user authenticates with the SSO identity provider.
The easiest way to test is to open an incognito mode window to the Keeper Web Vault and login with SSO Cloud. You will not be prompted for device approval.
Google Cloud with GCP Cloud Run
Running the Keeper Automator service on the Google Cloud platform with Cloud Run
Overview
This guide provides step-by-step instructions to run the Keeper Automator service on Google Cloud, specifically using the GCP Cloud Run service. The Automator is also protected by the Google Armor service in order to restrict access to Keeper's infrastructure IPs.
(1) Create a Project
From the Google Cloud console (https://console.cloud.google.com) create a new project.
Then click "Select Project" on this new project.
(2) Start the Cloud Shell
For this documentation, we'll use the Google Cloud Shell from the web interface. Click to activate the Cloud Shell or install this on your local machine.
Note the Project ID, which in this case is
keeper-automator-439714. This Project ID will be used in subsequent commands.
(3) Link a Billing Account
If you haven't done so, you must link a valid Billing account to the project. This is performed in the Google Cloud user interface from the Billing menu.
(3) Create an Automator Config key
From the Cloud Shell, generate a 256-bit AES key in URL-encoded format:
Example key: 6C45ibUhoYqkTD4XNFqoZoZmslvklwyjQO4ZqLdUECs=
Save the resulting Key in Keeper. This will be used as an environment variable when deploying the container. This key ensures that ephemeral containers will be configured at startup.
(4) Enable the Artifact Registry
(5) Select a Region
You need to select a region for the service to run. The available region codes can be found by using the following command:
For this example, we will use us-east1
(6) Create Artifact Repository for the Automator service
Run the below 2 commands, replacing "us-east1" with your preferred value from Step 5
(7) Upload the Automator container to the Artifact Registry
Create a file called cloudbuild.yaml that contains the following content, ensuring to replace the string "us-east1" with your preferred location from Step 5. Leave all other content the same.
Replace
us-east1with your preferred location from Step 5
Upload this file through the Cloud Shell user interface, or create the text file in the cloud shell.
From the Cloud Shell, execute the following:
Then execute the build:
This will sync the latest Automator container to your Google Artifact Registry.
(8) Deploy the Automator service
The following command will deploy the Keeper Automator service to Google Cloud Run from your Artifact Registry. This service is limited to internal access and load balancers only.
Note the following:
[PROJECT_ID]needs to be replaced by your Project ID as found in Step 2XXXis replaced with the configuration key that you created in Step 3 above.AUTOMATOR_PORTtells the container to listen on port 8080SSL_MODEallows the SSL connection to terminate with the load balancerDISABLE_SNI_CHECKallows the request to complete behind the load balancerThe mininum number of instances is 1, which is acceptable in most environments.
If min/max is not set, the service will drop to zero instances and startup on the first request
(9) Create Managed Certificate
The Keeper system is going to communicate with your Automator service through a publicly routable DNS name. In this example, I'm using gcpautomator.lurey.com. In order to set this up, you need to first create a managed SSL certificate. The command for this is below.
Replace
gcpautomator.lurey.comwith your desired name
(10) Create a Serverless Network Endpoint Group
The next command links the Cloud Run service to a Google Cloud Load Balancer.
Replace
us-east1with the region of your Cloud Run service from Step 5.
(11) Create a backend service that will use the NEG
This creates a backend service that links to the Cloud Run service:
(12) Attach the NEG to the backend service
This attaches the NEG to the backend service.
Replace
us-east1with the desired location specified in Step 5
(13) Create a URL map that directs incoming traffic to the backend service
(14) Create the HTTPS target proxy and map the Automator certificate
(15) Reserve a static IP address and assign DNS entry
Get the IP address and note for later:
The IP address must be mapped to a valid DNS.
In your DNS provider, set up an A-record pointing to the IP.
Example A-Record Configuration
A
gcpautomator.lurey.com
xx.xx.xx.xx
60
This step is important. Ensure that the desired domain name is pointing to the IP address provided. This step must be performed in your DNS provider directly.
(16) Create a Global Forwarding Rule
Create a global forwarding rule to direct incoming requests to the target proxy:
(17) Lock down access to specific IPs
The Keeper Automator service should be restricted to only the necessary IPs as discussed on the Ingress Requirements page.
Let's create a Cloud Armor Security Policy to restrict access to certain IP addresses
In this step, we will attach IPs Keeper's US Data Center as found in this page. Additional rules can be created as you see fit.
We recommend adding your external IP to this list, so that you can test the Automator service
We will also add a default "deny" rule to restrict other traffic:
Finally, attach the Cloud Armor security policy to the backend service
At this point, the Automator service should be running and the service should be exposed only to the Keeper infrastructure.
The next step is to finish the configuration with the Keeper Commander utility.
(18) Login to Keeper Commander
Keeper Commander is required to perform the final step of Automator configuration. This can be run from anywhere, it does not need to be installed on the server.
On your workstation or server, install Keeper Commander CLI. The installation instructions including binary installers are here:
https://docs.keeper.io/secrets-manager/commander-cli/commander-installation-setup
After Commander is installed, launch Keeper Commander, or from an existing terminal you can type keeper shell to open the session, then login using the login command. In order to set up Automator, you must login as a Keeper Administrator, or an Admin with the ability to manage the SSO node.
(19) Create the Automator
Create the Automator using a series of commands, starting with automator create
The Node Name (in this case "Azure Cloud") comes from the Admin Console UI as seen below.
The output of the command will display the Automator settings, including metadata from the identity provider.
Note that the "URL" is not populated yet. This will be populated with the automator URL.
Run the "automator edit" command as displayed below, which sets the URL and also sets up the skills (team, team_for_user and device).
NOTE: Replace
gcpautomator.lurey.comwith the domain name you created in Step 15
Next we exchange keys: The enterprise private key encrypted with the Automator public key is provided to Automator:
Initialize the Automator with the new configuration
Enable the service
Testing the User Experience
Now that Keeper Automator is deployed, you can test the end-user experience. No prompts for approval will be required after the user authenticates with the SSO identity provider.
The easiest way to test is to open an incognito mode window to the Keeper Web Vault and login with SSO Cloud. You will not be prompted for device approval.
Updating the Container
To update the container in Google when there is a new version available from Keeper, run the following commands:
Need help?
If you need assistance, please email commander@keepersecurity.com or open a support ticket.
Kubernetes Service
Installation of Keeper Automator as a Kubernetes service
This guide provides step-by-step instructions to publish Keeper Automator as a Kubernetes service.
(1) Set up Kubernetes
Installation and deployment of Kubernetes is not the intent of this guide, however a very basic single-node environment using two EC2 instances (Master and Worker) without any platform dependencies is documented here for demonstration purposes. Skip to Step 2 assuming you already have your K8 environment running.
Set up Docker
Kubernetes requires a container runtime, and we will use Docker.
Install kubeadm, kubelet, and kubectl
These packages need to be installed on both master and worker nodes. The example here is using AWS Amazon Linux 2 instance types.
Initialize the Master Node
On the machine you want to use as the master node, run:
The --pod-network-cidr argument is required for certain network providers. Substitute the IP range you want your pods to have.
After kubeadm init completes, it will give you a command that you can use to join worker nodes to the master. Make a note of the response and initialization code for the next step.
Set up the local kubeconfig:
Install a Pod Network
You need to install a Pod network before the cluster will be functional. For simplicity, you can use flannel:
Join Your Worker Nodes
On each machine you want to add as a worker node, the command below with the initialization code.
Note that port 6443 must be open between the worker and master node in your security group.
After the worker has been joined, the Kubernetes cluster should be up and running. You can check the status of your nodes by running kubectl get nodes on the master.
(2) Create a Kubernetes Secret
The SSL certificate for the Keeper Automator is provided to the Kubernetes service as a secret. To store the SSL certificate and SSL certificate password (created from the SSL Certificate guide), run the below command:
(3) Create a Manifest
Below is a manifest file that can be saved as automator-deployment.yaml. This file contains configurations for both a Deployment resource and a Service resource.
The deployment resource runs the Keeper Automator docker container
The SSL certificate and certificate password files are referenced as a mounted secret
The secrets are copied over to the pod in an initialization container
The Automator service is listening on port 30000 and then routes to port 443 on the container.
In this step, we are only deploying a single container (replicas: 1) so that we can configure the container, and we will increase the number of replicas in the last step.
(4) Deploy the Service
The service should start up within 30 seconds.
(5) Check Service Status
Confirm the service is running through a web browser (note that port 30000 must be opened from whatever device you are testing). In this case, the URL is: https://automator2.lurey.com:30000/api/rest/status
For automated health checks, you can also use the below URL:
https://<server>/health
Example:
Now that the service with a single pod is running, you need to integrate the Automator into your environment using Keeper Commander.
(6) Configure the Pod with Commander
Keeper Commander is required to configure the pod to perform automator functions. This can be run from anywhere.
On your workstation, install Keeper Commander CLI. The installation instructions including binary installers are here:
https://docs.keeper.io/secrets-manager/commander-cli/commander-installation-setup
After Commander is installed, you can type keeper shell to open the session, then login using the login command. In order to set up Automator, you must login as a Keeper Administrator, or an Admin with the ability to manage the SSO node.
Login to Keeper Commander and activate the Automator using a series of commands, starting with automator create
The Node Name (in this case "Azure Cloud") comes from the Admin Console UI as seen below.
The output of the command will display the Automator settings, including metadata from the identity provider.
Note that the "URL" is not populated yet. So let's do that next.
Run the "automator edit" command as displayed below, which sets the URL and also sets up the skills (team, team_for_user and device).
Next we exchange keys: The enterprise private key encrypted with the Automator public key is provided to Automator:
Next, send other IdP metadata to the Automator:
Enable the Automator service
At this point, the configuration is complete.
(7) Securing the Service
We recommend limiting network access to the service from Keeper's servers and your own workstation. Please see the Ingress Requirements section for a list of Keeper IP addresses to allow.
(8) Test the Automator Service
To ensure that the Automator service is working properly with a single pod, follow the below steps:
Open a web browser in an incognito window
Login to the Keeper web vault using an SSO user account
Ensure that no device approvals are required after successful SSO login
(9) Update the Pod configuration
At this point, we are running a single pod configuration. Now that the first pod is set up with the Automator service and configured with the Keeper cloud, we can increase the number of pods.
Update the "replicas" statement in the YAML file with the number of pods you would like to run. For example:
Then apply the change:
With more than one pod running, the containers will be load balanced in a round-robin type of setup. The Automator pods will automatically and securely load their configuration settings from the Keeper cloud upon the first request for approval.
Troubleshooting the Automator Service
The log files running the Automator service can be monitored for errors. To get a list of pods:
Connect via terminal to the Automator container using the below command:
The log files are located in the logs/ folder. Instead of connecting to the terminal, you can also just tail the logfile of the container from this command:
Windows Service
Keeper Automator sample implementation on a Windows server
The instructions on this page are created for customers who would like to simply run the Automator service on a Windows server without Docker.
(1) Install the Automator Service
On the Automator instance, download, unzip and run the Keeper Automator installer:
https://keepersecurity.com/automator/keeper-automator-windows.zip
In the setup screens, check the "Java" box to ensure that the Java runtime is embedded in the installation. Currently it ships with the Java 17 runtime, and this is updated as new versions are released.
This will install Keeper Automator into:
C:\Program Files\Keeper Security\Keeper Automator\
The configuration and settings will be set up in:
C:\ProgramData\Keeper Automator\
(2) Create the "config" folder
In the C:\ProgramData\Keeper Automator\ folder please create a folder called "config".
(3) Copy the certificate file and password file
Place ssl-certificate.pfx file (from the Custom SSL Certificate page) to the Automator Configuration settings folder in C:\ProgramData\Keeper Automator\Config
If your ssl-certificate.pfx file is protected by a passphrase, you also need to create a file called ssl-certificate-password.txt in the folder C:\ProgramData\Keeper Automator\Config
(4) Restart the Service
From the Services screen, select Keeper Automator and Restart the the service.
Confirm the service is running through a web browser (note that port 443 must be opened from whatever device you are testing) In this case, the URL is: https://automator.company.com/api/rest/status
For automated health checks, you can also use the below URL:
https://automator.company.com/health
Windows Firewall
If you are deploying on Windows running Defender Firewall, most likely you will need to open port 443 (or whatever port you specified) on Windows Defender Firewall. Follow these steps:
Open the Start menu > type Windows Defender Firewall, and select it from the list of results. Select Advanced settings on the side navigation menu... Select Inbound Rules. To open a port, select New Rule and complete the instructions.
Here's a couple of screenshots:
Final Configuration with Commander
Now that the service is running, you can integrate the Automator into your Keeper environment using Keeper Commander.
(5) Install Keeper Commander
On your workstation or server, install Keeper Commander CLI. The installation instructions including binary installers are here:
https://docs.keeper.io/secrets-manager/commander-cli/commander-installation-setup
(6) Login to Keeper Commander and activate the Automator using a series of commands, starting with automator create and name the automator whatever you want.
The Node Name (in this case "Azure Cloud") comes from the Admin Console UI as seen below.
The output of the command will display the Automator settings, including metadata from the identity provider.
Note that the "URL" is not populated yet. So let's do that next.
Run the "automator edit" command as displayed below, which sets the URL and also sets up the skills (team, team_for_user and device).
Next we exchange keys: The enterprise private key encrypted with the Automator public key is provided to Automator:
Next, initialize the Automator with the new configuration with the command below:
Lastly, enable the Automator service with the following command:
At this point, the configuration is complete.
For environments using AD FS ...
When activating Keeper Automator with AD FS as the identity provider, users will not be able to login until you update the Keeper certificate using the instructions below:
Login to the Keeper Admin Console
Go to Admin > SSO Node > Provisioning and then view the SSO Cloud configuration.
Click on "Export SP Cert".
In the AD FS Management Console select the Keeper Cloud SSO Relying Party Trust properties.
On the "Encryption" tab, replace the old certificate with this new cert.
On the "Signature" tab, Add/Replace the new SP certificate with this new cert.
Testing the User Experience
Now that Keeper Automator is deployed, you can test the end-user experience. No prompts for approval will be required after the user authenticates with the SSO identity provider.
The easiest way to test is to open an incognito mode window to the Keeper Web Vault and login with SSO Cloud. You will not be prompted for device approval.
Service Updates
When you reconfigure the Keeper Automator service, you'll need to use Keeper Commander to re-initialize the service endpoint.
Troubleshooting
Service not starting
Please check the Keeper Automator logs. This usually describes the issue. On Windows, they can be found in C:\ProgramData\Keeper Automator\logs\
Users always getting prompted for approval
When you reinstall the Keeper Automator service, you'll need to use Keeper Commander to re-initialize the service endpoint. (Keeper Commander documentation is linked here).
The commands required on Keeper Commander to re-initialize your Automator instance:
Multi-Tenant Mode
Setting up multiple tenants in a single Automator instance
Overview
Keeper Automator supports a multi-tenant configuration, so that a single deployment can perform automations for multiple Keeper Enterprise environments.
For MSP environments, a single Keeper Automator instance can be used to run multiple Managed Companies.
For Enterprise customers, a single instance can process approvals for any number of identity providers.
Once the server is running, you can use it for multiple SSO nodes, even in different enterprises.
MSP with Multiple Managed Companies
The steps for activating one Automator instance for multiple Managed Companies is below:
(1) Login to Commander as the MSP Admin
(2) Switch context to the Managed Company
Find the MC you want to set up, select the ID and then type:
(3) Create an Automator instance
Use the common Automator URL in the "edit" step
For example:
(4) Switch back to MSP
Switch back to the MSP Admin context
For each Managed Company, repeat the above 4 steps.
Multi-Tenant Enterprise
The steps for activating one Automator instance for multiple Nodes in the same Enterprise tenant is below:
(1) Login to Commander as Admin
(2) Create the Automator Instance
For each Node, use the same "edit" URL. For example:
Then, simply set up another instance with the same URL endpoint:
Note that they have different names and IDs and are assigned to different nodes but they use the same URL.
Repeat step (2) for every node to set up multiple tenants on the same Automator instance.
Custom SSL Certificate
How to configure Keeper Automator with a custom SSL certificate
Overview
Keeper Automator encrypts the communication between the Keeper backend and the Automator service running in the customer's environment.
If a custom certificate is not used, Keeper Automator will generate a self-signed certificate by default.
You can obtain a quick, easy, and free SSL certificate at ZeroSSL. Or if you prefer to have more control over each step of the process, you can proceed with the following instructions.
Generate and Prepare the SSL Certificate
Keeper Automator requires a valid signed SSL certificate that has been signed by a public certificate authority. The process of generating an SSL certificate varies depending on the provider, but the general flow is documented here.
Follow these steps to create the two certificate files needed for automator to run, which must be named ssl-certificate.pfx and ssl-certificate-password.txt
(1) Using the openssl command prompt, generate a private key
(2) Generate a CSR, making sure to use the hostname which you plan to use for Automator. In this case, we will be using automator.lurey.com. The important item here is that the Common Name matches exactly to the domain.
(3) Purchase an SSL certificate (or grab a free 90 day cert) and Submit the CSR to your SSL certificate provider.
Ensure that the SSL certificate created for your Automator instance is only used for this purpose. Do not use a wildcard certificate that is shared with other services.
If you don't have a provider already, you can use is: https://www.ssls.com/. The least expensive SSL cert for one domain is fine.
Choose a URL and create a certificate for a domain that is specific for Automator, e.g. automator.company.com.
The SSL certificate provider will deliver you a zip file that contains a signed certificate (.crt file) and intermediate CA cert. The bundle may be in either .crt or .ca-bundle file extension type. Unzip this file into the same location as your .key file that you created earlier.
(4) After the certificate has been issued, it needs to be converted using OpenSSL to .pfx format including the full certificate chain (root, intermediate and CA cert).
Set your export password when prompted. Then create a new text file called ssl-certificate-password.txt and put the export password into that file and save it.
automator.keyis the private key generated in step 1.automator.yourcompany.com.crtis the signed certificate delivered in step 3.automator.yourcompany.com.ca-bundleis the CA bundlessl-certificate.pfxis the output file used by Automator that has been encrypted with a password.ssl-certificate-password.txtcontains the password used to encrypt the .pfx file.
We recommend to save all 5 files in your Keeper vault.
Ensure that your .pfx file contains your issued cert AND the full certificate chain from your provider. If you don't provide a full certificate chain, the communication will fail and Automator will be unable to connect to your URL.
To check the .pfx, use openssl:
openssl pkcs12 -in ssl-certificate.pfx -info
If the .pfx is correct, you will see 3 certificates.
If you only see one certificate, or if you see four or five certificates, the .pfx is incorrect and you need to repeat the process.
(5) Save ssl-certificate.pfx and ssl-certificate-password.txt for the deployment steps later in this guide.
Please also ensure that you have backed up the files in your Keeper vault so that you can refer to these later when updating the service or re-keying the certificate.
(6) Review the annual certificate update process documented below.
Using Windows
Generate and Prepare the SSL Certificate
Keeper Automator requires a valid signed SSL certificate that has been signed by a public certificate authority. We do not support self-signed certificates. The process of generating an SSL certificate varies depending on the provider, but the general flow is documented here.
Download and install OpenSSL. For convenience, a 3rd party (slproweb.com) has created a binary installer. A popular binary installer is linked below:
https://slproweb.com/products/Win32OpenSSL.html Install the version at the bottom labeled "Win32 OpenSSL vX.X.X Light"
During install, the default options can be selected. In the install process, you may be asked to also install a Microsoft Visual Studio extension. Go ahead and follow the instructions to install this extension before completing the OpenSSL setup.
Run the OpenSSL Command Prompt
In your Start Menu there will be an OpenSSL folder. Click on the Win32 OpenSSL Command Prompt.
Annual Renewal Process
On an annual basis, you will need to renew your SSL certificate. Most certificate providers will generate a new cert for you. After certificate renewal, replace the .pfx certificate file in your Automator instance and then restart the service. Refer to the specific automator install method documentation on the exact process for updating the file and restarting the service.
For environments using AD FS ...
If you are using Keeper Automator with AD FS as the identity provider, users will not be able to login until you update the Keeper certificate using the instructions below:
Login to the Keeper Admin Console
Go to Admin > SSO Node > Provisioning and then view the SSO Cloud configuration.
Click on "Export SP Cert".
In the AD FS Management Console select the Keeper Cloud SSO Relying Party Trust properties.
On the "Encryption" tab, replace the old certificate with this new cert.
On the "Signature" tab, Add/Replace the new SP certificate with this new cert.
If you are experiencing login issues after the certificate update
After certificate renewal, sometimes it is necessary to publish a new SP certificate in your identity provider following the below steps:
Login to the Keeper Admin Console
Go to Admin > SSO Node > Provisioning and then view the SSO Cloud configuration.
Click on "Export SP Cert" and save the certificate file.
Click on "Export Metadata" and save the metadata file, which also contains the certificate.
Login to your Identity Provider portal and view the SSO configuration for Keeper.
Upload Keeper's SP certificate file (or metadata, if required) following their instructions to update the Service Provider certificate and Save.
The reason for this, is because the Automator service essentially becomes the service provider. The SSL certificate generated by the customer is used in the signing process.
Azure and AWS Deployments
If you are updating the SSL certificate in an environment that utilizes application gateways or a load balancer with a custom domain that terminates SSL, you need to also update the certificate on that device.
For Azure deployments using an App Gateway, the
.pfxcertificate must also be updated in the https listener for the gateway. Go to your Azure > Resource groups > App Gateway > Listeners and upload the new certificate.
Advanced Settings
Configuration settings and features on Automator
Overview
The settings in this document control the features and security of the Automator service.
Setting: automator_debug
automator_debugEnv Variable: AUTOMATOR_DEBUG
Description: This is an easier way to turn on/off debug logging in Automator.
Setting: automator_config_key
automator_config_keyEnv Variable: AUTOMATOR_CONFIG_KEY
Default: Empty
Description: Base64-url-encoded 256-bit AES key. This is normally only used as an environment variable. (since v3.1.0). This setting is required to load the encrypted configuration from the Keeper cloud if there is no shared /usr/mybin/config file storage between container instances.
Setting: automator_host
automator_hostEnv Variable: AUTOMATOR_HOST
Default: localhost
Description: The hostname or IP address where the Automator service is listening locally. If SSL is enabled (ssl_mode parameter), the automator_host value needs to match the SSL certificate subject name. The setting disable_sni_check can be set to false if the subject name does not match.
If the service is running on a machine with multiple network IPs, this setting will bind the Automator service to the specified IP.
If you encounter binding errors in the service startup, it is recommended to use the local network IP address in the host setting instead of localhost.
Setting: automator_port
automator_portEnv Variable: AUTOMATOR_PORT
Default: 8089
Description: The port where the Automator listens. If running in Docker, use the default 8089.
Setting: disable_sni_check
disable_sni_checkEnv Variable: DISABLE_SNI_CHECK
Default: false
Description: Disable the SNI check against the certificate subject name, if SSL is being used.
Setting: email_domains
email_domainsEnv Variable: EMAIL_DOMAINS
Default: null
Description: A comma-separated list of user email domains for which Automator will approve devices or teams. Example: "example.com, test.com, mydomain.com". This depends on the filter_by_email_domains setting to be enabled as well.
Setting: filter_by_email_domains
filter_by_email_domainsEnv Variable: FILTER_BY_EMAIL_DOMAINS
Description: If true, Keeper will consult the email_domains list. If false, the email_domains list will be ignored.
Setting: enabled
enabledEnv Variable: N/A
Default: false
Description: This determines if Automator is enabled or disabled.
Setting: enable_rate_limits
enable_rate_limitsEnv Variable: ENABLE_RATE_LIMITS
Default: false
Description: If true, Automator will rate limit incoming calls per the following schedule:
approve_device: 100 calls/minute with bursts to 200
approve_teams_for_user: 100 calls/minute with bursts to 200
full_reset: 4 per minute, with bursts to 6
health: 4 per minute
initialize: 4 per minute, with bursts to 6
setup: 4 per minute, with bursts to 6
status: 5 per minute
Setting: ip_allow and ip_deny
ip_allow and ip_denyEnv Variable: IP_ALLOW and IP_DENY
Default: ""
Description: This restriction allows users to be eligible for automatic approval. Users accepted by the IP restriction filter still need to be approved in the usual way by Automator. Users denied by the IP restriction filter will not be automatically approved.
If "ip_allow" is empty, all IP addresses are allowed except those listed in the "ip_deny" list. If used, devices at IP addresses outside the allowed range are not approved by Automator. The values are a comma-separated list of single IP addresses or IP ranges. The "ip_allow" list is checked first, then the "ip_deny" list is checked.
Example 1: ip_allow=
ip_deny=
Example 2:
ip_allow=10.10.1.1-10.10.1.255, 172.58.31.3, 175.200.1.10-175.200.1.20
ip_deny=10.10.1.25
Setting: name
nameEnv Variable: N/A
Default: Automator-1
Description: The name of the Automator. It should be unique inside an Enterprise. An automator can be referenced by its name or by its ID.
Setting: persist_state
persist_stateEnv Variable: N/A
Default: true
Description: If true, the Automator state will be preserved across shutdowns. Leave this on.
Setting: skill
skillEnv Variable: N/A
Default: device_approval
Description: “device_approval” means device approval. “team_for_user_approval” means team approvals. An Automator can have multiple skills. “device_approval” is the default.
Setting: ssl_certificate
ssl_certificateEnv Variable: SSL_CERTIFICATE
Default: null
Description: A Base64-encoded string containing the contents of the PFX file used for the SSL certificate. For example, on UNIX base64 -i my-certificate.pfx will produce the required value.
Using this environment variable will override the ssl_certificate_filename setting.
Setting: ssl_certificate_file_password
ssl_certificate_file_passwordEnv Variable: SSL_CERTIFICATE_PASSWORD
Default: ""
Description: The password on the SSL file. If used, the key password should be empty, or should be the same. The library we use does not allow different passwords.
Setting: ssl_certificate_key_password
ssl_certificate_key_passwordEnv Variable: SSL_CERTIFICATE_KEY_PASSWORD
Default: ""
Description: The password on the private key inside the SSL file. This should be empty or the same as the file password.
Setting: ssl_mode
ssl_modeEnv Variable: SSL_MODE
Default: certificate
Description: The method of communication on the Automator service. This can be: certificate, self_signed, or none. If none, the Automator server will use HTTP instead of HTTPS. This may be acceptable when Automator is hosted under a load balancer that decrypts SSL traffic.
Setting: url
urlEnv Variable: N/A
Default: ""
Description: The URL where the Automator can be contacted.
Troubleshooting
Common issues and troubleshooting for your Automator service
Unable to communicate with the Automator service
There are several reasons why Keeper Commander is unable to communicate with your Automator service:
Ensure that the automator service is open to Keeper’s IP addresses. The list of IPs that must be open are found at this Ingress Requirements page. We recommend also adding your own IP address so that you can troubleshoot the connection.
If you are using a custom SSL certificate, ensure that the SSL certificate is loaded. Check the Automator log files which will indicate if the certificate is loaded by the service restart. If the IP address is open to you, you can run a health check on the command line using curl, for example:
curl https://automator.mycompany.com/healthCheck that the subject name of the certificate matches the FQDN.
Check that your SSL certificate includes the CA intermediate certificate chain. This is the most common issue that causes a problem. Keeper will refuse to connect to Automator if the intermediate certificate chain is missing. You can do this using openssl like the following:
This command will clearly show you the number of certificates in the chain. If there's only a single cert, this means you did not load the full chain. To resolve this, see Step 4 of the Custom SSL Certificate step by step instructions page.
400 Error in Health Checks
This may occur if the healthcheck request URI does not match the SSL certificate domain. To allow the healthcheck to complete, you need to disable SNI checks on the service. This can be accomplished by setting the disable_sni_check=true in the Automator configuration or passing in the environmental variable DISABLE_SNI_CHECK with the value of "true".