diff --git a/docs/azure/sdk/authentication/additional-methods.md b/docs/azure/sdk/authentication/additional-methods.md index 9657476f57c4c..36d9e9f732f3c 100644 --- a/docs/azure/sdk/authentication/additional-methods.md +++ b/docs/azure/sdk/authentication/additional-methods.md @@ -16,25 +16,92 @@ This method interactively authenticates an application through [`InteractiveBrow Interactive browser authentication enables the application for all operations allowed by the interactive login credentials. As a result, if you're the owner or administrator of your subscription, your code has inherent access to most resources in that subscription without having to assign any specific permissions. For this reason, the use of interactive browser authentication is discouraged for anything but experimentation. +### Enable applications for interactive browser authentication + +Perform the following steps to enable the application to authenticate through the interactive browser flow. These steps also work for the [device code authentication](#device-code-authentication) flow described later. This process is only necessary if you are using `InteractiveBrowserCredential` in your code. + +1. In the [Azure portal](https://portal.azure.com), navigate to **Microsoft Entra ID** and select **App registrations** on the left navigation. +1. Select the registration for your app, then select **Authentication**. +1. Under **Advanced settings**, select **Yes** for **Allow public client flows**. +1. Select **Save** to apply the changes. +1. To authorize the application for specific resources, navigate to the resource in question, select **API Permissions**, and enable **Microsoft Graph** and other resources you want to access. Microsoft Graph is usually enabled by default. + + > [!IMPORTANT] + > You must also be the admin of your tenant to grant consent to your application when you sign in for the first time. + ### Example using InteractiveBrowserCredential The following example demonstrates using an [`InteractiveBrowserCredential`](/dotnet/api/azure.identity.interactivebrowsercredential) to authenticate with the [`BlobServiceClient`](/dotnet/api/azure.storage.blobs.blobserviceclient): -```csharp -using Azure.Identity; -using Azure.Storage.Blobs; +:::code language="csharp" source="../snippets/additional-auth/interactive/InteractiveBrowserAuth.cs" highlight="15-17"::: -var client = new BlobServiceClient( - new Uri("https://.blob.core.windows.net"), - new InteractiveBrowserCredential()); +For more exact control, such as setting redirect URIs, you can supply specific arguments to `InteractiveBrowserCredential` such as `redirect_uri`. -foreach (var blobItem in client.GetBlobContainers()) -{ - Console.WriteLine(blobItem.Name); -} -``` +## Interactive brokered authentication -For more exact control, such as setting redirect URIs, you can supply specific arguments to `InteractiveBrowserCredential` such as `redirect_uri`. +This method interactively authenticates an application through [`InteractiveBrowserCredential`](/dotnet/api/azure.identity.interactivebrowsercredential?view=azure-dotnet) by collecting user credentials using the system authentication broker. A system authentication broker is an app running on a user's machine that manages the authentication handshakes and token maintenance for all connected accounts. Currently, only the Windows authentication broker, Web Account Manager (WAM), is supported. Users on macOS and Linux will be authenticated through the non-brokered interactive browser flow. + +WAM enables identity providers such as Microsoft Entra ID to natively plug into the OS and provide the service to other apps to provide a more secure login process. WAM offers the following benefits: + +- **Feature support**: Apps can access OS-level and service-level capabilities, including Windows Hello, conditional access policies, and FIDO keys. +- **Streamlined single sign-on**: Apps can use the built-in account picker, allowing the user to select an existing account instead of repeatedly entering the same credentials. +- **Enhanced security**: Bug fixes and enhancements ship with Windows. +- **Token protection**: Refresh tokens are device-bound, and apps can acquire device-bound access tokens. + +Interactive brokered authentication enables the application for all operations allowed by the interactive login credentials. Personal Microsoft accounts and work or school accounts are supported. If a supported version of Windows is used, the default browser-based UI is replaced with a smoother authentication experience, similar to Windows built-in apps. + +### Enable applications for interactive brokered authentication + +Perform the following steps to enable the application to authenticate through the interactive broker flow. + +1. On the [Azure portal](https://portal.azure.com), navigate to **Microsoft Entra ID** and select **App registrations** on the left-hand menu. +1. Select the registration for your app, then select **Authentication**. +1. Add the WAM redirect URI to your app registration via a platform configuration: + 1. Under **Platform configurations**, select **+ Add a platform**. + 1. Under **Configure platforms**, select the tile for your application type (platform) to configure its settings, such as **mobile and desktop applications**. + 1. In **Custom redirect URIs**, enter the following WAM redirect URI: + + ```text + ms-appx-web://microsoft.aad.brokerplugin/{client_id} + ``` + + The `{client_id}` placeholder must be replaced with the **Application (client) ID** listed on the **Overview** pane of the app registration. + + 1. Select **Configure**. + + To learn more, see [Add a redirect URI to an app registration](/entra/identity-platform/quickstart-register-app#add-a-redirect-uri). + +1. Back on the **Authentication** pane, under **Advanced settings**, select **Yes** for **Allow public client flows**. +1. Select **Save** to apply the changes. +1. To authorize the application for specific resources, navigate to the resource in question, select **API Permissions**, and enable **Microsoft Graph** and other resources you want to access. Microsoft Graph is usually enabled by default. + + > [!IMPORTANT] + > You must also be the admin of your tenant to grant consent to your application when you sign in for the first time. + +### Example using InteractiveBrowserCredential + +The following example demonstrates using an [`InteractiveBrowserCredential`](/dotnet/api/azure.identity.interactivebrowsercredential?view=azure-dotnet) in a Windows Forms app to authenticate with the [`BlobServiceClient`](/dotnet/api/azure.storage.blobs.blobserviceclient): + +:::code language="csharp" source="../snippets/additional-auth/interactive/InteractiveBrokeredAuth.cs" highlight="16-20"::: + +> [!NOTE] +> Visit the [Parent window handles](/entra/msal/dotnet/acquiring-tokens/desktop-mobile/wam#parent-window-handles) and [Retrieve a window handle](/windows/apps/develop/ui-input/retrieve-hwnd) articles for more information about retrieving window handles. + +For the code to run successfully, your user account must be assigned an Azure role on the storage account that allows access to blob containers such as **Storage Account Data Contributor**. If an app is specified, it must have API permissions set for **user_impersonation Access Azure Storage** (step 6 in the previous section). This API permission allows the app to access Azure storage on behalf of the signed-in user after consent is granted during sign-in. + +The following screenshot shows the user sign-in experience: + +:::image type="content" source="../media/web-account-manager-sign-in-account-picker.png" alt-text="A screenshot that shows the sign-in experience when using the interactive browser broker credential to authenticate a user." ::: + +### Authenticate the default system account via WAM + +Many people always sign in to Windows with the same user account and, therefore, only ever want to authenticate using that account. WAM and `InteractiveBrowserCredential` also support a silent login process that automatically uses a default account so the user doesn't have to repeatedly select it. + +The following example shows how to enable sign-in with the default system account: + +:::code language="csharp" source="../snippets/additional-auth/interactive/SilentBrokeredAuth.cs" highlight="16-24"::: + +Once you opt into this behavior, the credential attempts to sign in by asking the underlying Microsoft Authentication Library (MSAL) to perform the sign-in for the default system account. If the sign-in fails, the credential falls back to displaying the account picker dialog, from which the user can select the appropriate account. ## Device code authentication @@ -49,7 +116,7 @@ For more information, see [Microsoft identity platform and the OAuth 2.0 device Device code authentication in a development environment enables the application for all operations allowed by the interactive login credentials. As a result, if you're the owner or administrator of your subscription, your code has inherent access to most resources in that subscription without having to assign any specific permissions. However, you can use this method with a specific client ID, rather than the default, for which you can assign specific permissions. -## Authentication with a username and password +## Username and password authentication This method authenticates an application using previously collected credentials and the [UsernamePasswordCredential](/dotnet/api/azure.identity.usernamepasswordcredential) object. @@ -58,21 +125,4 @@ This method authenticates an application using previously collected credentials > > Furthermore, this method authenticates only work and school accounts; Microsoft accounts aren't supported. For more information, see [Sign up your organization to use Microsoft Entra ID](/entra/fundamentals/sign-up-organization). -```csharp -using Azure.Identity; -using Azure.Storage.Blobs; - -var clientId = Environment.GetEnvironmentVariable("AZURE_CLIENT_ID"); -var tenantId = Environment.GetEnvironmentVariable("AZURE_TENANT_ID"); -var username = Environment.GetEnvironmentVariable("AZURE_USERNAME"); -var password = Environment.GetEnvironmentVariable("AZURE_PASSWORD"); - -var client = new BlobServiceClient( - new Uri("https://.blob.core.windows.net"), - new UsernamePasswordCredential(username, password, tenantId, clientId)); - -foreach (var blobItem in client.GetBlobContainers()) -{ - Console.WriteLine(blobItem.Name); -} -``` +:::code language="csharp" source="../snippets/additional-auth/username-password/Program.cs" highlight="9-11"::: diff --git a/docs/azure/sdk/media/web-account-manager-sign-in-account-picker.png b/docs/azure/sdk/media/web-account-manager-sign-in-account-picker.png new file mode 100644 index 0000000000000..bb26d331cd22d Binary files /dev/null and b/docs/azure/sdk/media/web-account-manager-sign-in-account-picker.png differ diff --git a/docs/azure/sdk/snippets/additional-auth/interactive/InteractiveBrokeredAuth.Designer.cs b/docs/azure/sdk/snippets/additional-auth/interactive/InteractiveBrokeredAuth.Designer.cs new file mode 100644 index 0000000000000..5080b5712c60e --- /dev/null +++ b/docs/azure/sdk/snippets/additional-auth/interactive/InteractiveBrokeredAuth.Designer.cs @@ -0,0 +1,59 @@ +namespace InteractiveBrokeredAuthSample +{ + partial class InteractiveBrokeredAuth + { + /// + /// Required designer variable. + /// + private System.ComponentModel.IContainer components = null; + + /// + /// Clean up any resources being used. + /// + /// true if managed resources should be disposed; otherwise, false. + protected override void Dispose(bool disposing) + { + if (disposing && (components != null)) + { + components.Dispose(); + } + base.Dispose(disposing); + } + + #region Windows Form Designer generated code + + /// + /// Required method for Designer support - do not modify + /// the contents of this method with the code editor. + /// + private void InitializeComponent() + { + button1 = new Button(); + SuspendLayout(); + // + // button1 + // + button1.Location = new Point(25, 12); + button1.Name = "button1"; + button1.Size = new Size(200, 44); + button1.TabIndex = 0; + button1.Text = "TestInteractiveBrokeredAuth"; + button1.UseVisualStyleBackColor = true; + button1.Click += testInteractiveBrokeredAuth_Click; + // + // InteractiveBrokeredAuth + // + AutoScaleDimensions = new SizeF(7F, 15F); + AutoScaleMode = AutoScaleMode.Font; + ClientSize = new Size(800, 450); + Controls.Add(button1); + Name = "InteractiveBrokeredAuth"; + Text = "InteractiveBrokeredAuth"; + ResumeLayout(false); + } + + #endregion + + private Button button1; + } +} \ No newline at end of file diff --git a/docs/azure/sdk/snippets/additional-auth/interactive/InteractiveBrokeredAuth.cs b/docs/azure/sdk/snippets/additional-auth/interactive/InteractiveBrokeredAuth.cs new file mode 100644 index 0000000000000..911232d71c356 --- /dev/null +++ b/docs/azure/sdk/snippets/additional-auth/interactive/InteractiveBrokeredAuth.cs @@ -0,0 +1,44 @@ +using Azure.Identity; +using Azure.Identity.Broker; +using Azure.Storage.Blobs; + +namespace InteractiveBrokeredAuthSample +{ + public partial class InteractiveBrokeredAuth : Form + { + public InteractiveBrokeredAuth() + { + InitializeComponent(); + } + + private void testInteractiveBrokeredAuth_Click(object sender, EventArgs e) + { + // Get the handle of the current window + IntPtr windowHandle = this.Handle; + + var credential = new InteractiveBrowserCredential( + new InteractiveBrowserCredentialBrokerOptions(windowHandle)); + + // To authenticate and authorize with an Entra ID app registration, substitute the + // and placeholders with the values for your app and tenant. + // var credential = new InteractiveBrowserCredential( + // new InteractiveBrowserCredentialBrokerOptions(windowHandle) + // { + // TenantId = "your-tenant-id", + // ClientId = "your-client-id" + // } + // ); + + var client = new BlobServiceClient( + new Uri("https://.blob.core.windows.net/"), + credential + ); + + // Prompt for credentials appears on first use of the client + foreach (var container in client.GetBlobContainers()) + { + Console.WriteLine(container.Name); + } + } + } +} diff --git a/docs/azure/sdk/snippets/additional-auth/interactive/InteractiveBrokeredAuth.resx b/docs/azure/sdk/snippets/additional-auth/interactive/InteractiveBrokeredAuth.resx new file mode 100644 index 0000000000000..af32865ec12ff --- /dev/null +++ b/docs/azure/sdk/snippets/additional-auth/interactive/InteractiveBrokeredAuth.resx @@ -0,0 +1,120 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + text/microsoft-resx + + + 2.0 + + + System.Resources.ResXResourceReader, System.Windows.Forms, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089 + + + System.Resources.ResXResourceWriter, System.Windows.Forms, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089 + + \ No newline at end of file diff --git a/docs/azure/sdk/snippets/additional-auth/interactive/InteractiveBrokeredAuthSample.csproj b/docs/azure/sdk/snippets/additional-auth/interactive/InteractiveBrokeredAuthSample.csproj new file mode 100644 index 0000000000000..125a0db706c2a --- /dev/null +++ b/docs/azure/sdk/snippets/additional-auth/interactive/InteractiveBrokeredAuthSample.csproj @@ -0,0 +1,17 @@ + + + + WinExe + net8.0-windows + enable + true + enable + + + + + + + + + \ No newline at end of file diff --git a/docs/azure/sdk/snippets/additional-auth/interactive/InteractiveBrowserAuth.Designer.cs b/docs/azure/sdk/snippets/additional-auth/interactive/InteractiveBrowserAuth.Designer.cs new file mode 100644 index 0000000000000..a9e6f078a2fa7 --- /dev/null +++ b/docs/azure/sdk/snippets/additional-auth/interactive/InteractiveBrowserAuth.Designer.cs @@ -0,0 +1,59 @@ +namespace InteractiveBrokeredAuthSample +{ + partial class InteractiveBrowserAuth + { + /// + /// Required designer variable. + /// + private System.ComponentModel.IContainer components = null; + + /// + /// Clean up any resources being used. + /// + /// true if managed resources should be disposed; otherwise, false. + protected override void Dispose(bool disposing) + { + if (disposing && (components != null)) + { + components.Dispose(); + } + base.Dispose(disposing); + } + + #region Windows Form Designer generated code + + /// + /// Required method for Designer support - do not modify + /// the contents of this method with the code editor. + /// + private void InitializeComponent() + { + button1 = new Button(); + SuspendLayout(); + // + // button1 + // + button1.Location = new Point(34, 39); + button1.Name = "button1"; + button1.Size = new Size(207, 43); + button1.TabIndex = 0; + button1.Text = "TestInteractiveBrowserAuth"; + button1.UseVisualStyleBackColor = true; + button1.Click += testInteractiveBrowserAuth_Click; + // + // InteractiveBrowserAuth + // + AutoScaleDimensions = new SizeF(7F, 15F); + AutoScaleMode = AutoScaleMode.Font; + ClientSize = new Size(800, 450); + Controls.Add(button1); + Name = "InteractiveBrowserAuth"; + Text = "InteractiveBrowserAuth"; + ResumeLayout(false); + } + + #endregion + + private Button button1; + } +} \ No newline at end of file diff --git a/docs/azure/sdk/snippets/additional-auth/interactive/InteractiveBrowserAuth.cs b/docs/azure/sdk/snippets/additional-auth/interactive/InteractiveBrowserAuth.cs new file mode 100644 index 0000000000000..e370b50fde56d --- /dev/null +++ b/docs/azure/sdk/snippets/additional-auth/interactive/InteractiveBrowserAuth.cs @@ -0,0 +1,25 @@ +using Azure.Identity; +using Azure.Storage.Blobs; + +namespace InteractiveBrokeredAuthSample +{ + public partial class InteractiveBrowserAuth : Form + { + public InteractiveBrowserAuth() + { + InitializeComponent(); + } + + private void testInteractiveBrowserAuth_Click(object sender, EventArgs e) + { + var client = new BlobServiceClient( + new Uri("https://.blob.core.windows.net"), + new InteractiveBrowserCredential()); + + foreach (var blobItem in client.GetBlobContainers()) + { + Console.WriteLine(blobItem.Name); + } + } + } +} diff --git a/docs/azure/sdk/snippets/additional-auth/interactive/InteractiveBrowserAuth.resx b/docs/azure/sdk/snippets/additional-auth/interactive/InteractiveBrowserAuth.resx new file mode 100644 index 0000000000000..af32865ec12ff --- /dev/null +++ b/docs/azure/sdk/snippets/additional-auth/interactive/InteractiveBrowserAuth.resx @@ -0,0 +1,120 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + text/microsoft-resx + + + 2.0 + + + System.Resources.ResXResourceReader, System.Windows.Forms, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089 + + + System.Resources.ResXResourceWriter, System.Windows.Forms, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089 + + \ No newline at end of file diff --git a/docs/azure/sdk/snippets/additional-auth/interactive/Program.cs b/docs/azure/sdk/snippets/additional-auth/interactive/Program.cs new file mode 100644 index 0000000000000..262fffa6a0e23 --- /dev/null +++ b/docs/azure/sdk/snippets/additional-auth/interactive/Program.cs @@ -0,0 +1,21 @@ +using InteractiveBrokeredAuthSample; + +namespace WinFormsApp1 +{ + internal static class Program + { + /// + /// The main entry point for the application. + /// + [STAThread] + static void Main() + { + // To customize application configuration such as set high DPI settings or default font, + // see https://aka.ms/applicationconfiguration. + ApplicationConfiguration.Initialize(); + Application.Run(new InteractiveBrowserAuth()); + + + } + } +} \ No newline at end of file diff --git a/docs/azure/sdk/snippets/additional-auth/interactive/SilentBrokeredAuth.Designer.cs b/docs/azure/sdk/snippets/additional-auth/interactive/SilentBrokeredAuth.Designer.cs new file mode 100644 index 0000000000000..078edbd759e50 --- /dev/null +++ b/docs/azure/sdk/snippets/additional-auth/interactive/SilentBrokeredAuth.Designer.cs @@ -0,0 +1,59 @@ +namespace InteractiveBrokeredAuthSample +{ + partial class SilentBrokeredAuth + { + /// + /// Required designer variable. + /// + private System.ComponentModel.IContainer components = null; + + /// + /// Clean up any resources being used. + /// + /// true if managed resources should be disposed; otherwise, false. + protected override void Dispose(bool disposing) + { + if (disposing && (components != null)) + { + components.Dispose(); + } + base.Dispose(disposing); + } + + #region Windows Form Designer generated code + + /// + /// Required method for Designer support - do not modify + /// the contents of this method with the code editor. + /// + private void InitializeComponent() + { + button1 = new Button(); + SuspendLayout(); + // + // button1 + // + button1.Location = new Point(35, 36); + button1.Name = "button1"; + button1.Size = new Size(165, 39); + button1.TabIndex = 0; + button1.Text = "TestSilentBrokeredAuth"; + button1.UseVisualStyleBackColor = true; + button1.Click += testSilentBrokeredAuth_Click; + // + // SilentBrokeredAuth + // + AutoScaleDimensions = new SizeF(7F, 15F); + AutoScaleMode = AutoScaleMode.Font; + ClientSize = new Size(800, 450); + Controls.Add(button1); + Name = "SilentBrokeredAuth"; + Text = "SilentBrokeredAuth"; + ResumeLayout(false); + } + + #endregion + + private Button button1; + } +} \ No newline at end of file diff --git a/docs/azure/sdk/snippets/additional-auth/interactive/SilentBrokeredAuth.cs b/docs/azure/sdk/snippets/additional-auth/interactive/SilentBrokeredAuth.cs new file mode 100644 index 0000000000000..20f6ccf87f6f7 --- /dev/null +++ b/docs/azure/sdk/snippets/additional-auth/interactive/SilentBrokeredAuth.cs @@ -0,0 +1,48 @@ +using Azure.Identity; +using Azure.Identity.Broker; +using Azure.Storage.Blobs; + +namespace InteractiveBrokeredAuthSample +{ + public partial class SilentBrokeredAuth : Form + { + public SilentBrokeredAuth() + { + InitializeComponent(); + } + + private void testSilentBrokeredAuth_Click(object sender, EventArgs e) + { + // Get the handle of the current window + IntPtr windowHandle = this.Handle; + + var credential = new InteractiveBrowserCredential( + new InteractiveBrowserCredentialBrokerOptions(windowHandle) + { + // Enable silent brokered authentication using the default account + UseDefaultBrokerAccount = true, + }); + + // To authenticate and authorize with an app, substitute the + // and placeholders with the values for your app and tenant. + // var credential = new InteractiveBrowserCredential( + // new InteractiveBrowserCredentialBrokerOptions(windowHandle) + // { + // TenantId = "your-tenant-id", + // ClientId = "your-client-id" + // } + // ); + + var client = new BlobServiceClient( + new Uri("https://.blob.core.windows.net/"), + credential + ); + + // Prompt for credentials appears on first use of the client + foreach (var container in client.GetBlobContainers()) + { + Console.WriteLine(container.Name); + } + } + } +} diff --git a/docs/azure/sdk/snippets/additional-auth/interactive/SilentBrokeredAuth.resx b/docs/azure/sdk/snippets/additional-auth/interactive/SilentBrokeredAuth.resx new file mode 100644 index 0000000000000..af32865ec12ff --- /dev/null +++ b/docs/azure/sdk/snippets/additional-auth/interactive/SilentBrokeredAuth.resx @@ -0,0 +1,120 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + text/microsoft-resx + + + 2.0 + + + System.Resources.ResXResourceReader, System.Windows.Forms, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089 + + + System.Resources.ResXResourceWriter, System.Windows.Forms, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089 + + \ No newline at end of file diff --git a/docs/azure/sdk/snippets/additional-auth/username-password/Program.cs b/docs/azure/sdk/snippets/additional-auth/username-password/Program.cs new file mode 100644 index 0000000000000..3dbf88e473626 --- /dev/null +++ b/docs/azure/sdk/snippets/additional-auth/username-password/Program.cs @@ -0,0 +1,16 @@ +using Azure.Identity; +using Azure.Storage.Blobs; + +var clientId = Environment.GetEnvironmentVariable("AZURE_CLIENT_ID"); +var tenantId = Environment.GetEnvironmentVariable("AZURE_TENANT_ID"); +var username = Environment.GetEnvironmentVariable("AZURE_USERNAME"); +var password = Environment.GetEnvironmentVariable("AZURE_PASSWORD"); + +var client = new BlobServiceClient( + new Uri("https://.blob.core.windows.net"), + new UsernamePasswordCredential(username, password, tenantId, clientId)); + +foreach (var blobItem in client.GetBlobContainers()) +{ + Console.WriteLine(blobItem.Name); +} \ No newline at end of file diff --git a/docs/azure/sdk/snippets/additional-auth/username-password/UsernamePassword.csproj b/docs/azure/sdk/snippets/additional-auth/username-password/UsernamePassword.csproj new file mode 100644 index 0000000000000..35120169687dd --- /dev/null +++ b/docs/azure/sdk/snippets/additional-auth/username-password/UsernamePassword.csproj @@ -0,0 +1,16 @@ + + + + Exe + net9.0 + enable + enable + + + + + + + + +