View source for Configuring MS Teams with ICI


= Configuring MS Teams with ICI =

To enable this capability, you (client) can make use of the existing ICI UI and API apps (App Registrations) or create 2 new apps for the same on Azure portal. Further we are going to provide certain API Permissions to these apps for interacting with Microsoft Teams to create new teams, channel, add team members to a team, add file and so on.

In case you are using a different identity provider like Okta, Ping Identity then all the internal ICI users are required to be part of the Azure Ad for this integration to work.

With the help of the following sections, you can create/edit the ICI UI and API apps (App Registrations), add URL redirects, provide API permissions etc.



== Azure Portal Configuration for ICI UI Application ==

'''1. ICI UI Application (API Permissions)'''
<ol style="list-style-type:lower-alpha;">
<li>Clients with different identity provider (for example, Okta or Ping Identity) must create a new ICI UI app registration and provide the required API permissions (listed under Section B.3) on their Azure portal.</li>
<li>Clients with Azure AD will have to provide the required API permission (''listed under Section B.2'') to the existing ICI UI app registration on Azure portal.</li>
<li>In both the above scenarios the following details with respect to the newly created or modified app are required to be shared with Icertis (''to be able to enable ICI integration with Microsoft Teams'').</li>
</ol>
<ul style="margin-left: 80px;">
<li>Directory ID (Tenant ID)</li>
<li>Application ID (Client ID)</li>
<li>Client Secret</li>
<li>(ICI UI) Redirect URI</li>
</ul>

'''2. ICI UI application (app registration) on Azure portal requires the following Microsoft Graph delegated API permission with Admin consent.'''

'''[[File:8.1 Configure Teams 1.PNG|620px|8.1 Configure Teams 1.PNG]]<br/> [[File:8.1 Configure Teams 2.PNG|620px|8.1 Configure Teams 2.PNG]]<br/> [[File:8.1 Configure Teams 3.PNG|620px|8.1 Configure Teams 3.PNG]]'''

'''3. Create a new or update existing ICI UI Application:''' Clients who are updating the existing ICI UI app can skip points '''‘a’''' to '''‘d’''' and directly open the existing ICI UI app on Azure portal and start with point '''‘e’.'''

a. Go to ‘'''App Registrations'''’ under ‘'''Azure Active Directory'''’ on Azure portal and on the right panel, click ‘'''New registration’''' tab.

&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;i.&nbsp;Provide the following information:&nbsp; &nbsp; &nbsp;&nbsp;
<ol style="margin-left: 80px;">
<li>'''Name''': Enter the name for the application</li>
<li>Select the '''Supported account types''' for your application. Select Accounts in this organizational directory only (ABC only - Single tenant).</li>
<li>For the '''Redirect URI:'''</li>
</ol>

a.&nbsp;&nbsp; &nbsp;Select Web.

b.&nbsp;&nbsp; &nbsp;Set the URL to (ICI UI Application URL)&nbsp;<br/> &nbsp;&nbsp; &nbsp;i.&nbsp;&nbsp; &nbsp;[https://{{your-tenant-name}}.icertis.com https://{{your-tenant-name}}.icertis.com]

b. Click '''Register'''

c. Once it is created, Azure displays the '''Overview''' page for the app.

d. In the left panel, select Certificates & secrets to create a client secret for your application.
<ol style="list-style-type:lower-roman;">
<li>Under '''Client secrets''', select ➕ '''New client secret'''.</li>
<li>Add a description to identify this secret from others.</li>
<li>Set '''Expires''' to your selection.</li>
<li>Select '''Add'''.</li>
<li>Before leaving this page, '''record the secret'''.</li>
</ol>

e.&nbsp;In the left panel, select ‘API permissions’ to add certain delegated permission for your UI application.
<ol style="list-style-type:lower-roman;">
<li>Click ‘Add a permission’.</li>
<li>Under ‘Microsoft APIs’ select ‘Microsoft Graph’.</li>
<li>Select ‘Delegated permissions’.</li>
<li>Now select the following permission (''please find more information on usage of every API permission under ‘'''Section B.2'''’'')</li>
</ol>
<ul style="margin-left: 40px;">
<li>AppCatalog.Read.All</li>
<li>Channel.Create</li>
<li>Files.ReadWrite.All</li>
<li>Group.ReadWrite.All</li>
<li>Team.Create</li>
<li>Team.ReadBasic.All</li>
<li>TeamMember.ReadWrite.All</li>
<li>TeamsAppInstallation.ReadWriteForTeam</li>
<li>User.Read</li>
<li>User.ReadBasic.All</li>
</ul>

f.&nbsp;Copy and save the following information to a file:
<ol style="list-style-type:lower-roman;">
<li>The '''Application (client) ID''' value. You'll use this value later as the ''Client ID'' when you register this Azure identity application with your bot.</li>
<li>The '''Directory (tenant) ID''' value. You'll also use this value later as the ''Tenant ID'' to register this Azure identity application with your bot.</li>
</ol>

g. With respect to the newly created or modified ICI API app, you are required to share the following with Icertis (''to be able to enable ICI integration with Microsoft Teams'').
<ol style="list-style-type:lower-roman;">
<li>Directory ID (Tenant ID) '''[Copy value to E.1]'''</li>
<li>Application ID (Client ID) '''[Copy value to E.2]'''</li>
<li>Client Secret '''[Copy value to E.3]'''</li>
<li>(ICI UI) Redirect URI</li>
</ol>





== Azure Portal Configuration for ICI API Application ==

'''1. ICI API Application (API Permissions)'''
<ol style="list-style-type:lower-alpha;">
<li>Clients with different identity provider (for example, Okta or Ping Identity) must create a new ICI API app registration and provide the required API permissions (listed below) on their Azure portal.</li>
<li>Clients with Azure AD will have to provide the required API permission to the existing ICI API app registration on Azure portal.</li>
<li>For those customers who do not have an existing ICI API application, are required to create a new app registration by following the steps mentioned under '''Section C.3.'''</li>
<li>For clients with existing ICI API application, an additional ‘Redirect URI’ is required to be added: <ol style="list-style-type:lower-roman;">
<li>In the ICI API application go to ‘'''Authentication'''’ under ‘'''Manage'''’</li>
<li>For the '''Redirect URI''', click ‘'''Add URI'''’</li>
<li>Set the URL to [https://token.botframework.com/.auth/web/redirect '''https://token.botframework.com/.auth/web/redirect'''] (''required to authenticate the Icertis Teamworks App'')</li>
</ol> </li>
</ol>

2.&nbsp;'''ICI API application (app registration) on Azure portal requires the following Microsoft Graph delegated API permission with Admin consent.'''

'''[[File:8.1 Configure Teams 4.PNG|620px|8.1 Configure Teams 4.PNG]]'''

'''3. Create a new ICI API Application: '''We need an identity provider that can be used for authentication of ICI API & ‘Icertis Teamworks’ (Microsoft Teams) app. For clients who are updating the existing ICI API app can skip points '''‘a’''' to '''‘d’''' and directly open the existing ICI API app on Azure portal and start with point '''‘e’.'''

a.&nbsp;Go to ‘'''App Registrations'''’ under ‘'''Azure Active Directory'''’ on Azure portal and on the right panel, click ‘'''New registration’''' tab.

*You'll be asked to provide the following information: 
*#
*##'''Name'''. Enter the name for the application 
*##Select the '''Supported account types''' for your application. Select Accounts in this organizational directory only (ABC only - Single tenant). 
*##For the '''Redirect URI'''    <ul style="margin-left: 80px;">
<li>Select '''Web'''.</li>
<li>Set the URL to (ICI UI Application URL)&nbsp;</li>
</ul>  </ul>

&nbsp;&nbsp; &nbsp;i.&nbsp;&nbsp; &nbsp;https://{{your-tenant-name}}.icertis.com<br/> &nbsp;

b. Click on '''Register'''

c. Once it is created, Azure displays the '''Overview''' page for the app.

d. In the left panel, select Certificates & secrets to create a client secret for your application.

e. In the left panel, select ‘'''Authentication'''’ under ‘'''Manage'''’

f. In the left panel, select ‘API permissions’ to add certain delegated permission for your UI application.
<ol style="list-style-type:lower-roman;">
<li>Under '''Client secrets''', select ➕ '''New client secret'''.</li>
<li>Add a description to identify this secret from others.</li>
<li>Set '''Expires''' to your selection.</li>
<li>Select '''Add'''.</li>
<li>Before leaving this page, '''record the secret'''.</li>
<li>For the '''Redirect URI''', click ‘'''Add URI'''’</li>
<li>Add a new redirect URL i.e.,&nbsp; [https://token.botframework.com/.auth/web/redirect '''https://token.botframework.com/.auth/web/redirect'''] (''required to authenticate the Icertis Teamworks App'')</li>
<li>Click on '''Save'''</li>
<li>Click ‘Add a permission’.</li>
<li>Under ‘Microsoft APIs’ select ‘Microsoft Graph’.</li>
<li>Select ‘Delegated permissions’.</li>
<li>Now select the following permission (''please find more information on usage of every API permission under ‘'''Section C.2'''’'') 
*Files.ReadWrite.All 
*User.Read  
#g. Copy and save the following information to a file: 
#*The '''Application (client) ID''' value. You'll use this value later as the ''Client ID'' when you register this Azure identity application with your bot. 
#*The '''Directory (tenant) ID''' value. You'll also use this value later as the ''Tenant ID'' to register this Azure identity application with your bot. h. Click on '''Overview''' in the left panel. In the right panel on the top click on ‘Endpoints’ (We need to record/copy a few values for the next step: Bot channel Authentication mechanism '''Step F''') 
#*Copy and record '''OAuth 2.0 authorization endpoint (v2)''' value. 
#*Copy and record '''OAuth 2.0 token endpoint (v2)''' value. i. Click on '''Expose an API, '''copy the '''scope''' value that you have added. j. With respect to the newly created or modified ICI API app, you are required to share the following with Icertis (''to be able to enable ICI integration with Microsoft Teams''). 
#*Application ID (Client ID) '''[Copy value to E.4]''' 
#*Client Secret '''[Copy value to E.5]''' 
#*(ICI API) Redirect URI 
#*OAuth 2.0 authorization endpoint (v2) '''[Copy value to E.7]''' 
#*OAuth 2.0 token endpoint (v2) '''[Copy value to E.8]''' 
#*Scope (defined under section B.3.i) '''[Copy value to E.6]'''    </li>

== Azure Portal Configuration for Microsoft Teams App ==

1.&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; Under ‘'''Azure Active Directory'''’, click on ‘'''App registrations'''’.&nbsp;

2.&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; Click the '''New registration''' tab on the top left.&nbsp;

3.&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; Enter the name of the bot application you are registering. You need to select your own unique name.&nbsp;

4.&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; For the Supported account types select '''Accounts in any organizational directory (Any Azure AD directory - Multitenant)'''&nbsp;

5.&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; Click the Register button. Once completed, Azure displays the Overview page for the application.&nbsp;

6.&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; Copy and save to a file the '''Application (client) ID''' & '''Directory (tenant) ID''' value.&nbsp;

7.&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; In the left panel, click '''Certificate and secrets'''.&nbsp;

8.&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; Under Client secrets, click '''New client secret'''.&nbsp;

9.&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; Add a description to identify this secret from others you might need to create for this app.&nbsp;

10.&nbsp;&nbsp; Set Expires to your selection.&nbsp;

11.&nbsp;&nbsp; Click Add.&nbsp;

12.&nbsp;&nbsp; Copy the client secret and save it to a file.&nbsp;

13.&nbsp;&nbsp; With respect to the newly created Bot app, you are required to share the following with Icertis (''to be able to enable ICI integration with Microsoft Teams'').&nbsp;

a.&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; Application ID (Client ID) '''[Copy value to E.9]'''&nbsp;&nbsp;

b.&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; Client Secret '''[Copy value to E.10]'''&nbsp;

== Icertis Configuration Sheet ==
<div class="note-box" style="margin-left: 0.25in;">Note: Based upon the app’s created/modified in the previous 3 sections please update the value column below. In every section which value that is top be copied to respected row in below table is mentioned above and highlighted in '''yellow'''.</div> 
[[File:8.1 Configure Teams 5.PNG|620px|8.1 Configure Teams 5.PNG]]

&nbsp;


== Upload & Approval Process for new Icertis Teamworks app in Microsoft Teams admin center ==

1. Go to URL [https://admin.teams.microsoft.com/ '''https://admin.teams.microsoft.com/'''] & login to the ‘'''Microsoft Teams admin center'''’.
<div class="image-green-border">[[File:8.1 Configure Teams 6.png|720px|8.1 Configure Teams 6.png]]</div> <div class="image-green-border">&nbsp;</div> <div class="image-green-border">2.&nbsp;In the left panel expand ‘'''Teams apps'''’ section.</div> <div class="image-green-border">&nbsp;</div> <div class="image-green-border">[[File:8.1 Configure Teams 7.png|720px|8.1 Configure Teams 7.png]]</div> <div class="image-green-border">&nbsp;</div> <div class="image-green-border">3. Click on ‘'''Manage apps'''’</div> <div class="image-green-border">&nbsp;</div> <div class="image-green-border">[[File:8.1 Configure Teams 8.png|720px|8.1 Configure Teams 8.png]]</div> <div class="image-green-border">&nbsp;</div> <div class="image-green-border">4.&nbsp;In the right panel under ‘Manage apps’ click on ‘'''+ Upload'''’ link</div> <div class="image-green-border">&nbsp;</div> <div class="image-green-border">[[File:8.1 Configure Teams 9.png|720px|8.1 Configure Teams 9.png]]</div> <div class="image-green-border">&nbsp;</div> <div class="image-green-border">[[File:8.1 Configure Teams 10.png|720px|8.1 Configure Teams 10.png]]</div> <div class="image-green-border">&nbsp;</div> <div class="image-green-border">5.&nbsp;Clicking the ‘'''Upload'''’ button will open a file selection window. Go to the location where the ‘'''manifest.zip'''’ file shared by Icertis is stored. Select the ‘manifest.zip’ file and click ‘Open’.</div> <div class="image-green-border">&nbsp;</div> <div class="image-green-border">[[File:8.1 Configure Teams 11.png|720px|8.1 Configure Teams 11.png]]</div> <div class="image-green-border">&nbsp;</div> <div class="image-green-border">6. The app should be submitted to the app catalog and its ‘'''Publishing Status'''’ status should be ‘'''Published'''’. You can search for the app by typing the app name i.e., ‘Icertis Teamworks’ as shown below,</div> <div class="image-green-border">&nbsp;</div> <div class="image-green-border">[[File:8.1 Configure Teams 12.png|720px|8.1 Configure Teams 12.png]]</div> <div class="image-green-border">&nbsp;</div> <div class="image-green-border">7.&nbsp;The ‘Icertis Teamworks’ app should now be visible under the ‘Build for your org’ under App section in ‘Microsoft Teams’</div> <div class="image-green-border">&nbsp;</div> <div class="image-green-border">[[File:8.1 Configure Teams 13.png|720px|8.1 Configure Teams 13.png]]</div> <div class="image-green-border">&nbsp;</div> <div class="image-green-border">&nbsp;</div> <div class="image-green-border">&nbsp;</div> 
'''If the ‘Icertis Teamworks’ app is not in ‘Published’ state as after following the steps stated in the previous section, then you will be required to manually publish/approve the app by performing the subsequent steps:'''

'''a.&nbsp;'''The ‘'''Pending approval'''’ widget under the ‘Manage apps’ panel at the top of the page which lets the Microsoft Teams admin know when a custom app is submitted for approval
<div class="image-green-border">[[File:8.1 Configure Teams 14.png|720px|8.1 Configure Teams 14.png]]</div> 
b.&nbsp;Search for the app name as shown below that you want to approve. The app to be approved status would be ‘Blocked’ currently.
<div class="image-green-border">[[File:8.1 Configure Teams 15.png|720px|8.1 Configure Teams 15.png]]</div> 
c.&nbsp;Clicking the app link will take you to the app details page.
<div class="image-green-border">[[File:8.1 Configure Teams 16.png|720px|8.1 Configure Teams 16.png]]</div> <div class="image-green-border">[[File:8.1 Configure Teams 17.PNG|720px|8.1 Configure Teams 17.PNG]]</div> 
d.&nbsp;On the ‘Icertis Teamworks’ app details page, click the ‘Publish’ button to approve the app.
<div class="image-green-border">[[File:8.1 Configure Teams 18.PNG|720px|8.1 Configure Teams 18.PNG]]</div> 
e.&nbsp;The ‘Icertis Teamworks’ app should now be visible under the ‘Build for your org’ under App section in ‘Microsoft Teams’
<div class="image-green-border">[[File:8.1 Configure Teams 19.png|720px|8.1 Configure Teams 19.png]]</div>

== Update an existing Icertis Teamworks app in Microsoft Teams admin center ==

1.&nbsp;Go to URL [https://admin.teams.microsoft.com/ '''https://admin.teams.microsoft.com/'''] & login to the ‘'''Microsoft Teams admin center'''’.

[[File:8.1 Configure Teams 20.png|720px|8.1 Configure Teams 20.png]]

2.&nbsp;In the left panel expand ‘'''Teams apps'''’ section.
<div class="image-green-border">[[File:8.1 Configure Teams 21.png|720px|8.1 Configure Teams 21.png]]</div> <div class="image-green-border">3.&nbsp;Click on ‘'''Manage apps'''’</div> <div class="image-green-border">&nbsp;</div> <div class="image-green-border">[[File:8.1 Configure Teams 22.png|720px|8.1 Configure Teams 22.png]]</div> <div class="image-green-border">&nbsp;</div> <div class="image-green-border">4.&nbsp;Search for the app by typing the app name i.e., ‘Icertis Teamworks’ as shown below,</div> <div class="image-green-border">&nbsp;</div> <div class="image-green-border">[[File:8.1 Configure Teams 23.png|720px|8.1 Configure Teams 23.png]]</div> <div class="image-green-border">&nbsp;</div> <div class="image-green-border">5.&nbsp;Clicking the app link will take you to the app details page.</div> <div class="image-green-border">&nbsp;</div> <div class="image-green-border">[[File:8.1 Configure Teams 24.png|720px|8.1 Configure Teams 24.png]]</div> <div class="image-green-border">&nbsp;</div> <div class="image-green-border">[[File:8.1 Configure Teams 25.png|720px|8.1 Configure Teams 25.png]]</div> <div class="image-green-border">&nbsp;</div> <div class="image-green-border">6.&nbsp;Click on Upload file to update the existing app</div> <div class="image-green-border">&nbsp;</div> <div class="image-green-border">[[File:8.1 Configure Teams 26.png|720px|8.1 Configure Teams 26.png]]</div> <div class="image-green-border">&nbsp;</div> <div class="image-green-border">[[File:8.1 Configure Teams 27.png|720px|8.1 Configure Teams 27.png]]</div> <div class="image-green-border">&nbsp;</div> 
== Installing the Microsoft Teams app ==

#Go to Microsoft Teams. 
#Click ‘Apps’ in the bottom left of the Microsoft Teams screen. 
#Select ‘Built for your org’. 
#Click on the ‘Icertis Teamworks’ app. A window opens. 
#Click on ‘Add to Team’. 
#Select the channel where you want to install the Icertis Teamworks application. 
#Click ‘Set up a Bot’. 
#‘Icertis Teamworks’ application is ready for use. 


== Verification in ICI ==

Once all the above configurations done. User should be able to see ‘Collaborate in Teams’ button on published Agreement instance.
<div class="image-green-border">[[File:8.1 Teams 1.png|420px|8.1 Teams 1.png]]</div> 
When user clicks on ‘Collaborate in Teams’ button, user should see Wizard to push/send information from ICI to MS teams.
<div class="image-green-border">[[File:8.1 Teams 2.png|620px|8.1 Teams 2.png]]</div> 
&nbsp;

&nbsp;
<div class="image-green-border">&nbsp;</div>