|
| 1 | +--- |
| 2 | +title: Microsoft app credentials |
| 3 | +description: Run Microsoft Entra ID, SharePoint, Dataverse, and Dynamics 365 blocks as an app registration with a client secret, a certificate, or a keyless federated credential that trusts Sim |
| 4 | +--- |
| 5 | + |
| 6 | +import { Callout } from '@/components/ui/callout' |
| 7 | +import { Step, Steps } from '@/components/ui/steps' |
| 8 | + |
| 9 | +A Microsoft app credential signs in as a Microsoft Entra app registration instead of a person (the OAuth 2.0 client credentials flow). One credential works for the **Azure AD** (Microsoft Entra ID), **SharePoint**, **Microsoft Dataverse**, and **Dynamics 365** blocks. Connecting a Microsoft account through OAuth keeps working exactly as before; the app credential is an additional option in the same account picker. |
| 10 | + |
| 11 | +<Callout type="info"> |
| 12 | +Outlook, OneDrive, Excel, Word, Planner, and Teams act on behalf of a signed-in person and don't accept an app credential. The Azure AD **Reset password** operation also needs a signed-in admin, because Microsoft Graph doesn't support application permissions for it. |
| 13 | +</Callout> |
| 14 | + |
| 15 | +## Choose how the app signs in |
| 16 | + |
| 17 | +| Option | What Sim stores | When to use it | |
| 18 | +| --- | --- | --- | |
| 19 | +| **Federated credential (keyless, via Sim OIDC)** | Nothing secret: the tenant ID, client ID, and this credential's subject | Recommended. No secret to rotate, expire, or leak. | |
| 20 | +| **Client secret** | The tenant ID, client ID, and client secret | Quick setup. Secrets expire, so plan to rotate them. | |
| 21 | +| **Certificate** | The tenant ID, client ID, the certificate, and its private key | When your organization requires certificate credentials. Sim signs each token request with the key. | |
| 22 | + |
| 23 | +Every option resolves on Sim's servers at run time, and tokens never appear in block outputs, logs, or anything a model sees. Azure AD and SharePoint blocks get a Microsoft Graph token; Dataverse and Dynamics 365 blocks get a token for the credential's own environment. |
| 24 | + |
| 25 | +## Register the app and grant permissions |
| 26 | + |
| 27 | +<Steps> |
| 28 | + <Step> |
| 29 | + In the [Microsoft Entra admin center](https://entra.microsoft.com), go to **App registrations** → **New registration**. A single-tenant app is fine. Copy the **Application (client) ID** and **Directory (tenant) ID** from its Overview page. |
| 30 | + </Step> |
| 31 | + <Step> |
| 32 | + Under **API permissions** → **Add a permission** → **Microsoft Graph** → **Application permissions**, add what your workflows need, then select **Grant admin consent**. Application permissions always need admin consent. For example: |
| 33 | + - Azure AD: `User.Read.All` or `User.ReadWrite.All`, `Group.ReadWrite.All`, `GroupMember.ReadWrite.All`, `AuditLog.Read.All` for sign-in and audit logs, `Policy.Read.All` for conditional access, `UserAuthenticationMethod.Read.All` for authentication methods, `User.RevokeSessions.All` to revoke sessions. Setting a password needs `User-PasswordProfile.ReadWrite.All` **and** the app assigned at least the User Administrator role. |
| 34 | + - SharePoint: `Sites.Read.All` or `Sites.ReadWrite.All`. Creating and editing pages needs `Sites.ReadWrite.All`. `Sites.Selected` limits the app to sites you grant it, but searching for sites doesn't work with it, so enter site IDs directly. |
| 35 | + </Step> |
| 36 | + <Step> |
| 37 | + Dataverse and Dynamics 365 don't use API permissions. Instead, in the [Power Platform admin center](https://admin.powerplatform.microsoft.com), open the environment → **Settings** → **Users + permissions** → **Application users** → **New app user**, add this app, pick a business unit, and assign a security role. Then enter the environment URL (like `https://contoso.crm.dynamics.com`) on the credential. |
| 38 | + </Step> |
| 39 | +</Steps> |
| 40 | + |
| 41 | +## Set up a keyless federated credential [#keyless-federated-credential] |
| 42 | + |
| 43 | +<Steps> |
| 44 | + <Step> |
| 45 | + In Sim, add a **Microsoft app credential**, choose **Federated credential (keyless, via Sim OIDC)**, and enter the tenant ID and client ID. The dialog shows an **Issuer**, **Audience**, and **Subject**. |
| 46 | + </Step> |
| 47 | + <Step> |
| 48 | + In the app registration, go to **Certificates & secrets** → **Federated credentials** → **Add credential** → **Other issuer**. Paste the **Issuer** and the **Subject identifier** exactly as shown, set the audience to `api://AzureADTokenExchange` (the dialog's value), and give it a name. Matching is case-sensitive. |
| 49 | + </Step> |
| 50 | + <Step> |
| 51 | + Save in Sim. Sim requests a token as the app and reads the app's own service principal from Microsoft Graph, which needs no extra permission. It also checks that the app refuses a subject no credential holds, so only this credential can use the app. A new federated credential can take a few minutes to take effect; if saving fails with a matching error right after you add it, wait and try again. |
| 52 | + </Step> |
| 53 | +</Steps> |
| 54 | + |
| 55 | +An app can have up to 20 federated credentials. Each Sim credential has its own subject, and reconnecting keeps the subject by default so the federated credential keeps working. Keyless credentials are available for workspace credentials, not organization credentials. |
| 56 | + |
| 57 | +## Use a client secret or certificate |
| 58 | + |
| 59 | +- **Client secret:** under **Certificates & secrets** → **Client secrets** → **New client secret**, copy the secret's **Value** (not the Secret ID). |
| 60 | +- **Certificate:** upload the certificate's public part (`.cer`, `.pem`, or `.crt`) under **Certificates & secrets** → **Certificates**, then paste the certificate and its unencrypted PEM RSA private key (2048 to 4096 bits) into Sim. Sim checks the key belongs to the certificate before saving, and signs a PS256 assertion with the certificate's SHA-256 thumbprint. |
| 61 | + |
| 62 | +## Self-hosted deployments |
| 63 | + |
| 64 | +Keyless credentials need `WORKLOAD_IDENTITY_SIGNING_KEY` set and an `https` issuer Microsoft Entra can reach over the public internet. See [AWS credentials](/integrations/aws-credentials#self-hosted-deployments) for the same settings and for rotating the signing key. App credentials use the global Microsoft Entra endpoint (`login.microsoftonline.com`) and public-cloud Dataverse environments. |
| 65 | + |
| 66 | +## Troubleshooting |
| 67 | + |
| 68 | +- **"No federated credential on this app matches…":** the federated credential's issuer, subject, or audience differs from the dialog (check case and trailing slashes), it's on a different app than the client ID, or it was added moments ago. |
| 69 | +- **"Microsoft Entra rejected the client secret":** you pasted the Secret ID, or the secret was deleted. **"This client secret has expired":** create a new one and reconnect. |
| 70 | +- **"…could not verify the signed assertion":** the certificate in Sim isn't the one uploaded to the app registration. |
| 71 | +- **"…the Dataverse environment did not accept it":** add the app as an application user of the environment with a security role. |
| 72 | +- **A block fails with 403 "Insufficient privileges":** the app is missing an application permission for that operation, or admin consent wasn't granted after adding it. |
0 commit comments