|
| 1 | +--- |
| 2 | +title: Microsoft |
| 3 | +description: Microsoft provider documentation |
| 4 | +icon: i-simple-icons-microsoft |
| 5 | +--- |
| 6 | + |
| 7 | +## Feature/OIDC support |
| 8 | + |
| 9 | +✅ PKCE<br> |
| 10 | +✅ Nonce<br> |
| 11 | +✅ State<br> |
| 12 | +❌ Access Token validation<br> |
| 13 | +✅ ID Token validation<br> |
| 14 | + |
| 15 | +## Introduction |
| 16 | + |
| 17 | +This is the simplified Microsoft provider for social login with a Microsoft Account (MSA). You need access to the Azure portal (portal.azure.com) to configure an app registration and get the required properties. |
| 18 | +Learn how to creat an app registration [here](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app?tabs=client-secret). |
| 19 | +Be sure that you select one of the bottom two options if you want persoanl Microsoft accounts to be able to login to your application: |
| 20 | + |
| 21 | +::contentImage{src="/content/microsoft-accounttype.png" alt="Microsoft account types"} |
| 22 | +:: |
| 23 | + |
| 24 | +Choose 'Web' as the target platform under `Manage` -> `Authentication` -> `Platform configurations` |
| 25 | + |
| 26 | +::contentImage{src="/content/microsoft-platform.png" alt="Microsoft Platform configurations"} |
| 27 | +:: |
| 28 | + |
| 29 | +This provider uses the predefined userInfo url `https://graph.microsoft.com/v1.0/me` to get user information for an account. |
| 30 | + |
| 31 | +## Example Configurations |
| 32 | + |
| 33 | +::callout{icon="i-carbon-warning-alt" color="amber"} |
| 34 | +Never store sensitive values like your client secret in your Nuxt config. Our recommendation is to inject at least client id and client secret via. environment variables. |
| 35 | +:: |
| 36 | + |
| 37 | +### Minimal |
| 38 | + |
| 39 | +```typescript [nuxt.config.ts] |
| 40 | +entra: { |
| 41 | + redirectUri: 'http://localhost:3000/auth/microsoft/callback', |
| 42 | + clientId: '', |
| 43 | + clientSecret: '', |
| 44 | +}, |
| 45 | +``` |
| 46 | + |
| 47 | +### Get user information |
| 48 | + |
| 49 | +You can also add the `profile` or another OIDC common scope. `User.Read` as a delegated permission is configured by default in **API permissons**. |
| 50 | + |
| 51 | +```typescript [nuxt.config.ts] |
| 52 | +entra: { |
| 53 | + redirectUri: 'http://localhost:3000/auth/microsoft/callback', |
| 54 | + clientId: '', |
| 55 | + clientSecret: '', |
| 56 | + responseType: 'code', |
| 57 | + scope: ['openid', 'User.Read'], |
| 58 | +}, |
| 59 | +``` |
| 60 | + |
| 61 | +### Get additonal user information with ID token |
| 62 | + |
| 63 | +To be able to use the ID token, make sure you have set the checkbox at **Manage** -> **Authentication** -> **Implicit grant and hybrid flows** -> `ID tokens (used for implicit and hybrid flows)`. |
| 64 | +To add additional claims you want to use, configure them on your app registration under **Manage** -> **Token configuration** and add them by using the `optionalClaims: ['name', 'preferred_username'],` parameter. |
| 65 | +The default setting is `optionalClaims: ['name', 'preferred_username'],`. |
| 66 | + |
| 67 | +```typescript [nuxt.config.ts] |
| 68 | +entra: { |
| 69 | + redirectUri: 'http://localhost:3000/auth/microsoft/callback', |
| 70 | + clientId: '', |
| 71 | + clientSecret: '', |
| 72 | + responseType: 'code id_token', |
| 73 | + scope: ['openid', 'User.Read'], |
| 74 | +}, |
| 75 | +``` |
| 76 | + |
| 77 | +### Offline access/refresh token |
| 78 | + |
| 79 | +In order to get a refresh token, you need to add the "Microsoft Graph" delegated permission `offline_access` and add it to the scopes. |
| 80 | +**Manage** -> **API permissions** -> `Add a permission` |
| 81 | + |
| 82 | +::contentImage{src="/content/microsoft-scopes.png" alt="Microsoft account types"} |
| 83 | +:: |
| 84 | + |
| 85 | +```typescript [nuxt.config.ts] |
| 86 | +entra: { |
| 87 | + redirectUri: 'http://localhost:3000/auth/microsoft/callback', |
| 88 | + clientId: '', |
| 89 | + clientSecret: '', |
| 90 | + responseType: 'code id_token', |
| 91 | + scope: ['openid', 'User.Read', 'offline_access'], |
| 92 | +}, |
| 93 | +``` |
| 94 | + |
| 95 | +### Environment variables |
| 96 | + |
| 97 | +Dotenv files are only for (local) development. Use a proper configuration management or injection system in production. |
| 98 | + |
| 99 | +```ini [.env] |
| 100 | +NUXT_OIDC_PROVIDERS_MICROSOFT_CLIENT_SECRET=CLIENT_SECRET |
| 101 | +NUXT_OIDC_PROVIDERS_MICROSOFT_CLIENT_ID=CLIENT_ID |
| 102 | +``` |
| 103 | + |
| 104 | +## Provider specific parameters |
| 105 | + |
| 106 | +| Option | Type | Default | Description | |
| 107 | +|---|---|---|---| |
| 108 | +| tenantId | `string` | - | Required. The tenant id is used to automatically configure the correct endpoint urls for the Microsoft provider to work. | |
| 109 | +| prompt | `string` | 'login' | Optional. Indicates the type of user interaction that is required. Valid values are `login`, `none`, `consent`, and `select_account`. Can be used in `additionalAuthParameters`, `additionalTokenParameters` or `additionalLogoutParameters`. | |
| 110 | +| loginHint | `string` | - | Optional. You can use this parameter to pre-fill the username and email address field of the sign-in page for the user. Apps can use this parameter during reauthentication, after already extracting the login_hint optional claim from an earlier sign-in. Can be used in `additionalAuthParameters`, `additionalTokenParameters` or `additionalLogoutParameters`. | |
| 111 | +| logoutHint | `string` | - | Optional. Enables sign-out to occur without prompting the user to select an account. To use logout_hint, enable the login_hint optional claim in your client application and use the value of the login_hint optional claim as the logout_hint parameter. Can be used in `additionalAuthParameters`, `additionalTokenParameters` or `additionalLogoutParameters`. | |
| 112 | +| domainHint | `string` | - | Optional. If included, the app skips the email-based discovery process that user goes through on the sign-in page, leading to a slightly more streamlined user experience. Can be used in `additionalAuthParameters`, `additionalTokenParameters` or `additionalLogoutParameters`. | |
0 commit comments