Skip to content

Deployment guide

Jump to bottom
Adrian Solis edited this page Oct 8, 2019 · 4 revisions

Prerequisites

To begin, you will need:

We recommend forking the Git repo, so that you have full control over when to take changes (and which changes) from the master repo into your own.

Step 1: Register Azure AD applications

Bot

Register a multi-tenant Azure AD application with one secret. This is the Azure AD application for your bot, and it has to be a multi-tenant app because it will be used to register a service principal in the botframework.com tenant.

  1. Log in to the Azure Portal for your subscription, and go to the “App registrations” blade at https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredApps.
  2. Click on "New registration", and create an Azure AD application.
    1. Name: A name for your Teams bot app - if you are following the template for a default deployment, we recommend "Celebrations Bot".

      This name is not user-visible.

    2. Supported account types: Select "Accounts in any organizational directory"
    3. Leave the "Redirect URI" field blank. multitenant_app_creation
  3. Click on the "Register" button.
  4. When the app is registered, you'll be taken to the app's "Overview" page. Verify that the "Supported account types" is set to Multiple organizations. Copy the Application (client) ID: we will need it later. ClientID
  5. On the side rail in the Manage section, navigate to the "Certificates & secrets" section. In the Client secrets section, click on "+ New client secret". Add a description for the secret, and choose when the secret will expire. Click "Add". Secret
  6. Once the client secret is created, copy its Value: we will need it later.

Teams app

Register a single-tenant Azure AD application in the tenant where you will be using the Celebrations app. This is the app that will be used to authenticate your users.

Because this is a single-tenant AAD app, it MUST be registered in the same tenant where you will be using the Celebrations app.

  1. Go back to the “App registrations” blade.
  2. Click on "New registration", and create an Azure AD application.
    1. Name: The name of your Teams app - if you are following the template for a default deployment, we recommend "Celebrations".
    2. Supported account types: Select "Accounts in this organizational directory only"
    3. Leave the "Redirect URI" field blank. singletenant_app_creation
  3. Click on the "Register" button.
  4. When the app is registered, you'll be taken to the app's "Overview" page. Verify that the "Supported account types" is "My organization only". Copy the Application (client) ID: we will need it later.

At this point you have 3 values:

  • Application (client) ID for the bot (from the first app that you registered)
  • Client secret for the bot
  • Application (client) ID for the app (from the second app that you registered)

Step 2: Deploy to your Azure subscription

  1. Click on the "Deploy to Azure" button below.

    Deploy to Azure

  2. When prompted, log in to your Azure subscription.

  3. Azure will create a "Custom deployment" based on the ARM template and ask you to fill in the template parameters. Custom deployment

  4. Select a subscription and resource group.

    • We recommend creating a new resource group.
    • The resource group location MUST be in a datacenter that supports: Application Insights; Azure Functions; App Service; Storage Accounts; Cosmos DB. For an up-to-date list, click here, and select a region where all of the following services are available:
      • Storage Accounts
      • Application Insights
      • Azure Functions
      • App Service
      • Azure Cosmos DB

  5. Fill in the various IDs in the template:

    1. Bot Client ID: The Application (client) ID for the bot
    2. Bot Client Secret: The client secret for the bot
    3. App Client ID: The Application (client) ID for the app

Make sure that the values are copied as-is, with no extra spaces. The template checks that the IDs are exactly 36 characters.

  1. If you wish to change the app name, description, and icon from the defaults, modify the corresponding template parameters.

    If you forked the repo, update the "Git Repo Url" and "Git Branch" parameters to point to your fork.

    If you're going to be running this app in a different tenant from the one that's associated with your subscription, enter your tenant ID (a GUID) in the "Tenant ID" parameter. By default, the app is deployed using the tenant ID associated with the current Azure subscription.

  2. Agree to the Azure terms and conditions by clicking on the check box "I agree to the terms and conditions stated above" located at the bottom of the page.

  3. Click on "Purchase" to start the deployment.

  4. Wait for the deployment to finish. You can check the progress of the deployment from the "Notifications" pane of the Azure Portal.

  5. Once the deployment has finished, go to the deployment's "Outputs" tab, and note down the values. We will need them later.

    • botId: This is the Microsoft Application ID for the Celebrations app. (We will refer to the value as %botId% in the following steps.)
    • appDomain: This is the base domain for the Celebrations app. (We will refer to the value as %appDomain% in the following steps.)
    • redirectUri: This is the redirect URI for the Celebrations Azure AD app. (We will refer to the value as %redirectUri% in the following steps.)

Step 3: Set up authentication

  1. Go to the Azure AD app registration page for your Teams application.

    This is the second Azure AD app that you registered above.

  2. Under "Manage", click on "Authentication" to bring up authentication settings.
  3. Add a new entry to "Redirect URIs":
    • Type: Web
    • Redirect URI: Enter %redirectUri% from the template deployment output for the URL e.g. https://celebrations-xxxxx.azurewebsites.net/TabAuth/Callback
  4. Under "Implicit grant", check "ID tokens" and "Access tokens".
  5. Click "Save" to commit your changes.

Step 4: Create the Teams app packages

  1. Make sure you have cloned the app repository locally.
  2. Open the Manifest\manifest.json file in a text editor.
  3. Change the placeholder fields in the manifest to values appropriate for your organization.
    • developer.name (What's this?)
    • developer.websiteUrl
    • developer.privacyUrl
    • developer.termsOfUseUrl
  4. Change the <appDomain> placholders to be the %appDomain% value. There are 2 instances of this placeholder:
  5. Change the <botId> placeholder in the botId setting to be the %botId% value. This is the same GUID that you entered in the template under "Bot Client ID".
  6. Create a ZIP package with the manifest.json,color.png, and outline.png. The two image files are the icons for your app in Teams.
    • Make sure that the 3 files are the top level of the ZIP package, with no nested folders. manifest

Step 5: Run the app in Microsoft Teams

  1. If your tenant has sideloading apps enabled, you can install your app to a team by following the instructions below.
  2. You can also upload it to your tenant's app catalog, so that it can be available for everyone in your tenant to install: https://docs.microsoft.com/en-us/microsoftteams/tenant-apps-catalog-teams
  3. Install the app to a team.

Troubleshooting

Please see our Troubleshooting page.

Clone this wiki locally