Provisioning a Bot Tenant

Provisioning a Bot Tenant in EmpowerID involves creating a configuration document in Cosmos DB that enables the EmpowerID Bot to operate within your organization’s Azure environment.

Prerequisites

Before starting, ensure the following:

Before provisioning a Bot Tenant, ensure the following components are configured:

Azure Cosmos DB (bot_database) with containers:
- bot_config
- conversation
- templates
Azure App Service for the EmpowerID Bot endpoint
Azure Blob Storage container
EmpowerID OAuth application for Bot and Mobile access
Required EmpowerID workflows published

Required Access

Azure Portal access with Cosmos DB Contributor or equivalent
EmpowerID admin credentials with workflow management privileges

Steps to Provision a Bot Tenant

1. Navigate to the Cosmos DB Container

In the Azure Portal, go to your Cosmos DB account and open the bot_database database. Then, select the bot_config container.

2. Add a New Configuration Document

To create the bot configuration document:

Click "New Item" in the bot_config container.
Copy the JSON template shown below.
Replace all placeholder values such as [GUID], [Secret Key], and [Secret] with the appropriate values for your environment.

Click Save to store the document.

{
"document": {
    "Locale": "en-US",
    "TenantId": "[GUID]",
    "WorkflowServiceUrl": "https://sso.empoweriam.com",
    "WebChatUrl": "https://mychat.azurewebsites.net/api/Callback/OAuth",
    "WebChatTokenSecretKey": "[Secret Key]",
    "WebChatTokenUrl": "https://directline.botframework.com/v3/directline/tokens/generate",
    "UserExperience": {
    "MaxProcessTimeInSeconds": "10",
    "MaxRequestTimeoutInSeconds": "3"
    },
    "StateBlobConfig": {
    "ConnectionString": "[Blob connection string]",
    "ConainerName": "[container name]",
    "BlobName": "[blob name]"
    },
    "LuisAI": {
    "AppId": "[Luis App Id]",
    "PredictionKey": "[Luis Prediction key]",
    "PredictionEndpoint": "https://westus.api.cognitive.microsoft.com/"
    },
    "StateDatabaseConfig": {
    "CosmosDbEndpoint": "https://mydb.documents.azure.com/",
    "AuthKey": "[Auth key]",
    "DatabaseId": "bot_database",
    "ContainerId": "conversation",
    "CosmosClientOptions": {
        "MaxTcpConnectionsPerEndpoint": null,
        "MaxRequestsPerTcpConnection": null,
        "OpenTcpConnectionTimeout": null,
        "IdleTcpConnectionTimeout": null,
        "MaxRetryWaitTimeOnRateLimitedRequests": null,
        "MaxRetryAttemptsOnRateLimitedRequests": null,
        "ConnectionMode": 0,
        "RequestTimeout": "00:00:00",
        "GatewayModeMaxConnectionLimit": 0,
        "ApplicationRegion": null,
        "ApplicationName": null,
        "ConsistencyLevel": null
    },
    "ContainerThroughput": 400,
    "KeySuffix": null,
    "CompatibilityMode": false
    },
    "TemplateDatabaseConfig": {
    "CosmosDbEndpoint": "https://mydb.documents.azure.com/",
    "AuthKey": "[Auth key]",
    "DatabaseId": "bot_database",
    "ContainerId": "templates",
    "CosmosClientOptions": {
        "MaxTcpConnectionsPerEndpoint": null,
        "MaxRequestsPerTcpConnection": null,
        "OpenTcpConnectionTimeout": null,
        "IdleTcpConnectionTimeout": null,
        "MaxRetryWaitTimeOnRateLimitedRequests": null,
        "MaxRetryAttemptsOnRateLimitedRequests": null,
        "ConnectionMode": 0,
        "RequestTimeout": "00:00:00",
        "GatewayModeMaxConnectionLimit": 0,
        "ApplicationRegion": null,
        "ApplicationName": null,
        "ConsistencyLevel": null
    },
    "ContainerThroughput": 400,
    "KeySuffix": null,
    "CompatibilityMode": false
    },
    "OAuthConfig": {
    "ApiKey": "[Api Key]",
    "ClientID": "[Client ID]",
    "Secret": "[Client Secret]",
    "TokenInfoUrl": "https://sso.empoweriam.com/oauth/v2/tokeninfo",
    "TokenUrl": "https://sso.empoweriam.com/oauth/v2/token",
    "AuthorizeUrl": "https://sso.empoweriam.com/oauth/v2/ui/authorize",
    "UserInfoUrl": "https://sso.empoweriam.com/oauth/v2/userinfo",
    "RevokeUrl": "https://sso.empoweriam.com/oauth/v2/tokenrevoke"
    },
    "AppSettingsJson64": null,
    "BaseWorkflow": "BotBaseWorkflow",
    "AuthWorkflow": "BotAuthWorkflow",
    "AskToSeeTemplate": "AskToSeeTemplate",
    "AskToSeeCardTemplate": "AskToSee",
    "id": "botsvcconfig_[GUID]"
},
"realId": "botsvcconfig_[GUID]",
"id": "botsvcconfig_[GUID]",
"PartitionKey": "botsvcconfig_[GUID]"
}

info

Use a consistent naming convention for id, realId, and PartitionKey, such as botsvcconfig_TenantID. This should match your Microsoft Entra ID (Azure AD tenant).

Configuration Settings Reference

General Configuration

Key	Description
`Locale`	Locale the bot uses (e.g., `en-US`)
`TenantId`	Azure AD Tenant ID for Microsoft Teams
`WorkflowServiceUrl`	URL for EmpowerID Workflow Services
`WebChatUrl`	OAuth callback URL of the Web Chat Bot
`WebChatTokenSecretKey`	Direct Line secret key
`WebChatTokenUrl`	Token generation URL (keep default)

User Experience

Key	Description
`MaxProcessTimeInSeconds`	Max processing time per user request (in seconds)
`MaxRequestTimeoutInSeconds`	Max timeout before aborting user request (in seconds)

StateBlobConfig

Key	Description
`ConnectionString`	Azure Blob connection string
`ConainerName`	Name of the blob container (note typo)
`BlobName`	Name of the blob where state is stored

LuisAI

Key	Description
`AppId`	LUIS Application ID
`PredictionKey`	Prediction key for calling the LUIS model
`PredictionEndpoint`	API endpoint for LUIS predictions

StateDatabaseConfig (Cosmos DB – Conversation State)

Key	Description
`CosmosDbEndpoint`	URL of the Cosmos DB instance
`AuthKey`	Auth key for Cosmos DB
`DatabaseId`	Name of the Cosmos DB database (`bot_database`)
`ContainerId`	Container for conversation state (`conversation`)
`CosmosClientOptions`	Leave defaults unless performance tuning is required
`ContainerThroughput`	Throughput in RU/s (default: `400`)
`KeySuffix`	Leave as `null`
`CompatibilityMode`	Leave as `false`

TemplateDatabaseConfig (Cosmos DB – Adaptive Card Templates)

Key	Description
`CosmosDbEndpoint`	Cosmos DB endpoint
`AuthKey`	Cosmos DB auth key
`DatabaseId`	Cosmos DB database name (typically `bot_database`)
`ContainerId`	Container for templates (typically `templates`)
`CosmosClientOptions`	Default Cosmos client config – no changes required
`ContainerThroughput`	Throughput in RU/s (default: `400`)
`KeySuffix`	Leave as `null`
`CompatibilityMode`	Leave as `false`

OAuthConfig

Key	Description
`ApiKey`	OAuth API Key from EmpowerID application
`ClientID`	OAuth Client ID from EmpowerID
`Secret`	OAuth Client Secret
`TokenInfoUrl`	URL for checking token status
`TokenUrl`	URL for requesting OAuth token
`AuthorizeUrl`	URL for launching EmpowerID OAuth Authorization UI
`UserInfoUrl`	URL for retrieving user identity claims
`RevokeUrl`	URL for revoking access tokens

Workflow References

Key	Description
`BaseWorkflow`	Main bot workflow definition
`AuthWorkflow`	Workflow for bot authentication
`AskToSeeTemplate`	ID of "Ask To See" workflow request template
`AskToSeeCardTemplate`	ID of Adaptive Card Template for "Ask To See"

Document Metadata

Key	Description
`id`	Document ID – must match `realId` and `PartitionKey`
`realId`	Duplicate of `id` – for backward compatibility or filtering
`PartitionKey`	Cosmos DB partition key – must match `id` and `realId`

Sample Configuration

A complete example is provided below for a real EmpowerID tenant deployment.

Click to expand sample JSON configuration

{
"document": {
    "Locale": "en-US",
    "TenantId": "0d8be8a9-3e46-4c80-8e50-4a1f7285c7c2",
    "WorkflowServiceUrl": "https://michael.empoweriam.com",
    "WebChatUrl": "https://eidwebchat.azurewebsites.net/api/Callback/OAuth",
    "WebChatTokenSecretKey": "wE9j-bT5z9Q.eHGZe-citiqQ3dxyu_Y9zJ5zX02MZcPu-zDBKy4D2_g",
    "WebChatTokenUrl": "https://directline.botframework.com/v3/directline/tokens/generate",
    "UserExperience": {
    "MaxProcessTimeInSeconds": "10",
    "MaxRequestTimeoutInSeconds": "3"
    },
    "StateBlobConfig": {
    "ConnectionString": "DefaultEndpointsProtocol=https;AccountName=eidazurejobengine;AccountKey=kNGSID50BEmwdInwNwbOyFmzrO+M/PggUHkSU5Nb9xq/ACzFj0CWn4H5SNALMY17TKJFz7qbnVa8qojP25dVhw==;EndpointSuffix=core.windows.net",
    "ConainerName": "bot",
    "BlobName": "data"
    },
    "LuisAI": {
    "AppId": "67d4f5cd-73b4-4034-8789-d6872bd15b42",
    "PredictionKey": "93a84538b63241718022c9994d83a46c",
    "PredictionEndpoint": "https://westus.api.cognitive.microsoft.com/"
    },
    "StateDatabaseConfig": {
    "CosmosDbEndpoint": "https://bottenanta.documents.azure.com/",
    "AuthKey": "XVnMCpGNYobjpqJrVQbQS9vnBAx8oYDCPEwGLNjUddZnctob9jDP8aROR5d3IN4pO8SvXEglKIu92xJVBhOscQ==",
    "DatabaseId": "botdb",
    "ContainerId": "botdb",
    "CosmosClientOptions": {
        "MaxTcpConnectionsPerEndpoint": null,
        "MaxRequestsPerTcpConnection": null,
        "OpenTcpConnectionTimeout": null,
        "IdleTcpConnectionTimeout": null,
        "MaxRetryWaitTimeOnRateLimitedRequests": null,
        "MaxRetryAttemptsOnRateLimitedRequests": null,
        "ConnectionMode": 0,
        "RequestTimeout": "00:00:00",
        "GatewayModeMaxConnectionLimit": 0,
        "ApplicationRegion": null,
        "ApplicationName": null,
        "ConsistencyLevel": null
    },
    "ContainerThroughput": 400,
    "KeySuffix": null,
    "CompatibilityMode": false
    },
    "TemplateDatabaseConfig": {
    "CosmosDbEndpoint": "https://bottenanta.documents.azure.com/",
    "AuthKey": "XVnMCpGNYobjpqJrVQbQS9vnBAx8oYDCPEwGLNjUddZnctob9jDP8aROR5d3IN4pO8SvXEglKIu92xJVBhOscQ==",
    "DatabaseId": "botdb",
    "ContainerId": "bottemplates",
    "CosmosClientOptions": {
        "MaxTcpConnectionsPerEndpoint": null,
        "MaxRequestsPerTcpConnection": null,
        "OpenTcpConnectionTimeout": null,
        "IdleTcpConnectionTimeout": null,
        "MaxRetryWaitTimeOnRateLimitedRequests": null,
        "MaxRetryAttemptsOnRateLimitedRequests": null,
        "ConnectionMode": 0,
        "RequestTimeout": "00:00:00",
        "GatewayModeMaxConnectionLimit": 0,
        "ApplicationRegion": null,
        "ApplicationName": null,
        "ConsistencyLevel": null
    },
    "ContainerThroughput": 400,
    "KeySuffix": null,
    "CompatibilityMode": false
    },
    "OAuthConfig": {
    "ApiKey": "7c90d994-7f94-47b3-8d63-4dfefd4ba389",
    "ClientID": "b1ac3974-488b-40bc-ba52-e9cc81b74d68",
    "Secret": "C1Gorhadn3btvsZlzvBl7DwQnwoW4N",
    "TokenInfoUrl": "https://michael.empoweriam.com/oauth/v2/tokeninfo",
    "TokenUrl": "https://michael.empoweriam.com/oauth/v2/token",
    "AuthorizeUrl": "https://michael.empoweriam.com/oauth/v2/ui/authorize",
    "UserInfoUrl": "https://michael.empoweriam.com/oauth/v2/userinfo",
    "RevokeUrl": "https://michael.empoweriam.com/oauth/v2/tokenrevoke"
    },
    "AppSettingsJson64": null,
    "BaseWorkflow": "BotBaseWorkflow",
    "AuthWorkflow": "BotAuthWorkflow",
    "AskToSeeTemplate": "AskToSeeTemplate",
    "AskToSeeCardTemplate": "AskToSee",
    "CreatedDateTimeUtc": "2020-12-31T04:19:57.4223927Z",
    "id": "botsvcconfig_0d8be8a9-3e46-4c80-8e50-4a1f7285c7c2"
},
"realId": "botsvcconfig_0d8be8a9-3e46-4c80-8e50-4a1f7285c7c2",
"id": "botsvcconfig_0d8be8a9-3e46-4c80-8e50-4a1f7285c7c2",
"PartitionKey": "botsvcconfig_0d8be8a9-3e46-4c80-8e50-4a1f7285c7c2"
}

Next Step

Once the Bot Tenant is provisioned and the configuration document has been saved to Cosmos DB, proceed to define the Ask to See command templates that the bot will use to display cards to users.

info

You must configure Ask-to-See templates for your bot to respond properly to user prompts within Microsoft Teams or WebChat.

Prerequisites​

Required Access​

Steps to Provision a Bot Tenant​

1. Navigate to the Cosmos DB Container​

2. Add a New Configuration Document​

Configuration Settings Reference​

General Configuration​

User Experience​

StateBlobConfig​

LuisAI​

StateDatabaseConfig (Cosmos DB – Conversation State)​

TemplateDatabaseConfig (Cosmos DB – Adaptive Card Templates)​

OAuthConfig​

Workflow References​

Document Metadata​

Sample Configuration​

Next Step​