Ctrlk
HomepageSystem Status
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Google Chat App

Google Chat Approval Workflow Integration with the Keeper Vault and Endpoint Privilege Manager

Overview

The Keeper Google Chat App enables just-in-time access management and secure credential sharing within your Google Workspace environment. By integrating directly with Google Chat, teams can request, approve, and manage Keeper vault access without leaving their collaboration platform.

This self-hosted solution runs entirely on your infrastructure alongside Commander Service Mode, preserving Keeper's zero-knowledge security model. All communications between Google Chat and your Keeper vault remain end-to-end encrypted.

This guide covers deploying the Google Chat App using Cloud Pub/Sub for real-time message delivery. A Keeper Secrets Manager or KeeperPAM license is required — contact your account manager if you need to enable these features.

Features

Feature
Description

Record Access Requests

Users can request time-limited or permanent access to individual vault records, including KeeperPAM resources. Approvers see full request details and can grant custom permission levels. PAM User records support optional automatic credential rotation when temporary access expires.

Folder Access Requests

Grant users access to Classic Shared Folders or Nested Share Folders (NSF) with granular permission controls. Supports time-bound access with optional password rotation for PAM User folders upon expiration.

External/One-Time Share Requests

Generate secure, self-destructing share links for passwords, credentials, or sensitive data. Links can be view-only or editable for bi-directional sharing scenarios.

Self-Serve Record Creation

Empower engineers to add new credentials directly into shared folders they already have access to. The /keeper-create-secret command guides users through folder selection and record creation, with automatic admin notifications.

Endpoint Privilege Manager Approvals

Process KEPM elevation requests in real-time. When users need temporary admin privileges on their endpoints, approval cards appear instantly in your designated Google Chat space.

SSO Cloud Device Approvals

Authorize new SSO Cloud devices through Google Chat when Keeper Automator is not deployed. Admins receive device approval requests and can approve or deny with a single click.

Prerequisites

Infrastructure Requirements

The Keeper Google Chat App follows a self-hosted architecture where your organization maintains full control over the integration components. This design ensures that sensitive credential data never passes through external services.

Requirement
Details

Linux VM

Any VM in the cloud or on-prem that can establish outbound HTTPS connections to Google Chat and Keeper services.

Docker

Docker is the recommended method for setting up the service

Keeper Commander

Service Mode running and accessible

Keeper Secrets Manager

Either Keeper Secrets Manager or KeeperPAM license used for retrieving the secret configuration data

Google Workspace Account

Administrator access for Chat app registration and API enablement

Google Cloud Project

Houses the Pub/Sub infrastructure and service credentials

Important: The gchat-app-setup command requires Keeper Secrets Manager (KSM) to be activated. If KSM is not available, please contact your account manager.

Setup Steps

Configuring the Google Chat App involves setting up Google Cloud resources, registering the Chat application, and deploying the containerized services:

Follow these steps to configure the Google Chat App:

  1. Set Up Google Cloud Project

  2. Create a service account and key

  3. Configure Pub/Sub Messaging

  4. Grant IAM permissions

  5. Register the Chat Application

  6. Prepare the Approvals Space

  7. Commander Service Mode Setup

  8. Run Google Chat App Setup Command

  9. Deploy to Docker Environment

Step 1. Set Up Google Cloud Project

  1. Navigate to the Google Cloud Console

  2. Create a dedicated project for the Keeper (Name as - Keeper Security Google chat App ).

Record your Project ID — this identifier is required throughout the setup process.

  1. Enable the necessary APIs:

  • Open APIs & Services → Library

  • Locate/search and enable the Google Chat API

  • Locate/search and enable the Cloud Pub/Sub API

Step 2. Create a service account and key

This account lets the app pull events from Pub/Sub and post messages to Chat.

  1. Go to IAM & Admin → Service Accounts

  2. Select Create Service Account

  1. Enter a descriptive name: keeper-chat-worker -> create

  2. Open the account -> Keys -> Add key -> Create new key -> JSON.

  3. Rename and Save the downloaded file as service-account.json .

The service-account.json will be used in Step 8.

Step 3. Configure Pub/Sub Messaging

Cloud Pub/Sub serves as the message broker between Google Chat and your self-hosted application. This pull-based approach eliminates the need for public endpoints or inbound firewall rules.

a. Create the Topic:

  1. In the Cloud Console, open Pub/Sub -> Topics

  2. Enter Topic ID: keeper-chat-events

  3. Disable "Add a default subscription" (we'll create a custom one)

Leave everything else at defaults and click Create -> Confirm with Create

b. Create the Subscription:

  1. Navigate to Pub/Sub -> Subscriptions (direct link)

  2. Select Create Subscription

  1. Enter Subscription ID: keeper-chat-events-sub

  2. Choose the topic created above from Step 3(a).

  3. Configure delivery settings:

    • Delivery type: Pull

    • Acknowledgement deadline: 60 seconds

  4. Leave all other fields at defaults and click Create.

Step 4. Grant IAM permissions

Two separate grants are required. Missing either causes "Keeper Security is not responding" or events never arriving.

a. Let Google Chat publish to the topic

  1. Pub/Sub -> Topics -> keeper-chat-events -> Permissions -> Add Principle.

Add the following as Pub/Sub Publisher:

Principal
Role

chat-api-push@system.gserviceaccount.com

Pub/Sub Publisher

b. Let the worker read the subscription

Pub/Sub -> Subscriptions -> keeper-chat-events-sub -> Permissions -> Add Principle.

Principal
Role

keeper-chat-worker@<YOUR_PROJECT_ID>.iam.gserviceaccount.com

Pub/Sub Subscriber

Step 5. Register the Chat Application

Important: Leave "Deploy as a Google Workspace Add-on" unchecked. Enabling this option locks your configuration and prevents future modifications.

  1. Return to Google Cloud Console

  2. Open APIs & Services -> Enabled APIs & services

  3. Click on Google Chat API

  1. Select the Configuration tab

  2. Complete the application profile:

Build this Chat app as a Google Workspace add-on: leave UNCHECKED.

Setting
Value

App name

Keeper Security

Avatar URL

https://keeper-email-images.s3.amazonaws.com/common/256x256_icon.png

Description

Keeper vault credentials access in chat

Interactive features

Enabled

Join spaces and group conversations

Enabled

Connection settings

Cloud Pub/Sub

Pub/Sub topic name

projects/YOUR_PROJECT_ID/topics/keeper-chat-events

  1. Register the slash commands:

Command
Command ID
Description

/keeper-request-record

1

Request access to a keeper vault record

/keeper-request-folder

2

Request access to a keeper shared folder

/keeper-external-share

3

Request access to a keeper vault record for External share

/keeper-create-secret

4

Create a new record to a shared folder in Keeper

  1. Configure visibility under the Visibility section:

    • Add your email address under Development/Testing Users.

Note: Only the email addresses added here will be able to see and interact with the app during development and testing. Complete the remaining setup and verify that the Keeper Google Chat app is working as expected. Once verified, publish the app internally so that users across the organization can access and use it.

  1. Save your configuration

Step 6. Prepare the Approvals Space

Access requests and administrative notifications are posted to a designated Google Chat space where approvers can review and act on them.

  1. Open Google Chat

  2. Under Spaces, select Create space

  3. Configure the space:

    • Name: Keeper-vault-Approvers (or your preference)

    • Add team members who should handle access requests

  1. Install the Keeper app in this space:

  • Click the space name → View details

  • Select Apps & integrations → Add apps

  • Find "Keeper Security" and add it

  1. Obtain the Space ID:

  • The URL shows: https://chat.google.com/chat/XXXXXXXXX

  • Your Space ID is: spaces/XXXXXXXXX

Space ID will be used in step 8.

Step 7. Commander Service Mode Setup

To enable the service to authenticate and execute commands within the Keeper tenant, an authorized Keeper Commander configuration file must be created. This configuration can be generated on a host computer or workstation.

  • Install Keeper Commander locally on your machine

  • If required, create a new Keeper service account dedicated to this integration, ensuring it has access to the relevant records and folders and the ability to perform record and folder sharing.

  • Login to Commander with the Keeper Service account (serviceuser@company.com)

  • Complete the authentication process including any 2FA requirements. Once you are fully authenticated, proceed to Step 4.

Step 8. Run Google Chat App Setup Command

The gchat-app-setup command generates a docker-compose.yml used to run the Google Chat App and Commander Service Mode.

From the Commander shell:

Command Line Options

Parameter
Description
Default Value

--folder-name (optional)

Name for the shared folder

Commander Service Mode - Google Chat App

--app-name (optional)

Name for the Secrets Manager app

Commander Service Mode - KSM App

--config-record-name (optional)

Name for the Commander config record

Commander Service Mode Docker Config

--gchat-record-name (optional)

Name for the Google Chat config record

Commander Service Mode Google Chat App Config

--config-path (optional)

Path to config.json file

~/.keeper/config.json

--timeout (optional)

Device timeout setting

30d

--skip-device-setup (optional)

Skip device registration if already configured

false

Example with custom names:

Phase 1: Docker Service Mode Setup

The command configures KSM and uploads the configuration file for Docker Service Mode.

Service Configuration

Configure the Commander Service port:

Prompt
Description
Example

Port

Port number for Commander Service Mode (1024-65535).

8900

Tunneling Configuration (Optional)

Prompt
Description

Ngrok Auth Token

Your ngrok authentication token for public URL generation.

Ngrok Custom Domain

Custom ngrok domain (for example, myapp.ngrok.io).

Cloudflare Tunnel Token

Cloudflare tunnel token for public URL generation.

Cloudflare Custom Domain

Your Cloudflare domain (for example, gchat.company.com).

Ngrok and Cloudflare are mutually exclusive. This is NOT required for the Google Chat App. You may need a tunnel if you also use other integrations such as the Jira app. Cloudflare example domain: gchat.company.com.

Phase 2: Google Chat App Integration Setup

Enter the values from the earlier GCP and Google Chat setup steps:

Prompt
Description
Example

Path to service account JSON file (required)

Path to the GCP service account JSON key used for Pub/Sub pull and Google Chat API. Inline JSON paste is not accepted.

/path/to/service-account.json

Project ID (required)

GCP project ID. Press Enter to use project_id from the service account JSON. If it differs from the SA project, confirm before continuing.

your-gcp-project-id

Topic ID (required)

Pub/Sub topic that receives Google Chat events.

keeper-chat-events

Subscription ID (required)

Pub/Sub subscription used to pull events.

keeper-chat-events-sub

Space ID (required)

Google Chat space where approval cards are posted. Must start with spaces/ and include a space id.

spaces/<YOUR_ID>

/keeper-request-record command ID

Slash command ID should be same as registered in slash command id in console.

1

/keeper-request-folder command ID

Slash command ID should be same as registered in slash command id in console.

2

/keeper-external-share command ID

Slash command ID should be same as registered in slash command id in console.

3

/keeper-create-secret command ID

Slash command ID should be same as registered in slash command id in console.

4

Enable PEDM? (optional)

Enable Endpoint Privilege Manager approvals (y/n).

y

PEDM Polling Interval (optional)

Seconds. Default 120.

120

Enable Device Approvals? (optional)

Enable SSO Cloud device approvals (y/n).

y

Device Approval Polling Interval (optional)

Seconds. Default 120.

120

After setup, the command creates a Google Chat configuration record. It includes these fields:

  • google_service_account_json (secret), google_project_id, google_topic_id, and google_subscription_id

  • chat_approvals_space_id, chat_command_request_record_id, chat_command_request_folder_id, chat_command_external_share_id, and chat_command_create_secret_id

  • Optional pedm_* and device_approval_* fields

The command generates a docker-compose.yml for Commander Service Mode and the Google Chat App.

Once setup is complete, terminate the Commander session. Delete the local .keeper/config.json file to prevent device token conflicts.

Step 9. Deploy to Docker Environment

Set up Docker Compose on the Linux VM or host that runs Commander Service Mode.

  • Launch a Linux VM or prepare a Linux host and connect through SSH.

  • Install docker and docker-compose. See the Installing Docker on Linux.

  • Transfer the generated docker-compose.yml file from Step 7 to the host.

Start the services:

Service Startup Sequence

  1. Commander Service starts and stores its API key and URL in the vault record.

  2. Health checks validate the Commander Service.

  3. Google Chat App starts after the health check passes.

Verify Successful Startup

Check the container status:

View Commander Service logs:

View Google Chat App logs:

After verifying that the app is working as expected, follow the instructions in the link below to publish the app internally. Once published, users within the organization will be able to install the Keeper Google Chat app and use it to raise access requests.

Publishing the Keeper Google Chat App Internally

Command Reference for Requesting User

/keeper-request-record

Request access to a specific Keeper record.

Syntax:

/keeper-request-folder

Request access to a shared folder.

Syntax:

/keeper-create-secret

Create a new secret record in a shared folder that has been shared with you.

Syntax:

/keeper-external-share

Request a one-time share link for a record for external user or vendor.

Syntax:

Screenshots

The below screenshots demonstrate the core features of the Keeper Google chat App.

Interacting with the Google chat App for Requests

Requesting Access to a Record (no UID provided)

Requesting Access to a Record (with UID provided)

Search for Nested/New Record Type [NSF] - Admin View

Record Access Request - Admin View

Requesting Access to a Folder (with UID provided)

Folder Access Request - Admin View

NSF Folders Search with Permissions - Admin View

External/One-time Share Request for vendors

Classic and New Record Creation - Admin View

Self-Serve Record Creation (Requesting user)

One-Time Share - Admin View with Search for Existing Record

Endpoint Privilege Manager - Approval for Elevation

SSO Cloud Device Approval - Admin View

Updates

Updating the Commander Service Mode and Google Chat App Container

To update Commander or the Google Chat App, stop the services, update the containers, and restart them.

Troubleshooting

Startup Errors

Error
Cause
Solution

Commander Service Mode is prompting for master password

Multiple config.json files are attached to the vault record

Run gchat-app-setup with a new folder name to create a new JSON configuration file.

[WARN] Warning: Cannot reach Keeper Service Mode

Service Mode is not running or has the wrong URL

Verify the service URL in the vault record.

Service Mode Errors

Error
Cause
Solution

Failed to submit command: HTTP 403

API key invalid or missing

Verify api_key in config vault record matches service mode

Failed to submit command: HTTP 404

Wrong API endpoint version

Use V2 endpoint: /api/v2/ (not /api/v1/)

Failed to submit command: HTTP 405

Using wrong HTTP method

Ensure Service Mode is running with queue enabled

Command timed out or failed

Service Mode overloaded or command not registered

Register command in Service Mode; increase timeout

No request_id received from API

Service Mode not using queue/async mode

Restart Service Mode with queue enabled (V2)

Access Grant Errors

Error
Cause
Solution

Record Not Found

Invalid UID or record deleted

Verify the record UID exists in Keeper vault

Folder Not Found

Invalid folder UID

Verify the folder UID exists in Keeper vault

Invalid UID Type (record vs folder)

Used wrong command for item type

Use /keeper-request-folder for folders, /keeper-request-record for records

This user already has time-limited access...

Conflict with existing share

Revoke existing access first, then grant new permission

Share permissions require permanent access

Trying to use duration with Can Share/Edit & Share

Share permissions (Can Share, Edit & Share, Change Owner) are always permanent

User share...failed

Permission conflict on folder

User may have incompatible existing access; revoke and re-grant

Search & Modal Errors

Error
Cause
Solution

No records found matching...

Search query too specific or no matches

Try broader search terms; check record exists in vault

Search command timed out

Service Mode slow or vault very large

Increase max_wait in _poll_for_result() or use more specific search

Error processing search modal submission

Modal data corrupted or expired

Close modal and try again; check logs for specific error

Modal shows "Searching..." forever

Poll result never returned

Check Service Mode logs; verify search command is registered

External/One-Time Share Errors

Error
Cause
Solution

one-time share links can not be created for PAM records

Commander doesn't support

Request for non-pam records

Share link created but URL not found in response

Unexpected Service Mode response format

Check Service Mode version; verify one-time-share command registered

Failed to create one-time share

Record may not be shareable

Verify user has share permissions on the record

Record Creation Errors

Error
Cause
Solution

Failed to create record

Missing required fields or command error

Ensure title, login, and password are provided

Record created but UID could not be retrieved

Search after creation failed

Record exists but search timed out; manually search for it

KEPM Errors

Error
Cause
Solution

No data returned

KEPM feature not enabled

Enable KEPM in your Keeper enterprise settings. Ensure that your service user has necessary admin permissions.

KEPM sync failed

Service Mode can't reach KEPM server

Check network connectivity and KEPM configuration

Failed to approve/deny KEPM request

Request may have expired

Check if request is still pending; it may have auto-expired

References

PreviousGitLab
NextPublishing the Keeper Google Chat App Internally

Last updated