Skip to content
This repository has been archived by the owner on Jun 4, 2024. It is now read-only.

docs: Remove old MSFT Teams content and point to official documentation #941

Merged
merged 3 commits into from
Oct 10, 2023
Merged

docs: Remove old MSFT Teams content and point to official documentation #941

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
ff6b343
Remove old content and point to official documentation
lsgunn-teleport Oct 2, 2023
ba20704
Merge branch 'master' into LG/microsoft-teams-ReadMe
lsgunn-teleport Oct 10, 2023
0e6c6b4
Merge branch 'master' into LG/microsoft-teams-ReadMe
lsgunn-teleport Oct 10, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
249 changes: 3 additions & 246 deletions access/msteams/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,248 +1,5 @@
# Teleport MS Teams Plugin
# Teleport Microsoft Teams access request plugin

This plugin notifies MS Teams users on upcoming AccessRequests.
The Teleport Access API provides a Microsoft Teams access request plugin that sends a message to users on Microsoft Teams when an access request is created. You can find the Teleport Access API in the main Teleport repository and examples of access request plugins in `github.com/gravitational/teleport/api/integrations/access/`.

## Setup

[See setup instructions on Teleport's docs website](https://goteleport.com/docs/access-controls/access-request-plugins/ssh-approval-msteams/)

## Install the plugin

There are several methods to installing and using the Teleport MS Teams Plugin:

1. Use a [precompiled binary](#precompiled-binary)

2. Use a [docker image](#docker-image)

3. Install from [source](#building-from-source)

### Precompiled Binary

Get the plugin distribution.

```bash
$ curl -L https://get.gravitational.com/teleport-access-msteams-v7.0.2-linux-amd64-bin.tar.gz
$ tar -xzf teleport-access-msteams-v7.0.2-linux-amd64-bin.tar.gz
$ cd teleport-access-msteams
$ ./install
```

### Docker Image
```bash
$ docker pull public.ecr.aws/gravitational/teleport-plugin-msteams:9.0.2
```

```bash
$ docker run public.ecr.aws/gravitational/teleport-plugin-msteams:9.0.2 version
teleport-msteams v9.0.2 git:teleport-msteams-v9.0.2-0-g9e149895 go1.17.8
```

For a list of available tags, visit [https://gallery.ecr.aws/](https://gallery.ecr.aws/gravitational/teleport-plugin-msteams)

### Building from source

To build the plugin from source you need [Go](https://go.dev/) and `make`.

```bash
$ git clone https://github.com/gravitational/teleport-plugins.git
$ cd teleport-plugins/access/msteams
$ make
$ ./build/teleport-msteams start
```



## Teleport User and Role

Using Web UI or `tctl` CLI utility, create the role `access-msteams` and the user `access-msteams` belonging to the role `access-msteams`. You may use the following YAML declarations.

### Role

```yaml
kind: role
metadata:
name: access-msteams
spec:
allow:
rules:
- resources: ['access_request']
verbs: ['list', 'read', 'update']
version: v6
```

### User

```yaml
kind: user
metadata:
name: access-msteams
spec:
roles: ['access-msteams']
version: v2
```

## Configure Microsoft Bot and App

You need a paid Azure subscription to make the plugin work.

Please note that you must have the appropriate Azure AD adminstrator permissions and MS Teams organization admin role to follow these steps. Contact your IT department administrator for details.

1. [Register new Azure bot](https://portal.azure.com/#create/Microsoft.AzureBot). Set "Single Tenant" type of app. Choose "Create new Microsoft App ID".

![Create Microsoft Bot](images/app_create.png)

2. Open the newly created bot -> Channels tab. Add Microsoft Teams channel.

![Add Bot channel](images/add_channel.png)

3. Open the associated Microsoft App (Configuration tab, find "Microsoft App ID", click "Manage" link next to it).

![Manage app](images/manage_app.png)

4. Go to "Certificates & secrets" section. Click "New client secret". Press "Add". Copy and save the generated password in a secure location.

![Add password](images/add_password.png)

5. Go to "API permissions" section. Click "Add a permission". Choose "Microsoft Graph". Choose "Application permissions". Add the following permissions:

* `TeamsAppInstallation.ReadWriteSelfForUser.All`
* `TeamsAppInstallation.ReadWriteSelfForTeam.All`
* `AppCatalog.Read.All`
* `User.Read.All`

6. Grant admin consent for the newly added permissions.

7. Goto the bot Configuration tab (back to step #3). Find "Microsoft App ID", "App Tenant ID" and run the following command:

```sh
$ ./teleport-msteams configure ~/ms_teams --appID <Microsoft App ID value> --tenantID <App Tenant ID value> --appSecret <password value saved on step #4>
```

`~ms_teams` must be a path to non existent folder. It will be created. All required files will be generated.

8. There will be `app.zip` in the target directory. This archive contains MS Teams app. If you want to change the application name, URLs and other settings, please update `manifest.json` and recreate `app.zip` from `color.png`, `outline.png` and `manifest.json`.

9. Upload the app to MS Teams organization store. Open "Apps", then "Manage your apps", click "Upload an app", choose "Upload an app to your org's app catalog", choose `app.zip`

![Upload app](images/upload_app.png)

10. Add the newly uploaded app to a team. Open the app, click "Add to a team", choose team, click "Set up a bot".

![Add to the team](images/add_to_team.png)

## Validating the installation

```sh
$ ./teleport-msteams validate -c ~/ms_teams/teleport-msteams.toml [email protected]
```

You'll see the following output:

```
- Checking application 5eb63f63-da3a-4d77-8d35-55b5ef98f5be status...
- Application found in the team app store (internal ID: c18f0770-4b36-453f-aa46-2d1ba552c238)
- User [email protected] found: 0x14000120800
- Application installation ID for user: M2UwMzM3YmMtYjVkZC00YWRiLTliYzgtYTJhMTZjZDNiMDgxIyNjMThmMDc3MC00YjM2LTQ1M2YtYWE0Ni0yZDFiYTU1MmMyMzg=
- Chat ID for user: 19:3e0337bc-b5dd-4adb-9bc8-a2a16cd3b081_2b6d7f7d-f8f3-4815-b50b-c7593c60981f@unq.gbl.spaces
- Chat web URL: https://teams.microsoft.com/l/chat/19%3A3e0337bc-b5dd-4adb-9bc8-a2a16cd3b081_2b6d7f7d-f8f3-4815-b50b-c7593c60981f%40unq.gbl.spaces/0?tenantId=2ca235ec-37d0-44b0-964d-ca359e770603
- Hailing the user...
- Message sent, ID: 1657712789098

Check your MS Teams!
```

User receives "Hello, World!" message along with the mock access request.

![Add to the team](images/add_to_team.png)

You can use User ID instead of an email. To your User ID, open [Users](https://portal.azure.com/#view/Microsoft_AAD_IAM/UsersManagementMenuBlade/~/MsGraphUsers) section of the Azure Portal. Open a user and copy the "Object ID" field value.

## Running the plugin

With the config above, you should be able to run the bot invoking

```bash
$ teleport-msteams start -c ~/msteams/teleport-msteams.toml
```

or with docker:

```bash
$ docker run -v <path/to/config>:~/msteams/teleport-msteams.toml public.ecr.aws/gravitational/teleport-plugin-msteams:9.0.2 start
```

## Usage

Once your MS Teams plugin has been configured, you can verify that it's working
correctly by using `tctl request create <user> --roles=<roles>` to simulate an
access request.

Select `Deny` and verify that the request was indeed denied using
`tctl request ls`.

Specify ```preload = true``` at the top of your configuration file if you want plugin to check the user existence prior to startup.

## Plugin-specific Architecture

The plugin leverages 2 different Microsoft APIs to provide access-request notifications:
```mermaid
sequenceDiagram
participant Teleport
participant Plugin
participant GraphAPI
participant BotService as Azure Bot Service
participant MsTeams
actor Users

Note over Plugin,MsTeams: Azure Tenant
Plugin->>GraphAPI: Install TeamsApp with AppID/Secret
activate GraphAPI
GraphAPI->>MsTeams: Install Process
activate MsTeams
MsTeams-->>GraphAPI: OK
deactivate MsTeams
GraphAPI-->>Plugin: OK
deactivate GraphAPI

loop forever
Teleport->>Plugin: Send Events
Plugin->>BotService: Message with AppID/Secret
BotService->>MsTeams: PostMessage as TeamsAppID
MsTeams->>Users: Message
end
```

### The Bot Connector service

This is an Azure managed service that comes with an SDK (not available in golang) and allows developers to
write platform-agnostic messaging bots. It is billed per 1k messages and requires a valid Azure subscription.
We use this service only for posting messages to MSTeams, but it could be used to send messages to other destinations.

Warning: In this service, the term _channel_ represents the messaging connector used (Teams, Slack, Skype, ...).
Conversations abstract any kind of communication channel with the user like Private Messages, Group Chat or Team channel.
All inbound/outbound messages and events are called activities.

Using the Bot connector service requires an `AzureBot` resource in Azure, an application (service account) and a secret.

The Bot connector service should also be authorized to post on MSTeams, this is what the `TeamsApplication` does.
The Teams application is a ZIP file composed of an application manifest, a logo, and an accent color. It
contains the AzureBot ID that can interact on its behalf, an admin has to upload it to the Organisation AppCatalog.

### The Graph API

The Graph API allows to interact with a lot of Microsoft resources. This includes listing AD users, MsTeams
applications, installing applications on their behalf, ... However, this API does not allow to post messages on Teams
(technically it is possible when doing a migration but Microsoft warns against using this method for implementing a bot).

The graph API has an official go client (currently in beta). While it works, the client is a heavy and make compiling
the plugin really slow (30 min of CPU time). As we also need to implement the authentication flow for the Bot Connector
service, we chose not to use the graph client.

MsTeams bot communication requires an already established communication channel. As we need to send notifications
without user interaction we can't have all users ping the bot. Thus, we pre-emptively install the app for each
recipient, this is our main use of the Graph API. Installing an app for a user can take several seconds.
As we need to treat each event before the HTTP timeout, the plugin is preloading by default and installing its Teams
app for all users.

Interacting with this API requires an application (service account) and an application secret. We reuse the Bot Connector
application and secret.
If you have a self-hosted Teleport deployment, you can find information for configuring this access request plugin in [Access Requests with Microsoft Teams](https://goteleport.com/docs/access-controls/access-request-plugins/ssh-approval-msteams/).