Integrate Microsoft Teams 编辑

Deploy the Microsoft Teams integration to schedule Teams Meetings, create a team from scratch or based on an existing team, add a new channel to an existing team, send a message to a specific channel and receive a notification for newly created channels.

Note:

We want your feedback! Please provide feedback for this integration template as you use it. For any issues, our team will also monitor our dedicated forum on a daily basis.

For comprehensive details of the out-of-the-box microapp for MS Teams, see Use Microsoft Teams microapps.

Review prerequisites

These prerequisites assume that the administrator is part of the MS Teams integration set up of the organization. This MS Teams admin account must have full read privileges for user information. After you set up this integration with Microsoft Teams, you will need these artifacts to add the integration in Citrix Workspace Microapps:

• BASE URL: https://graph.microsoft.com/
• AUTHORIZATION URL: https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/authorize
• TOKEN URL: https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token
• CLIENT ID: The client ID is the string representing client registration information unique to the authorization server.
• SECRET: The client secret is a unique string issued when setting up the target application integration.

Note:

It is recommended that you always use OAuth 2.0 as your service authentication method where available. OAuth 2.0 ensures that your integration meets the maximum security compliance with your configured microapp.

Configure Citrix Gateway to support single sign-on for MS Teams so that once users log in they are automatically logged in again without having to enter their credentials a second time. For more information about configuring SSO, see Citrix Gateway Service.

Permissions

The integration requires regular access to your MS Teams instance, so we recommend creating a dedicated user account. You can view the permission/privileges at https://docs.microsoft.com/en-us/graph/permissions-reference.

This service account must have either one of the following permission scope setups:

• Global Administrator or
• Application Administrator and Teams Service Administrator

Details of the roles:

• Global Administrator role grants admin consent for delegated permissions in Microsoft Teams and allows API access.
• Application Administrator role is grants admin consent for delegated permission.
• Teams Service Administrator role is required to access the channel API.

The number of API requests that can be made to specific resources is limited, we therefore recommend the following:

• Microsoft Teams API limitation form link: https://docs.microsoft.com/en-us/graph/throttling

Create a new service account

Sign in here: https://portal.azure.com. For more information about getting started with Microsoft Teams, see https://support.microsoft.com/en-us/office/how-do-i-get-microsoft-teams-fc7f1634-abd3-4f26-a597-9df16e4ca65b.

Configure OAuth server

Configure the OAuth server to read data through the MS Teams integration.

1. Log in with your service account to: https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredApps.
2. Select New registration.
3. For Supported account types, select Accounts in any organizational directory (Any Azure AD directory - Multitenant).

4. Complete the required fields and enter the following authorized redirect URLs for this integration in the Redirect URL field:

   https://{yourmicroappserverurl}/admin/api/gwsc/auth/serverContext

5. Select Register.
6. Copy and save the Application (client) ID and Directory (tenant) ID shown on the screen. You use these details for Service Authentication while configuring the integration.
7. Select View Permissions under Call APIs. Select Add a permission and choose the Microsoft Graph tile.

8. Select Delegated permissions tile and add the below listed scopes:

   Group.Read.All User.Read.All GroupMember.Read.All Channel.ReadBasic.All

9. Select Grant admin consent for Citrix Systems, and select Yes.
10. Select Certificates & secrets from the left panel, and select New client secret. Choose never for expiration validity, and select Add.
11. Copy and save the Value from the client secrets.

Configure OAuth client

Configure the OAuth client to write back data through the MS Teams integration.

1. Log in with your service account to: https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredApps.
2. Select New registration.
3. For Supported account types, select Accounts in any organizational directory (Any Azure AD directory - Multitenant).

4. Complete the required fields and enter the following authorized redirect URLs for this integration in the Redirect URL field:

   https://{yourmicroappserverurl}/app/api/auth/serviceAction/callback

5. Select Register.
6. Copy and save the Application (client) ID and Directory (tenant) ID shown on the screen. You use these details for Service Action Authentication while configuring the integration.
7. Select View Permissions under Call APIs. Select Add a permission and choose the Microsoft Graph tile.

8. Select Delegated permissions tile and add the below listed scopes:

   Channel.Create Group.ReadWrite.All ChannelMessage.Send Calendars.ReadWrite

9. Select Grant admin consent for Citrix Systems, and select Yes.
10. Select Certificates & secrets from the left panel, and select New client secret. Choose never for expiration validity, and select Add.
11. Copy and save the Value from the client secrets.

Add the integration to Citrix Workspace Microapps

Add the Microsoft Teams integration to Citrix Workspace Microapps to connect to your application. The authentication options are preselected. Ensure that these options are selected as you complete the process. This delivers out-of-the-box microapps with pre-configured notifications and actions which are ready to use within your Workspace.

Follow these steps:

1. From the Microapp Integrations page, select Add New Integration, and Add a new integration from Citrix-provided templates.
2. Choose the Microsoft Teams tile.
3. Enter an Integration name for the integration.
4. Enter Connector parameters.
   • Enter the instance Base URL: https://graph.microsoft.com/
   • Select an Icon for the integration from the Icon Library, or leave this as the default icon.

5. Under Service authentication, select OAuth 2.0 from the Authentication method menu and complete the authentication details. The authentication options are preselected. Ensure that these options are selected as you complete the process. Use the OAuth 2.0 security protocol to generate request/authorization tokens for delegated access. It is recommended that you always use OAuth 2.0 as your service authentication method where available. OAuth 2.0 ensures that your integration meets the maximum security compliance with your configured microapp.

   1. Select Authorization code from the Grant type menu. This grants a temporary code that the client exchanges for an access token. The code is obtained from the authorization server where you can see the information the client is requesting. Only this grant type enables secure user impersonation. This displays the Callback URL, which you use when registering your application.
   2. Select Request body from the Token authorization menu.
   3. The Authorization URL is prefilled: https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/authorize
   4. The Token URL is prefilled: https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token
   5. Ensure the following is entered for Scope: https://graph.microsoft.com/default offline_access
   6. Enter your Client ID. The client ID is the string representing client registration information unique to the authorization server. You collect this and the secret when you configure the OAuth server. You need to add the Callback URL you see on the integration configuration page.
   7. Enter your Client secret. The client secret is a unique string issued when setting up the target application integration.

6. Under Service Action Authentication, enable the Use Separate User Authentication in Actions toggle. Service action authentication authenticates at the service action level. The authentication options are preselected. Ensure that these options are selected as you complete the process.

   1. Select OAuth 2.0 from the Authentication method menu and complete the authentication details.
   2. Select Request body from the Token authorization menu.
   3. The Authorization URL is prefilled: https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/authorize
   4. The Token URL is prefilled: https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token
   5. Ensure the following is entered for Scope: https://graph.microsoft.com/default offline_access
   6. Enter your Client ID. The client ID is the string representing client registration information unique to the authorization server. You collect this and the secret when you configure the OAuth client. You need to add the Callback URL you see on the integration configuration page.
   7. Enter your Client secret. The client secret is a unique string issued when setting up the target application integration.

7. Enable the Enable request rate limiting toggle. Enter 60 for Number of requests and 1 second for Time interval.

8. (Optional) Enable Logging toggle to keep 24 hours of logging for support purposes.
9. Select Save to proceed.
10. Under OAuth Authorization, select Authorize to log in with your service account. A pop-up appears with a Microsoft login screen.
    1. Enter your Service Account username and password and select Sign in.
    2. Select Accept.

Note:

• It is recommended to set the Full Synchronization interval as Daily to regularly refresh data from MS Graph to the Microapps platform and receive timely notifications for any newly created channels.
• As the currently available 40 time zones are hardcoded in the Create Meeting microapp, addition of any other time zone would require the admin to add them manually.
• When a user creates a channel using Add Channel or Create Team microapp, the newly created channel is hidden by default in MS Teams.
• We have currently hardcoded the template list in Create Team microapp. To add any other template type, the admin must add them manually.
• To populate only Microsoft365 (Teams) related groups/channels, we use a filter used in the Groups endpoint:filter=groupTypes/any(g:g+eq+'Unified'. Note that + has been replaced by a blank space.
• If users are getting additional Teams in the Select Team component in Send Message and Add channel microapps, use the beta endpoint from Microsoft at https://graph.microsoft.com/beta/groups?$filter=grouptypes/any(g:g eq 'Unified') and resourceProvisioningOptions/any(p:p eq 'Team') to filter only Teams(Groups) related to MS Teams.

The Microapp Integrations page opens with your added integration and its microapps. From here, you can add another integration, continue setting up your out-of-the-box Microapps, or create a new microapp for this integration.

You are now ready to set and run your first data synchronization. As a large quantity of data can be pulled from your integrated application to the Microapps platform, we recommend you use the Table page to filter entities for your first data synchronization to speed up synchronization. For more information, see Verify needed entities. For complete information about synchronization rules, synchronization that does not meet its schedule and veto rules, see Synchronize data.

For more details of API endpoints and table entities, see Microsoft Teams connector specifications.

Use MS Teams microapps

Existing application integrations come with out-of-the-box microapps. Start with these microapps and customize them for your needs.

Add Channel: Add a new channel to an existing team.

Create Meeting: Schedule an MS Teams meeting as per user preference.

Create Team: Create a team from scratch or based on an existing team as per user preference. Additionally, whenever a Channel is created for any team, the team owner will receive a notification.

Send Message: Send a message to a specific channel in any team.