Skip to content

Deployment guide

Jump to bottom
bhartwick edited this page Oct 15, 2020 · 15 revisions

Prerequisites

To begin, you will need:

  • User account to sign in to Badgr. Choose one of the available regions: US, Canada, Australia, or EU/Ireland and remember your selection.

  • An Azure subscription where you can create the following kinds of resources:

  • App service

  • App service plan

  • Bot channels registration

  • Azure Key Vault

  • Application Insights

  • A copy of the Badgr app GitHub repo URL

Step 1 : Set up Badgr registration

  1. User account to sign in US Server Badgr website

    • If this is the first time you are setting up an account in Badgr, then please Sign up with your preferred region.
    • Sign in to Badgr with the account you created above.
    • Please note which server location you are using:

  2. After successful sign in, please go to the Issuers menu and add Create new issuer. For more help, please refer

    • Please add details in Issuer form
      • Name (for e.g. Fabrikam University). Please make sure that the issuer name is not used before to avoid unwanted conflicts.
      • Website URL (for e.g. http://fabrikam.com/ )
      • Contact Email - please select the same email account you have signed up
      • Description - Add your group description
      • Please read the policy and click Create Issuer
    • Please note the name of Issuer as it will be used in step 3 section 6

  3. We recommend to create few badges after this step. These badges will be available for all users in your company once they sign in via Open Badges teams application.

    • tip: Decide a few badges that you would like to allow team members to award to each other. Upload badge images that match your brand and program instead of random images.

  4. Client id and client secret from Badgr (Needed in Step 4)

    • To get client id and client secret, please send email to Badgr support team with following details
      • Mail address: [email protected]
      • Subject: : Client id and secret for Open Badges Microsoft Teams app
      • Body: Please make sure to add below information in email
        • Badgr account email - (Your Badgr account email)
        • Badgr account server location (US, CA, EU, AU) from step 1.1
        • Redirect URL - https://token.botframework.com/.auth/web/redirect
        • Website URL - https://open-badges-{yourcompanyname}.azurewebsites.net (please make sure to use the same URL you are planning for deployment and remove the {} symbols)
        • Service name (required, for example "Fabrikam University Professional Development")
        • Application logo (optional, will use MS Teams logo if none provided)
        • Privacy policy URL of your organization (required for step 5.2 even if not functional yet)
        • Terms of service URL of your organization (required for step 5.2 even if not functional yet)
    • Badgr support team will revert back within 2-3 business day with link to access client id and secret via Owncloud secure file share.
    • Please copy and save the client id and secret as it will be used while setting up the authentication in steps 4.4.iii and 4.4.iv

By this time, you should have following details :

  • User account email and password of Issuer owner in Badgr
  • Issuer name within Badgr

Step 2: Register Azure Active Directory applications

  1. Open the Azure Active Directory panel in the Azure portal. If you are not in the correct tenant, click Switch directory to switch to the correct tenant. (For instruction on creating a tenant, see Access the portal and create a tenant.)

  2. Open the App registrations panel.

  3. In the App registrations panel, click New registration.

  4. Fill in the required fields and create the app registration.

    • Name your application - if you are following the template for a default deployment, we recommend "Open Badges".
    • Select the Supported account type as Accounts in any organizational directory.
    • For the Redirect URI
    • Once it is created, Azure displays the Overview page for the app.
    • Record the Application (client) ID value. You will use this value later as the Client ID when you register your Microsoft Azure Active Directory application with your bot.
      • Also record the Directory (tenant) ID value. You will also use this to register this application with your bot (Step 3.6.iii)

  5. In the navigation pane, click Certificates & secrets to create a secret for your application.

    • Under Client secrets, click New client secret.
    • Add a description to identify this secret from others you might need to create for this app, such as bot login.
    • Set Expires to Never
    • Click Add
    • Before leaving this page, record the secret. You will use this value later as the Client secret when you register your Microsoft Azure Active Directory application with your bot. Application Secret = Bot Client Secret (Step 3.6.ii).

You now have an application registered in Microsoft Azure Active Directory.

Step 3: 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.

  4. Select a subscription and resource group.

    • We recommend creating a new resource group.
    • The resource group location MUST be in a data center that supports: Application Insights; Key Vault. For an up-to-date list, click here, and select a region where the following services are available:
    • Application Insights
    • Key Vault

  5. Enter a "Base Resource Name", which the template uses to generate names for the other resources. (no spaces)

    • The app service name [Base Resource Name] must be available. For example, if you select Open Badges as the base name, the name Open Badges must be available (not taken); otherwise, the deployment will fail with a Conflict error.
    • Remember the base resource name that you selected. We will need it later.

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

    1. Bot client ID: The application (client) ID of the Microsoft Teams bot app
    2. Bot client secret: The client secret of the Microsoft Teams bot app
    3. Tenant ID: Tenant ID where application is hosted (from step 2)
    4. Badge provider base URL:
    5. Issuer entity name: User need to provide Issuer group entity name (created in Step 1)
    6. Superuser username: User need to provide issuer group owners user id (Owner account used in Step 1)
    7. Superuser Password: User need to provide issuer group owners password (Owner account password used in Step 1)

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

  8. 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.

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

  10. Wait for the deployment to finish. You can check the progress of the deployment from the "Notifications" pane of the Azure Portal. It can take up to 20 minutes for the deployment to finish.

  11. Once the deployment has finished, you would be directed to a page that has the following fields:

    • BotId - This is the Microsoft Application ID for the Open Badges.
    • AppDomain - This is the base domain for the Open Badges.

Step 4: Set up authentication for bot

  1. Note the name of the bot that you deployed, which is [BaseResourceName].

  2. Go to azure portal here and search for your bot.

  3. Click on the bot in the application list. Under "Settings", click on "Add Setting".

  4. Fill in the form as follows:

    1. For Name, enter "BadgrAuth". You'll use it in your bot code.
    2. For Service Provider, select Generic Oauth 2.
    3. For Client ID, enter the application (client) ID that Badgr team has provided from step 1.4.
    4. For Client secret, enter the secret that you have received from Badgr team from step 1.4.
    5. For Authorization URL, use https://badgr.io/auth/oauth2/authorize (US Server ONLY)
    6. For Token URL, use https://api.badgr.io/o/token (US Server ONLY)
    7. For Refresh URL, use https://api.badgr.io/o/token (US Server ONLY)
    8. For Scopes, enter the names of the permission you chose from application registration: rw:backpack rw:profile rw:issuer

  5. Click Save.

Step 5: Create the Teams app packages

Create Teams app package:

  1. Open the Manifest\manifest.json file in a text editor.

  2. Change the placeholder fields in the manifest to values appropriate for your organization.

    • developer.name (What's this?)
    • developer.websiteUrl
    • developer.privacyUrl
    • developer.termsOfUseUrl

  3. Change the <<botId>> placeholder to your Azure Active Directory application's ID from step 3.11. This is the same GUID that you entered in the template under "Bot Client ID".

  4. In the "validDomains" section, replace the <<appDomain>> with your bot App Service's domain. This will be [BaseResourceName].azurewebsites.net. For example if you chose "contosoBadgr" as the base name, change the placeholder to contosoBadgr.azurewebsites.net.

  5. 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. If the names of the .png files differ, be sure to update the file names to match in the manifest file.

    • Name this package OpenBadges.zip.
    • Make sure that the 3 files are the top level of the ZIP package, with no nested folders.

Step 6: Run the apps in Microsoft Teams

  1. If your tenant has sideloading apps enabled, you can install your app by following the instructions here

  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. See here

  3. Install the end-user app (the OpenBadges.zip package) to your users.

Troubleshooting

Please see our Troubleshooting page.

Clone this wiki locally