The goal of this document is to have an icon appear pinned on Microsoft Teams App Navigation Bar for a SharePoint site we want available to all users of Teams or specific people using Teams not matter if they are members of any Teams or Channels. The solution will provide new users access to a customer’s own portal for Teams training before they have ever joined or created their first Team.
Teams App Controls in the Admin Console
Apps appearing on the Teams Apps Bar are controlled from the Teams Admin console in the Tenant.
Warning! Not preparing your Tenant properly ahead of time for uploading a custom app will result in the following message later in this document.
Warning! Not preparing your Tenant to allow only certain people to upload custom apps will allow everyone to upload apps into your app store.
Controlling who can upload Custom Apps
On the App setup policies page create a new custom policy.
Informational: Documentation on Teams Custom App Policies can be found in the appendix.
We chose the name “App Upload Policy” but you all can use what makes sense. In the new policy flip “ON” the ability to upload custom apps if your users id is assigned to this policy.
Ignore all other settings and click “Save”
On the policy screen select the new policy and click “Manage Users”
On the Managed Users page type the names of the users you want to assign this policy to.
Any users not part of this policy will get the following error attempting to upload an app.
Warning! After saving these policy settings it can take hours for them to go in effect.
Checking what policies are applied to a user
Browse to the “Users” tab in the Teams Admin Center
Search for a user you just applied the policy to in the previous step then check the box next to the user. This will allow you to see how many policies apply to this user. You can then select the “Edit Settings” option to edit the user’s policy settings.
Locate the “App setup Policy” option and click the drop down.
You will see all the current App Setup policies controlling this user’s access to Teams Apps.
Controlling Permissions to Teams Apps
In the Teams Admin Console, look for the “Permissions Policies” tab under “Teams Apps”
Click on the “Org-wide app settings” button to check the current permissions to use Teams apps in your Tenant.
Warning! If the administrator for your Tenant has set the below options in green to “Off” you cannot successfully complete this documents mission of adding and using a custom app in Teams.
Next, we must check Policy level app permission if the previous settings looked to be on.
In the “App Permission policies” select the “Global (Org-wide default) policy for is settings by checking the policy and clicking “Edit”
The best scenario is the box in green are set to all apps and users are below to this policy. It’s the default and no other policy restricts them from these settings.
Warning! If the administrator has altered the default apps permission to something other than “Allow all apps” we will need to whitelist our custom app at the end of this document and the “Teams Apps Studio” app from the beginning to allow them to be seen by the users in Teams.
At this point our Portal App has not been created so we cannot whitelist is until we complete the steps in this document and upload the custom app to the Tenant App Catalog.
Be sure to save any changes you have made and give time for the policies changes to take effect.
Creating the App
Now that we have our App & Permissions policies prepared, we are ready to create the custom app for displaying the icon linked to our SharePoint Portal in the Teams App Navigation Bar.
- Login to Teams web version or Desktop version as a user we added to the “App Upload Policy”
- In Teams click on the App Store icon in the app navigation bar in the left of Teams.
- When the store opens type “App Studio” to locate the app we need to install for this user to create our custom app.
- Click the “Add” button to install the app
- After the App Studio app opens click on “Manifest Editor”
- In the Manifest editor tab look for “Create a new App”
- Next, you will see the following screen with many fields we must complete. We will take them one section at a time.
- App Details Warning! Don’t put “Microsoft” in the naming. If you make the “Short Name” too long, it will truncate and show an ellipse next to the name.
In the identification section, you must click the “Generate” button to generate a unique key for this app. You must fill in the “Package Name”. You can use any names just follow the format shown above. The “Version” also needs to be set.
- Description Warning! Don’t put “Microsoft” in the naming
- Developer information
The developer information just identifies who built the app and a website to go find out more about the developer. I would suggest linking to a page people can find out more about the development and purpose of the app. In this example, we just point back to the SharePoint site that launches the Learning Pathways site in a Tenant.
- App URLs
You will need at least two logos from the branding page. They must be of the exact size listed in their description. You have now completed all options on the “Apps Details” tab. Now move to the “Tabs” tab under “Capabilities”.
Click on “Add a personal tab”
In the Name tab, pick a name that will show up in the webpage of the portal as shown below.
Set any number the entity ID
The “Content URL” we have pointing back to our Learning Pathways portal
The “Website URL” we have pointing back to our Learning Pathways portal Click Save.
- Valid domains
- Web app single sign-on
The AAD application ID in this example is for a SharePoint site. The official number is 00000003-0000-0ff1-ce00-000000000000 do not us any other number for this example. The “Resource URL” needs to have your tenant unique name in place of my “m365x360288”. Press Save after completing the fields.
We have now completed setting up our custom app.
Testing the App
Under the “Finish” heading in the App Studio App select “Test and Distribute”
Next, you will see the following screen with a series of warnings. Don’t worry about the warnings in this example use case. In a production environment, you would want to follow the guidance of making them port to internal URLs.
If you failed to enter things correctly you will see the following warning.
If you did everything right the App installer will pop-up ready for you to test Add it to your Teams. Before you click add, review the information about the about. You will see how the information was used from above.
After the App install it will load the Learning Pathways Portal if it works.
Packaging the App
Return to the App Studio app by clicking the ellipse in the App Navigation Bar.
The following window will open displaying the “App Studio” App and the “Contoso Learning” App we just test add to our users Team. Click on the “App Studio” icon to relaunch the app. Select the “Manifest editor”
Look under “Recently created apps” for the “Contoso Learning” app and click on it.
Click on “Test and distribute” tab
Click the “Download” button to package the app for import.
You will see a pop-up indicating the package was exported and it’s file name.
The location will be the downloads folder on the PC. Remember that location for the upload into the Tenant App Portal.
Uploading the App
Go backing into Teams and look for the “Apps” icon on the App Navigation Bar
If your user id has the correct permission granted to upload custom app, you can click on “Upload a custom app” at the bottom of the list. Click on it. Then click to upload to your Tenant. Not sure why it’s a double click Browse to the downloads folder to locate our package and click “Open”
If you failed to use an account that’s in the “Upload App Policy” we created, you will see the following error.
If successful, the app will now appear in the Tenant App Catalog
Searching for this app in the app catalog and clicking add will install the app under the ellipse as it did on the test install. STOP! We are not going to install the app that way. Instead, we are going to pin the app to the App Navigation Bar using our “App Setup Policy”
Making the App available
Go back into the Teams Admin Console and move to the “Setup Policies” tab.
Locate the App Setup Policy we created earlier and check the box. Then click “Edit”
Under “Pinned apps” click “Add apps”
Browse for the “Learning” app and select it and click “Add” The click the “Add” button at the bottom to close out the screen.
You will now see the App how I will appear on the App Navigation Bar. The default is at the bottom you can highlight the app and move it up. If you are satisfied with the position click “Save”
Now we wait for the policy settings to sync on o365 backend systems before we will see the results of our work. We will not see our new app show up on the App Navigation Bar for about 2 hours.
Click on the New App Icon and see the finished project.