# How to connect to Microsoft Outlook

The Microsoft Outlook connector reads and writes contacts and users in your organisation's Microsoft 365 tenant through Microsoft Graph. It connects as an application, not as a signed-in user: your organisation registers an app in Microsoft Entra, an administrator grants it application permissions, and you enter three values in Apideck Vault: the **Client ID**, the **Client Secret** and the **Tenant ID**.

## Prerequisites

- A Microsoft 365 work or school tenant. Personal Microsoft accounts (such as outlook.com addresses) cannot be used with this connector.
- An account that can register apps in Microsoft Entra, at least the **Application Developer** role, and at least **Global Reader** to look up the Tenant ID.
- An administrator who can grant admin consent for the organisation, such as a **Privileged Role Administrator**. Application permissions for Microsoft Graph always need admin consent, and Microsoft excludes them from what the Cloud Application Administrator and Application Administrator roles can consent to.

## Steps

### 1. Register a new app in Microsoft Entra

Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade), go to **Entra ID** > **App registrations** and select **New registration**.

![App registrations page in Microsoft Entra](https://res.cloudinary.com/apideck/image/upload/v1729082531/docs/connectors/microsoft-outlook/entra-apps.png)

Microsoft describes each field in [Register an application in Microsoft Entra](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app).

### 2. Enter the app details

- **Name**: a name your administrators will recognise, for example the name of the product you are connecting.
- **Supported account types**: select **Single tenant only** (accounts in this organisational directory only). Microsoft recommends this for most applications, and the connector only works within your own tenant.
- **Redirect URI**: set the platform to **Web** and enter `https://unify.apideck.com/vault/callback`. You can also add it later under **Manage** > **Authentication** > **Add Redirect URI** > **Web** (see [How to add a redirect URI](https://learn.microsoft.com/en-us/entra/identity-platform/how-to-add-redirect-uri)).

Select **Register**.

### 3. Copy the Application (client) ID

On the app's **Overview** page, copy the **Application (client) ID**. This is the value you enter as **Client ID** in Vault.

### 4. Add application permissions

Select **API permissions** in the sidebar, then **Add a permission** > **Microsoft Graph** > **Application permissions**. Make sure you choose **Application permissions**, not Delegated permissions: the connector has no signed-in user, so delegated permissions have no effect.

![Entra API permissions](https://res.cloudinary.com/apideck/image/upload/v1729082835/docs/connectors/microsoft-outlook/entra-app-permissions.png)

Search for and add these permissions:

| Access | Contacts | Users |
|--------|----------|-------|
| Read only | `Contacts.Read` | `User.Read.All` |
| Read and write | `Contacts.ReadWrite` | `User.ReadWrite.All` |

`User.Read.All` (or `User.ReadWrite.All`) is needed to list users, so include one of them in either case. Microsoft lists every permission in the [Microsoft Graph permissions reference](https://learn.microsoft.com/en-us/graph/permissions-reference), and explains this screen in [Configure an application to access a web API](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-configure-app-access-web-apis).

### 5. Grant admin consent

On the **API permissions** page, select **Grant admin consent for** your organisation and confirm. Each permission should then show a granted status. If you do not hold the administrator role described under Prerequisites, ask someone who does to complete this step (see [Grant tenant-wide admin consent](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/grant-admin-consent)).

### 6. Create a client secret

Go to **Certificates & secrets** > **Client secrets** and select **New client secret**. Enter a description and choose an expiry. Microsoft allows at most 24 months and recommends less than 12.

![Client secret for app in Entra](https://res.cloudinary.com/apideck/image/upload/v1694615381/docs/connectors/azure-ad/azure-ad-generate_secret.png)

Copy the secret **Value** straight away: Microsoft shows it only once, and you cannot retrieve it after you leave the page. You do not need the **Secret ID**; it is not your Client ID and is not used anywhere in Vault.

![Client secret for app in Entra](https://res.cloudinary.com/apideck/image/upload/v1694615392/docs/connectors/azure-ad/azure-ad-secrets.png)

Note the expiry date somewhere your team will see it. Microsoft's steps are in [Add and manage application credentials](https://learn.microsoft.com/en-us/entra/identity-platform/how-to-add-credentials).

### 7. Copy the Tenant ID

In the Entra admin center, go to **Entra ID** > **Overview** > **Properties** and copy the **Tenant ID** (also called the Directory (tenant) ID). Reading it needs at least the **Global Reader** role (see [Find your Microsoft Entra tenant ID](https://learn.microsoft.com/en-us/entra/fundamentals/how-to-find-tenant)).

### 8. Enter the values in Vault

In Apideck Vault, open Microsoft Outlook and enter:

| Vault field | Value from Microsoft Entra |
|-------------|----------------------------|
| **Client ID** | The **Application (client) ID** from step 3 |
| **Client Secret** | The client secret **Value** from step 6 (not the Secret ID) |
| **Tenant ID** | The **Tenant ID** from step 7 |

Save the connection.

## Notes

- **Tenant-wide access.** Application permissions cover every mailbox in your tenant, not only the people who use the connected product. If you want to limit the app to specific mailboxes, an Exchange administrator can do so for the Contacts permissions with [Role Based Access Control for Applications in Exchange Online](https://learn.microsoft.com/en-us/graph/auth-limit-mailbox-access). This does not narrow `User.Read.All`, which applies across your directory.
- **Whose contacts are returned.** Which mailbox a contacts request reads from is described on the Gotchas tab.

## Renewing the client secret

The connection uses the client secret every time it requests a token, so once the secret expires the connection stops working. Before the expiry date:

1. In the Entra admin center, open your app and go to **Certificates & secrets** > **Client secrets** > **New client secret**.
2. Copy the new secret **Value** immediately.
3. In Apideck Vault, open the Microsoft Outlook connection and replace the **Client Secret** with the new Value. The Client ID and Tenant ID stay the same.

## Troubleshooting

- **Authentication fails.** Check that **Client ID** holds the Application (client) ID and not the Secret ID, that **Client Secret** holds the secret Value, and that **Tenant ID** matches the tenant where you registered the app.
- **Requests are denied after connecting.** Check on the **API permissions** page that the permissions are of type **Application** and that admin consent shows as granted.
- **Users cannot be listed.** Add `User.Read.All` (or `User.ReadWrite.All`) as an application permission and grant admin consent again.
- **The connection stopped working after months of use.** The client secret has most likely expired. Follow the renewal steps above.
- **Using a personal Microsoft account.** Personal accounts are not supported. Use a work or school tenant.

For anything else, contact [Apideck Support](https://help.apideck.com/en/articles/7774658).