> For the complete documentation index, see [llms.txt](https://codemash.gitbook.io/codemash/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://codemash.gitbook.io/codemash/cloud/membership/integrations/providers/microsoft.md).

# Microsoft (Azure AD)

Connect Microsoft (Azure AD) to Membership — let your users sign in with Microsoft.

Lets your users sign in with a Microsoft work, school or personal account, through an app registration in Microsoft Entra ID (formerly Azure AD).

## Get your credentials

1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com) as at least an Application Developer.
2. Browse to **Entra ID** → **App registrations** → **New registration**. Enter a name, choose **Supported account types** (for example **Single tenant only**), and add a **Web** redirect URI for your app. Press **Register**.
3. On the app's **Overview** page, copy the **Application (client) ID** and the **Directory (tenant) ID**.
4. Open **Certificates & secrets** → **New client secret**, add it, and copy its **Value** at once — it is shown only once.

Source: Microsoft, [How to register an app in Microsoft Entra ID](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app).

## Connect it in Cloud

**Where:** Membership → Integrations → **Add New Integration** → Microsoft (Azure AD) → **Connect** · `/projects/<project>/membership/integrations/new/microsoft`

Fill the form and press **Save**. The form stays open as **Editing Microsoft integration** with the **ENABLED** badge and the new id (`int_4arjQTFv3tO4HTJ7VZV796`).

| Field            | Required  | What it does                                                      | Example                                |
| ---------------- | --------- | ----------------------------------------------------------------- | -------------------------------------- |
| Tenant Id        | yes (new) | The Directory (tenant) ID that owns the app registration.         | `11111111-2222-3333-4444-555555555555` |
| Client Id        | yes (new) | The Application (client) ID.                                      | `aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee` |
| Client Secret    | yes       | The client secret value. Encrypted on save and never shown again. | `example-not-a-secret` (made up)       |
| Integration Name | yes       | The name in your integrations list.                               | `Microsoft work accounts`              |

**OAuth Modes** — press **Add OAuth mode** for each surface of your app (web, mobile, admin) that signs in with this provider:

| Field                                      | Required | What it does                                       | Example                                           |
| ------------------------------------------ | -------- | -------------------------------------------------- | ------------------------------------------------- |
| Mode name                                  | yes      | A name for the surface.                            | `web`                                             |
| Callback URL                               | yes      | Where the user lands in your app after signing in. | `https://app.example.com/auth/microsoft/callback` |
| Logout URL (optional)                      | no       | Where the user lands after signing out.            | —                                                 |
| Failure redirect URL (optional)            | no       | Where the user lands when the sign-in fails.       | `https://app.example.com/sign-in?failed=1`        |
| Role to assign on first sign-in (optional) | no       | The role a new user gets on the first sign-in.     | —                                                 |

<figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-c6fe8badf66484955577332b0a63f2ab7ec562d2%2Fmicrosoft-form-1.png?alt=media" alt="New Microsoft Integration form: Tenant Id, Client Id, a hidden Client Secret, Integration Name Microsoft work accounts"><figcaption><p>The filled form.</p></figcaption></figure>

<figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-c618e6725f0af7cc0ca23e40c833a81ff0675edb%2Fmicrosoft-form-2.png?alt=media" alt="OAuth Modes with one mode: Mode name web, Callback URL https://app.example.com/auth/microsoft/callback, Failure redirect URL https://app.example.com/sign-in?failed=1, and Add OAuth mode"><figcaption><p>One OAuth mode for the web app.</p></figcaption></figure>

<figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-d59a8d24db0d4ea0c23b15368c5d3584fd9ecdc7%2Fmicrosoft-saved-3.png?alt=media" alt="Editing Microsoft integration after save: the ENABLED badge, the id int_4arjQTFv3tO4HTJ7VZV796, the provider fields empty and the Integration Name Microsoft work accounts"><figcaption><p>After save.</p></figcaption></figure>

{% hint style="warning" %}
Two things to know today. **(1)** When you open a saved integration, its fields come back empty — only the name and the state load, and the saved OAuth modes are not shown — so type every value again before you press **Save** on it. **(2)** No Norbix sign-in endpoint uses membership integrations yet: saving stores the settings, but your users cannot sign in with Microsoft through the API until it ships.
{% endhint %}

## Test and set as default

Membership integrations have no **Test** and no **Set as default** in Cloud — see [Test an integration](/codemash/cloud/membership/integrations/test.md) and [Set an integration as default](/codemash/cloud/membership/integrations/set-default.md). Check the values against the provider's console; **Actions → Disable** turns the integration off — see [Disable or delete an integration](/codemash/cloud/membership/integrations/disable.md).

## Common errors

| Message                                          | Cause                                          | Fix                                                      |
| ------------------------------------------------ | ---------------------------------------------- | -------------------------------------------------------- |
| *Required* under a field                         | A required field is empty.                     | Fill it; on a saved integration, type the secret again.  |
| Secret is not provided (`CM-ERRORS-SECRETS-001`) | Saved from code without the secret.            | Send the secret on every save.                           |
| *AADSTS50011* (at Microsoft)                     | The redirect URI is not registered on the app. | Add it under **Authentication** of the app registration. |
| *AADSTS7000215* (at Microsoft)                   | The client secret is wrong or expired.         | Create a new client secret and save it here.             |

Messages marked *(at …)* are the provider's own, shown to the user while signing in; see the [provider documentation](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app).

## Do it from code

```sh
norbix hub membership integration save --integration '{"provider":"Microsoft","integrationName":"Microsoft (staging)","isEnabled":true,"tenantId":"11111111-2222-3333-4444-555555555555","clientId":"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee","clientSecret":"your-client-secret"}'
```

With the SDK, send the same object as `integration` to `saveMembershipIntegration` — see the run example on [Providers](/codemash/cloud/membership/integrations/providers.md#do-it-from-code) and in [Save Membership Integration](/codemash/sdks/membership/integrations/save-membership-integration.md). Send `isEnabled: true`; to update, add the id as `integrationId` and the secret again. API: [Save Membership Integration](/codemash/api-reference/membership/integrations/save-membership-integration.md)