Skip to content

Commit 01e2ddf

Browse files
cilwernercilwerner
committed
readding client app config
1 parent 0dbbfcd commit 01e2ddf

File tree

2 files changed

+166
-0
lines changed

2 files changed

+166
-0
lines changed

‎articles/active-directory/develop/TOC.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -643,6 +643,8 @@
643643
- name: National clouds and MSAL
644644
displayName: china, germany, gov, 21vianet
645645
href: msal-national-cloud.md
646+
- name: Application configuration
647+
href: msal-client-application-configuration.md
646648
- name: MSAL Android
647649
items:
648650
- name: Library initialization

‎articles/active-directory/develop/msal-client-application-configuration.md

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
---
2+
title: Client application configuration (MSAL)
3+
description: Learn about configuration options for public client and confidential client applications using the Microsoft Authentication Library (MSAL).
4+
services: active-directory
5+
author: cilwerner
6+
manager: CelesteDG
7+
8+
ms.service: active-directory
9+
ms.subservice: develop
10+
ms.topic: conceptual
11+
ms.workload: identity
12+
ms.date: 08/11/2023
13+
ms.author: cwerner
14+
ms.reviewer: saeeda
15+
ms.custom: aaddev, has-adal-ref
16+
#Customer intent: As an application developer, I want to learn about the types of client applications so I can decide if this platform meets my app development needs.
17+
---
18+
19+
# Application configuration options
20+
21+
To authenticate and acquire tokens, you initialize a new public or confidential client application in your code. You can set several configuration options when you initialize the client app in the Microsoft Authentication Library (MSAL). These options fall into two groups:
22+
23+
- Registration options, including:
24+
- [Authority](#authority) (composed of the identity provider [instance](#cloud-instance) and sign-in [audience](#application-audience) for the app, and possibly the tenant ID)
25+
- [Client ID](#client-id)
26+
- [Redirect URI](#redirect-uri)
27+
- [Client secret](#client-secret) (for confidential client applications)
28+
- [Logging options](#logging), including log level, control of personal data, and the name of the component using the library
29+
30+
## Authority
31+
32+
The authority is a URL that indicates a directory that MSAL can request tokens from.
33+
34+
Common authorities are:
35+
36+
| Common authority URLs | When to use |
37+
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
38+
| `https://login.microsoftonline.com/<tenant>/` | Sign in users of a specific organization only. The `<tenant>` in the URL is the tenant ID of the Azure Active Directory (Azure AD) tenant (a GUID), or its tenant domain. |
39+
| `https://login.microsoftonline.com/common/` | Sign in users with work and school accounts or personal Microsoft accounts. |
40+
| `https://login.microsoftonline.com/organizations/` | Sign in users with work and school accounts. |
41+
| `https://login.microsoftonline.com/consumers/` | Sign in users with personal Microsoft accounts (MSA) only. |
42+
43+
The authority you specify in your code needs to be consistent with the **Supported account types** you specified for the app in **App registrations** in the Azure portal.
44+
45+
The authority can be:
46+
47+
- An Azure AD cloud authority.
48+
- An Azure AD B2C authority. See [B2C specifics](msal-net-b2c-considerations.md).
49+
- An Active Directory Federation Services (AD FS) authority. See [AD FS support](msal-net-adfs-support.md).
50+
51+
Azure AD cloud authorities have two parts:
52+
53+
- The identity provider _instance_
54+
- The sign-in _audience_ for the app
55+
56+
The instance and audience can be concatenated and provided as the authority URL. This diagram shows how the authority URL is composed:
57+
58+
![How the authority URL is composed](media/msal-client-application-configuration/authority.png)
59+
60+
## Cloud instance
61+
62+
The _instance_ is used to specify if your app is signing users from the Azure public cloud or from national clouds. Using MSAL in your code, you can set the Azure cloud instance by using an enumeration or by passing the URL to the [national cloud instance](authentication-national-cloud.md#azure-ad-authentication-endpoints) as the `Instance` member.
63+
64+
MSAL.NET will throw an explicit exception if both `Instance` and `AzureCloudInstance` are specified.
65+
66+
If you don't specify an instance, your app will target the Azure public cloud instance (the instance of URL `https://login.onmicrosoftonline.com`).
67+
68+
## Application audience
69+
70+
The sign-in audience depends on the business needs for your app:
71+
72+
- If you're a line of business (LOB) developer, you'll probably produce a single-tenant application that will be used only in your organization. In that case, specify the organization by its tenant ID (the ID of your Azure AD instance) or by a domain name associated with the Azure AD instance.
73+
- If you're an ISV, you might want to sign in users with their work and school accounts in any organization or in some organizations (multitenant app). But you might also want to have users sign in with their personal Microsoft accounts.
74+
75+
### How to specify the audience in your code/configuration
76+
77+
Using MSAL in your code, you specify the audience by using one of the following values:
78+
79+
- The Azure AD authority audience enumeration
80+
- The tenant ID, which can be:
81+
- A GUID (the ID of your Azure AD instance), for single-tenant applications
82+
- A domain name associated with your Azure AD instance (also for single-tenant applications)
83+
- One of these placeholders as a tenant ID in place of the Azure AD authority audience enumeration:
84+
- `organizations` for a multitenant application
85+
- `consumers` to sign in users only with their personal accounts
86+
- `common` to sign in users with their work and school accounts or their personal Microsoft accounts
87+
88+
MSAL will throw a meaningful exception if you specify both the Azure AD authority audience and the tenant ID.
89+
90+
It is recommended to specify an audience, as many tenants, and the applications deployed in them will have guest users. If your application will have external users, the endpoints of `common` and `organization` are best avoided. If you don't specify an audience, your app will target Azure AD and personal Microsoft accounts as an audience and will behave as though `common` were specified.
91+
92+
### Effective audience
93+
94+
The effective audience for your application will be the minimum (if there's an intersection) of the audience you set in your app and the audience that's specified in the app registration. In fact, the [App registrations](https://aka.ms/appregistrations) experience lets you specify the audience (the supported account types) for the app. For more information, see [Quickstart: Register an application with the Microsoft identity platform](quickstart-register-app.md).
95+
96+
Currently, the only way to get an app to sign in users with only personal Microsoft accounts is to configure both of these settings:
97+
98+
- Set the app registration audience to `Work and school accounts and personal accounts`.
99+
- Set the audience in your code/configuration to `AadAuthorityAudience.PersonalMicrosoftAccount` (or `TenantID` ="consumers").
100+
101+
## Client ID
102+
103+
The client ID is the unique **Application (client) ID** assigned to your app by Azure AD when the app was registered. You can find the **Application (Client) ID** in your Azure subscription by Azure AD => Enterprise applications => Application ID.
104+
105+
## Redirect URI
106+
107+
The redirect URI is the URI the identity provider will send the security tokens back to.
108+
109+
### Redirect URI for public client apps
110+
111+
If you're a public client app developer who's using MSAL:
112+
113+
- You'd want to use `.WithDefaultRedirectUri()` in desktop or Universal Windows Platform (UWP) applications (MSAL.NET 4.1+). The `.WithDefaultRedirectUri()` method will set the public client application's redirect URI property to the default recommended redirect URI for public client applications.
114+
115+
| Platform | Redirect URI |
116+
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
117+
| Desktop app (.NET FW) | `https://login.microsoftonline.com/common/oauth2/nativeclient` |
118+
| UWP | value of `WebAuthenticationBroker.GetCurrentApplicationCallbackUri()`. This enables single sign-on (SSO) with the browser by setting the value to the result of WebAuthenticationBroker.GetCurrentApplicationCallbackUri(), which you need to register |
119+
| .NET Core | `https://localhost` enables the user to use the system browser for interactive authentication since .NET Core doesn't have a UI for the embedded web view at the moment. |
120+
121+
- You don't need to add a redirect URI if you're building a Xamarin Android and iOS application that doesn't support the broker redirect URI. It's automatically set to `msal{ClientId}://auth` for Xamarin Android and iOS.
122+
123+
- Configure the redirect URI in [App registrations](https://aka.ms/appregistrations):
124+
125+
![Redirect URI in App registrations](media/msal-client-application-configuration/redirect-uri.png)
126+
127+
You can override the redirect URI by using the `RedirectUri` property (for example, if you use brokers). Here are some examples of redirect URIs for that scenario:
128+
129+
- `RedirectUriOnAndroid` = "msauth-5a434691-ccb2-4fd1-b97b-b64bcfbc03fc://com.microsoft.identity.client.sample";
130+
- `RedirectUriOnIos` = $"msauth.{Bundle.ID}://auth";
131+
132+
For more iOS details, see [Migrate iOS applications that use Microsoft Authenticator from ADAL.NET to MSAL.NET](msal-net-migration-ios-broker.md) and [Leveraging the broker on iOS](msal-net-use-brokers-with-xamarin-apps.md).
133+
For more Android details, see [Brokered auth in Android](msal-android-single-sign-on.md).
134+
135+
### Redirect URI for confidential client apps
136+
137+
For web apps, the redirect URI (or reply URL) is the URI that Azure AD will use to send the token back to the application. The URI can be the URL of the web app/web API if the confidential app is one of them. The redirect URI needs to be registered in app registration. The registration is especially important when you deploy an app that you've initially tested locally. You then need to add the reply URL of the deployed app in the application registration portal.
138+
139+
For daemon apps, you don't need to specify a redirect URI.
140+
141+
## Client secret
142+
143+
This option specifies the client secret for the confidential client app. The client secret (app password) is provided by the application registration portal or provided to Azure AD during app registration with PowerShell AzureAD, PowerShell AzureRM, or Azure CLI.
144+
145+
## Logging
146+
147+
To help in debugging and authentication failure troubleshooting scenarios, the MSAL provides built-in logging support. Logging in each library is covered in the following articles:
148+
149+
:::row:::
150+
:::column:::
151+
- [Logging in MSAL.NET](msal-logging-dotnet.md)
152+
- [Logging in MSAL for Android](msal-logging-android.md)
153+
- [Logging in MSAL.js](msal-logging-js.md)
154+
:::column-end:::
155+
:::column:::
156+
- [Logging in MSAL for iOS/macOS](msal-logging-ios.md)
157+
- [Logging in MSAL for Java](/entra/msal/java/advanced/msal-logging-java)
158+
- [Logging in MSAL for Python](/entra/msal/python/advanced/msal-logging-python)
159+
:::column-end:::
160+
:::row-end:::
161+
162+
## Next steps
163+
164+
Learn about [instantiating client applications by using MSAL.NET](msal-net-initializing-client-applications.md) and [instantiating client applications by using MSAL.js](msal-js-initializing-client-applications.md).

0 commit comments

Comments
 (0)