Teams App

Teams Approval Workflow Integration with the Keeper Vault and Endpoint Privilege Manager

Overview

The Keeper Teams App helps achieve zero standing privilege and streamlines credential workflow requests and approvals directly from Teams. The customer hosts the Teams agent and Commander Service Mode, ensuring that zero knowledge is maintained with end-to-end encryption.

This document describes the installation of the Keeper Teams App using a streamlined setup method that requires the use of Keeper Secrets Manager. If you don't have a Secrets Manager or KeeperPAM license, please contact your Keeper account manager.

Features

Feature
Description

Record Access Requests

Request access to specific Keeper records with justification, custom permissions and access time limits. This includes standard vault records and KeeperPAM resources.

Folder Access Requests

Request access to specific Keeper Shared Folders with justification, custom permissions and access time limits.

One-Time Share Requests

Request for a one-time share, password reset or other dynamic password generation with a self-destructing share link. The one-time share can also be editable, offering bi-directional sharing capabilities.

Endpoint Privilege Manager Approvals

Keeper Endpoint Privilege Manager (KEPM) just-in-time elevation approvals in realtime through a dedicated Teams channel.

SSO Cloud Device Approvals

Perform approvals of SSO Cloud devices directly through Teams, if the Keeper Automator service is not deployed.


Prerequisites

System Requirements

To maintain zero knowledge and full end-to-end encryption, the Keeper Teams App and Commander Service Mode containers are hosted by each customer on their own infrastructure to interact with the Microsoft Teams cloud service. Commander is used locally to help set everything up.

Requirement
Details

Linux VM

Any VM in the cloud or on-prem which can establish https/443 outbound connections to Teams and Keeper services.

Docker

Docker is the recommended method for setting up the service

Keeper Commander

Latest Keeper Commander needs to be install

Keeper Secrets Manager

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

Microsoft Azure Tenant

Requires admin access to register apps in Azure AD

Microsoft Teams

Teams workspace with permissions to install custom apps

circle-exclamation

Setup Steps

In the below setup instructions, we'll be using Commander and Teams-App Docker Images (keeper/commanderarrow-up-right and keeper/teams-apparrow-up-right). This integration also leverages Keeper Secrets Manager to secure the configurations used by the services.

Follow these eight steps to configure the Teams app:


Step 1. Register Azure AD Application

In this section, you will create an Azure AD Application in your Microsoft 365 tenant to authenticate the Teams bot.

  • Sign in to the Azure Portalarrow-up-right as a Global Administrator or Application Administrator

  • Navigate to Azure Active DirectoryApp registrations

  • Click New registration -> All applications

  • Configure the application: - Name: keeper-security-teams - Supported account types: "Accounts in this organizational directory only" - Redirect URI: Leave blank for now

  • Click Register

  • After creation, note the following values from the Overview page:

    • Application (client) ID - Save this as AZURE_CLIENT_ID

    • Directory (tenant) ID - Save this as AZURE_TENANT_ID

  • Configure API Permissions:

    • Go to Manage → API permissionsAdd a permission

    • Select Microsoft GraphApplication permissions

    • Add the following permissions:

      • ChannelMessage.Read.All

      • User.Read.All

    • Click Grant admin consent for MSFT

  • Create a Client Secret:

  • Go to Certificates & secretsClient secrets

  • Click New client secret

  • Description: Keeper Teams App

  • Expiration: Select appropriate duration (recommend 24 months)

  • Click Add

  • Copy the Value immediately - Save this as AZURE_CLIENT_SECRET

After creating the app, collect these credentials:

Credential
Location

CLIENT_ID

App Registration → Overview → Application (client) ID

TENANT_ID

App Registration → Overview → Directory (tenant) ID

Signing Secret

App Registration → Certificates & secrets →Client secrets(Value)

circle-info

Save the Generated Client ID, Tenant ID and Signing Secret value for Step 4.


Step 2. Create Azure Bot Registration

  • In the Azure Portal, search for Bot Services -> click Create a resource

  • Search for Bot Services and click Create

  • Configure the bot:

    • Bot handle: keeper-security-bot (must be unique)

    • Subscription: Select your subscription

    • Resource group: Create new or use existing

    • Pricing tier: Free (F0) for testing, Standard (S1) for production

    • Type of App: Single Tenant

    • Creation type: Use existing app registration

    • App ID: Enter the Application (client) ID and tenant ID from Step 1

  • Click Review + createCreate

  • Note the Microsoft App ID (same as Application ID from Step 1) - Save this as BOT_ID


Step 3. Create Approvals Channel

  • In Microsoft Teams, create a new Private channel (e.g., #keeper-vault-approvers)

    • Right-click on your Team → Add channel

    • Channel name: keeper-vault-approvers

    • Privacy: Private - Only specific teammates can access

    • Click Create

  • Get the Team ID and Channel ID:

    • Open Teams in a web browser

    • Navigate to the approvals channel

    • Click on the channel name -> will open a popup like below

    • Copy the link and open in a new tab

    • The URL will look like: https://teams.microsoft.com/l/channel/19%[email protected]/...?groupId=<TEAM_ID>&tenantId=...

    • Extract the groupId as Team ID

    • Channel ID: The value between /channel/ and the channel name, URL-decoded Replace %3A with : and %40 with @ Example (before): 19%3AXSD5456476qe-a915_bN8WU7qScl7687678nj1Ya0e0RM1%40thread.tacv2 Example (after): 19:[email protected]

circle-info

Save the Channel ID and Team ID for Step 5.

Step 4. 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 ([email protected])

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


Step 5. Run Teams App Setup Command

The teams-app-setup command generates a docker-compose.yml file which you will use to operate the Teams App and Commander Service Mode services.

From the Commander shell, type:

Command Line Options

The teams-app-setup command supports the following optional flags for customization:

Parameter
Description
Default Value

--folder-name (optional)

Name for the shared folder

Commander Service Mode - Teams 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

--teams-record-name (optional)

Name for the Teams config record

Commander Service Mode Teams 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:

The command will guide you through the following prompts:

Phase 1: Docker Service Mode Setup

It automatically configures KSM and uploads the config file required for setting up service mode via Docker.

Service Configuration

Configure the Commander Service port:

Prompt
Description
Example

Port

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

8900

Phase 2: Teams App Integration Setup

Enter the Teams credentials obtained from Steps 1 and 2:

Prompt
Description
Example

Teams Client ID (required)

Azure App Registration Application (client) ID

2efdee8-6a0a-0...

Client Secret (required)

Azure App Registration secret value

f16241e1-b52a-24...

Tenant ID (required)

Azure AD Directory (tenant) ID

a1b2c3d4e5f6...

Teams Approvals Channel ID (required)

The channel ID from Step 3.(Required)

Approvals Team ID (required)

The channel ID from Step 3.(Required)

9336604b-038e-4...

Teams bot port

Port on which the Teams bot will listen for incoming requests

eg: 3978

Enable PEDM? (optional)

Enable Endpoint Privilege Manager approvals (y/n).

y

PEDM Polling Interval (optional)

How often to check for PEDM requests in seconds. Default: 120.

120

Enable Device Approvals?(optional)

Enable SSO Cloud device approvals (y/n).

y

Device Approval Polling Interval (optional)

How often to check for device approvals in seconds. Default: 120.

120

circle-info

In order to process Endpoint Privilege Manager approvals and SSO Cloud approvals, the Teams App service user must have administrative permissions "Manage Endpoint Privilege" and "Managing the Keeper Admin Console.

After the command executes successfully, it automatically performs the following actions:

  • Configures persistent device authentication

  • Creates a Shared Folder named “Commander Service Mode – Teams App”

  • Creates a KSM application with access to the shared folder

  • Creates a client device and generates a Base64-encoded configuration value

  • Creates a Docker Config record and uploads the config.json file from the .keeper directory

  • Creates a Teams App Config record containing the Teams App credentials.

  • Upon successful execution, a docker-compose.yml is generated containing both the Commander Service Mode and Teams App services, ready for deployment.

Once setup is complete, ensure that the Commander session is terminated and the local .keeper/config.json file is deleted to prevent device token conflicts.


Step 6. Deploy to Docker Environment

In this section, you will set up a Docker Compose environment on a Linux virtual machine or host where the Commander Service will run.

  • Launch a Linux VM or prepare a Linux host and connect to it via SSH.

  • Install docker and docker-compose (refer to the installation instructions here)

  • Transfer the generated docker-compose.yml file from Step 4 to the target Linux server.

Start up the services on the host machine:

Service Startup Sequence

The services start sequentially:

  1. Commander Service starts first, generates an API key, and saves it along with the service URL to the vault record

  2. Health checks validate the Commander service is running

  3. Teams App starts after health checks pass, automatically retrieving the API key and service URL from the vault record

Verify Successful Startup

Monitor the logs to make sure everything starts up.

  • Check container status:

  • View Commander Service logs:

circle-info

The API key is redacted in Docker logs for security. Both services communicate securely via the shared vault record.

  • View Teams App logs:

If everything is successful, you'll see the messages below:


Step 7. Configure Messaging Endpoint

After the bot is deployed and running, you need to configure the messaging endpoint so Microsoft Teams can communicate with your bot.

  1. Install and authenticate ngrok in the Linux VM

Get your auth token from the ngrok dashboardarrow-up-right. Reserve a static domain under Domains in the dashboard.

  1. Start ngrok

  1. Set the messaging endpoint in Azure

    1. Go to the Azure Portalarrow-up-right → your Azure Bot resource

    2. Navigate to SettingsConfiguration

    3. Set Messaging endpoint to: https://<YOUR_STATIC_DOMAIN>/api/messages

    4. Click Apply

  2. Verify

Step 8. Upload Teams app package

In this section, After the Docker services are running, upload the Teams app package to your Microsoft Teams environment.

  • Download the app package template from the releases pagearrow-up-right

  • Extract the ZIP file, which contains:

  • Edit manifest.json and replace the placeholders:

    • Replace ${{TEAMS_APP_ID}} with your Azure Client ID (from Step 1)

    eg:-

    • Replace ${{BOT_ID}} with your Bot ID (same Azure Client ID)

    eg:-

  • Repackage the files into a ZIP:

  • Upload to Teams Admin Center:

    • Navigate to Teams appsManage apps

    • Click Upload an app → Select Upload an app to your organization's app catalogue

    • Select your keeper-teams-app.zip file

    • then, click upload

triangle-exclamation
  • After upload the Zip file -> Install the App to Your Team

    • In Microsoft Teams, navigate to your team

    • Click ... next to the team name → Manage team

    • Go to the Apps tab

    • Click More apps (bottom right)

    • Search for Keeper Security and click open with your approver team/channel.

    Once the app is installed at the team level, the bot needs to be initialized in the approvals channel so it can route approval requests there.

    • It will auto-redirect you to channel or Navigate to the keeper-vault-approvers private channel.

    • Mention your bot name with this command, @keeper Security /channel-status.

Thats it now end users can start raise requests.


Command Reference for Requesting User

circle-exclamation

keeper-request-record

Request access to a specific Keeper record.

Syntax:

keeper-request-folder

Request access to a shared folder.

Syntax:

keeper-one-time-share

Request a one-time share link for a record.

Syntax:


Screenshots

The below screenshots demonstrate the core features of the Keeper Teams App.

Interacting with the Teams App bot for Requests (Requesting User View)


Requesting Access to a Record (no UID provided)


Requesting Access to a Record with UID provided - (Admin View)


Record Access Request - (Admin View)


Requesting Access to a Folder - After Approved (Admin View)


Folder Access Request with UID- (Admin View)


One-time Share Request - (Admin View)


One-Time Share - Admin View with New Record Creation


One-Time Share - Requesting User View with after approved


Endpoint Privilege Manager - Approval for Elevation


SSO Cloud Device Approval - Admin View


Updates

Updating the Commander Service Mode and Teams app Container

To update to the latest version of Commander or the Teams App, follow the steps below to stop the service, update the containers and start up the new containers.


Troubleshooting

Startup Errors

Error
Cause
Solution

Commander Service Mode is prompting for master password

Multiple config.json files are attached to the Vault record

Follow steps 4-5 to run the teams-app-setup command with new folder name again to create a new JSON config file.

[WARN] Warning: Cannot reach Keeper Service Mode

Service Mode not running or wrong URL

Verify the service URL in the vault record is as expected

BotFrameworkAdapter initialization failed

Invalid bot credentials

Verify MICROSOFT_APP_ID and MICROSOFT_APP_PASSWORD

Azure AD authentication error

Invalid tenant or client credentials

Verify AZURE_TENANT_ID, AZURE_CLIENT_ID, and AZURE_CLIENT_SECRET


Teams API Errors

Error
Cause
Solution

Conversation not found

Invalid team or channel ID

Verify TEAMS_TEAM_ID and TEAMS_CHANNEL_ID

Authorization denied (401)

Bot not properly configured or token expired

Regenerate client secret and update configuration

Forbidden (403)

Missing API permissions

Ensure Graph API permissions are granted admin consent

Channel not found

Bot not added to channel

Add the bot to the approvals channel

Activity not found

Message was deleted or activity ID invalid

This may occur when updating old cards; can be ignored


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


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

Last updated

Was this helpful?