Updates from: 08/30/2021 03:03:39
Service Microsoft Docs article Related commit history on GitHub Change details
active-directory-b2c Add Api Connector Token Enrichment https://github.com/MicrosoftDocs/azure-docs/commits/master/articles/active-directory-b2c/add-api-connector-token-enrichment.md
Previously updated : 08/04/2021 Last updated : 08/29/2021 zone_pivot_groups: b2c-policy-type
Content-type: application/json
"objectId": "ab3ec3b2-a435-45e4-b93a-56a005e88bb7", "extension_<extensions-app-id>_CustomAttribute1": "custom attribute value", "extension_<extensions-app-id>_CustomAttribute2": "custom attribute value",
- "objectId": "ab3ec3b2-a435-45e4-b93a-56a005e88bb7",
"client_id": "231c70e8-8424-48ac-9b5d-5623b9e4ccf3", "step": "PreTokenIssuance", "ui_locales":"en-US"
active-directory-b2c Billing https://github.com/MicrosoftDocs/azure-docs/commits/master/articles/active-directory-b2c/billing.md
Previously updated : 05/28/2021 Last updated : 08/26/2021
Azure Active Directory B2C (Azure AD B2C) pricing is based on monthly active users (MAU), which is the count of unique users with authentication activity within a calendar month. This billing model applies to both Azure AD B2C tenants and [Azure AD guest user collaboration (B2B)](../active-directory/external-identities/external-identities-pricing.md). MAU billing helps you reduce costs by offering a free tier and flexible, predictable pricing. In this article, learn about MAU billing, linking your Azure AD B2C tenants to a subscription, and changing your pricing tier.
+## MAU overview
+
+A monthly active user (MAU) is a unique user that performs an authentication within a given month. A user that authenticates multiple times within a given month is counted as one MAU. Customers are not charged for a MAUΓÇÖs subsequent authentications during the month, nor for inactive users. Authentications may include:
+
+- Active, interactive sign-in by the user, for example through [sign-up or sign-in](add-sign-up-and-sign-in-policy.md), [self-service password reset](add-password-reset-policy.md), [profile editing](add-profile-editing-policy.md), or any type of [user flow](user-flow-overview.md) or [custom policy](custom-policy-overview.md).
+- Passive, non-interactive sign-in such as [single sign-on (SSO)](session-behavior.md), or any type of token acquisition, such as authorization code flow, token refresh, or [resource owner password credentials (ROPC)](add-ropc-policy.md).
+
+If you choose to provide higher levels of assurance using Multi-factor Authentication (MFA) for Voice and SMS, you will continue to be charged a worldwide flat fee for each MFA attempt that month, whether the sign-in is successful or unsuccessful.
+ > [!IMPORTANT] > This article does not contain pricing details. For the latest information about usage billing and pricing, see [Azure Active Directory B2C pricing](https://azure.microsoft.com/pricing/details/active-directory-b2c/). See also [Azure AD B2C region availability and data residency](data-residency.md) for details about where the Azure AD B2C service is available and where user data is stored.
If the source and destination subscriptions are associated with different Azure
## Next steps
-For the latest pricing information, see [Azure Active Directory B2C pricing](https://azure.microsoft.com/pricing/details/active-directory-b2c/).
+For the latest pricing information, see [Azure Active Directory B2C pricing](https://azure.microsoft.com/pricing/details/active-directory-b2c/).
active-directory-b2c Configure Authentication Sample Android App https://github.com/MicrosoftDocs/azure-docs/commits/master/articles/active-directory-b2c/configure-authentication-sample-android-app.md
Title: Configure authentication in a sample Android application using Azure Active Directory B2C
-description: Using Azure Active Directory B2C to sign in and sign up users in an Android application.
+ Title: Configure authentication in a sample Android application by using Azure Active Directory B2C
+description: This article discusses how to use Azure Active Directory B2C to sign in and sign up users in an Android application.
-# Configure authentication in a sample Android application using Azure Active Directory B2C
+# Configure authentication in a sample Android app by using Azure AD B2C
This article uses a sample Android application (Kotlin and Java) to illustrate how to add Azure Active Directory B2C (Azure AD B2C) authentication to your mobile apps. ## Overview
-OpenID Connect (OIDC) is an authentication protocol built on OAuth 2.0, which you can securely use to sign-in in a user to an application. This mobile app sample uses [MSAL](../active-directory/develop/msal-overview.md) library with OpenId Connect authorization code PKCE flow. The MSAL library is a Microsoft provided library that simplifies adding authentication and authorization support to mobile apps.
+OpenID Connect (OIDC) is an authentication protocol that's built on OAuth 2.0. You can use OIDC to securely sign users in to an application. This mobile app sample uses the [Microsoft Authentication Library (MSAL](../active-directory/develop/msal-overview.md) with OIDC authorization code PKCE flow. The MSAL is a Microsoft-provided library that simplifies adding authentication and authorization support to mobile apps.
-The sign-in flow involves following steps:
+The sign-in flow involves the following steps:
-1. The user opens the app and selects **sign-in**.
-1. The app opens the mobile device's system browser, and starts an authentication request to Azure AD B2C.
-1. The user [signs-up or signs-in](add-sign-up-and-sign-in-policy.md), [resets the password](add-password-reset-policy.md), or signs-in with a [social account](add-identity-provider.md).
-1. Upon successful sign-in, Azure AD B2C returns an authorization code to the app.
+1. Users open the app and select **sign-in**.
+1. The app opens the mobile device's system browser and starts an authentication request to Azure AD B2C.
+1. Users [sign up or sign in](add-sign-up-and-sign-in-policy.md), [reset the password](add-password-reset-policy.md), or sign in with a [social account](add-identity-provider.md).
+1. After users sign in successfully, Azure AD B2C returns an authorization code to the app.
1. The app takes the following actions:
- 1. Exchanges the authorization code to an ID token, access token and refresh token.
- 1. Reads the ID token claims.
- 1. Stores the tokens to an in-memory cache for later use.
+ 1. It exchanges the authorization code to an ID token, access token, and refresh token.
+ 1. It reads the ID token claims.
+ 1. It stores the tokens in an in-memory cache for later use.
### App registration overview To enable your app to sign in with Azure AD B2C and call a web API, register two applications in the Azure AD B2C directory. -- The **mobile application** registration enables your app to sign in with Azure AD B2C. During app registration, specify the *Redirect URI*. The redirect URI is the endpoint to which the user is redirected by Azure AD B2C after they authenticate with Azure AD B2C is completed. The app registration process generates an *Application ID*, also known as the *client ID*, that uniquely identifies your mobile app. For example, **App ID: 1**.
+- The **mobile application** registration enables your app to sign in with Azure AD B2C. During app registration, specify the *redirect URI*. The redirect URI is the endpoint to which users are redirected by Azure AD B2C after they've authenticated with Azure AD B2C. The app registration process generates an *Application ID*, also known as the *client ID*, which uniquely identifies your mobile app (for example, *App ID: 1*).
-- The **web API** registration enables your app to call a protected web API. The registration exposes the web API permissions (scopes). The app registration process generates an *Application ID*, that uniquely identifies your web API. For example, **App ID: 2**. Grant your mobile app (App ID: 1) permissions to the web API scopes (App ID: 2).
+- The **web API** registration enables your app to call a protected web API. The registration exposes the web API permissions (scopes). The app registration process generates an *Application ID*, which uniquely identifies your web API (for example, *App ID: 2*). Grant your mobile app (App ID: 1) permissions to the web API scopes (App ID: 2).
-The following diagrams describe the apps registration and the application architecture.
+The apps registration and application architecture are illustrated in the following diagrams:
-![Mobile app with web API call registrations and tokens](./media/configure-authentication-sample-android-app/mobile-app-with-api-architecture.png)
+![Diagram of the mobile app with web API call registrations and tokens.](./media/configure-authentication-sample-android-app/mobile-app-with-api-architecture.png)
### Call to a web API [!INCLUDE [active-directory-b2c-app-integration-call-api](../../includes/active-directory-b2c-app-integration-call-api.md)]
-### Sign-out
+### The sign-out flow
[!INCLUDE [active-directory-b2c-app-integration-sign-out-flow](../../includes/active-directory-b2c-app-integration-sign-out-flow.md)]
The following diagrams describe the apps registration and the application archit
A computer that's running: -- [Java Development Kit (JDK)](https://openjdk.java.net/) 8, or above.
+- [Java Development Kit (JDK) 8 or later](https://openjdk.java.net/)
- [Apache Maven](https://maven.apache.org/)-- [Android API Level 16](https://developer.android.com/studio/releases/platforms), or above.-- [Android studio](https://developer.android.com/studio), or another code editor.
+- [Android API level 16 or later](https://developer.android.com/studio/releases/platforms)
+- [Android Studio](https://developer.android.com/studio) or another code editor
## Step 1: Configure your user flow
A computer that's running:
## Step 2: Register mobile applications
-In this step, create the mobile app and the web API application registration, and specify the scopes of your web API.
+Create the mobile app and web API application registration, and specify the scopes of your web API.
-### 2.1 Register the web API app
+### Step 2.1: Register the web API app
[!INCLUDE [active-directory-b2c-app-integration-register-api](../../includes/active-directory-b2c-app-integration-register-api.md)]
-### 2.2 Configure web API app scopes
+### Step 2.2: Configure web API app scopes
[!INCLUDE [active-directory-b2c-app-integration-api-scopes](../../includes/active-directory-b2c-app-integration-api-scopes.md)]
-### 2.3 Register the mobile app
+### Step 2.3: Register the mobile app
-Follow these steps to create the mobile app registration:
+To create the mobile app registration, do the following:
+1. Sign in to the [Azure portal](https://portal.azure.com).
1. Select **App registrations**, and then select **New registration**.
-1. Enter a **Name** for the application. For example, *android-app1*.
+1. Under **Name**, enter a name for the application (for example, *android-app1*).
1. Under **Supported account types**, select **Accounts in any identity provider or organizational directory (for authenticating users with user flows)**.
-1. Under **Redirect URI**, select **Public client/native (mobile & desktop)**, and then in the URL text box, enter one of the following URIs:
+1. Under **Redirect URI**, select **Public client/native (mobile & desktop)** and then, in the URL box, enter one of the following URIs:
- For the Kotlin sample: `msauth://com.azuresamples.msalandroidkotlinapp/1wIqXSqBj7w%2Bh11ZifsnqwgyKrY%3D` - For the Java sample: `msauth://com.azuresamples.msalandroidapp/1wIqXSqBj7w%2Bh11ZifsnqwgyKrY%3D` 1. Select **Register**. 1. After the app registration is completed, select **Overview**.
-1. Record the **Application (client) ID** for use in a later step when you configure the mobile application.
+1. Record the **Application (client) ID** for later use, when you configure the mobile application.
- ![Get your mobile application ID](./media/configure-authentication-sample-android-app/get-azure-ad-b2c-app-id.png)
+ ![Screenshot highlighting the Android application ID](./media/configure-authentication-sample-android-app/get-azure-ad-b2c-app-id.png)
-### 2.4 Grant the mobile app permissions for the web API
+### Step 2.4: Grant the mobile app permissions for the web API
[!INCLUDE [active-directory-b2c-app-integration-grant-permissions](../../includes/active-directory-b2c-app-integration-grant-permissions.md)] ## Step 3: Get the Android mobile app sample
-Download one of the following samples: [Kotlin](https://github.com/Azure-Samples/ms-identity-android-kotlin/archive/refs/heads/master.zip), or [Java](https://github.com/Azure-Samples/ms-identity-android-java/archive/refs/heads/master.zip). Extract the sample ZIP file to your working folder.
+Do either of the following:
-Or clone the sample Android mobile application from GitHub.
+- Download either of these samples:
+ - [Kotlin](https://github.com/Azure-Samples/ms-identity-android-kotlin/archive/refs/heads/master.zip)
+ - [Java](https://github.com/Azure-Samples/ms-identity-android-java/archive/refs/heads/master.zip)
-#### [Kotlin](#tab/kotlin)
+ Extract the sample .zip file to your working folder.
+- Clone the sample Android mobile application from GitHub.
-```bash
-git clone https://github.com/Azure-Samples/ms-identity-android-kotlin
-```
+ #### [Kotlin](#tab/kotlin)
-#### [Java](#tab/java)
-```bash
-git clone https://github.com/Azure-Samples/ms-identity-android-java
-```
+ ```bash
+ git clone https://github.com/Azure-Samples/ms-identity-android-kotlin
+ ```
-
+ #### [Java](#tab/java)
+
+ ```bash
+ git clone https://github.com/Azure-Samples/ms-identity-android-java
+ ```
+
+
## Step 4: Configure the sample web API
-This sample acquires an access token with the relevant scopes the mobile app can use to for a web API. To call a web API from code, follow these steps:
+This sample acquires an access token with the relevant scopes that the mobile app can use for a web API. To call a web API from code, do the following:
-1. Use an existing web API, or create a new one. For more information, see [Enable authentication in your own web API using Azure AD B2C](enable-authentication-web-api.md).
-1. Change the sample code to [call a web API](enable-authentication-android-app.md#call-a-web-api).
+1. Use an existing web API, or create a new one. For more information, see [Enable authentication in your own web API by using Azure AD B2C](enable-authentication-web-api.md).
+1. Change the sample code to [call a web API](enable-authentication-android-app.md#step-6-call-a-web-api).
## Step 5: Configure the sample mobile app
-Open the sample project with Android Studio, or other code editor. Then open the `/app/src/main/res/raw/auth_config_b2c.json` file.
+Open the sample project with Android Studio or another code editor, and then open the */app/src/main/res/raw/auth_config_b2c.json* file.
-The *auth_config_b2c.json* configuration file contains information about your Azure AD B2C identity provider. The mobile app uses this information to establish a trust relationship with Azure AD B2C, sign-in the user in and out, acquire tokens, and validate them.
+The *auth_config_b2c.json* configuration file contains information about your Azure AD B2C identity provider. The mobile app uses this information to establish a trust relationship with Azure AD B2C, sign users in and out, acquire tokens, and validate them.
-Update the following properties of the app settings:
+Update the following app settings properties:
|Key |Value | |||
-| [client_id](../active-directory/develop/msal-client-application-configuration.md#client-id) | The mobile application ID from [step 2.3](#23-register-the-mobile-app). |
-| [redirect_uri](../active-directory/develop/msal-client-application-configuration.md#redirect-uri) | The mobile application redirect URI from [step 2.3](#23-register-the-mobile-app). |
-| [authorities](../active-directory/develop/msal-client-application-configuration.md#authority)| The authority is a URL that indicates a directory that MSAL can request tokens from. Use the following format: `https://<your-tenant-name>.b2clogin.com/<your-tenant-name>.onmicrosoft.com/<your-sign-in-sign-up-policy>`. Replace the `<your-tenant-name>` with your Azure AD B2C [tenant name](tenant-management.md#get-your-tenant-name). Then, replace the `<your-sign-in-sign-up-policy>` with the user flows, or custom policy you created in [step 1](#step-1-configure-your-user-flow). |
+| [client_id](../active-directory/develop/msal-client-application-configuration.md#client-id) | The mobile application ID from [step 2.3](#step-23-register-the-mobile-app). |
+| [redirect_uri](../active-directory/develop/msal-client-application-configuration.md#redirect-uri) | The mobile application redirect URI from [step 2.3](#step-23-register-the-mobile-app). |
+| [authorities](../active-directory/develop/msal-client-application-configuration.md#authority)| The authority is a URL that indicates a directory that the MSAL can request tokens from. Use the following format: `https://<your-tenant-name>.b2clogin.com/<your-tenant-name>.onmicrosoft.com/<your-sign-in-sign-up-policy>`. Replace `<your-tenant-name>` with your Azure AD B2C [tenant name](tenant-management.md#get-your-tenant-name). Then, replace `<your-sign-in-sign-up-policy>` with the user flows or custom policy that you created in [step 1](#step-1-configure-your-user-flow). |
+| | |
-Open the `B2CConfiguration` class, and update the following class members:
+Open the `B2CConfiguration` class, and update the following class members:
|Key |Value | |||
-| Policies| List of the user flows, or custom policies you created in [step 1](#step-1-configure-your-user-flow).|
-| azureAdB2CHostName| The first part of your Azure AD B2C [tenant name](tenant-management.md#get-your-tenant-name). For example, `https://contoso.b2clogin.com`.|
-| tenantName| Your Azure AD B2C tenant full [tenant name](tenant-management.md#get-your-tenant-name). For example, `contoso.onmicrosoft.com`.|
-| scopes| The web API scopes you created in [step 2.4](#24-grant-the-mobile-app-permissions-for-the-web-api).|
+| Policies| The list of user flows or custom policies that you created in [step 1](#step-1-configure-your-user-flow).|
+| azureAdB2CHostName| The first part of your Azure AD B2C [tenant name](tenant-management.md#get-your-tenant-name) (for example, `https://contoso.b2clogin.com`).|
+| tenantName| Your Azure AD B2C tenant full [tenant name](tenant-management.md#get-your-tenant-name) (for example, `contoso.onmicrosoft.com`).|
+| scopes| The web API scopes that you created in [step 2.4](#step-24-grant-the-mobile-app-permissions-for-the-web-api).|
+| | |
## Step 6: Run and test the mobile app 1. Build and run the project.
-1. Select the hamburger icon.
+1. At the top left, select the hamburger icon (also called the collapsed menu icon), as shown here:
- ![Screenshot demonstrate how to select the hamburger icon.](./media/configure-authentication-sample-android-app/select-hamburger-icon.png)
+ ![Screenshot highlighting the hamburger, or collapsed menu, icon.](./media/configure-authentication-sample-android-app/select-hamburger-icon.png)
-1. Select **B2C mode**.
+1. On the left pane, select **B2C Mode**.
- ![Screenshot demonstrate how to select B2C mode.](./media/configure-authentication-sample-android-app/select-azure-ad-b2c-mode.png)
+ ![Screenshot highlighting the "B2C Mode" command on the left pane.](./media/configure-authentication-sample-android-app/select-azure-ad-b2c-mode.png)
-1. Select **RUN USER FLOW**.
+1. Select **Run User Flow**.
- ![Screenshot demonstrate how to start the sign-in flow.](./media/configure-authentication-sample-android-app/select-policy-and-sign-in.png)
+ ![Screenshot highlighting the "Run User Flow" button.](./media/configure-authentication-sample-android-app/select-policy-and-sign-in.png)
-1. Sign-up or sign-in with your Azure AD B2C local or social account.
+1. Sign up or sign in with your Azure AD B2C local or social account.
-1. After successful authentication, you'll see your display name in the navigation bar.
+1. After successful authentication, you'll see your display name on the **B2C mode** pane.
- ![Azure AD B2C access token and user ID.](./media/configure-authentication-sample-android-app/access-token.png)
+ ![Screenshot showing a successful authentication, with signed-in user and policy displayed.](./media/configure-authentication-sample-android-app/access-token.png)
## Next steps
-* Learn how to [Enable authentication in your own Android application](enable-authentication-android-app.md)
-* [Configure authentication options in an Android application](enable-authentication-android-app-options.md)
+Learn how to:
+* [Enable authentication in your own Android app](enable-authentication-android-app.md)
+* [Configure authentication options in an Android app](enable-authentication-android-app-options.md)
* [Enable authentication in your own web API](enable-authentication-web-api.md)
active-directory-b2c Configure Authentication Sample Ios App https://github.com/MicrosoftDocs/azure-docs/commits/master/articles/active-directory-b2c/configure-authentication-sample-ios-app.md
Title: Configure authentication in a sample iOS Swift application using Azure Active Directory B2C
-description: Using Azure Active Directory B2C to sign in and sign up users in an iOS Swift application.
+ Title: Configure authentication in a sample iOS Swift application by using Azure Active Directory B2C
+description: This article discusses how to use Azure Active Directory B2C to sign in and sign up users in an iOS Swift application.
-# Configure authentication in a sample iOS Swift application using Azure Active Directory B2C
+# Configure authentication in a sample iOS Swift app by using Azure AD B2C
This article uses a sample [iOS Swift](https://developer.apple.com/swift/) application to illustrate how to add Azure Active Directory B2C (Azure AD B2C) authentication to your mobile apps. ## Overview
-OpenID Connect (OIDC) is an authentication protocol built on OAuth 2.0, which you can securely use to sign-in in a user to an application. This mobile app sample uses [MSAL](../active-directory/develop/msal-overview.md) library with OpenId Connect authorization code PKCE flow. The MSAL library is a Microsoft provided library that simplifies adding authentication and authorization support to mobile apps.
+OpenID Connect (OIDC) is an authentication protocol that's built on OAuth 2.0. You can use OIDC to securely sign users in to an application. This mobile app sample uses the [Microsoft Authentication Library (MSAL)](../active-directory/develop/msal-overview.md) with OIDC authorization code Proof Key for Code Exchange (PKCE) flow. The MSAL is a Microsoft-provided library that simplifies adding authentication and authorization support to mobile apps.
-The sign-in flow involves following steps:
+The sign-in flow involves the following steps:
-1. The user opens the app and selects **sign-in**.
-1. The app opens the mobile device's system browser, and starts an authentication request to Azure AD B2C.
-1. The user [signs up or signs in](add-sign-up-and-sign-in-policy.md), [resets the password](add-password-reset-policy.md), or signs in with a [social account](add-identity-provider.md).
-1. Upon successful sign-in, Azure AD B2C returns an authorization code to the app.
+1. Users open the app and select **sign-in**.
+1. The app opens the mobile device's system browser and starts an authentication request to Azure AD B2C.
+1. Users [sign up or sign in](add-sign-up-and-sign-in-policy.md), [reset the password](add-password-reset-policy.md), or sign in with a [social account](add-identity-provider.md).
+1. After users sign in successfully, Azure AD B2C returns an authorization code to the app.
1. The app takes the following actions:
- 1. Exchanges the authorization code for an ID token, access token and refresh token.
- 1. Reads the ID token claims.
- 1. Stores the tokens to an in-memory cache for later use.
+ 1. It exchanges the authorization code to an ID token, access token, and refresh token.
+ 1. It reads the ID token claims.
+ 1. It stores the tokens in an in-memory cache for later use.
### App registration overview
-To enable your app to sign in with Azure AD B2C and call a web API, register two applications in the Azure AD B2C directory.
+To enable your app to sign in with Azure AD B2C and call a web API, register two applications in the Azure AD B2C directory:
-- The **mobile application** registration enables your app to sign in with Azure AD B2C. During app registration, specify the *Redirect URI*. The redirect URI is the endpoint to which the user is redirected by Azure AD B2C after they authenticate with Azure AD B2C. The app registration process generates an *Application ID*, also known as the *client ID*, that uniquely identifies your mobile app. For example, **App ID: 1**.
+- The **mobile application** registration enables your app to sign in with Azure AD B2C. During app registration, specify the *redirect URI*. The redirect URI is the endpoint to which users are redirected by Azure AD B2C after they've authenticated with Azure AD B2C. The app registration process generates an *application ID*, also known as the *client ID*, which uniquely identifies your mobile app (for example, *App ID: 1*).
-- The **web API** registration enables your app to call a protected web API. The registration exposes the web API permissions (scopes). The app registration process generates an *Application ID* that uniquely identifies your web API. For example, **App ID: 2**. Grant your mobile app (App ID: 1) permissions to the web API scopes (App ID: 2).
+- The **web API** registration enables your app to call a protected web API. The registration exposes the web API permissions (scopes). The app registration process generates an *application ID*, which uniquely identifies your web API (for example, *App ID: 2*). Grant your mobile app (App ID: 1) permissions to the web API scopes (App ID: 2).
-The following diagrams describe the apps registration and the application architecture.
+The application registration and architecture are illustrated in the following diagrams:
-![Diagram describes a mobile app with web API, registrations and tokens.](./media/configure-authentication-sample-ios-app/mobile-app-with-api-architecture.png)
+![Diagram of the mobile app with web API call registrations and tokens.](./media/configure-authentication-sample-ios-app/mobile-app-with-api-architecture.png)
### Call to a web API [!INCLUDE [active-directory-b2c-app-integration-call-api](../../includes/active-directory-b2c-app-integration-call-api.md)]
-### Sign-out
+### The sign-out flow
[!INCLUDE [active-directory-b2c-app-integration-sign-out-flow](../../includes/active-directory-b2c-app-integration-sign-out-flow.md)]
The following diagrams describe the apps registration and the application archit
A computer that's running: -- [Xcode](https://developer.apple.com/xcode/) 13, or above.
+- [Xcode 13 or later](https://developer.apple.com/xcode/).
- [CocoaPods](https://cocoapods.org/) dependency manager for Swift and Objective-C Cocoa projects.
A computer that's running:
## Step 2: Register mobile applications
-In this step, create the mobile app and the web API application registration, and specify the scopes of your web API.
+Create the mobile app and the web API application registration, and specify the scopes of your web API.
-### 2.1 Register the web API app
+### Step 2.1: Register the web API app
[!INCLUDE [active-directory-b2c-app-integration-register-api](../../includes/active-directory-b2c-app-integration-register-api.md)]
-### 2.2 Configure web API app scopes
+### Step 2.2: Configure web API app scopes
[!INCLUDE [active-directory-b2c-app-integration-api-scopes](../../includes/active-directory-b2c-app-integration-api-scopes.md)]
-### 2.3 Register the mobile app
+### Step 2.3: Register the mobile app
-Follow these steps to create the mobile app registration:
+To create the mobile app registration, do the following:
+1. Sign in to the [Azure portal](https://portal.azure.com).
1. Select **App registrations**, and then select **New registration**.
-1. Enter a **Name** for the application. For example, *iOs-app1*.
+1. Under **Name**, enter a name for the application (for example, *iOs-app1*).
1. Under **Supported account types**, select **Accounts in any identity provider or organizational directory (for authenticating users with user flows)**.
-1. Under **Redirect URI**, select **Public client/native (mobile & desktop)**, and then enter: `msauth.com.microsoft.identitysample.MSALiOS://auth`.
+1. Under **Redirect URI**, select **Public client/native (mobile & desktop)** and then, in the URL box, enter `msauth.com.microsoft.identitysample.MSALiOS://auth`.
1. Select **Register**. 1. After the app registration is completed, select **Overview**.
-1. Record the **Application (client) ID** for use in a later step when you configure the mobile application.
- ![Screenshot showing how to get the mobile application ID.](./media/configure-authentication-sample-ios-app/get-azure-ad-b2c-app-id.png)
+1. Record the **Application (client) ID** for later use, when you configure the mobile application.
+ ![Screenshot highlighting the mobile application ID.](./media/configure-authentication-sample-ios-app/get-azure-ad-b2c-app-id.png)
-### 2.4 Grant the mobile app permissions for the web API
+### Step 2.4: Grant the mobile app permissions for the web API
[!INCLUDE [active-directory-b2c-app-integration-grant-permissions](../../includes/active-directory-b2c-app-integration-grant-permissions.md)] ## Step 3: Configure the sample web API
-This sample acquires an access token with the relevant scopes the mobile app can use for a web API. To call a web API from code, follow these steps:
+This sample acquires an access token with the relevant scopes that the mobile app can use for a web API. To call a web API from code, do the following:
-1. Use an existing web API, or create a new one. For more information, see [Enable authentication in your own web API using Azure AD B2C](enable-authentication-web-api.md).
-1. Change the sample code to [call a web API](enable-authentication-iOs-app.md#call-a-web-api).
-
-After you configure the web API, copy the URI of the web API endpoint. You will use the web API endpoint in the next steps.
+1. Use an existing web API, or create a new one. For more information, see [Enable authentication in your own web API by using Azure AD B2C](enable-authentication-web-api.md).
+1. Change the sample code to [call a web API](enable-authentication-iOs-app.md#step-63-call-a-web-api).
+1. After you configure the web API, copy the URI of the web API endpoint. You will use the web API endpoint in the next steps.
> [!TIP] > If you don't have a web API, you can still run this sample. In this case, the app returns the access token but won't be able to call the web API. ## Step 4: Get the iOS mobile app sample
-1. [Download the zip file](https://github.com/Azure-Samples/active-directory-b2c-ios-swift-native-msal/archive/refs/heads/vNext.zip), or clone the sample web application from [GitHub repo](https://github.com/Azure-Samples/active-directory-b2c-ios-swift-native-msal).
+1. [Download the .zip file](https://github.com/Azure-Samples/active-directory-b2c-ios-swift-native-msal/archive/refs/heads/vNext.zip), or clone the sample web app from the [GitHub repo](https://github.com/Azure-Samples/active-directory-b2c-ios-swift-native-msal).
```bash git clone https://github.com/Azure-Samples/active-directory-b2c-ios-swift-native-msal/tree/vNext.git ```
-1. Use [CocoaPods](https://cocoapods.org/) to install the MSAL library. In a terminal window, navigate to the project root folder. This folder contains the `podfile`. Run the following command:
+1. Use [CocoaPods](https://cocoapods.org/) to install the MSAL library. In a terminal window, go to the project root folder. This folder contains the *podfile* file. Run the following command:
```bash pod install ```
-1. Open `MSALiOS.xcworkspace` workspace with Xcode.
+1. Open the `MSALiOS.xcworkspace` workspace with Xcode.
## Step 5: Configure the sample mobile app
-Open the `ViewController.swift` file. The `ViewController` class members contain information about your Azure AD B2C identity provider. The mobile app uses this information to establish a trust relationship with Azure AD B2C, sign the user in and out, acquire tokens, and validate them.
+Open the *ViewController.swift* file. The `ViewController` class members contain information about your Azure AD B2C identity provider. The mobile app uses this information to establish a trust relationship with Azure AD B2C, sign users in and out, acquire tokens, and validate them.
-Update the following members:
+Update the following class members:
|Key |Value | |||
-|kTenantName| Your Azure AD B2C tenant full [tenant name](tenant-management.md#get-your-tenant-name). For example, `contoso.onmicrosoft.com`.|
-|kAuthorityHostName|The first part of your Azure AD B2C [tenant name](tenant-management.md#get-your-tenant-name). For example, `contoso.b2clogin.com`.|
-|kClientID|The mobile application ID from [step 2.3](#23-register-the-mobile-app).|
-|kRedirectUri|The mobile application redirect URI from [step 2.3](#23-register-the-mobile-app), `msauth.com.microsoft.identitysample.MSALiOS://auth`.|
+|kTenantName| Your Azure AD B2C tenant full [tenant name](tenant-management.md#get-your-tenant-name) (for example, `contoso.onmicrosoft.com`).|
+|kAuthorityHostName|The first part of your Azure AD B2C [tenant name](tenant-management.md#get-your-tenant-name) (for example, `contoso.b2clogin.com`).|
+|kClientID|The mobile application ID from [step 2.3](#step-23-register-the-mobile-app).|
+|kRedirectUri|The mobile application redirect URI from [step 2.3](#step-23-register-the-mobile-app), `msauth.com.microsoft.identitysample.MSALiOS://auth`.|
|kSignupOrSigninPolicy| The sign-up or sign-in user flow or custom policy you created in [step 1](#step-1-configure-your-user-flow).| |kEditProfilePolicy|The edit profile user flow or custom policy you created in [step 1](#step-1-configure-your-user-flow).|
-|kGraphURI| (Optional) the web API endpoint you created in [Step 3](#step-3-configure-the-sample-web-api). For example, `https://contoso.azurewebsites.net/hello`.|
-| kScopes | The web API scopes you created in [step 2.4](#24-grant-the-mobile-app-permissions-for-the-web-api).|
+|kGraphURI| (Optional) The web API endpoint that you created in [step 3](#step-3-configure-the-sample-web-api) (for example, `https://contoso.azurewebsites.net/hello`).|
+| kScopes | The web API scopes that you created in [step 2.4](#step-24-grant-the-mobile-app-permissions-for-the-web-api).|
+| | |
Update the following members:
1. Build and run the project with a [simulator of a connected iOS device](https://developer.apple.com/documentation/xcode/running-your-app-in-the-simulator-or-on-a-device).
-1. Select **Sign In**. Then sign up or sign in with your Azure AD B2C local or social account.
+1. Select **Sign In**, and then sign up or sign in with your Azure AD B2C local or social account.
- ![Screenshot demonstrates how to start the sign-in flow.](./media/configure-authentication-sample-ios-app/sign-in.png)
+ ![Screenshot highlighting how to start the sign-in flow.](./media/configure-authentication-sample-ios-app/sign-in.png)
1. After successful authentication, you'll see your display name in the navigation bar.
- ![Screenshot showing the Azure AD B2C access token and user ID.](./media/configure-authentication-sample-ios-app/post-sign-in.png)
+ ![Screenshot highlighting the Azure AD B2C access token and user ID.](./media/configure-authentication-sample-ios-app/post-sign-in.png)
## Next steps
-* Learn how to [Enable authentication in your own iOS application](enable-authentication-ios-app.md)
-* [Configure authentication options in an iOS application](enable-authentication-ios-app-options.md)
-* [Enable authentication in your own web API](enable-authentication-web-api.md)
+Learn how to:
+* [Enable authentication in your own iOS app by using Azure AD B2C](enable-authentication-ios-app.md)
+* [Configure authentication options in an iOS app by using Azure AD B2C](enable-authentication-ios-app-options.md)
+* [Enable authentication in your own web API by using Azure AD B2C](enable-authentication-web-api.md)
active-directory-b2c Configure Authentication Sample Python Web App https://github.com/MicrosoftDocs/azure-docs/commits/master/articles/active-directory-b2c/configure-authentication-sample-python-web-app.md
Title: Configure authentication in a sample Python web application using Azure Active Directory B2C
-description: Using Azure Active Directory B2C to sign in and sign up users in a Python web application.
+ Title: Configure authentication in a sample Python web application by using Azure Active Directory B2C
+description: This article discusses how to use Azure Active Directory B2C to sign in and sign up users in a Python web application.
-# Configure authentication in a sample Python web application using Azure Active Directory B2C
+# Configure authentication in a sample Python web app by using Azure AD B2C
This article uses a sample Python web application to illustrate how to add Azure Active Directory B2C (Azure AD B2C) authentication to your web applications. - ## Overview
-OpenID Connect (OIDC) is an authentication protocol built on OAuth 2.0 that you can use to securely sign a user in to an application. This web app sample uses [MSAL for Python](https://github.com/AzureAD/microsoft-authentication-library-for-python). The MSAL for Python simplifies adding authentication and authorization support to Python web apps.
+OpenID Connect (OIDC) is an authentication protocol that's built on OAuth 2.0. You can use OIDC to securely sign users in to an application. This web app sample uses the [Microsoft Authentication Library (MSAL) for Python](https://github.com/AzureAD/microsoft-authentication-library-for-python). The MSAL for Python simplifies adding authentication and authorization support to Python web apps.
-The sign-in flow involves following steps:
+The sign-in flow involves the following steps:
-1. User navigates to the web app and select **Sign-in**.
-1. The app initiates authentication request, and redirects the user to Azure AD B2C.
-1. The user [sign-up or sign-in](add-sign-up-and-sign-in-policy.md), [reset the password](add-password-reset-policy.md), or sign-in with a [social account](add-identity-provider.md).
-1. Upon successful sign-in, Azure AD B2C returns an ID token to the app.
-1. The app exchanges the authorization code to an ID token. Then validates the ID token, reads the claims, and returns a secure page to the user.
+1. Users go to the web app and select **Sign-in**.
+1. The app initiates an authentication request and redirects users to Azure AD B2C.
+1. Users [sign up or sign in](add-sign-up-and-sign-in-policy.md), [reset the password](add-password-reset-policy.md), or sign in with a [social account](add-identity-provider.md).
+1. After users sign in successfully, Azure AD B2C returns an ID token to the app.
+1. The app exchanges the authorization code with an ID token, validates the ID token, reads the claims, and then returns a secure page to users.
### Sign-out
The sign-in flow involves following steps:
## Prerequisites
-A computer that's running either:
+A computer that's running:
* [Visual Studio Code](https://code.visualstudio.com/) or another code editor * [Python](https://nodejs.org/en/download/) 2.7+ or 3+
A computer that's running either:
To enable your application to sign in with Azure AD B2C, register your app in the Azure AD B2C directory. Registering your app establishes a trust relationship between the app and Azure AD B2C.
-During app registration, you'll specify the **Redirect URI**. The redirect URI is the endpoint to which the user is redirected by Azure AD B2C after they authenticate with Azure AD B2C. The app registration process generates an **Application ID**, also known as the **client ID**, that uniquely identifies your app. Once your app is registered, Azure AD B2C will use both the application ID and redirect URI to create authentication requests.
+During app registration, you'll specify the *Redirect URI*. The redirect URI is the endpoint to which users are redirected by Azure AD B2C after they authenticate with Azure AD B2C. The app registration process generates an *Application ID*, also known as the *client ID*, that uniquely identifies your app. After your app is registered, Azure AD B2C uses both the application ID and the redirect URI to create authentication requests.
-### 2.1 Register the app
+### Step 2.1: Register the app
-Follow these steps to create the app registration:
+To create the web app registration, do the following:
1. Sign in to the [Azure portal](https://portal.azure.com). 1. Select the **Directory + Subscription** icon in the portal toolbar, and then select the directory that contains your Azure AD B2C tenant.
-1. In the Azure portal, search for and select **Azure AD B2C**.
+1. Search for and select **Azure AD B2C**.
1. Select **App registrations**, and then select **New registration**.
-1. Enter a **Name** for the application. For example, *webapp1*.
+1. Under **Name**, enter a name for the application (for example, *webapp1*).
1. Under **Supported account types**, select **Accounts in any identity provider or organizational directory (for authenticating users with user flows)**.
-1. Under **Redirect URI**, select **Web**, and then enter `http://localhost:5000/getAToken` in the URL text box.
-1. Under **Permissions**, select the **Grant admin consent to openid and offline access permissions** check box.
+1. Under **Redirect URI**, select **Web** and then, in the URL box, enter `http://localhost:5000/getAToken`.
+1. Under **Permissions**, select the **Grant admin consent to openid and offline access permissions** checkbox.
1. Select **Register**. 1. Select **Overview**.
-1. Record the **Application (client) ID** for use in a later step when you configure the web application.
+1. Record the **Application (client) ID** for later use, when you configure the web application.
- ![Get your application ID](./media/configure-authentication-sample-python-web-app/get-azure-ad-b2c-app-id.png)
+ ![Screenshot of the web app Overview page for recording your web app ID.](./media/configure-authentication-sample-python-web-app/get-azure-ad-b2c-app-id.png)
-### 2.2 Create a web app client secret
+### Step 2.2: Create a web app client secret
[!INCLUDE [active-directory-b2c-app-integration-client-secret](../../includes/active-directory-b2c-app-integration-client-secret.md)]
Follow these steps to create the app registration:
git clone https://github.com/Azure-Samples/ms-identity-python-webapp.git ```
-Extract the sample file to a folder where the total character length of the path is less than 260.
+Extract the sample file to a folder where the total length of the path is 260 or fewer characters.
-## Step 4: Configure the sample application
+## Step 4: Configure the sample web app
-In the project's root directory:
+In the project's root directory, do the following:
-1. Rename the *app_config.py* file to *app_config.py.OLD*
-1. Rename the *app_config_b2c.py* to *app_config.py*
+1. Rename the *app_config.py* file to *app_config.py.OLD*.
+1. Rename the *app_config_b2c.py* file to *app_config.py*.
-Open the *app_config.py* file. This file contains information about your Azure AD B2C identity provider. Update the following properties of the app settings:
+Open the *app_config.py* file. This file contains information about your Azure AD B2C identity provider. Update the following app settings properties:
|Key |Value | |||
-|`b2c_tenant`| The first part of your Azure AD B2C [tenant name](tenant-management.md#get-your-tenant-name). For example, `contoso`.|
-|`CLIENT_ID`| The web API application ID from [step 2.1](#21-register-the-app).|
-|`CLIENT_SECRET`| The client secret you created in [step 2.2](#22-create-a-web-app-client-secret). For increased security, considering storing it instead in an environment variable as recommended in the comments. |
-|`*_user_flow`|The user flows, or custom policy you created in [step 1](#step-1-configure-your-user-flow).|
+|`b2c_tenant`| The first part of your Azure AD B2C [tenant name](tenant-management.md#get-your-tenant-name) (for example, `contoso`).|
+|`CLIENT_ID`| The web API application ID from [step 2.1](#step-21-register-the-app).|
+|`CLIENT_SECRET`| The client secret you created in [step 2.2](#step-22-create-a-web-app-client-secret). To help increase security, consider storing it instead in an environment variable, as recommended in the comments. |
+|`*_user_flow`|The user flows or custom policy you created in [step 1](#step-1-configure-your-user-flow).|
+| | |
Your final configuration file should look like the following Python code:
CLIENT_ID = "11111111-1111-1111-1111-111111111111" # Application (client) ID of
CLIENT_SECRET = "xxxxxxxxxxxxxxxxxxxxxxxx" # Placeholder - for use ONLY during testing. ```
-> [!WARNING]
-> As noted in the code snippet comments, we recommend you **do not store secrets in plaintext** in your application code. The hardcoded variable is used in the code sample for *convenience only*. Consider using an environment variable or a secret store like Azure Key Vault.
+> [!IMPORTANT]
+> As noted in the code snippet comments, we recommend that you *do not store secrets in plaintext* in your application code. The hard-coded variable is used in the code sample *for convenience only*. Consider using an environment variable or a secret store, such as an Azure key vault.
-## Step 5: Run the sample application
+## Step 5: Run the sample web app
-1. In your console or terminal, switch to the directory containing the sample. For example:
+1. In your console or terminal, switch to the directory that contains the sample. For example:
```console cd ms-identity-python-webapp ```
-1. Run the following commands to install the required packages from PyPi and run the web app on your local machine:
+1. Install the required packages from PyPi and run the web app on your local machine by running the following commands:
```console pip install -r requirements.txt
CLIENT_SECRET = "xxxxxxxxxxxxxxxxxxxxxxxx" # Placeholder - for use ONLY during t
```
-1. Browse to http://localhost:5000 to view the web application running on your local machine.
+1. To view the web application running on your local machine, go to [http://localhost:5000](http://localhost:5000).
1. Select **Sign In**.
- ![Screenshot shows the sign-in with Azure AD B2C.](./media/configure-authentication-sample-python-web-app/web-app-sign-in.png)
+ ![Screenshot showing the sign-in with Azure AD B2C.](./media/configure-authentication-sample-python-web-app/web-app-sign-in.png)
1. Complete the sign-up or sign-in process.
-1. After successful authentication, you'll see your display name in.
+1. After successful authentication, you'll see your display name, as shown here:
- ![Screenshot demonstrates the web app token's display name claim.](./media/configure-authentication-sample-python-web-app/web-app-token-claims.png)
+ ![Screenshot showing the web app token's display name claim.](./media/configure-authentication-sample-python-web-app/web-app-token-claims.png)
-## Call to a web API
+## Step 6: Call to a web API
To enable your app to sign in with Azure AD B2C and call a web API, you must register two applications in the Azure AD B2C directory. - The **web application** (Python) registration you already created in [Step 2](#step-2-register-a-web-application). This app registration enables your app to sign in with Azure AD B2C. The app registration process generates an *Application ID*, also known as the *client ID*, that uniquely identifies your app. For example, **App ID: 1**. -- The **web API** registration enables your app to call a protected web API. The registration exposes the web API permissions (scopes). The app registration process generates an *Application ID* that uniquely identifies your web API. For example, **App ID: 2**. Grant your app (App ID: 1) permissions to the web API scopes (App ID: 2).
+- The **web API** registration enables your app to call a protected web API. The registration exposes the web API permissions (scopes). The app registration process generates an *Application ID* that uniquely identifies your web API (for example, *App ID: 2*). Grant your app (App ID: 1) permissions to the web API scopes (App ID: 2).
-The following diagrams describe the app registrations and the application architecture.
+The app registrations and the application architecture are described in the following diagrams:
-![Diagram describes a web app with web API, registrations and tokens.](./media/configure-authentication-sample-python-web-app/web-app-with-api-architecture.png)
+![Diagram describing a web app with web API, registrations, and tokens.](./media/configure-authentication-sample-python-web-app/web-app-with-api-architecture.png)
[!INCLUDE [active-directory-b2c-app-integration-call-api](../../includes/active-directory-b2c-app-integration-call-api.md)]
-### Register the web API application
+### Step 6.1: Register the web API app
[!INCLUDE [active-directory-b2c-app-integration-register-api](../../includes/active-directory-b2c-app-integration-register-api.md)]
-### Configure scopes
+### Step 6.2: Configure scopes
[!INCLUDE [active-directory-b2c-app-integration-api-scopes](../../includes/active-directory-b2c-app-integration-api-scopes.md)]
-### Grant the web app permissions
+### Step 6.3: Grant the web app permissions
[!INCLUDE [active-directory-b2c-app-integration-grant-permissions](../../includes/active-directory-b2c-app-integration-grant-permissions.md)]
-### Configure your web API
+### Step 6.4: Configure your web API
-This sample acquires an access token with the relevant scopes the web app can use to for a web API. To call a web API from code, use an existing web API, or create a new one. For more information, see [Enable authentication in your own web API using Azure AD B2C](enable-authentication-web-api.md).
+This sample acquires an access token with the relevant scopes, which the web app can use for a web API. To call a web API from the code, use an existing web API or create a new one. For more information, see [Enable authentication in your own web API by using Azure AD B2C](enable-authentication-web-api.md).
-### Configure the sample application with the web API
+### Step 6.5: Configure the sample app with the web API
Open the *app_config.py* file. This file contains information about your Azure AD B2C identity provider. Update the following properties of the app settings: |Key |Value | |||
-|`ENDPOINT`| The URI of your web API. For example, https://localhost:44332/hello.|
-|`SCOPE`| The web API [scopes](#configure-scopes) you created.|
+|`ENDPOINT`| The URI of your web API (for example, https://localhost:44332/hello).|
+|`SCOPE`| The web API [scopes](#step-62-configure-scopes) that you created.|
+| | |
Your final configuration file should look like the following Python code:
ENDPOINT = 'https://localhost:44332'
SCOPE = ["https://contoso.onmicrosoft.com/api/demo.read", "https://contoso.onmicrosoft.com/api/demo.write"] ```
-### Run the sample application
+### Step 6.6: Run the sample app
-1. In your console or terminal, switch to the directory containing the sample.
-1. Stop the app and rerun it.
+1. In your console or terminal, switch to the directory that contains the sample.
+1. Stop the app. and then rerun it.
1. Select **Call Microsoft Graph API**.
- ![Screenshot shows how to call a web API.](./media/configure-authentication-sample-python-web-app/call-web-api.png)
+ ![Screenshot showing how to call a web API.](./media/configure-authentication-sample-python-web-app/call-web-api.png)
-## Deploy your application
+## Step 7: Deploy your application
-In a production application, the app registration redirect URI is typically a publicly accessible endpoint where your app is running, like `https://contoso.com/getAToken`.
+In a production application, the app registration redirect URI is ordinarily a publicly accessible endpoint where your app is running, such as `https://contoso.com/getAToken`.
You can add and modify redirect URIs in your registered applications at any time. The following restrictions apply to redirect URIs:
You can add and modify redirect URIs in your registered applications at any time
## Next steps
-* Learn how to [Configure authentication options in a Python web application using Azure Active Directory B2C](enable-authentication-python-web-app-options.md)
+* Learn how to [Configure authentication options in a Python web app by using Azure AD B2C](enable-authentication-python-web-app-options.md).
active-directory-b2c Configure Authentication Sample Web App https://github.com/MicrosoftDocs/azure-docs/commits/master/articles/active-directory-b2c/configure-authentication-sample-web-app.md
Title: Configure authentication in a sample web application using Azure Active Directory B2C
-description: Using Azure Active Directory B2C to sign in and sign up users in an ASP.NET web application.
+ Title: Configure authentication in a sample web application by using Azure Active Directory B2C
+description: This article discusses how to use Azure Active Directory B2C to sign in and sign up users in an ASP.NET web application.
-# Configure authentication in a sample web application using Azure Active Directory B2C
+# Configure authentication in a sample web app by using Azure AD B2C
This article uses a sample ASP.NET web application to illustrate how to add Azure Active Directory B2C (Azure AD B2C) authentication to your web applications. > [!IMPORTANT]
-> The sample ASP.NET web application referenced in this article can't be used to call a REST API because it returns an ID token but not an access token. For a web application that is able to call a REST API, see [Secure a Web API built with ASP.NET Core using the Azure AD B2C](https://github.com/Azure-Samples/active-directory-aspnetcore-webapp-openidconnect-v2/tree/master/4-WebApp-your-API/4-2-B2C).
+> The sample ASP.NET web app that's referenced in this article can't be used to call a REST API, because it returns an ID token and not an access token. For a web app that can call a REST API, see [Secure a Web API that's built with ASP.NET Core by using Azure AD B2C](https://github.com/Azure-Samples/active-directory-aspnetcore-webapp-openidconnect-v2/tree/master/4-WebApp-your-API/4-2-B2C).
## Overview
-OpenID Connect (OIDC) is an authentication protocol built on OAuth 2.0 that you can use to securely sign a user in to an application. This web app sample uses [Microsoft Identity Web](https://www.nuget.org/packages/Microsoft.Identity.Web). Microsoft Identity Web is a set of ASP.NET Core libraries that simplifies adding authentication and authorization support to web apps.
+OpenID Connect (OIDC) is an authentication protocol that's built on OAuth 2.0. You can use OIDC to securely sign users in to an application. This web app sample uses [Microsoft Identity Web](https://www.nuget.org/packages/Microsoft.Identity.Web). Microsoft Identity Web is a set of ASP.NET Core libraries that simplify adding authentication and authorization support to web apps.
-The sign-in flow involves following steps:
+The sign-in flow involves the following steps:
-1. User navigates to the web app and select **Sign-in**.
-1. The app initiates authentication request, and redirects the user to Azure AD B2C.
-1. The user [sign-up or sign-in](add-sign-up-and-sign-in-policy.md), [reset the password](add-password-reset-policy.md), or sign-in with a [social account](add-identity-provider.md).
-1. Upon successful sign-in, Azure AD B2C returns an ID token to the app.
-1. The app validates the ID token, reads the claims, and returns a secure page to the user.
+1. Users go to the web app and select **Sign-in**.
+1. The app initiates an authentication request and redirects users to Azure AD B2C.
+1. Users [sign up or sign in](add-sign-up-and-sign-in-policy.md) and [reset the password](add-password-reset-policy.md). Alternatively, they can sign in with a [social account](add-identity-provider.md).
+1. After users sign in successfully, Azure AD B2C returns an ID token to the app.
+1. The app validates the ID token, reads the claims, and returns a secure page to users.
-When the ID token is expired, or the app session is invalidated, the app initiates a new authentication request, and redirects the user to Azure AD B2C. If the Azure AD B2C [SSO session](session-behavior.md) is active, Azure AD B2C issues an access token without prompting the user to sign in again. If the Azure AD B2C session expires or becomes invalid, the user is prompted to sign-in again.
+When the ID token is expired or the app session is invalidated, the app initiates a new authentication request and redirects users to Azure AD B2C. If the Azure AD B2C [SSO session](session-behavior.md) is active, Azure AD B2C issues an access token without prompting users to sign in again. If the Azure AD B2C session expires or becomes invalid, users are prompted to sign in again.
### Sign-out
When the ID token is expired, or the app session is invalidated, the app initiat
## Prerequisites
-A computer that's running either:
+A computer that's running either of the following:
# [Visual Studio](#tab/visual-studio)
-* [Visual Studio 2019 16.8 or later](https://visualstudio.microsoft.com/downloads/?utm_medium=microsoft&utm_source=docs.microsoft.com&utm_campaign=inline+link&utm_content=download+vs2019) with the **ASP.NET and web development** workload
+* [Visual Studio 2019 16.8 or later](https://visualstudio.microsoft.com/downloads/?utm_medium=microsoft&utm_source=docs.microsoft.com&utm_campaign=inline+link&utm_content=download+vs2019), with the ASP.NET and web development workload
* [.NET 5.0 SDK](https://dotnet.microsoft.com/download/dotnet) # [Visual Studio Code](#tab/visual-studio-code)
A computer that's running either:
To enable your application to sign in with Azure AD B2C, register your app in the Azure AD B2C directory. Registering your app establishes a trust relationship between the app and Azure AD B2C.
-During app registration, you'll specify the **Redirect URI**. The redirect URI is the endpoint to which the user is redirected by Azure AD B2C after they authenticate with Azure AD B2C. The app registration process generates an **Application ID**, also known as the **client ID**, that uniquely identifies your app. Once your app is registered, Azure AD B2C will use both the application ID and redirect URI to create authentication requests.
+During app registration, you'll specify the *redirect URI*. The redirect URI is the endpoint to which users are redirected by Azure AD B2C after they authenticate with Azure AD B2C. The app registration process generates an *application ID*, also known as the *client ID*, that uniquely identifies your app. After your app is registered, Azure AD B2C uses both the application ID and the redirect URI to create authentication requests.
-### Register the app
+### Step 2.1: Register the app
-Follow these steps to create the app registration:
+To create the web app registration, do the following:
1. Sign in to the [Azure portal](https://portal.azure.com). 1. Select the **Directory + Subscription** icon in the portal toolbar, and then select the directory that contains your Azure AD B2C tenant.
-1. In the Azure portal, search for and select **Azure AD B2C**.
+1. Search for and select **Azure AD B2C**.
1. Select **App registrations**, and then select **New registration**.
-1. Enter a **Name** for the application. For example, *webapp1*.
+1. Under **Name**, enter a name for the application (for example, *webapp1*).
1. Under **Supported account types**, select **Accounts in any identity provider or organizational directory (for authenticating users with user flows)**.
-1. Under **Redirect URI**, select **Web**, and then enter `https://localhost:5001/signin-oidc` in the URL text box.
-1. Under **Permissions**, select the **Grant admin consent to openid and offline access permissions** check box.
+1. Under **Redirect URI**, select **Web** and then, in the URL box, enter `https://localhost:5001/signin-oidc`.
+1. Under **Permissions**, select the **Grant admin consent to openid and offline access permissions** checkbox.
1. Select **Register**. 1. Select **Overview**.
-1. Record the **Application (client) ID** for use in a later step when you configure the web application.
+1. Record the **Application (client) ID** for later use, when you configure the web application.
- ![Get your application ID](./media/configure-authentication-sample-web-app/get-azure-ad-b2c-app-id.png)
+ ![Screenshot of the web app Overview page for recording your web application ID.](./media/configure-authentication-sample-web-app/get-azure-ad-b2c-app-id.png)
-### Enable ID tokens
+### Step 2.2: Enable ID tokens
For web apps that request an ID token directly from Azure AD B2C, enable the implicit grant flow in the app registration.
-1. In the left menu, under **Manage**, select **Authentication**.
-1. Under **Implicit grant**, select the **ID tokens (used for implicit and hybrid flows)**, and the **Access tokens (used for implicit flows)** check boxes.
+1. On the left pane, under **Manage**, select **Authentication**.
+1. Under **Implicit grant**, select the **ID tokens (used for implicit and hybrid flows)** and **Access tokens (used for implicit flows)** checkboxes.
1. Select **Save**. ## Step 3: Get the web app sample
For web apps that request an ID token directly from Azure AD B2C, enable the imp
git clone https://github.com/Azure-Samples/active-directory-aspnetcore-webapp-openidconnect-v2 ```
-Extract the sample file to a folder where the total character length of the path is less than 260.
+Extract the sample file to a folder where the total length of the path is 260 or fewer characters.
-## Step 4: Configure the sample application
+## Step 4: Configure the sample web app
-In the sample folder, under the `1-WebApp-OIDC/1-5-B2C/` folder, open the **WebApp-OpenIDConnect-DotNet.csproj** project with Visual Studio or Visual Studio Code.
+In the sample folder, under the *1-WebApp-OIDC/1-5-B2C/* folder, open the **WebApp-OpenIDConnect-DotNet.csproj** project with Visual Studio or Visual Studio Code.
-Under the project root folder, open the `appsettings.json` file. This file contains information about your Azure AD B2C identity provider. Update the following properties of the app settings:
+Under the project root folder, open the *appsettings.json* file. This file contains information about your Azure AD B2C identity provider. Update the following app settings properties:
|Section |Key |Value | ||||
-|AzureAdB2C|Instance| The first part of your Azure AD B2C [tenant name](tenant-management.md#get-your-tenant-name). For example, `https://contoso.b2clogin.com`.|
-|AzureAdB2C|Domain| Your Azure AD B2C tenant full [tenant name](tenant-management.md#get-your-tenant-name). For example, `contoso.onmicrosoft.com`.|
+|AzureAdB2C|Instance| The first part of your Azure AD B2C [tenant name](tenant-management.md#get-your-tenant-name) (for example, `https://contoso.b2clogin.com`).|
+|AzureAdB2C|Domain| Your Azure AD B2C tenant full [tenant name](tenant-management.md#get-your-tenant-name) (for example, `contoso.onmicrosoft.com`).|
|AzureAdB2C|ClientId| The web API application ID from [step 2](#step-2-register-a-web-application).|
-|AzureAdB2C|SignUpSignInPolicyId|The user flows, or custom policy you created in [step 1](#step-1-configure-your-user-flow).|
+|AzureAdB2C|SignUpSignInPolicyId|The user flows or custom policy you created in [step 1](#step-1-configure-your-user-flow).|
Your final configuration file should look like the following JSON:
-```JSon
+```JSON
"AzureAdB2C": { "Instance": "https://contoso.b2clogin.com", "Domain": "contoso.onmicrosoft.com",
Your final configuration file should look like the following JSON:
} ```
-## Step 5: Run the sample application
+## Step 5: Run the sample web app
1. Build and run the project.
-1. Browse to https://localhost:5001.
-1. Select **SignIn/Up**.
+1. Go to [https://localhost:5001](https://localhost:5001).
+1. Select **Sign Up/In**.
- ![Select sign-in or sign-up](./media/configure-authentication-sample-web-app/web-app-sign-in.png)
+ ![Screenshot of the "Sign Up/In" button on the project Welcome page.](./media/configure-authentication-sample-web-app/web-app-sign-in.png)
1. Complete the sign-up or sign-in process.
-After successful authentication, you'll see your display name in the navigation bar. To view the claims that Azure AD B2C token returns to your app, select **Claims**.
+After successful authentication, you'll see your display name on the navigation bar. To view the claims that the Azure AD B2C token returns to your app, select **Claims**.
-![Web app token's claims](./media/configure-authentication-sample-web-app/web-app-token-claims.png)
+![Screenshot of the web app token claims.](./media/configure-authentication-sample-web-app/web-app-token-claims.png)
## Deploy your application
-In a production application, the app registration redirect URI is typically a publicly accessible endpoint where your app is running, like `https://contoso.com/signin-oidc`.
+In a production application, the app registration redirect URI is ordinarily a publicly accessible endpoint where your app is running, such as `https://contoso.com/signin-oidc`.
You can add and modify redirect URIs in your registered applications at any time. The following restrictions apply to redirect URIs:
You can add and modify redirect URIs in your registered applications at any time
## Next steps
-* Learn more [about the code sample](https://github.com/Azure-Samples/active-directory-aspnetcore-webapp-openidconnect-v2/tree/master/1-WebApp-OIDC/1-5-B2C#about-the-code)
-* Learn how to [Enable authentication in your own web application using Azure AD B2C](enable-authentication-web-application.md)
+* Learn more about the [code sample](https://github.com/Azure-Samples/active-directory-aspnetcore-webapp-openidconnect-v2/tree/master/1-WebApp-OIDC/1-5-B2C#about-the-code).
+* Learn how to [Enable authentication in your own web app by using Azure AD B2C](enable-authentication-web-application.md).
active-directory-b2c Configure Authentication Sample Wpf Desktop App https://github.com/MicrosoftDocs/azure-docs/commits/master/articles/active-directory-b2c/configure-authentication-sample-wpf-desktop-app.md
Title: Configure authentication in a sample WPF desktop application using Azure Active Directory B2C
-description: Using Azure Active Directory B2C to sign in and sign up users in a WPF desktop application.
+ Title: Configure authentication in a sample WPF desktop application by using Azure Active Directory B2C
+description: This article discusses how to use Azure Active Directory B2C to sign in and sign up users in a WPF desktop application.
-# Configure authentication in a sample WPF desktop application using Azure Active Directory B2C
+# Configure authentication in a sample WPF desktop app by using Azure AD B2C
-This article uses a sample [WPF desktop](/visualstudio/designers/getting-started-with-wpf) application to illustrate how to add Azure Active Directory B2C (Azure AD B2C) authentication to your desktop apps.
+This article uses a sample [Windows Presentation Foundation (WPF) desktop](/visualstudio/designers/getting-started-with-wpf) application to illustrate how to add Azure Active Directory B2C (Azure AD B2C) authentication to your desktop apps.
## Overview
-OpenID Connect (OIDC) is an authentication protocol built on OAuth 2.0, which you can securely use to sign-in a user to an application. This desktop app sample uses [MSAL](../active-directory/develop/msal-overview.md) library with OpenId Connect authorization code PKCE flow. The MSAL library is a Microsoft provided library that simplifies adding authentication and authorization support to desktop apps.
+OpenID Connect (OIDC) is an authentication protocol built on OAuth 2.0. You can use OIDC to securely sign users in to an application. This desktop app sample uses the [Microsoft Authentication Library (MSAL)](../active-directory/develop/msal-overview.md) with OIDC authorization code Proof Key for Code Exchange (PKCE) flow. The MSAL is a Microsoft-provided library that simplifies adding authentication and authorization support to desktop apps.
The sign-in flow involves following steps:
-1. The user opens the app and selects **sign-in**.
-1. The app opens the desktop device's system browser, and starts an authentication request to Azure AD B2C.
-1. The user [signs up or signs in](add-sign-up-and-sign-in-policy.md), [resets the password](add-password-reset-policy.md), or signs in with a [social account](add-identity-provider.md).
-1. Upon successful sign-in, Azure AD B2C returns an authorization code to the app.
+1. Users open the app and select **sign-in**.
+1. The app opens the desktop device's system browser and starts an authentication request to Azure AD B2C.
+1. Users [sign up or sign in](add-sign-up-and-sign-in-policy.md), [reset the password](add-password-reset-policy.md), or sign in with a [social account](add-identity-provider.md).
+1. After users sign in successfully, Azure AD B2C returns an authorization code to the app.
1. The app takes the following actions:
- 1. Exchanges the authorization code for an ID token, access token and refresh token.
- 1. Reads the ID token claims.
- 1. Stores the tokens to an in-memory cache for later use.
+ 1. It exchanges the authorization code to an ID token, access token, and refresh token.
+ 1. It reads the ID token claims.
+ 1. It stores the tokens in an in-memory cache for later use.
### App registration overview To enable your app to sign in with Azure AD B2C and call a web API, register two applications in the Azure AD B2C directory. -- The **desktop application** registration enables your app to sign in with Azure AD B2C. During app registration, specify the *Redirect URI*. The redirect URI is the endpoint to which the user is redirected by Azure AD B2C after they authenticate with Azure AD B2C. The app registration process generates an *Application ID*, also known as the *client ID*, that uniquely identifies your desktop app. For example, **App ID: 1**.
+- The **desktop application** registration enables your app to sign in with Azure AD B2C. During app registration, specify the *Redirect URI*. The redirect URI is the endpoint to which users are redirected by Azure AD B2C after they've authenticated with Azure AD B2C. The app registration process generates an *application ID*, also known as the *client ID*, which uniquely identifies your desktop app (for example, *App ID: 1*).
-- The **web API** registration enables your app to call a protected web API. The registration exposes the web API permissions (scopes). The app registration process generates an *Application ID* that uniquely identifies your web API. For example, **App ID: 2**. Grant your desktop app (App ID: 1) permissions to the web API scopes (App ID: 2).
+- The **web API** registration enables your app to call a protected web API. The registration exposes the web API permissions (scopes). The app registration process generates an *application ID*, which uniquely identifies your web API (for example, *App ID: 2*). Grant your desktop app (App ID: 1) permissions to the web API scopes (App ID: 2).
-The following diagrams describe the apps registration and the application architecture.
+The application registration and architecture are illustrated in the following diagrams:
-![Diagram describes a desktop app with web API, registrations and tokens.](./media/configure-authentication-sample-wpf-desktop-app/desktop-app-with-api-architecture.png)
+![Diagram of the desktop app with web API, registrations, and tokens.](./media/configure-authentication-sample-wpf-desktop-app/desktop-app-with-api-architecture.png)
### Call to a web API [!INCLUDE [active-directory-b2c-app-integration-call-api](../../includes/active-directory-b2c-app-integration-call-api.md)]
-### Sign-out
+### The sign-out flow
[!INCLUDE [active-directory-b2c-app-integration-sign-out-flow](../../includes/active-directory-b2c-app-integration-sign-out-flow.md)] ## Prerequisites
-A computer that's running [Visual Studio 2019](https://www.visualstudio.com/downloads/) with **.NET desktop development**.
+A computer that's running [Visual Studio 2019](https://www.visualstudio.com/downloads/) with .NET desktop development.
## Step 1: Configure your user flow
A computer that's running [Visual Studio 2019](https://www.visualstudio.com/down
## Step 2: Register your applications
-In this step, create the desktop app and the web API application registration, and specify the scopes of your web API.
+Create the desktop app and the web API application registration, and specify the scopes of your web API.
-### 2.1 Register the web API app
+### Step 2.1: Register the web API app
[!INCLUDE [active-directory-b2c-app-integration-register-api](../../includes/active-directory-b2c-app-integration-register-api.md)]
-### 2.2 Configure web API app scopes
+### Step 2.2: Configure web API app scopes
[!INCLUDE [active-directory-b2c-app-integration-api-scopes](../../includes/active-directory-b2c-app-integration-api-scopes.md)]
-### 2.3 Register the desktop app
+### Step 2.3: Register the desktop app
-Follow these steps to create the desktop app registration:
+To create the desktop app registration, do the following:
+1. Sign in to the [Azure portal](https://portal.azure.com).
1. Select **App registrations**, and then select **New registration**.
-1. Enter a **Name** for the application. For example, *desktop-app1*.
+1. Under **Name**, enter a name for the application (for example, *desktop-app1*).
1. Under **Supported account types**, select **Accounts in any identity provider or organizational directory (for authenticating users with user flows)**.
-1. Under **Redirect URI**, select **Public client/native (desktop & desktop)**, and then enter: `https://your-tenant-name.b2clogin.com/oauth2/nativeclient`. Replace the `your-tenant-name` with your [tenant name](tenant-management.md#get-your-tenant-name). For more options, see [Configure redirect URI](enable-authentication-wpf-desktop-app-options.md#configure-redirect-uri).
+1. Under **Redirect URI**, select **Public client/native (desktop & desktop)** and then, in the URL box, enter `https://your-tenant-name.b2clogin.com/oauth2/nativeclient`. Replace `your-tenant-name` with your [tenant name](tenant-management.md#get-your-tenant-name). For more options, see [Configure redirect URI](enable-authentication-wpf-desktop-app-options.md#configure-the-redirect-uri).
1. Select **Register**. 1. After the app registration is completed, select **Overview**.
-1. Record the **Application (client) ID** for use in a later step when you configure the desktop application.
- ![Screenshot showing how to get the desktop application ID.](./media/configure-authentication-sample-wpf-desktop-app/get-azure-ad-b2c-app-id.png)
+1. Record the **Application (client) ID** for later use, when you configure the desktop application.
+ ![Screenshot highlighting the desktop application ID.](./media/configure-authentication-sample-wpf-desktop-app/get-azure-ad-b2c-app-id.png)
-### 2.4 Grant the desktop app permissions for the web API
+### Step 2.4: Grant the desktop app permissions for the web API
[!INCLUDE [active-directory-b2c-app-integration-grant-permissions](../../includes/active-directory-b2c-app-integration-grant-permissions.md)] ## Step 3: Configure the sample web API
-This sample acquires an access token with the relevant scopes the desktop app can use for a web API. To call a web API from code, follow these steps:
+This sample acquires an access token with the relevant scopes that the desktop app can use for a web API. To call a web API from code, do the following:
1. Use an existing web API, or create a new one. For more information, see [Enable authentication in your own web API using Azure AD B2C](enable-authentication-web-api.md). 1. After you configure the web API, copy the URI of the web API endpoint. You will use the web API endpoint in the next steps.
This sample acquires an access token with the relevant scopes the desktop app ca
## Step 4: Get the WPF desktop app sample
-1. [Download the zip file](https://github.com/Azure-Samples/active-directory-b2c-dotnet-desktop.git), or clone the sample web application from [GitHub repo](https://github.com/Azure-Samples/active-directory-b2c-dotnet-desktop.git).
+1. [Download the .zip file](https://github.com/Azure-Samples/active-directory-b2c-dotnet-desktop.git), or clone the sample web application from the [GitHub repo](https://github.com/Azure-Samples/active-directory-b2c-dotnet-desktop.git).
```bash git clone https://github.com/Azure-Samples/active-directory-b2c-dotnet-desktop.git ```
-1. Open the **active-directory-b2c-wpf** solution (`active-directory-b2c-wpf.sln`) in Visual Studio.
+1. Open the **active-directory-b2c-wpf** solution (the *active-directory-b2c-wpf.sln* file) in Visual Studio.
## Step 5: Configure the sample desktop app
-In the **active-directory-b2c-wpf** project, open the *App.xaml.cs* file. The `App.xaml.cs` class members contain information about your Azure AD B2C identity provider. The desktop app uses this information to establish a trust relationship with Azure AD B2C, sign the user in and out, acquire tokens, and validate them.
+In the **active-directory-b2c-wpf** project, open the *App.xaml.cs* file. The `App.xaml.cs` class members contain information about your Azure AD B2C identity provider. The desktop app uses this information to establish a trust relationship with Azure AD B2C, sign users in and out, acquire tokens, and validate them.
-Update the following members:
+Update the following class members:
|Key |Value | |||
-|`TenantName`|The first part of your Azure AD B2C [tenant name](tenant-management.md#get-your-tenant-name). For example, `contoso.b2clogin.com`.|
-|`ClientId`|The desktop application ID from [step 2.3](#23-register-the-desktop-app).|
-|`PolicySignUpSignIn`| The sign-up or sign-in user flow or custom policy you created in [step 1](#step-1-configure-your-user-flow).|
-|`PolicyEditProfile`|The edit profile user flow or custom policy you created in [step 1](#step-1-configure-your-user-flow).|
-|`ApiEndpoint`| (Optional) the web API endpoint you created in [Step 3](#step-3-configure-the-sample-web-api). For example, `https://contoso.azurewebsites.net/hello`.|
-| `ApiScopes` | The web API scopes you created in [step 2.4](#24-grant-the-desktop-app-permissions-for-the-web-api).|
+|`TenantName`|The first part of your Azure AD B2C [tenant name](tenant-management.md#get-your-tenant-name) (for example, `contoso.b2clogin.com`).|
+|`ClientId`|The desktop application ID from [step 2.3](#step-23-register-the-desktop-app).|
+|`PolicySignUpSignIn`| The sign-up or sign-in user flow or custom policy that you created in [step 1](#step-1-configure-your-user-flow).|
+|`PolicyEditProfile`|The edit profile user flow or custom policy that you created in [step 1](#step-1-configure-your-user-flow).|
+|`ApiEndpoint`| (Optional) The web API endpoint that you created in [step 3](#step-3-configure-the-sample-web-api) (for example, `https://contoso.azurewebsites.net/hello`).|
+| `ApiScopes` | The web API scopes that you created in [step 2.4](#step-24-grant-the-desktop-app-permissions-for-the-web-api).|
+| | |
Your final *App.xaml.cs* file should look like the following C# code:
public static string ApiEndpoint = "https://contoso.azurewebsites.net/hello";
## Step 6: Run and test the desktop app 1. [Restore the NuGet packages](/nuget/consume-packages/package-restore).
-1. Press **F5** to build and run the sample.
-1. Select **Sign In**. Then sign up or sign in with your Azure AD B2C local or social account.
+1. Select F5 to build and run the sample.
+1. Select **Sign In**, and then sign up or sign in with your Azure AD B2C local or social account.
- ![Screenshot demonstrates how to start the sign-in flow.](./media/configure-authentication-sample-wpf-desktop-app/sign-in.png)
+ ![Screenshot highlighting how to start the sign-in flow.](./media/configure-authentication-sample-wpf-desktop-app/sign-in.png)
-1. After a successful sign-up or sign-in, the token details are displayed in the lower pane of the WPF app.
+1. After a successful sign-up or sign-in, the token details are displayed on the lower pane of the WPF app.
- ![Screenshot showing the Azure AD B2C access token and user ID.](./media/configure-authentication-sample-wpf-desktop-app/post-signin.png)
+ ![Screenshot highlighting the Azure AD B2C access token and user ID.](./media/configure-authentication-sample-wpf-desktop-app/post-signin.png)
-1. Select **Call API**, to call your web API.
+1. Select **Call API** to call your web API.
## Next steps
-* [Configure authentication options in a WPF desktop application using Azure Active Directory B2C](enable-authentication-wpf-desktop-app-options.md)
+Learn how to [Configure authentication options in a WPF desktop app by using Azure AD B2C](enable-authentication-wpf-desktop-app-options.md).
active-directory-b2c Deploy Custom Policies Github Action https://github.com/MicrosoftDocs/azure-docs/commits/master/articles/active-directory-b2c/deploy-custom-policies-github-action.md
+
+ Title: Deploy custom policies with GitHub Actions
+
+description: Learn how to deploy Azure AD B2C custom policies in a CI/CD pipeline by using GitHub Actions.
+++++++ Last updated : 08/25/2021++++
+# Deploy custom policies with GitHub Actions
+
+[GitHub Actions](https://docs.github.com/actions/quickstart) allows you to create custom continuous integration (CI) and continuous deployment (CD) workflows directly in your GitHub repository. This article describes how to automate the deployment of Azure Active Directory B2C (Azure AD B2C) [custom policies](user-flow-overview.md) using GitHub Actions.
+
+To automate the custom policy deployment process, use the [GitHub Action for deploying Azure AD B2C custom policies](https://github.com/marketplace/actions/deploy-azure-ad-b2c-custom-policy). This GitHub Action has developed by the [Azure AD B2C community](https://github.com/azure-ad-b2c/deploy-trustframework-policy).
+
+This action deploys Azure AD B2C custom policies into your Azure AD B2C tenant using the [Microsoft Graph API](/graph/api/resources/trustframeworkpolicy?view=graph-rest-beta&preserve-view=true). If the policy does not yet exist in your tenant, it will be created. Otherwise, it will be replaced.
+
+> [!IMPORTANT]
+> Managing Azure AD B2C custom policies with Azure Pipelines currently uses **preview** operations available on the Microsoft Graph API `/beta` endpoint. Use of these APIs in production applications is not supported. For more information, see the [Microsoft Graph REST API beta endpoint reference](/graph/api/overview?toc=.%2fref%2ftoc.json&view=graph-rest-beta&preserve-view=true).
+
+## Prerequisites
+
+* Complete the steps in [Get started with custom policies in Active Directory B2C](tutorial-create-user-flows.md).
+* If you haven't created GitHub repo, [create one](https://docs.github.com/en/get-started/quickstart/create-a-repo).
+
+## Select a custom policies folder
+
+Your GitHub repository can contain all of your Azure AD B2C policy files and other assets. In the root directory of your repository, create or choose an existing folder that contains your custom policies.
+
+For example, select a folder named *policies*. Add your Azure AD B2C custom policy files to the *policies* folder. Then **Commit** the changes.
+
+Do not **Push** the changes. You will do this later, after you set up the deployment workflow.
+
+## Register a Microsoft Graph application
+
+To allow the GitHub Action to interact with the [Microsoft Graph API](microsoft-graph-operations.md), create an application registration in your Azure AD B2C tenant. If you haven't already done so, [register a Microsoft Graph application](microsoft-graph-get-started.md).
+
+For the GitHub Action to access data in Microsoft Graph, grant the registered application the relevant [application permissions](/graph/permissions-reference). Grant the **Microsoft Graph** > **Policy** > **Policy.ReadWrite.TrustFramework** permission within the **API Permissions** of the app registration.
+
+## Create a GitHub encrypted secret
+
+GitHub secrets are encrypted environment variables that you create in an organization, repository, or repository environment. In this step, you store the application secret for the application you registered earlier in the [Register an MS Graph application](#register-a-microsoft-graph-application) step.
+
+The GitHub Action for deploying Azure AD B2C custom policies uses the secret to acquire an access token that is used to interact with the Microsoft Graph API. For more information, see [Creating encrypted secrets for a repository](https://docs.github.com/actions/reference/encrypted-secrets#creating-encrypted-secrets-for-a-repository).
+
+To create a GitHub secret, follow these steps:
+
+1. In GitHub, navigate to the main page of the repository.
+1. Under your repository name, select **Settings**.
+1. In the left sidebar, select **Secrets**.
+1. Select **New repository secret**.
+1. For the **Name**, type **ClientSecret**.
+1. For the **Value**, enter the application secret you created earlier.
+1. Select **Add secret**.
+
+## Create a GitHub workflow
+
+The GitHub workflow is an automated procedure that you add to your repository. Workflows are made up of one or more jobs and can be scheduled or triggered by an event. In this step, you create a workflow the deploys your custom policy.
+
+To create a workflow, follow these steps:
+
+1. In GitHub, navigate to the main page of your repository.
+1. Under your repository name, select **Actions**.
+
+ ![Screenshot showing the GitHub Actions tab](media/deploy-custom-policies-github-action/github-actions-tab.png)
+
+1. If you didn't configure a workflow before, select **set up a workflow yourself**. Otherwise, select **New Workflow**.
+
+ ![Screenshot showing how to create a new workflow](media/deploy-custom-policies-github-action/set-up-a-workflow.png)
+
+1. GitHub offers to create a workflow file named `main.yml` in the `.github/workflows` folder. This file contains information about the workflow, including your Azure AD B2C environment and the custom policies to deploy. In the GitHub web editor, add the following YAML code:
+
+ ```yml
+ on: push
+
+ env:
+ clientId: 00000000-0000-0000-0000-000000000000
+ tenant: your-tenant.onmicrosoft.com
+
+ jobs:
+ build-and-deploy:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v2
+
+ - name: 'Upload TrustFrameworkBase Policy'
+ uses: azure-ad-b2c/deploy-trustframework-policy@v3
+ with:
+ folder: "./Policies"
+ files: "TrustFrameworkBase.xml,TrustFrameworkExtensions.xml,SignUpOrSignin.xml"
+ tenant: ${{ env.tenant }}
+ clientId: ${{ env.clientId }}
+ clientSecret: ${{ secrets.clientSecret }}
+ ```
+
+1. Update the following properties of the YAML file:
+
+ | Section| Name | Value |
+ | - | -- |-- |
+ | `env` | `clientId` | **Application (client) ID** of the application you registered in the [Register an MS Graph application](#register-a-microsoft-graph-application) step. |
+ |`env`| `tenant` | Your Azure AD B2C [tenant name](tenant-management.md#get-your-tenant-name) (for example, contoso.onmicrosoft.com). |
+ | `with`| `folder`| A folder where the custom policies files are stored, for example, `./Policies`.|
+ | `with`| `files` | Comma-delimited list of policy files to deploy, for example, `TrustFrameworkBase.xml,TrustFrameworkExtensions.xml,SignUpOrSignin.xml`.|
+
+ > [!IMPORTANT]
+ > When running the agents and uploading the policy files, make sure they're uploaded in the correct order:
+ >
+ > 1. *TrustFrameworkBase.xml*
+ > 1. *TrustFrameworkExtensions.xml*
+ > 1. *SignUpOrSignin.xml*
+ > 1. *ProfileEdit.xml*
+ > 1. *PasswordReset.xml*
+
+1. Select **Start commit**.
+1. Below the commit message fields, indicate whether to add your commit to the current branch or to a new branch. Select **Commit new file**, or **Propose new file** to create a pull request.
+
+## Test your workflow
+
+To test the workflow you created, **Push** the changes of your custom policy. Once your job has started running, you can see a visualization graph of the run's progress and view each step's activity on GitHub.
+
+1. On GitHub, navigate to the main page of your repository.
+1. Under your repository name, select **Actions**.
+1. In the left sidebar, select the workflow you created.
+1. Under **Workflow runs**, select the name of the run you want to see.
+
+ ![Screenshot showing how to select workflow activity](media/deploy-custom-policies-github-action/workflow-report.png)
+
+1. Under **Jobs** or in the visualization graph, select the job you want to see.
+1. View the results of each step. The following screenshot demonstrates the **Upload custom policy** step log.
+
+ ![The upload custom policy step log](media/deploy-custom-policies-github-action/job-activity.png)
++
+## Optional: Schedule your workflow
+
+The workflow you created is triggered by the [push](https://docs.github.com/actions/reference/events-that-trigger-workflows#push) event. If you prefer, you can choose another event to trigger the workflow, for example a [pull request](https://docs.github.com/actions/reference/events-that-trigger-workflows#pull_request).
+
+You can also schedule a workflow to run at specific UTC times using [POSIX cron syntax](https://pubs.opengroup.org/onlinepubs/9699919799/utilities/crontab.html#tag_20_25_07). The schedule event allows you to trigger a workflow at a scheduled time. For more information, see [Scheduled events](https://docs.github.com/actions/reference/events-that-trigger-workflows#scheduled-events).
+
+The following example triggers the workflow every day at 5:30 and 17:30 UTC:
+
+```yml
+on:
+ schedule:
+ # * is a special character in YAML so you have to quote this string
+ - cron: '30 5,17 * * *'
+```
+
+To edit your workflow:
+
+1. In GitHub, navigate to the main page of your repository.
+1. Under your repository name, select **Actions**.
+1. In the left sidebar, select the workflow you created.
+1. Under **Workflow runs**, select the name of the run you want to see.
+1. From the menu, select the three dots **...**, and then select **View the workflow file**.
+
+ ![Screenshot showing how to view the workflow file](media/deploy-custom-policies-github-action/edit-workflow.png)
+
+1. In the GitHub web editor, select **Edit**.
+1. Change `on: push` to the example above.
+1. **Commit** your changes.
+
+## Next steps
+
+- Learn how to configure [Events that trigger workflows](https://docs.github.com/actions/reference/events-that-trigger-workflows)
++
active-directory-b2c Enable Authentication Android App Options https://github.com/MicrosoftDocs/azure-docs/commits/master/articles/active-directory-b2c/enable-authentication-android-app-options.md
Title: Enable Android mobile application options using Azure Active Directory B2C
-description: Enable the use of Android mobile application options by using several ways.
+ Title: Enable Android mobile application options by using Azure Active Directory B2C
+description: This article discusses several ways to enable Android mobile application options by using Azure Active Directory B2C.
-# Configure authentication options in an Android application using Azure Active Directory B2C
+# Configure authentication options in an Android app by using Azure AD B2C
-This article describes ways in which you can customize and enhance the Azure Active Directory B2C (Azure AD B2C) authentication experience for your Android application. Before you start, familiarize yourself with the following articles: [Configure authentication in a sample Android application](configure-authentication-sample-android-app.md), or [Enable authentication in your own Android app using Azure Active Directory B2C](enable-authentication-android-app.md).
+This article describes how you can enable, customize, and enhance the Azure Active Directory B2C (Azure AD B2C) authentication experience for your Android application.
+
+Before you start, familiarize yourself with the following articles:
+* [Configure authentication in a sample Android app by using Azure AD B2C](configure-authentication-sample-android-app.md)
+* [Enable authentication in your own Android app by using Azure AD B2C](enable-authentication-android-app.md)
[!INCLUDE [active-directory-b2c-app-integration-custom-domain](../../includes/active-directory-b2c-app-integration-custom-domain.md)]
-To use a custom domain and your tenant ID in the authentication URL, follow the guidance in [Enable custom domains](custom-domain.md). Find your MSAL configuration object and change the **authorities** with your custom domain name and tenant ID.
+To use a custom domain and your tenant ID in the authentication URL, follow the guidance in [Enable custom domains](custom-domain.md). Look for your Microsoft Authentication Library (MSAL configuration object, and then update the *authorities* with your custom domain name and tenant ID.
#### [Kotlin](#tab/kotlin)
b2cApp.acquireToken(parameters);
[!INCLUDE [active-directory-b2c-app-integration-login-hint](../../includes/active-directory-b2c-app-integration-login-hint.md)]
-1. If you're using a custom policy, add the required input claim as described in [Set up direct sign-in](direct-signin.md#prepopulate-the-sign-in-name).
-1. Find your MSAL configuration object and add the **withLoginHint()** method with the login hint.
+1. If you're using a custom policy, add the required input claim, as described in [Set up direct sign-in](direct-signin.md#prepopulate-the-sign-in-name).
+1. Look for your MSAL configuration object, and then add the `withLoginHint()` method with the login hint.
#### [Kotlin](#tab/kotlin)
b2cApp.acquireToken(parameters);
[!INCLUDE [active-directory-b2c-app-integration-domain-hint](../../includes/active-directory-b2c-app-integration-domain-hint.md)] 1. Check the domain name of your external identity provider. For more information, see [Redirect sign-in to a social provider](direct-signin.md#redirect-sign-in-to-a-social-provider).
-1. Create or use an exiting list object to store extra query parameters.
-1. Add the `domain_hint` parameter with the corresponding domain name to the list. For example, `facebook.com`.
+1. Create or use an existing list object to store extra query parameters.
+1. Add the `domain_hint` parameter with the corresponding domain name to the list (for example, `facebook.com`).
1. Pass the extra query parameters list into the MSAL configuration object's `withAuthorizationQueryStringParameters` method. #### [Kotlin](#tab/kotlin)
b2cApp.acquireToken(parameters);
[!INCLUDE [active-directory-b2c-app-integration-ui-locales](../../includes/active-directory-b2c-app-integration-ui-locales.md)]
-1. [Configure Language customization](language-customization.md).
-1. Create or use an exiting list object to store extra query parameters.
-1. Add the `ui_locales` parameter with the corresponding language code to the list. For example, `en-us`.
+1. [Configure language customization](language-customization.md).
+1. Create or use an existing list object to store extra query parameters.
+1. Add the `ui_locales` parameter with the corresponding language code to the list (for example, `en-us`).
1. Pass the extra query parameters list into the MSAL configuration object's `withAuthorizationQueryStringParameters` method. #### [Kotlin](#tab/kotlin)
b2cApp.acquireToken(parameters);
[!INCLUDE [active-directory-b2c-app-integration-custom-parameters](../../includes/active-directory-b2c-app-integration-custom-parameters.md)] 1. Configure the [ContentDefinitionParameters](customize-ui-with-html.md#configure-dynamic-custom-page-content-uri) element.
-1. Create or use an exiting list object to store extra query parameters.
-1. Add the custom query string parameter, such as `campaignId`. Set the parameter value. For example, `germany-promotion`.
+1. Create or use an existing list object to store extra query parameters.
+1. Add the custom query string parameter, such as `campaignId`. Set the parameter value (for example, `germany-promotion`).
1. Pass the extra query parameters list into the MSAL configuration object's `withAuthorizationQueryStringParameters` method. #### [Kotlin](#tab/kotlin)
b2cApp.acquireToken(parameters);
[!INCLUDE [active-directory-b2c-app-integration-id-token-hint](../../includes/active-directory-b2c-app-integration-id-token-hint.md)] 1. In your custom policy, define an [ID token hint technical profile](id-token-hint.md).
-1. In your code, generate or acquire an ID token, and set the token to a variable. For example, `idToken`.
-1. Create or use an exiting list object to store extra query parameters.
+1. In your code, generate or acquire an ID token, and then set the token to a variable (for example, `idToken`).
+1. Create or use an existing list object to store extra query parameters.
1. Add the `id_token_hint` parameter with the corresponding variable that stores the ID token. 1. Pass the extra query parameters list into the MSAL configuration object's `withAuthorizationQueryStringParameters` method.
b2cApp.acquireToken(parameters);
## Next steps -- Learn more: [MSAL for Android configuration options](https://github.com/AzureAD/microsoft-authentication-library-for-android/wiki)
+- To learn more about Android configuration, see [MSAL for Android configuration options](https://github.com/AzureAD/microsoft-authentication-library-for-android/wiki).
active-directory-b2c Enable Authentication Android App https://github.com/MicrosoftDocs/azure-docs/commits/master/articles/active-directory-b2c/enable-authentication-android-app.md
-# Enable authentication in your own Android application using Azure Active Directory B2C
+# Enable authentication in your own Android app by using Azure AD B2C
This article shows you how to add Azure Active Directory B2C (Azure AD B2C) authentication to your own Android mobile application.
-Use this article with [Configure authentication in a sample Android application](./configure-authentication-sample-android-app.md), substituting the sample Android app with your own Android app. After completing the steps in this article, your application will accept sign-ins via Azure AD B2C.
+Use this article with [Configure authentication in a sample Android app by using Azure AD B2C](./configure-authentication-sample-android-app.md), substituting the sample Android app with your own Android app. After you've completed the instructions in this article, your application will accept sign-ins via Azure AD B2C.
## Prerequisites
-Review the prerequisites and integration steps in [Configure authentication in a sample Android application](configure-authentication-sample-android-app.md) article.
+Review the prerequisites and integration instructions in [Configure authentication in a sample Android app by using Azure AD B2C](configure-authentication-sample-android-app.md).
## Create an Android app project
-If you don't already have an Android application, follow these steps to set up a new project.
+If you don't already have an Android application, set up a new project by doing the following:
-1. Open Android Studio, and select **Start a new Android Studio project**.
-2. Select **Basic Activity** and select **Next**.
-3. Name your application.
-4. Save the package name. You'll enter it later into the Azure portal.
-5. Change the language from **Kotlin** to **Java**.
-6. Set the **Minimum API level** to **API 19** or higher, and then select **Finish**.
-7. In the project view, choose **Project** in the drop-down to display source and non-source project files, open **app/build.gradle**, and set `targetSdkVersion` to `28`.
+1. In Android Studio, select **Start a new Android Studio project**.
+1. Select **Basic Activity**, and then select **Next**.
+1. Name your application.
+1. Save the package name. You'll enter it later in the Azure portal.
+1. Change the language from **Kotlin** to **Java**.
+1. Set the **Minimum API level** to **API 19** or higher, and then select **Finish**.
+1. In the project view, choose **Project** in the dropdown list to display source and non-source project files, open **app/build.gradle**, and then set **targetSdkVersion** to **28**.
-## Install the dependencies
+## Step 1: Install the dependencies
-In the Android Studio project window, navigate to **app** > **build.gradle** and add the following:
+In the Android Studio project window, go to **app** > **build.gradle**, and then add the following:
```gradle apply plugin: 'com.android.application'
packagingOptions{
```
-## Add the authentication components
+## Step 2: Add the authentication components
The [sample code](configure-authentication-sample-android-app.md#step-3-get-the-android-mobile-app-sample) is made up of the following components. Add these components from the sample Android app to your own app. |Component |Type | Source |Description | ||||| | B2CUser| Class| [Kotlin](https://github.com/Azure-Samples/ms-identity-android-kotlin/blob/master/app/src/main/java/com/azuresamples/msalandroidkotlinapp/B2CUser.kt) [Java](https://github.com/Azure-Samples/ms-identity-android-java/blob/master/app/src/main/java/com/azuresamples/msalandroidapp/B2CUser.java)| Represents a B2C user. This class allows users to sign in with multiple policies. |
-| B2CModeFragment | Fragment class| [Kotlin](https://github.com/Azure-Samples/ms-identity-android-kotlin/blob/master/app/src/main/java/com/azuresamples/msalandroidkotlinapp/B2CModeFragment.kt) [Java](https://github.com/Azure-Samples/ms-identity-android-java/blob/master/app/src/main/java/com/azuresamples/msalandroidapp/B2CModeFragment.java)| A fragment represents a modular portion of the sign-in with Azure AD B2C user interface within your main activity. This fragment contains most of the authentication code. |
+| B2CModeFragment | Fragment class| [Kotlin](https://github.com/Azure-Samples/ms-identity-android-kotlin/blob/master/app/src/main/java/com/azuresamples/msalandroidkotlinapp/B2CModeFragment.kt) [Java](https://github.com/Azure-Samples/ms-identity-android-java/blob/master/app/src/main/java/com/azuresamples/msalandroidapp/B2CModeFragment.java)| A fragment represents a modular portion of the sign-in with the Azure AD B2C user interface within your main activity. This fragment contains most of the authentication code. |
| fragment_b2c_mode.xml | Fragment layout| [Kotlin](https://github.com/Azure-Samples/ms-identity-android-kotlin/blob/master/app/src/main/res/layout/fragment_b2c_mode.xml) [Java](https://github.com/Azure-Samples/ms-identity-android-java/blob/master/app/src/main/res/layout/fragment_b2c_mode.xml) | Defines the structure for a user interface for the B2CModeFragment fragment component. |
-| B2CConfiguration| Class| [Kotlin](https://github.com/Azure-Samples/ms-identity-android-kotlin/blob/master/app/src/main/java/com/azuresamples/msalandroidkotlinapp/B2CConfiguration.kt) [Java](https://github.com/Azure-Samples/ms-identity-android-java/blob/master/app/src/main/java/com/azuresamples/msalandroidapp/B2CConfiguration.java)| A configuration file contains information about your Azure AD B2C identity provider. The mobile app uses this information to establish a trust relationship with Azure AD B2C, sign the user in and out, acquire tokens, and validate them. For more configuration settings, see the auth_config_b2c.json file. |
-|auth_config_b2c.json | JSON file| [Kotlin](https://github.com/Azure-Samples/ms-identity-android-kotlin/blob/master/app/src/main/res/raw/auth_config_b2c.json) [Java](https://github.com/Azure-Samples/ms-identity-android-java/blob/master/app/src/main/res/raw/auth_config_b2c.json)| A configuration file contains information about your Azure AD B2C identity provider. The mobile app uses this information to establish a trust relationship with Azure AD B2C, sign the user in and out, acquire tokens, and validate them. For more configuration settings, see the B2CConfiguration class. |
+| B2CConfiguration| Class| [Kotlin](https://github.com/Azure-Samples/ms-identity-android-kotlin/blob/master/app/src/main/java/com/azuresamples/msalandroidkotlinapp/B2CConfiguration.kt) [Java](https://github.com/Azure-Samples/ms-identity-android-java/blob/master/app/src/main/java/com/azuresamples/msalandroidapp/B2CConfiguration.java)| A configuration file contains information about your Azure AD B2C identity provider. The mobile app uses this information to establish a trust relationship with Azure AD B2C, sign users in and out, acquire tokens, and validate them. For more configuration settings, see the auth_config_b2c.json file. |
+|auth_config_b2c.json | JSON file| [Kotlin](https://github.com/Azure-Samples/ms-identity-android-kotlin/blob/master/app/src/main/res/raw/auth_config_b2c.json) [Java](https://github.com/Azure-Samples/ms-identity-android-java/blob/master/app/src/main/res/raw/auth_config_b2c.json)| A configuration file contains information about your Azure AD B2C identity provider. The mobile app uses this information to establish a trust relationship with Azure AD B2C, sign users in and out, acquire tokens, and validate them. For more configuration settings, see the B2CConfiguration class. |
+| | |
-## Configure your Android app
+## Step 3: Configure your Android app
-After you [add the authentication components](#add-the-authentication-components), configure your Android app with your Azure AD B2C settings. Azure AD B2C identity provider settings are configured in the auth_config_b2c.json file and B2CConfiguration class.
+After you [add the authentication components](#step-2-add-the-authentication-components), configure your Android app with your Azure AD B2C settings. Azure AD B2C identity provider settings are configured in the *auth_config_b2c.json* file and B2CConfiguration class.
-Follow the guidance for how to [Configure the sample mobile app](configure-authentication-sample-android-app.md#step-5-configure-the-sample-mobile-app).
+For guidance, see [Configure the sample mobile app](configure-authentication-sample-android-app.md#step-5-configure-the-sample-mobile-app).
-## Set the redirect URI
+## Step 4: Set the redirect URI
-In this section, configure where your application listens to the Azure AD B2C token response.
+Configure where your application listens to the Azure AD B2C token response.
-
-1. Generate a new development Signature Hash. This will change for each development environment.
+1. Generate a new development signature hash. This will change for each development environment.
- On Windows operating system:
+ For Windows:
``` keytool -exportcert -alias androiddebugkey -keystore %HOMEPATH%\.android\debug.keystore | openssl sha1 -binary | openssl base64 ```
- On IOS operating system:
+ For iOS:
```dotnetcli keytool -exportcert -alias androiddebugkey -keystore ~/.android/debug.keystore | openssl sha1 -binary | openssl base64
In this section, configure where your application listens to the Azure AD B2C to
keytool -exportcert -alias SIGNATURE_ALIAS -keystore PATH_TO_KEYSTORE | openssl sha1 -binary | openssl base64 ```
- For more help with signing your apps, check out [Signing your Android app](https://developer.android.com/studio/publish/app-signing).
+ For more help with signing your apps, see [Sign your Android app](https://developer.android.com/studio/publish/app-signing).
-1. In **app** > **src** > **main** > **AndroidManifest.xml**, add the `BrowserTabActivity` activity below to the application body:
+1. Select **app** > **src** > **main** > **AndroidManifest.xml**, and then add the following `BrowserTabActivity` activity to the application body:
```xml <!--Intent filter to capture System Browser or Authenticator calling back to our app after sign-in-->
In this section, configure where your application listens to the Azure AD B2C to
</intent-filter> </activity> ```
-1. Replace the `Signature_Hash` with the hash you generated.
-1. Replace the `Package_Name` with your Android package name.
+1. Replace `Signature_Hash` with the hash you generated.
+1. Replace `Package_Name` with your Android package name.
-Follow these steps to update the mobile app registration with your app redirect URI:
+To update the mobile app registration with your app redirect URI, do the following:
1. Sign in to the [Azure portal](https://portal.azure.com). 1. Select the **Directory + Subscription** icon in the portal toolbar, and then select the directory that contains your Azure AD B2C tenant.
-1. In the Azure portal, search for and select **Azure AD B2C**.
-1. Select **App registrations**, and then select the application you registered in [2.3 Register the mobile app](configure-authentication-sample-android-app.md#23-register-the-mobile-app).
+1. Search for and select **Azure AD B2C**.
+1. Select **App registrations**, and then select the application you registered in [Step 2.3: Register the mobile app](configure-authentication-sample-android-app.md#step-23-register-the-mobile-app).
1. Select **Authentication**. 1. Under **Android**, select **Add URI**.
-1. Enter the **Package name**, and **Signature hash**.
+1. Enter the **Package name** and **Signature hash**.
1. Select **Save**. Your redirect URI and the `BrowserTabActivity` activity should look similar to the following sample: #### [Kotlin](#tab/kotlin)
-The redirect URL for the sample Android:
+The redirect URL for the sample Android looks like this:
``` msauth://com.azuresamples.msalandroidkotlinapp/1wIqXSqBj7w%2Bh11ZifsnqwgyKrY%3D ```
-Then the intent filter uses the same pattern, as in the following XML snippet:
+The intent filter uses the same pattern, as shown in the following XML snippet:
```xml <activity android:name="com.microsoft.identity.client.BrowserTabActivity">
Then the intent filter uses the same pattern, as in the following XML snippet:
#### [Java](#tab/java)
-The redirect URL for the sample Android:
+The redirect URL for the sample Android looks like this:
``` msauth://com.azuresamples.msalandroidapp/1wIqXSqBj7w%2Bh11ZifsnqwgyKrY%3D ```
-Then the intent filter uses the same pattern, as in the following XML snippet:
+The intent filter uses the same pattern, as shown in the following XML snippet:
```xml <activity android:name="com.microsoft.identity.client.BrowserTabActivity">
Then the intent filter uses the same pattern, as in the following XML snippet:
-## Code building blocks
+## Step 5: Customize your code building blocks
-This section describes the code building blocks that enable the authentication for your Android app. The following table lists the B2CModeFragment's methods and how to customize your code.
+This section describes the code building blocks that enable authentication for your Android app. The following table lists the B2CModeFragment methods and how to customize your code.
-### Instantiate a public client application
+### Step 5.1: Instantiate a public client application
-Public client applications are not trusted to safely keep application secrets and they don't have client secrets. In the [onCreate](https://developer.android.com/reference/android/app/Fragment#onCreate(android.os.Bundle)), or [onCreateView](https://developer.android.com/reference/android/app/Fragment#onCreateView(android.view.LayoutInflater,%20android.view.ViewGroup,%20android.os.Bundle)) instantiate MSAL using the multiple account public client application object.
+Public client applications aren't trusted to safely keep application secrets, and they don't have client secrets. In [onCreate](https://developer.android.com/reference/android/app/Fragment#onCreate(android.os.Bundle)) or [onCreateView](https://developer.android.com/reference/android/app/Fragment#onCreateView(android.view.LayoutInflater,%20android.view.ViewGroup,%20android.os.Bundle)), instantiate the MSAL by using the multiple-account public client application object.
-The `MultipleAccountPublicClientApplication` class is used to create MSAL-based apps that allow multiple accounts to be signed in at the same time. It allows sign-in with multiple Azure AD B2C user flows or custom policies. For example, a user signs-in with a [sign-up or sign-in](add-sign-up-and-sign-in-policy.md) user flow, and later runs an [edit profile](add-profile-editing-policy.md) user flow.
+The `MultipleAccountPublicClientApplication` class is used to create MSAL-based apps that allow multiple accounts to be signed in at the same time. The class allows sign-in with multiple Azure AD B2C user flows or custom policies. For example, users sign in with a [sign-up or sign-in](add-sign-up-and-sign-in-policy.md) user flow and later, they run an [edit profile](add-profile-editing-policy.md) user flow.
The following code snippet demonstrates how to initiate the MSAL library with the `auth_config_b2c.json` configuration JSON file.
PublicClientApplication.createMultipleAccountPublicClientApplication(getContext(
-### Load accounts
+### Step 5.2: Load accounts
-When the app comes to the foreground, the app loads the existing account to determine if the user is signed in or not. Use this method to update the UI with the authentication state. For example, enable or disable the sign-out button.
+When the app comes to the foreground, the app loads the existing account to determine whether users are signed in. Use this method to update the UI with the authentication state. For example, you can enable or disable the sign-out button.
The following code snippet demonstrates how to load the accounts.
private void loadAccounts() {
-### Interactive authorization request
+### Step 5.3: Start an interactive authorization request
-An interactive authorization request is a flow where the user is prompted for sign-up or sign-in. The `initializeUI` method configures the `runUserFlowButton` click event. When the user selects the **RUN USER FLOW** button, the app takes the user to Azure AD B2C to complete the sign-in flow.
+An interactive authorization request is a flow where users are prompted to sign up or sign in. The `initializeUI` method configures the `runUserFlowButton` click event. When users select the **Run User Flow** button, the app takes them to Azure AD B2C to complete the sign-in flow.
-The `runUserFlowButton.setOnClickListener` method prepares the `AcquireTokenParameters` object with relevant data about the authorization request. Then the `acquireToken` method prompts the user to complete the sign-up or sign-in flow.
+The `runUserFlowButton.setOnClickListener` method prepares the `AcquireTokenParameters` object with relevant data about the authorization request. The `acquireToken` method then prompts users to complete the sign-up or sign-in flow.
-The following code snippet demonstrates how to start the interactive authorization request.
+The following code snippet demonstrates how to start the interactive authorization request:
#### [Kotlin](#tab/kotlin)
b2cApp.acquireToken(parameters);
-### Interactive authorization request callback
+### Step 5.4: Make an interactive authorization request callback
-Once the user finishes the authorization flow (successfully or unsuccessfully), the result is returned to the `getAuthInteractiveCallback()` callback method.
+After users finish the authorization flow, whether successfully or unsuccessfully, the result is returned to the `getAuthInteractiveCallback()` callback method.
The callback method passes the `AuthenticationResult` object, or an error message in the `MsalException` object. Use this method to: -- Update the mobile app UI with information after the sign-in has completed-- Reload the accounts object-- Call a web API service with an access token-- Handle authentication errors
+- Update the mobile app UI with information after the sign-in has finished.
+- Reload the accounts object.
+- Call a web API service with an access token.
+- Handle authentication errors.
The following code snippet demonstrates the use of the interactive authentication callback.
private val authInteractiveCallback: AuthenticationCallback
val B2C_PASSWORD_CHANGE = "AADB2C90118" if (exception.message!!.contains(B2C_PASSWORD_CHANGE)) { txt_log!!.text = """
- The user clicks the 'Forgot Password' link in a sign-up or sign-in user flow.
+ Users click the 'Forgot Password' link in a sign-up or sign-in user flow.
Your application needs to handle this error code by running a specific user flow that resets the password. """.trimIndent() return
private AuthenticationCallback getAuthInteractiveCallback() {
public void onError(MsalException exception) { final String B2C_PASSWORD_CHANGE = "AADB2C90118"; if (exception.getMessage().contains(B2C_PASSWORD_CHANGE)) {
- logTextView.setText("The user clicks the 'Forgot Password' link in a sign-up or sign-in user flow.\n" +
+ logTextView.setText("Users click the 'Forgot Password' link in a sign-up or sign-in user flow.\n" +
"Your application needs to handle this error code by running a specific user flow that resets the password."); return; }
private AuthenticationCallback getAuthInteractiveCallback() {
-## Call a web API
+## Step 6: Call a web API
-To call a [token-based authorization web API](enable-authentication-web-api.md), the app needs to have a valid access token. The app takes the following steps:
+To call a [token-based authorization web API](enable-authentication-web-api.md), the app needs to have a valid access token. The app does the following:
1. Acquires an access token with the required permissions (scopes) for the web API endpoint.
-1. Passes the access token as a bearer token in the authorization header of the HTTP request using this format:
+1. Passes the access token as a bearer token in the authorization header of the HTTP request by using this format:
```http Authorization: Bearer <access-token> ```
-When users [sign in interactively](#interactive-authorization-request), the app gets an access token in the `getAuthInteractiveCallback` callback method. For consecutive web API calls, use the acquire token silent procedure as described in this section.
+When users [sign in interactively](#step-53-start-an-interactive-authorization-request), the app gets an access token in the `getAuthInteractiveCallback` callback method. For consecutive web API calls, use the acquire token silent procedure as described in this section.
-Before calling a web API, call the `acquireTokenSilentAsync` method with the appropriate scopes for your web API endpoint. The MSAL library takes the following steps:
+Before you call a web API, call the `acquireTokenSilentAsync` method with the appropriate scopes for your web API endpoint. The MSAL library does the following:
1. Attempts to fetch an access token with the requested scopes from the token cache. If the token is present, the token is returned. 1. If the token isn't present in the token cache, MSAL attempts to use its refresh token to acquire a new token.
-1. If the refresh token doesn't exist or has expired, an exception is returned. It's recommended to prompt the user to [sign in interactively](#interactive-authorization-request).
+1. If the refresh token doesn't exist or has expired, an exception is returned. We recommend that you prompt the user to [sign in interactively](#step-53-start-an-interactive-authorization-request).
The following code snippet demonstrates how to acquire an access token:
private void callWebAPI(IAuthenticationResult authenticationResult) throws Excep
### Add permission to perform network operations
-To perform network operations in your application, include the following permission to your manifest. For more information, see [Connect to the network](https://developer.android.com/training/basics/network-ops/connecting).
+To perform network operations in your application, add the following permission to your manifest. For more information, see [Connect to the network](https://developer.android.com/training/basics/network-ops/connecting).
```xml <uses-permission android:name="android.permission.INTERNET"/>
To perform network operations in your application, include the following permiss
## Next steps
-* [Configure authentication options in an Android application](enable-authentication-android-app-options.md)
-* [Enable authentication in your own web API](enable-authentication-web-api.md)
+Learn how to:
+* [Configure authentication options in an Android app by using Azure AD B2C](enable-authentication-android-app-options.md)
+* [Enable authentication in your own web API by using Azure AD B2C](enable-authentication-web-api.md)
active-directory-b2c Enable Authentication Ios App Options https://github.com/MicrosoftDocs/azure-docs/commits/master/articles/active-directory-b2c/enable-authentication-ios-app-options.md
Title: Enable iOS Swift mobile application options using Azure Active Directory B2C
-description: Enable the use of iOS Swift mobile application options by using several ways.
+ Title: Enable iOS Swift mobile application options by using Azure Active Directory B2C
+description: This article discusses several ways to enable iOS Swift mobile application options by using Azure Active Directory B2C.
-# Configure authentication options in an iOS Swift application using Azure Active Directory B2C
+# Enable authentication options in an iOS Swift app by using Azure AD B2C
-This article describes ways you can customize and enhance the Azure Active Directory B2C (Azure AD B2C) authentication experience for your iOS Swift application. Before you start, familiarize yourself with the following articles: [Configure authentication in a sample iOS Swift application](configure-authentication-sample-ios-app.md) and [Enable authentication in your own iOS Swift app using Azure Active Directory B2C](enable-authentication-ios-app.md).
+This article describes ways you can enable, customize, and enhance the Azure Active Directory B2C (Azure AD B2C) authentication experience for your iOS Swift application.
+
+Before you start, familiarize yourself with the following articles:
+* [Configure authentication in a sample iOS Swift app by using Azure AD B2C](configure-authentication-sample-ios-app.md)
+* [Enable authentication in your own iOS Swift app by using Azure AD B2C](enable-authentication-ios-app.md)
[!INCLUDE [active-directory-b2c-app-integration-custom-domain](../../includes/active-directory-b2c-app-integration-custom-domain.md)]
-To use a custom domain and your tenant ID in the authentication URL:
+To use a custom domain and your tenant ID in the authentication URL, do the following:
1. Follow the guidance in [Enable custom domains](custom-domain.md). 1. Update the `kAuthorityHostName` class member with your custom domain.
let kTenantName = "contoso.onmicrosoft.com"
let kAuthorityHostName = "contoso.b2clogin.com" ```
-The following JSON shows the app settings after the change:
+The following Swift code shows the app settings after the change:
```swift let kTenantName = "00000000-0000-0000-0000-000000000000"
let kAuthorityHostName = "login.contoso.com"
[!INCLUDE [active-directory-b2c-app-integration-login-hint](../../includes/active-directory-b2c-app-integration-login-hint.md)]
-1. If you're using a custom policy, add the required input claim as described in [Set up direct sign-in](direct-signin.md#prepopulate-the-sign-in-name).
-1. Find your MSAL configuration object and add the **withLoginHint()** method with the login hint.
+1. If you're using a custom policy, add the required input claim, as described in [Set up direct sign-in](direct-signin.md#prepopulate-the-sign-in-name).
+1. Look for your Microsoft Authentication Library (MSAL) configuration object, and then add the `withLoginHint()` method with the login hint.
```swift
-let parameters = MSALInteractiveTokenParameters(scopes: kScopes, webviewParameters: self.webViewParamaters!)
+let parameters = MSALInteractiveTokenParameters(scopes: kScopes, webviewParameters: self.webViewParameters!)
parameters.promptType = .selectAccount parameters.authority = authority parameters.loginHint = "bob@contoso.com"
applicationContext.acquireToken(with: parameters) { (result, error) in
1. Check the domain name of your external identity provider. For more information, see [Redirect sign-in to a social provider](direct-signin.md#redirect-sign-in-to-a-social-provider). 1. Create or use an existing list object to store extra query parameters.
-1. Add the `domain_hint` parameter with the corresponding domain name to the list. For example, `facebook.com`.
+1. Add the `domain_hint` parameter with the corresponding domain name to the list (for example, `facebook.com`).
1. Pass the extra query parameters list into the MSAL configuration object's `extraQueryParameters` attribute. ```swift let extraQueryParameters: [String: String] = ["domain_hint": "facebook.com"]
-let parameters = MSALInteractiveTokenParameters(scopes: kScopes, webviewParameters: self.webViewParamaters!)
+let parameters = MSALInteractiveTokenParameters(scopes: kScopes, webviewParameters: self.webViewParameters!)
parameters.promptType = .selectAccount parameters.authority = authority parameters.extraQueryParameters = extraQueryParameters
applicationContext.acquireToken(with: parameters) { (result, error) in
[!INCLUDE [active-directory-b2c-app-integration-ui-locales](../../includes/active-directory-b2c-app-integration-ui-locales.md)]
-1. [Configure Language customization](language-customization.md).
+1. [Configure language customization](language-customization.md).
1. Create or use an existing list object to store extra query parameters.
-1. Add the `ui_locales` parameter with the corresponding language code to the list. For example, `en-us`.
+1. Add the `ui_locales` parameter with the corresponding language code to the list (for example, `en-us`).
1. Pass the extra query parameters list into the MSAL configuration object's `extraQueryParameters` attribute. ```swift let extraQueryParameters: [String: String] = ["ui_locales": "en-us"]
-let parameters = MSALInteractiveTokenParameters(scopes: kScopes, webviewParameters: self.webViewParamaters!)
+let parameters = MSALInteractiveTokenParameters(scopes: kScopes, webviewParameters: self.webViewParameters!)
parameters.promptType = .selectAccount parameters.authority = authority parameters.extraQueryParameters = extraQueryParameters
applicationContext.acquireToken(with: parameters) { (result, error) in
1. Configure the [ContentDefinitionParameters](customize-ui-with-html.md#configure-dynamic-custom-page-content-uri) element. 1. Create or use an existing list object to store extra query parameters.
-1. Add the custom query string parameter, such as `campaignId`. Set the parameter value. For example, `germany-promotion`.
+1. Add the custom query string parameter, such as `campaignId`. Set the parameter value (for example, `germany-promotion`).
1. Pass the extra query parameters list into the MSAL configuration object's `extraQueryParameters` attribute. ```swift let extraQueryParameters: [String: String] = ["campaignId": "germany-promotion"]
-let parameters = MSALInteractiveTokenParameters(scopes: kScopes, webviewParameters: self.webViewParamaters!)
+let parameters = MSALInteractiveTokenParameters(scopes: kScopes, webviewParameters: self.webViewParameters!)
parameters.promptType = .selectAccount parameters.authority = authority parameters.extraQueryParameters = extraQueryParameters
applicationContext.acquireToken(with: parameters) { (result, error) in
[!INCLUDE [active-directory-b2c-app-integration-id-token-hint](../../includes/active-directory-b2c-app-integration-id-token-hint.md)] 1. In your custom policy, define an [ID token hint technical profile](id-token-hint.md).
-1. In your code, generate or acquire an ID token, and set the token to a variable. For example, `idToken`.
+1. In your code, generate or acquire an ID token, and then set the token to a variable (for example, `idToken`).
1. Create or use an existing list object to store extra query parameters. 1. Add the `id_token_hint` parameter with the corresponding variable that stores the ID token. 1. Pass the extra query parameters list into the MSAL configuration object's `extraQueryParameters` attribute.
applicationContext.acquireToken(with: parameters) { (result, error) in
```swift let extraQueryParameters: [String: String] = ["id_token_hint": idToken]
-let parameters = MSALInteractiveTokenParameters(scopes: kScopes, webviewParameters: self.webViewParamaters!)
+let parameters = MSALInteractiveTokenParameters(scopes: kScopes, webviewParameters: self.webViewParameters!)
parameters.promptType = .selectAccount parameters.authority = authority parameters.extraQueryParameters = extraQueryParameters
applicationContext.acquireToken(with: parameters) { (result, error) in
[!INCLUDE [active-directory-b2c-app-integration-logging](../../includes/active-directory-b2c-app-integration-logging.md)]
-The MSAL Logger should be set as early as possible in the app launch sequence, before any MSAL requests are made. Configure MSAL [logging](../active-directory/develop/msal-logging-ios.md) in the *AppDelegate.swift* `application` method.
+The MSAL logger should be set as early as possible in the app launch sequence, before any MSAL requests are made. Configure MSAL [logging](../active-directory/develop/msal-logging-ios.md) in the *AppDelegate.swift* `application` method.
The following code snippet demonstrates how to configure MSAL logging:
func application(_ application: UIApplication, didFinishLaunchingWithOptions lau
} ```
-## Embedded webview experience
+## Embedded web view experience
-Web browsers are required for interactive authentication. By default, the MSAL library uses the system webview. During sign-in, the MSAL library pops up the iOS system webview with the Azure AD B2C user interface.
+Web browsers are required for interactive authentication. By default, the MSAL library uses the system web view. During sign-in, the MSAL library pops up the iOS system web view with the Azure AD B2C user interface.
For more information, see the [Customize browsers and WebViews for iOS/macOS](../active-directory/develop/customize-webviews.md) article.
-Depending on your requirements, you can use the embedded webview. There are visual and single sign-on behavior differences between the embedded webview and the system webview in MSAL.
+Depending on your requirements, you can use the embedded web view. There are visual and single sign-on behavior differences between the embedded web view and the system web view in MSAL.
-![Screenshot demonstrates the different between the system webview experience and the embedded webview experience.](./media/enable-authentication-ios-app-options/system-web-browser-vs-embedded-view.png)
+![Screenshot demonstrating the difference between the system web view experience and the embedded web view experience.](./media/enable-authentication-ios-app-options/system-web-browser-vs-embedded-view.png)
> [!IMPORTANT]
-> It's recommended that you use the platform default, which is typically the system browser. The system browser is better at remembering the users that have logged in before. Some identity providers, such as Google, don't support an embedded view experience.
+> We recommend that you use the platform default, which is ordinarily the system browser. The system browser is better at remembering the users that have logged in before. Some identity providers, such as Google, don't support an embedded view experience.
-To change this behavior, change the `webviewType` attribute of the `MSALWebviewParameters` to `wkWebView`. The following example demonstrates how to change the webview type to embedded view.
+To change this behavior, change the `webviewType` attribute of `MSALWebviewParameters` to `wkWebView`. The following example demonstrates how to change the web view type to embedded view:
```swift func initWebViewParams() {
- self.webViewParamaters = MSALWebviewParameters(authPresentationViewController: self)
+ self.webViewParameters = MSALWebviewParameters(authPresentationViewController: self)
// Use embedded view experience
- self.webViewParamaters?.webviewType = .wkWebView
+ self.webViewParameters?.webviewType = .wkWebView
} ``` ## Next steps -- Learn more: [MSAL for iOS Swift configuration options](https://github.com/AzureAD/microsoft-authentication-library-for-objc/wiki)
+- To learn more, see [MSAL for iOS Swift configuration options](https://github.com/AzureAD/microsoft-authentication-library-for-objc/wiki).
active-directory-b2c Enable Authentication Ios App https://github.com/MicrosoftDocs/azure-docs/commits/master/articles/active-directory-b2c/enable-authentication-ios-app.md
Title: Enable authentication in an iOS Swift app - Azure AD B2C
-description: Enable authentication in an iOS Swift application using Azure Active Directory B2C building blocks. Learn how to use Azure AD B2C to sign in and sign up users in an iOS Swift application.
+ Title: Enable authentication in an iOS Swift app by using Azure AD B2C
+description: This article discusses how to enable authentication in an iOS Swift application by using Azure Active Directory B2C building blocks. Learn how to use Azure AD B2C to sign in and sign up users in an iOS Swift application.
-# Enable authentication in your own iOS Swift application using Azure Active Directory B2C
+# Enable authentication in your own iOS Swift app by using Azure AD B2C
-This article shows you how to add Azure Active Directory B2C (Azure AD B2C) authentication to your own iOS Swift mobile application. Learn how to integrate an iOS Swift application with the [MSAL for iOS](https://github.com/AzureAD/microsoft-authentication-library-for-objc) authentication library.
+This article shows you how to add Azure Active Directory B2C (Azure AD B2C) authentication to your own iOS Swift mobile application. Learn how to integrate an iOS Swift application with the [Microsoft Authentication Library (MSAL) for iOS](https://github.com/AzureAD/microsoft-authentication-library-for-objc).
-Use this article with [Configure authentication in a sample iOS Swift application](./configure-authentication-sample-ios-app.md), substituting the sample iOS Swift app with your own iOS Swift app. After completing the steps in this article, your application will accept sign-ins via Azure AD B2C.
+Use this article with [Configure authentication in a sample iOS Swift application](./configure-authentication-sample-ios-app.md), substituting the sample iOS Swift app with your own iOS Swift app. After you've completed the instructions in this article, your application will accept sign-ins via Azure AD B2C.
## Prerequisites
-Review the prerequisites and integration steps in [Configure authentication in a sample iOS Swift application](configure-authentication-sample-ios-app.md) article.
+Review the prerequisites and integration instructions in [Configure authentication in a sample iOS Swift app by using Azure AD B2C](configure-authentication-sample-ios-app.md).
## Create an iOS Swift app project
-If you don't already have an iOS Swift application, follow these steps to set up a new project.
+If you don't already have an iOS Swift application, set up a new project by doing the following:
-1. Open [Xcode](https://developer.apple.com/xcode/) and select **File** > **New** > **Project**.
-1. For iOS apps, select **iOS** > **App** and select **Next**.
-1. For the **Choose options for your new project**, provide the following:
+1. Open [Xcode](https://developer.apple.com/xcode/), and then select **File** > **New** > **Project**.
+1. For iOS apps, select **iOS** > **App**, and then select **Next**.
+1. For **Choose options for your new project**, provide the following:
1. **Product name**, such as `MSALiOS`. 1. **Organization identifier**, such as `contoso.com`. 1. For the **Interface**, select **Storyboard**. 1. For the **Life cycle**, select **UIKit App Delegate**. 1. For the **Language**, select **Swift**. 1. Select **Next**.
-1. Select a folder to create your app and select **Create**.
+1. Select a folder in which to create your app, and then select **Create**.
-## Install the MSAL library
+## Step 1: Install the MSAL library
-1. Use [CocoaPods](https://cocoapods.org/) to install the MSAL library. In the same folder as your project's `.xcodeproj` file, if the `podfile` file doesn't exist, create an empty file called `podfile`. Add the following code to the `podfile` file:
+1. Use [CocoaPods](https://cocoapods.org/) to install the MSAL library. In the same folder as your project's *.xcodeproj* file, if the *podfile* file doesn't exist, create an empty file called *podfile*. Add the following code to the *podfile* file:
``` use_frameworks!
If you don't already have an iOS Swift application, follow these steps to set up
end ```
-1. Replace `<your-target-here>` with the name of your project. For example, `MSALiOS`. For more information, see [Podfile Syntax Reference](https://guides.cocoapods.org/syntax/podfile.html#podfile).
-1. In a terminal window, navigate to the folder that contains the `podfile` file. Run `pod install` to install the MSAL library.
-1. After you run the `pod install` command, a `<your project name>.xcworkspace` file is created. To reload the project in Xcode, close Xcode and open `<your project name>.xcworkspace`.
+1. Replace `<your-target-here>` with the name of your project (for example, `MSALiOS`). For more information, see [Podfile Syntax Reference](https://guides.cocoapods.org/syntax/podfile.html#podfile).
+1. In a terminal window, go to the folder that contains the *podfile* file, and then run *pod install* to install the MSAL library.
+1. After you run the `pod install` command, a *\<your project name>.xcworkspace* file is created. To reload the project in Xcode, close Xcode, and then open the *\<your project name>.xcworkspace* file.
-## Set the app URL scheme
+## Step 2: Set the app URL scheme
-When a user authenticates, Azure AD B2C sends an authorization code to the app by using the redirect URI configured on the Azure AD B2C application registration.
+When users authenticate, Azure AD B2C sends an authorization code to the app by using the redirect URI configured on the Azure AD B2C application registration.
-The MSAL default redirect URI format is `msauth.[Your_Bundle_Id]://auth`. For example, `msauth.com.microsoft.identitysample.MSALiOS://auth`, where `msauth.com.microsoft.identitysample.MSALiOS` is the URL scheme.
+The MSAL default redirect URI format is `msauth.[Your_Bundle_Id]://auth`. An example would be `msauth.com.microsoft.identitysample.MSALiOS://auth`, where `msauth.com.microsoft.identitysample.MSALiOS` is the URL scheme.
-In this step, register your URL scheme using the `CFBundleURLSchemes` array. Your application listens on the URL scheme for the callback from Azure AD B2C.
+In this step, register your URL scheme by using the `CFBundleURLSchemes` array. Your application listens on the URL scheme for the callback from Azure AD B2C.
-In Xcode, open the [Info.plist file](https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Introduction/Introduction.html) as a source code file. Add the following XML snippet inside of the `<dict>` section.
+In Xcode, open the [*Info.plist* file](https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Introduction/Introduction.html) as a source code file. In the `<dict>` section, add the following XML snippet:
```xml <key>CFBundleURLTypes</key>
In Xcode, open the [Info.plist file](https://developer.apple.com/library/archive
</array> ```
-## Add the authentication code
+## Step 3: Add the authentication code
The [sample code](configure-authentication-sample-ios-app.md#step-4-get-the-ios-mobile-app-sample) is made up of a `UIViewController` class. The class: - Defines the structure for a user interface. - Contains information about your Azure AD B2C identity provider. The app uses this information to establish a trust relationship with Azure AD B2C. -- Contains the authentication code to authenticates users, acquires tokens, and validates them.
+- Contains the authentication code to authenticate users, acquire tokens, and validate them.
-Choose a `UIViewController` where the users will authenticate. Merge the code with the one [provided here](https://github.com/Azure-Samples/active-directory-b2c-ios-swift-native-msal/blob/vNext/MSALiOS/ViewController.swift) into your `UIViewController`.
+Choose a `UIViewController` where users will authenticate. In your `UIViewController`, merge the code with the [code that's provided in GitHub](https://github.com/Azure-Samples/active-directory-b2c-ios-swift-native-msal/blob/vNext/MSALiOS/ViewController.swift).
-## Configure your iOS Swift app
+## Step 4: Configure your iOS Swift app
-After you [add the authentication code](#add-the-authentication-code), configure your iOS Swift app with your Azure AD B2C settings. Azure AD B2C identity provider settings are configured in the `UIViewController` class chosen in the previous section.
+After you [add the authentication code](#step-3-add-the-authentication-code), configure your iOS Swift app with your Azure AD B2C settings. Azure AD B2C identity provider settings are configured in the `UIViewController` class that was chosen in the previous section.
-Follow the guidance for how to [Configure the sample mobile app](configure-authentication-sample-ios-app.md#step-5-configure-the-sample-mobile-app).
+To learn how to configure your iOS Swift app, see [Configure authentication in a sample iOS Swift app by using Azure AD B2C](configure-authentication-sample-ios-app.md#step-5-configure-the-sample-mobile-app).
-## Run and test the mobile app
+## Step 5: Run and test the mobile app
1. Build and run the project with a [simulator of a connected iOS device](https://developer.apple.com/documentation/xcode/running-your-app-in-the-simulator-or-on-a-device).
-1. Select **Sign In**. Then sign up or sign in with your Azure AD B2C local or social account.
-1. After successful authentication, you'll see your display name in the navigation bar.
+1. Select **Sign In**, and then sign up or sign in with your Azure AD B2C local or social account.
+1. After you've authenticated successfully, you'll see your display name in the navigation bar.
-## How it works?
+## Step 6: Customize your code building blocks
-This section describes the code building blocks that enable the authentication for your iOS Swift app. It lists the UIViewController's methods and how to customize your code.
+This section describes the code building blocks that enable authentication for your iOS Swift app. It lists the UIViewController's methods and discusses how to customize your code.
-### Instantiate a public client application
+### Step 6.1: Instantiate a public client application
-Public client applications are not trusted to safely keep application secrets, and they don't have client secrets. In [viewDidLoad](https://developer.apple.com/documentation/uikit/uiviewcontroller/1621495-viewdidload), instantiate MSAL using a public client application object.
+Public client applications aren't trusted to safely keep application secrets, and they don't have client secrets. In [viewDidLoad](https://developer.apple.com/documentation/uikit/uiviewcontroller/1621495-viewdidload), instantiate an MSAL by using a public client application object.
-The following code snippet demonstrates how to initialize the MSAL library with a `MSALPublicClientApplicationConfig` configuration object.
+The following Swift code snippet demonstrates how to initialize the MSAL with a `MSALPublicClientApplicationConfig` configuration object.
-The configuration object provides information about your Azure AD B2C environment, for example, the client ID, redirect URI, and authority to build authentication requests to Azure AD B2C. For information about the configuration object, see [Configure the sample mobile app](configure-authentication-sample-ios-app.md#step-5-configure-the-sample-mobile-app).
+The configuration object provides information about your Azure AD B2C environment. For example, it provides the client ID, redirect URI, and authority to build authentication requests to Azure AD B2C. For information about the configuration object, see [Configure the sample mobile app](configure-authentication-sample-ios-app.md#step-5-configure-the-sample-mobile-app).
```swift do {
- let siginPolicyAuthority = try self.getAuthority(forPolicy: self.kSignupOrSigninPolicy)
+ let signinPolicyAuthority = try self.getAuthority(forPolicy: self.kSignupOrSigninPolicy)
let editProfileAuthority = try self.getAuthority(forPolicy: self.kEditProfilePolicy)
- let pcaConfig = MSALPublicClientApplicationConfig(clientId: kClientID, redirectUri: kRedirectUri, authority: siginPolicyAuthority)
- pcaConfig.knownAuthorities = [siginPolicyAuthority, editProfileAuthority]
+ let pcaConfig = MSALPublicClientApplicationConfig(clientId: kClientID, redirectUri: kRedirectUri, authority: signinPolicyAuthority)
+ pcaConfig.knownAuthorities = [signinPolicyAuthority, editProfileAuthority]
self.applicationContext = try MSALPublicClientApplication(configuration: pcaConfig) self.initWebViewParams()
do {
The `initWebViewParams` method configures the [interactive authentication](../active-directory/develop/customize-webviews.md) experience.
-The following Swift code snippet initializes the `webViewParamaters` class member with the system webview. For more information, see the [Customize browsers and WebViews for iOS/macOS](../active-directory/develop/customize-webviews.md) article.
+The following Swift code snippet initializes the `webViewParameters` class member with the system web view. For more information, see [Customize browsers and WebViews for iOS/macOS](../active-directory/develop/customize-webviews.md).
```swift func initWebViewParams() {
- self.webViewParamaters = MSALWebviewParameters(authPresentationViewController: self)
- self.webViewParamaters?.webviewType = .default
+ self.webViewParameters = MSALWebviewParameters(authPresentationViewController: self)
+ self.webViewParameters?.webviewType = .default
} ```
-### Interactive authorization request
+### Step 6.2: Start an interactive authorization request
-An interactive authorization request is a flow where the user is prompted for sign-up or sign-in using the system webview. When the user clicks on the **Sign In** button, the `authorizationButton` method is called.
+An interactive authorization request is a flow where users are prompted to sign up or sign in by using the system web view. When users select the **Sign In** button, the `authorizationButton` method is called.
-The `authorizationButton` method prepares the `MSALInteractiveTokenParameters` object with relevant data about the authorization request. The `acquireToken` method uses the `MSALInteractiveTokenParameters` to authenticate the user using the system webview.
+The `authorizationButton` method prepares the `MSALInteractiveTokenParameters` object with relevant data about the authorization request. The `acquireToken` method uses the `MSALInteractiveTokenParameters` to authenticate users via the system web view.
-The following code snippet demonstrates how to start the interactive authorization request.
+The following code snippet demonstrates how to start the interactive authorization request:
```swift
-let parameters = MSALInteractiveTokenParameters(scopes: kScopes, webviewParameters: self.webViewParamaters!)
+let parameters = MSALInteractiveTokenParameters(scopes: kScopes, webviewParameters: self.webViewParameters!)
parameters.promptType = .selectAccount parameters.authority = authority
applicationContext.acquireToken(with: parameters) { (result, error) in
// On error code guard let result = result else {
- self.updateLoggingText(text: "Could not acquire token: \(error ?? "No error informarion" as! Error)")
+ self.updateLoggingText(text: "Could not acquire token: \(error ?? "No error information" as! Error)")
return }
self.updateLoggingText(text: "Access token is \(self.accessToken ?? "Empty")")
} ```
-Once the user finishes the authorization flow (successfully or unsuccessfully), the result is returned to the [closure](https://docs.swift.org/swift-book/LanguageGuide/Closures.html) of the `acquireToken` method.
+After users finish the authorization flow, either successfully or unsuccessfully, the result is returned to the [closure](https://docs.swift.org/swift-book/LanguageGuide/Closures.html) of the `acquireToken` method.
-The acquireToken method returns the `result` and `error` objects. Use this closure to:
+The `acquireToken` method returns the `result` and `error` objects. Use this closure to:
- Update the mobile app UI with information after the authentication is completed. - Call a web API service with an access token.-- Handle authentication errors, for example, when a user cancels the sign-in flow.
+- Handle authentication errors (for example, when a user cancels the sign-in flow).
-### Call a web API
+### Step 6.3: Call a web API
-To call a [token-based authorization web API](enable-authentication-web-api.md), the app needs a valid access token. The app takes the following steps:
+To call a [token-based authorization web API](enable-authentication-web-api.md), the app needs a valid access token. The app does the following:
1. Acquires an access token with the required permissions (scopes) for the web API endpoint.
-1. Passes the access token as a bearer token in the authorization header of the HTTP request using this format:
+1. Passes the access token as a bearer token in the authorization header of the HTTP request by using this format:
```http Authorization: Bearer <access-token> ```
-When users [authenticate interactively](#interactive-authorization-request), the app gets an access token in the `acquireToken` closure. For subsequent web API calls, use the acquire token silent (`acquireTokenSilent`) method as described in this section.
+When users [authenticate interactively](#step-62-start-an-interactive-authorization-request), the app gets an access token in the `acquireToken` closure. For subsequent web API calls, use the acquire token silent (`acquireTokenSilent`) method, as described in this section.
-The `acquireTokenSilent` method takes the following steps:
+The `acquireTokenSilent` method does the following:
-1. Attempts to fetch an access token with the requested scopes from the token cache. If the token is present and not expired, the token is returned.
-1. If the token isn't present in the token cache or has expired, the MSAL library attempts to use the refresh token to acquire a new access token.
-1. If the refresh token doesn't exist or has expired, an exception is returned. In this case, you should prompt the user to [sign in interactively](#interactive-authorization-request).
+1. It attempts to fetch an access token with the requested scopes from the token cache. If the token is present and hasn't expired, the token is returned.
+1. If the token isn't present in the token cache or it has expired, the MSAL library attempts to use the refresh token to acquire a new access token.
+1. If the refresh token doesn't exist or has expired, an exception is returned. In this case, you should prompt the user to [sign in interactively](#step-62-start-an-interactive-authorization-request).
The following code snippet demonstrates how to acquire an access token:
self.updateLoggingText(text: "Unable to construct parameters before calling acqu
} ```
-The `callGraphAPI` method retrieves the access token and calls the web API.
+The `callGraphAPI` method retrieves the access token and calls the web API, as shown here:
```swift @objc func callGraphAPI(_ sender: UIButton) {
The `callGraphAPI` method retrieves the access token and calls the web API.
urlSession.dataTask(with: request) { data, response, error in guard let validData = data else {
- self.updateLoggingText(text: "Could not call API: \(error ?? "No error informarion" as! Error)")
+ self.updateLoggingText(text: "Could not call API: \(error ?? "No error information" as! Error)")
return }
The `callGraphAPI` method retrieves the access token and calls the web API.
} ```
-### Sign-out
+### Step 6.4: Sign out users
-Signing out with MSAL removes all known information about a user from the application. Use the sign-out method to sign out users and update the UI. For example, hide protected UI elements and the sign-out button, and show the sign-in button.
+Signing out with MSAL removes all known information about users from the application. Use the sign-out method to sign out users and update the UI. For example, you can hide protected UI elements, hide the sign-out button, or show the sign-in button.
-The following code snippet demonstrates how to sign-out a user:
+The following code snippet demonstrates how to sign out users:
```swift @objc func signoutButton(_ sender: UIButton) {
do {
## Next steps
-* [Configure authentication options in an iOS Swift application](enable-authentication-ios-app-options.md)
-* [Enable authentication in your own web API](enable-authentication-web-api.md)
+Learn how to:
+* [Configure authentication options in an iOS Swift app by using Azure AD B2C](enable-authentication-ios-app-options.md)
+* [Enable authentication in your own web API by using Azure AD B2C](enable-authentication-web-api.md)
active-directory-b2c Enable Authentication Python Web App Options https://github.com/MicrosoftDocs/azure-docs/commits/master/articles/active-directory-b2c/enable-authentication-python-web-app-options.md
Title: Enable Python web application options using Azure Active Directory B2C
-description: Enable the use of Python web application options by using several ways.
+ Title: Enable Python web application options by using Azure Active Directory B2C
+description: This article shows you how to enable the use of Python web application options.
-# Configure authentication options in a Python web application using Azure Active Directory B2C
+# Enable authentication options in a Python web app by using Azure AD B2C
-This article describes ways you can customize and enhance the Azure Active Directory B2C (Azure AD B2C) authentication experience for your Python web application.
+This article describes how to enable, customize, and enhance the Azure Active Directory B2C (Azure AD B2C) authentication experience for your Python web application.
-Before you start, it is important to familiarize yourself with the [Configure authentication in a sample Python web application](configure-authentication-sample-python-web-app.md) article.
+Before you start, it's important to familiarize yourself with how to [Configure authentication in a sample Python web app by using Azure AD B2C](configure-authentication-sample-python-web-app.md).
[!INCLUDE [active-directory-b2c-app-integration-custom-domain](../../includes/active-directory-b2c-app-integration-custom-domain.md)]
authority_template = "https://custom.domain.com/00000000-0000-0000-0000-00000000
[!INCLUDE [active-directory-b2c-app-integration-login-hint](../../includes/active-directory-b2c-app-integration-login-hint.md)] 1. If you're using a custom policy, add the required input claim as described in [Set up direct sign-in](direct-signin.md#prepopulate-the-sign-in-name).
-1. Find the `initiate_auth_code_flow` method and add the `login_hint` parameter with the identity provider domain name. For example, facebook.com.
+1. Find the `initiate_auth_code_flow` method, and then add the `login_hint` parameter with the identity provider domain name (for example, *facebook.com*).
```python def _build_auth_code_flow(authority=None, scopes=None):
def _build_auth_code_flow(authority=None, scopes=None):
[!INCLUDE [active-directory-b2c-app-integration-domain-hint](../../includes/active-directory-b2c-app-integration-domain-hint.md)] 1. Check the domain name of your external identity provider. For more information, see [Redirect sign-in to a social provider](direct-signin.md#redirect-sign-in-to-a-social-provider).
-1. Find the `initiate_auth_code_flow` method and add the `domain_hint` parameter with the login hint.
+1. Find the `initiate_auth_code_flow` method, and then add the `domain_hint` parameter with the login hint.
```python def _build_auth_code_flow(authority=None, scopes=None):
def _build_auth_code_flow(authority=None, scopes=None):
## Next steps -- Learn more: [MSAL for Python configuration options](https://github.com/AzureAD/microsoft-authentication-library-for-python/wiki)
+- To learn more, see [MSAL for Python configuration options](https://github.com/AzureAD/microsoft-authentication-library-for-python/wiki).
active-directory-b2c Enable Authentication Web Application Options https://github.com/MicrosoftDocs/azure-docs/commits/master/articles/active-directory-b2c/enable-authentication-web-application-options.md
Title: Enable web application options using Azure Active Directory B2C
-description: Enable the use of web application options by using several ways.
+ Title: Enable web app authentication options using Azure Active Directory B2C
+description: This article discusses several ways to enable web app authentication options.
-# Configure authentication options in a web application using Azure Active Directory B2C
+# Enable authentication options in a web app by using Azure AD B2C
-This article describes ways you can customize and enhance the Azure Active Directory B2C (Azure AD B2C) authentication experience for your web application. Before you start, it is important to familiarize yourself with the following articles: [Configure authentication in a sample web application](configure-authentication-sample-web-app.md) or [Enable authentication in your own web application](enable-authentication-web-application.md).
+This article describes how to enable, customize, and enhance the Azure Active Directory B2C (Azure AD B2C) authentication experience for your web application.
+
+Before you start, it's important to familiarize yourself with the following articles:
+* [Configure authentication in a sample web app](configure-authentication-sample-web-app.md)
+* [Enable authentication in your own web app](enable-authentication-web-application.md).
[!INCLUDE [active-directory-b2c-app-integration-custom-domain](../../includes/active-directory-b2c-app-integration-custom-domain.md)]
-To use a custom domain and your tenant ID in the authentication URL, follow the guidance in [Enable custom domains](custom-domain.md). Under the project root folder, open the `appsettings.json` file. This file contains information about your Azure AD B2C identity provider.
+To use a custom domain and your tenant ID in the authentication URL, follow the guidance in [Enable custom domains](custom-domain.md). Under the project root folder, open the *appsettings.json* file. This file contains information about your Azure AD B2C identity provider.
+
+In the *appsettings.json* file, do the following:
- Update the `Instance` entry with your custom domain. - Update the `Domain` entry with your [tenant ID](tenant-management.md#get-your-tenant-id). For more information, see [Use tenant ID](custom-domain.md#optional-use-tenant-id). The following JSON shows the app settings before the change:
-```JSon
+```JSON
"AzureAdB2C": { "Instance": "https://contoso.b2clogin.com", "Domain": "tenant-name.onmicrosoft.com",
The following JSON shows the app settings before the change:
The following JSON shows the app settings after the change:
-```JSon
+```JSON
"AzureAdB2C": { "Instance": "https://login.contoso.com", "Domain": "00000000-0000-0000-0000-000000000000",
The following JSON shows the app settings after the change:
The `AddMicrosoftIdentityWebAppAuthentication` method in the Microsoft identity platform API lets developers add code for advanced authentication scenarios or subscribe to OpenIdConnect events. For example, you can subscribe to OnRedirectToIdentityProvider, which allows you to customize the authentication request your app sends to Azure AD B2C.
-To support advanced scenarios, open the `Startup.cs`, and in the `ConfigureServices` function, replace the `AddMicrosoftIdentityWebAppAuthentication` with the following code snippet:
+To support advanced scenarios, open the *Startup.cs* file and, in the `ConfigureServices` function, replace `AddMicrosoftIdentityWebAppAuthentication` with the following code snippet:
```csharp // Configuration to sign-in users with Azure AD B2C
services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
}); ```
-The code above adds the OnRedirectToIdentityProvider event with a reference to the *OnRedirectToIdentityProviderFunc* method. Add the following code snippet to the `Startup.cs` class.
+The preceding code adds the OnRedirectToIdentityProvider event with a reference to the `OnRedirectToIdentityProviderFunc` method. Add the following code snippet to the `Startup.cs` class.
```csharp private async Task OnRedirectToIdentityProviderFunc(RedirectContext context)
private async Task OnRedirectToIdentityProviderFunc(RedirectContext context)
} ```
-You can pass parameters between your controller and the *OnRedirectToIdentityProvider* function using context parameters.
-
+You can pass parameters between your controller and the `OnRedirectToIdentityProvider` function by using context parameters.
[!INCLUDE [active-directory-b2c-app-integration-login-hint](../../includes/active-directory-b2c-app-integration-login-hint.md)]
-1. If you're using a custom policy, add the required input claim as described in [Set up direct sign-in](direct-signin.md#prepopulate-the-sign-in-name).
+1. If you're using a custom policy, add the required input claim, as described in [Set up direct sign-in](direct-signin.md#prepopulate-the-sign-in-name).
1. Complete the [Support advanced scenarios](#support-advanced-scenarios) procedure.
-1. Add the following line of code to the *OnRedirectToIdentityProvider* function:
+1. Add the following line of code to the `OnRedirectToIdentityProvider` function:
```csharp private async Task OnRedirectToIdentityProviderFunc(RedirectContext context)
You can pass parameters between your controller and the *OnRedirectToIdentityPro
1. Check the domain name of your external identity provider. For more information, see [Redirect sign-in to a social provider](direct-signin.md#redirect-sign-in-to-a-social-provider). 1. Complete the [Support advanced scenarios](#support-advanced-scenarios) procedure.
-1. In the *OnRedirectToIdentityProviderFunc* function, add the following line of code to the *OnRedirectToIdentityProvider* function:
+1. In the `OnRedirectToIdentityProviderFunc` function, add the following line of code to the `OnRedirectToIdentityProvider` function:
```csharp private async Task OnRedirectToIdentityProviderFunc(RedirectContext context)
You can pass parameters between your controller and the *OnRedirectToIdentityPro
[!INCLUDE [active-directory-b2c-app-integration-ui-locales](../../includes/active-directory-b2c-app-integration-ui-locales.md)]
-1. [Configure Language customization](language-customization.md).
+1. [Configure language customization](language-customization.md).
1. Complete the [Support advanced scenarios](#support-advanced-scenarios) procedure.
-1. Add the following line of code to the *OnRedirectToIdentityProvider* function:
+1. Add the following line of code to the `OnRedirectToIdentityProvider` function:
```csharp private async Task OnRedirectToIdentityProviderFunc(RedirectContext context)
You can pass parameters between your controller and the *OnRedirectToIdentityPro
1. Configure the [ContentDefinitionParameters](customize-ui-with-html.md#configure-dynamic-custom-page-content-uri) element. 1. Complete the [Support advanced scenarios](#support-advanced-scenarios) procedure.
-1. Add the following line of code to the *OnRedirectToIdentityProvider* function:
+1. Add the following line of code to the `OnRedirectToIdentityProvider` function:
```csharp private async Task OnRedirectToIdentityProviderFunc(RedirectContext context)
You can pass parameters between your controller and the *OnRedirectToIdentityPro
1. Complete the [Support advanced scenarios](#support-advanced-scenarios) procedure. 1. In your custom policy, define an [ID token hint technical profile](id-token-hint.md).
-1. Add the following line of code to the *OnRedirectToIdentityProvider* function:
+1. Add the following line of code to the `OnRedirectToIdentityProvider` function:
```csharp private async Task OnRedirectToIdentityProviderFunc(RedirectContext context)
You can pass parameters between your controller and the *OnRedirectToIdentityPro
## Account controller
-If you want to customize the **Sign-in**, **Sign-up** or **Sign-out** actions, you are encouraged to create your own controller. Having your own controller allows you to pass parameters between your controller and the authentication library. The `AccountController` is part of `Microsoft.Identity.Web.UI` NuGet package, which handles the sign-in and sign-out actions. You can find its implementation in the [Microsoft Identity Web library](https://github.com/AzureAD/microsoft-identity-web/blob/master/src/Microsoft.Identity.Web.UI/Areas/MicrosoftIdentity/Controllers/AccountController.cs).
+If you want to customize the *SignIn*, *SignUp*, or *SignOut* actions, we encourage you to create your own controller. Having your own controller allows you to pass parameters between your controller and the authentication library. `AccountController` is part of `Microsoft.Identity.Web.UI` NuGet package, which handles the sign-in and sign-out actions. You can find its implementation in the [Microsoft Identity Web library](https://github.com/AzureAD/microsoft-identity-web/blob/master/src/Microsoft.Identity.Web.UI/Areas/MicrosoftIdentity/Controllers/AccountController.cs).
### Add the Account controller
-In your Visual Studio project, right click the **Controllers** folder, and add a new **Controller**. Select **MVC - Empty Controller**, and provide the name **MyAccountController.cs**.
+In your Visual Studio project, right-click the *Controllers* folder, and then add a new **Controller**. Select **MVC - Empty Controller**, and then provide the name **MyAccountController.cs**.
-The following code snippet demonstrates a custom `MyAccountController` with the **SignIn** action.
+The following code snippet demonstrates a custom `MyAccountController` with the *SignIn* action.
```csharp using System;
namespace mywebapp.Controllers
} ```
-In the `_LoginPartial.cshtml` view, change the sign-in link to your controller
+In the *_LoginPartial.cshtml* view, change the sign-in link to your controller.
```html <form method="get" asp-area="MicrosoftIdentity" asp-controller="MyAccount" asp-action="SignIn">
public IActionResult SignUp([FromRoute] string scheme)
} ```
-In the `_LoginPartial.cshtml` view, change the `asp-controller` value to `MyAccountController` for any other authentication links, such as sign-up or edit profile.
+In the *_LoginPartial.cshtml* view, change the `asp-controller` value to `MyAccountController` for any other authentication links, such as sign-up or edit profile.
### Pass custom parameters
public IActionResult SignIn([FromRoute] string scheme)
} ```
-Complete the [Support advanced scenarios](#support-advanced-scenarios) procedure. Then in the `OnRedirectToIdentityProvider` method, read the custom parameter:
+Complete the [Support advanced scenarios](#support-advanced-scenarios) procedure and then, in the `OnRedirectToIdentityProvider` method, read the custom parameter:
```csharp private async Task OnRedirectToIdentityProviderFunc(RedirectContext context)
In the above example, the **post_logout_redirect_uri** passed into the logout re
## Role-based access control
-With [authorization in ASP.NET Core](/aspnet/core/security/authorization/introduction) you can use [role-based authorization](/aspnet/core/security/authorization/roles), [claims-based authorization](/aspnet/core/security/authorization/claims), or [policy-based authorization](/aspnet/core/security/authorization/policies) to check if the user is authorized to access a protected resource.
+With [authorization in ASP.NET Core](/aspnet/core/security/authorization/introduction) you can check to see whether users are authorized to access a protected resource by using one of the following methods:
+* [Role-based authorization](/aspnet/core/security/authorization/roles)
+* [Claims-based authorization](/aspnet/core/security/authorization/claims)
+* [Policy-based authorization](/aspnet/core/security/authorization/policies)
-In the *ConfigureServices* method, add the *AddAuthorization* method, which adds the authorization model. The following example creates a policy named `EmployeeOnly`. The policy checks that a claim `EmployeeNumber` exists. The value of the claim must be one of the following IDs: 1, 2, 3, 4 or 5.
+In the `ConfigureServices` method, add the `AddAuthorization` method, which adds the authorization model. The following example creates a policy named `EmployeeOnly`. The policy checks to verify that a claim `EmployeeNumber` exists. The value of the claim must be one of the following IDs: 1, 2, 3, 4, or 5.
```csharp services.AddAuthorization(options =>
services.AddAuthorization(options =>
}); ```
-Authorization in ASP.NET Core is controlled with [AuthorizeAttribute](/aspnet/core/security/authorization/simple) and its various parameters. In its most basic form, applying the `[Authorize]` attribute to a controller, action, or Razor Page, limits access to that component's authenticated users.
+You control authorization in ASP.NET Core by using [AuthorizeAttribute](/aspnet/core/security/authorization/simple) and its various parameters. In its most basic form, applying the `Authorize` attribute to a controller, action, or Razor Page limits access to that component's authenticated users.
-Policies are applied to controllers by using the `[Authorize]` attribute with the policy name. The following code limits access to the `Claims` action to users authorized by the `EmployeeOnly` policy:
+You apply policies to controllers by using the `Authorize` attribute with the policy name. The following code limits access to the `Claims` action to users who are authorized by the `EmployeeOnly` policy:
```csharp [Authorize(Policy = "EmployeeOnly")]
public IActionResult Claims()
## Next steps -- Learn more: [Introduction to authorization in ASP.NET Core](/aspnet/core/security/authorization/introduction)
+- To learn more about authorization, see [Introduction to authorization in ASP.NET Core](/aspnet/core/security/authorization/introduction).
active-directory-b2c Enable Authentication Web Application https://github.com/MicrosoftDocs/azure-docs/commits/master/articles/active-directory-b2c/enable-authentication-web-application.md
Title: Enable authentication in a web application using Azure Active Directory B2C building blocks
-description: The building blocks of Azure Active Directory B2C to sign in and sign up users in an ASP.NET web application.
+ Title: Enable authentication in a web app by using Azure Active Directory B2C building blocks
+description: This article discusses how to use the building blocks of Azure Active Directory B2C to sign in and sign up users in an ASP.NET web app.
-# Enable authentication in your own web application using Azure Active Directory B2C
+# Enable authentication in your own web app by using Azure AD B2C
-This article shows you how to add Azure Active Directory B2C (Azure AD B2C) authentication to your own ASP.NET web application. Learn how create an ASP.NET Core web application with ASP.NET Core middleware that uses the [OpenID Connect](openid-connect.md) protocol. Use this article in conjunction with [Configure authentication in a sample web application](configure-authentication-sample-web-app.md), substituting the sample web app with your own web app.
+This article shows you how to add Azure Active Directory B2C (Azure AD B2C) authentication to your own ASP.NET web application. Learn how create an ASP.NET Core web application with ASP.NET Core middleware that uses the [OpenID Connect](openid-connect.md) protocol.
+
+Use this article in conjunction with [Configure authentication in a sample web app](configure-authentication-sample-web-app.md), replacing the sample web app with your own web app.
## Prerequisites
-Review the prerequisites and integration steps in [Configure authentication in a sample web application](configure-authentication-sample-web-app.md).
+To review the prerequisites and integration instructions, see [Configure authentication in a sample web application](configure-authentication-sample-web-app.md).
-## Create a web app project
+## Step 1: Create a web app project
-You can use an existing ASP.NET MVC web app project or create new one. To create a new project, open a command shell, and enter the following command:
+You can use an existing ASP.NET model-view-controller (MVC) web app project or create new one. To create a new project, open a command shell, and then enter the following command:
```dotnetcli dotnet new mvc -o mywebapp ```
-The preceding command:
+The preceding command does the following:
-* Creates a new MVC web app.
+* It creates a new MVC web app.
* The `-o mywebapp` parameter creates a directory named *mywebapp* with the source files for the app.
-## Add the authentication libraries
+## Step 2: Add the authentication libraries
-First, add the Microsoft Identity Web library. This is a set of ASP.NET Core libraries that simplify adding Azure AD B2C authentication and authorization support to your web app. The Microsoft Identity Web library sets up the authentication pipeline with cookie-based authentication. It takes care of sending and receiving HTTP authentication messages, token validation, claims extraction, and more.
+Add the Microsoft Identity Web library, which is a set of ASP.NET Core libraries that simplify adding Azure AD B2C authentication and authorization support to your web app. The Microsoft Identity Web library sets up the authentication pipeline with cookie-based authentication. It takes care of sending and receiving HTTP authentication messages, token validation, claims extraction, and more.
To add the Microsoft Identity Web library, install the packages by running the following commands:
Install-Package Microsoft.Identity.Web.UI
-## Initiate the authentication libraries
+## Step 3: Initiate the authentication libraries
The Microsoft Identity Web middleware uses a startup class that runs when the hosting process starts. In this step, you add the necessary code to initiate the authentication libraries.
-Open `Startup.cs` and add the following `using` declarations at the beginning of the class:
+Open *Startup.cs* and then, at the beginning of the class, add the following `using` declarations:
```csharp using Microsoft.AspNetCore.Http;
using Microsoft.Identity.Web;
using Microsoft.Identity.Web.UI; ```
-Because Microsoft Identity Web uses cookie-based authentication to protect your web app, the following code sets the *SameSite* cookie settings. Then it reads the `AzureAdB2C` application settings and initiates the middleware controller with its view.
+Because Microsoft Identity Web uses cookie-based authentication to protect your web app, the following code sets the *SameSite* cookie settings. It then reads the `AzureAdB2C` application settings and initiates the middleware controller with its view.
-Replace the `ConfigureServices(IServiceCollection services)` function with the following code snippet.
+Replace the `ConfigureServices(IServiceCollection services)` function with the following code snippet:
```csharp public void ConfigureServices(IServiceCollection services)
public void ConfigureServices(IServiceCollection services)
} ```
-The following code adds the cookie policy, and uses the authentication model. Replace the `Configure` function, with the following code snippet.
+The following code adds the cookie policy and uses the authentication model. Replace the `Configure` function with the following code snippet:
```csharp public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
}; ```
-## Add the UI elements
+## Step 4: Add the UI elements
-To add user interface elements, use a partial view that contains logic for checking whether a user is signed in or not. If the user is not signed in, the partial view renders the sign-in button. If the user is signed in, it shows the user's display name and sign-out button.
+To add user interface elements, use a partial view that contains logic for checking to see whether users are signed in. If users aren't signed in, the partial view renders the sign-in button. If they are signed in, it shows the user's display name and sign-out button.
-Create a new file `_LoginPartial.cshtml` inside the `Views/Shared` folder with the following code snippet:
+Create a new file, *\_LoginPartial.cshtml*, inside the */Views/Shared* folder with the following code snippet:
```razor @using System.Security.Principal
else
} ```
-Modify your `Views\Shared\_Layout.cshtml` to include the *_LoginPartial.cshtml* file you added. The *_Layout.cshtml* file is a common layout that provides the user with a consistent experience as they navigate from page to page. The layout includes common user interface elements such as the app header, and footer.
+Modify your */Views/Shared_Layout.cshtml* file to include the *_LoginPartial.cshtml* file you added. The *_Layout.cshtml* file is a common layout that gives users a consistent experience as they go from page to page. The layout includes common user interface elements, such as the app header and footer.
> [!NOTE]
-> Depending on the .NET Core version and whether you're adding sign-in to an existing app, the UI elements might look different. If so, be sure to include *_LoginPartial* in the proper location within the page layout.
+> Depending on the .NET Core version you're running and whether you're adding sign-in to an existing app, the UI elements might look different. If so, be sure to include *_LoginPartial* in the proper location within the page layout.
-Open the */Views/Shared/_Layout.cshtml* and add the following `div` element.
+Open the */Views/Shared/_Layout.cshtml* file, and then add the following `div` element.
```razor <div class="navbar-collapse collapse">
Replace this element with the following Razor code:
</div> ```
-The preceding Razor code includes a link to the `Claims` action you'll create in the next step.
+The preceding Razor code includes a link to the `Claims` action that you'll create in the next step.
-## Add the claims view
+## Step 5: Add the claims view
-To view the ID token claims under the `Views/Home` folder, add the `Claims.cshtml` view.
+To view the ID token claims, under the */Views/Home* folder, add the *Claims.cshtml* view.
```razor @using System.Security.Claims
To view the ID token claims under the `Views/Home` folder, add the `Claims.cshtm
</table> ```
-In this step, you add the `Claims` action that links the *Claims.cshtml* view to the *Home* controller. It uses the `[Authorize]` attribute, which limits access to the Claims action to authenticated users.
+In this step, you add the `Claims` action that links the *Claims.cshtml* view to the *Home* controller. The `Claims` action uses the `Authorize` attribute, which limits access to the action to authenticated users.
-In the `/Controllers/HomeController.cs` controller, add the following action.
+In the */Controllers/HomeController.cs* controller, add the following action:
```csharp [Authorize]
public IActionResult Claims()
} ```
-Add the following `using` declaration at the beginning of the class:
+At the beginning of the class, add the following `using` declaration:
```csharp using Microsoft.AspNetCore.Authorization; ```
-## Add the app settings
+## Step 6: Add the app settings
-Azure AD B2C identity provider settings are stored in the `appsettings.json` file. Open appsettings.json and add the following settings:
+Azure AD B2C identity provider settings are stored in the *appsettings.json* file. Open *appsettings.json*, and then add the following settings:
```JSon "AzureAdB2C": {
Azure AD B2C identity provider settings are stored in the `appsettings.json` fil
} ```
-The required information is described in the [Configure authentication in a sample web application](configure-authentication-sample-web-app.md) article. Use the following settings:
+The required information is described in the [Configure authentication in a sample web app](configure-authentication-sample-web-app.md) article. Use the following settings:
-* **Instance** - Replace `<your-tenant-name>` with the first part of your Azure AD B2C [tenant name](tenant-management.md#get-your-tenant-name). For example, `https://contoso.b2clogin.com`.
-* **Domain** - Replace `<your-b2c-domain>` with your Azure AD B2C full [tenant name](tenant-management.md#get-your-tenant-name). For example, `contoso.onmicrosoft.com`.
-* **Client ID** - Replace `<web-app-application-id>` with the Application ID from [Step 2](configure-authentication-sample-web-app.md#step-2-register-a-web-application).
-* **Policy name** - Replace `<your-sign-up-in-policy>` with the user flows you created in [Step 1](configure-authentication-sample-web-app.md#step-1-configure-your-user-flow).
+* **Instance**: Replace `<your-tenant-name>` with the first part of your Azure AD B2C [tenant name](tenant-management.md#get-your-tenant-name) (for example, `https://contoso.b2clogin.com`).
+* **Domain**: Replace `<your-b2c-domain>` with your Azure AD B2C full [tenant name](tenant-management.md#get-your-tenant-name) (for example, `contoso.onmicrosoft.com`).
+* **Client ID**: Replace `<web-app-application-id>` with the Application ID from [Step 2](configure-authentication-sample-web-app.md#step-2-register-a-web-application).
+* **Policy name**: Replace `<your-sign-up-in-policy>` with the user flows you created in [Step 1](configure-authentication-sample-web-app.md#step-1-configure-your-user-flow).
-## Run your application
+## Step 7: Run your application
1. Build and run the project.
-1. Browse to https://localhost:5001.
-1. Select **SignIn/Up**.
+1. Go to [https://localhost:5001](https://localhost:5001).
+1. Select **Sign Up/In**.
1. Complete the sign-up or sign-in process.
-After you successfully authenticate, you will see your display name in the navigation bar. To view the claims the Azure AD B2C token return to your app, select **Claims**.
+After you're successfully authenticated, you'll see your display name in the navigation bar. To view the claims that the Azure AD B2C token returns to your app, select **Claims**.
## Next steps
-* Learn how to [customize and enhance the Azure AD B2C authentication experience for your web app](enable-authentication-web-application-options.md)
+* Learn how to [customize and enhance the Azure AD B2C authentication experience for your web app](enable-authentication-web-application-options.md).
active-directory-b2c Enable Authentication Wpf Desktop App Options https://github.com/MicrosoftDocs/azure-docs/commits/master/articles/active-directory-b2c/enable-authentication-wpf-desktop-app-options.md
-# Configure authentication options in a WPF desktop application using Azure Active Directory B2C
+# Enable authentication options in a WPF desktop app by using Azure AD B2C
-This article describes ways you can customize and enhance the Azure Active Directory B2C (Azure AD B2C) authentication experience for your WPF desktop application. Before you start, familiarize yourself with the [Configure authentication in a sample WPF desktop application](configure-authentication-sample-wpf-desktop-app.md) article.
+This article describes ways you can customize and enhance the Azure Active Directory B2C (Azure AD B2C) authentication experience for your Windows Presentation Foundation (WPF) desktop application.
+
+Before you start, familiarize yourself with the [Configure authentication in a sample WPF desktop app by using Azure AD B2C](configure-authentication-sample-wpf-desktop-app.md) article.
[!INCLUDE [active-directory-b2c-app-integration-login-hint](../../includes/active-directory-b2c-app-integration-login-hint.md)]
-1. If you're using a custom policy, add the required input claim as described in [Set up direct sign-in](direct-signin.md#prepopulate-the-sign-in-name).
-1. Find your MSAL configuration object and add the `withLoginHint()` method with the login hint.
+1. If you're using a custom policy, add the required input claim, as described in [Set up direct sign-in](direct-signin.md#prepopulate-the-sign-in-name).
+1. Look for your Microsoft Authentication Library (MSAL) configuration object, and then add the `withLoginHint()` method with the login hint.
```csharp authResult = await app.AcquireTokenInteractive(App.ApiScopes)
authResult = await app.AcquireTokenInteractive(App.ApiScopes)
1. Check the domain name of your external identity provider. For more information, see [Redirect sign-in to a social provider](direct-signin.md#redirect-sign-in-to-a-social-provider). 1. Create or use an existing `Dictionary` object to store extra query parameters.
-1. Add the `domain_hint` parameter with the corresponding domain name to the dictionary. For example, `facebook.com`.
+1. Add the `domain_hint` parameter with the corresponding domain name to the dictionary (for example, `facebook.com`).
1. Pass the extra query parameters object into the MSAL configuration object's `WithExtraQueryParameters` method. ```csharp
authResult = await app.AcquireTokenInteractive(App.ApiScopes)
[!INCLUDE [active-directory-b2c-app-integration-ui-locales](../../includes/active-directory-b2c-app-integration-ui-locales.md)]
-1. [Configure Language customization](language-customization.md).
+1. [Configure language customization](language-customization.md).
1. Create or use an existing `Dictionary` object to store extra query parameters.
-1. Add the `ui_locales` parameter with the corresponding language code to the dictionary. For example, `en-us`.
+1. Add the `ui_locales` parameter with the corresponding language code to the dictionary (for example, `en-us`).
1. Pass the extra query parameters object into the MSAL configuration object's `WithExtraQueryParameters` method. ```csharp
authResult = await app.AcquireTokenInteractive(App.ApiScopes)
1. Configure the [ContentDefinitionParameters](customize-ui-with-html.md#configure-dynamic-custom-page-content-uri) element. 1. Create or use an existing `Dictionary` object to store extra query parameters.
-1. Add the custom query string parameter, such as `campaignId`. Set the parameter value. For example, `germany-promotion`.
+1. Add the custom query string parameter, such as `campaignId`. Set the parameter value (for example, `germany-promotion`).
1. Pass the extra query parameters object into the MSAL configuration object's `WithExtraQueryParameters` method. ```csharp
authResult = await app.AcquireTokenInteractive(App.ApiScopes)
[!INCLUDE [active-directory-b2c-app-integration-id-token-hint](../../includes/active-directory-b2c-app-integration-id-token-hint.md)] 1. In your custom policy, define an [ID token hint technical profile](id-token-hint.md).
-1. In your code, generate or acquire an ID token, and set the token to a variable. For example, `idToken`.
+1. In your code, generate or acquire an ID token, and then set the token to a variable (for example, `idToken`).
1. Create or use an existing `Dictionary` object to store extra query parameters. 1. Add the `id_token_hint` parameter with the corresponding variable that stores the ID token. 1. Pass the extra query parameters object into the MSAL configuration object's `extraQueryParameters` attribute.
PublicClientApp = PublicClientApplicationBuilder.Create(ClientId)
.Build(); ```
-## Configure redirect URI
+## Configure the redirect URI
-In the [desktop app registration](configure-authentication-sample-wpf-desktop-app.md#23-register-the-desktop-app), there are important considerations when choosing a redirect URI:
+During the [desktop app registration](configure-authentication-sample-wpf-desktop-app.md#step-23-register-the-desktop-app) process, when you're choosing a redirect URI, keep in mind the following important considerations:
-* **Development** For development use, and **desktop apps**, you can set the redirect URI to `http://localhost` and Azure AD B2C will respect any port in the request. If the registered URI contains a port, Azure AD B2C will use that port only. For example, if the registered redirect URI is `http://localhost`, the redirect URI in the request can be `http://localhost:<randomport>`. If the registered redirect URI is `http://localhost:8080`, the redirect URI in the request must be `http://localhost:8080`.
-* **Unique**: The scheme of the redirect URI must be unique for every application. In the example `com.onmicrosoft.contosob2c.exampleapp://oauth/redirect`, `com.onmicrosoft.contosob2c.exampleapp` is the scheme. This pattern should be followed. If two applications share the same scheme, the user is given a choice to choose an application. If the user chooses incorrectly, the sign-in fails.
-* **Complete**: The redirect URI must have a both a scheme and a path. The path must contain at least one forward slash after the domain. For example, `//oauth/` works while `//oauth` fails. Don't include special characters in the URI, for example, underscores.
+* **Development**: For development use in desktop apps, you can set the redirect URI to `http://localhost`, and Azure AD B2C will respect any port in the request. If the registered URI contains a port, Azure AD B2C will use that port only. For example, if the registered redirect URI is `http://localhost`, the redirect URI in the request can be `http://localhost:<randomport>`. If the registered redirect URI is `http://localhost:8080`, the redirect URI in the request must be `http://localhost:8080`.
+* **Unique**: The scheme of the redirect URI must be unique for every application. In the example `com.onmicrosoft.contosob2c.exampleapp://oauth/redirect`, `com.onmicrosoft.contosob2c.exampleapp` is the scheme. This pattern should be followed. If two applications share the same scheme, users are given a choice of applications. If users choose incorrectly, the sign-in fails.
+* **Complete**: The redirect URI must have a both a scheme and a path. The path must contain at least one slash character after the domain. For example, `//oauth/` works, and `//oauth` fails. Don't include special characters in the URI. For example, the underscore character (_) isn't allowed.
## Next steps -- Learn more: [MSAL for .NET, UWP, NetCore, and Xamarin configuration options](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/wiki)
+- To learn more, see [MSAL for .NET, UWP, NetCore, and Xamarin configuration options](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/wiki).
active-directory Msal Net Token Cache Serialization https://github.com/MicrosoftDocs/azure-docs/commits/master/articles/active-directory/develop/msal-net-token-cache-serialization.md
Previously updated : 06/25/2021 Last updated : 08/28/2021
Here are examples of possible distributed caches:
.EnableTokenAcquisitionToCallDownstreamApi(new string[] { scopesToRequest } .AddDistributedTokenCaches();
-// and then choose your implementation
+// and then choose your implementation of distributed cache
// For instance the distributed in memory cache (not cleared when you stop the app)
-services.AddDistributedMemoryCache()
+services.AddDistributedMemoryCache();
// Or a Redis cache
+// Requires the Microsoft.Extensions.Caching.StackExchangeRedis NuGet package
services.AddStackExchangeRedisCache(options => { options.Configuration = "localhost";
services.AddStackExchangeRedisCache(options =>
}); // Or even a SQL Server token cache
+// Requires the Microsoft.Extensions.Caching.SqlServer NuGet package
services.AddDistributedSqlServerCache(options => { options.ConnectionString = _config["DistCache_ConnectionString"]; options.SchemaName = "dbo"; options.TableName = "TestCache"; });+
+// Or a Cosmos DB cache
+// Requires the Microsoft.Extensions.Caching.Cosmos NuGet package
+services.AddCosmosCache((CosmosCacheOptions cacheOptions) =>
+{
+ cacheOptions.ContainerName = Configuration["CosmosCacheContainer"];
+ cacheOptions.DatabaseName = Configuration["CosmosCacheDatabase"];
+ cacheOptions.ClientBuilder = new CosmosClientBuilder(Configuration["CosmosConnectionString"]);
+ cacheOptions.CreateIfNotExists = true;
+});
``` Their usage is featured in the [ASP.NET Core web app tutorial](/aspnet/core/tutorials/first-mvc-app/) in the phase [2-2 Token Cache](https://github.com/Azure-Samples/active-directory-aspnetcore-webapp-openidconnect-v2/tree/master/2-WebApp-graph-user/2-2-TokenCache).
Add the [Microsoft.Identity.Web](https://www.nuget.org/packages/Microsoft.Identi
### Configuring the token cache
-The following code shows how to add an in-memory well partitioned token cache to your app.
+The following code shows how to add an in-memory well-partitioned token cache to your app.
```CSharp
-#using Microsoft.Identity.Web
-#using Microsoft.Identity.Client
+using Microsoft.Identity.Web;
+using Microsoft.Identity.Client;
+using Microsoft.Extensions.DependencyInjection;
``` ```CSharp private static IConfidentialClientApplication app;
- public static async Task<IConfidentialClientApplication> BuildConfidentialClientApplication()
+public static async Task<IConfidentialClientApplication> BuildConfidentialClientApplication(
+ string clientId,
+ CertificateDescription certDescription,
+ string tenant)
{ if (app== null) {
The following code shows how to add an in-memory well partitioned token cache to
.Build(); // Add an in-memory token cache. Other options available: see below
- app.AddInMemoryTokenCaches();
+ app.AddInMemoryTokenCache();
}
- return clientapp;
+ return app;
} ```
-### Available serialization technologies
+### Available caching technologies
+
+Instead of `app.AddInMemoryTokenCache();` you can use different caching technologies, including distributed token caches provided by .NET.
#### In memory token cache
+In memory token cache serialization is great in samples. It's also good in production applications provided you don't mind if the token cache is lost when the web app is restarted.
+ ```CSharp // Add an in-memory token cache
- app.AddInMemoryTokenCaches();
+ app.AddInMemoryTokenCache();
```
-#### Distributed in memory token cache
+#### Distributed caches
+
+If you use `app.AddDistributedTokenCache`, the token cache is an adapter against the .NET `IDistributedCache` implementation, therefore enabling you to choose between a distributed memory cache, a Redis cache, a CosmosDb, or a SQL Server cache. For details about the `IDistributedCache` implementations, see [Distributed memory cache](/aspnet/core/performance/caching/distributed).
+
+##### Distributed in memory token cache
```CSharp // In memory distributed token cache
- app.AddDistributedTokenCaches(services =>
+ app.AddDistributedTokenCache(services =>
{ // In net462/net472, requires to reference Microsoft.Extensions.Caching.Memory services.AddDistributedMemoryCache(); }); ```
-#### SQL server
+##### SQL server
```CSharp // SQL Server token cache
- app.AddDistributedTokenCaches(services =>
+ app.AddDistributedTokenCache(services =>
{ services.AddDistributedSqlServerCache(options => {
The following code shows how to add an in-memory well partitioned token cache to
}); ```
-#### Redis cache
+##### Redis cache
```CSharp // Redis token cache
- app.AddDistributedTokenCaches(services =>
+ app.AddDistributedTokenCache(services =>
{ // Requires to reference Microsoft.Extensions.Caching.StackExchangeRedis services.AddStackExchangeRedisCache(options =>
The following code shows how to add an in-memory well partitioned token cache to
}); ```
-#### Cosmos DB
+See also [Disabling cache synchronization](#disabling-cache-synchronization) if you observe that token acquisition occasionally takes as much time as
+the redis cache timeout.
+
+##### Cosmos DB
```CSharp // Cosmos DB token cache
- app.AddDistributedTokenCaches(services =>
+ app.AddDistributedTokenCache(services =>
{
- // Requires to reference Microsoft.Extensions.Caching.Cosmos (preview)
+ // Requires to reference Microsoft.Extensions.Caching.Cosmos
services.AddCosmosCache((CosmosCacheOptions cacheOptions) => { cacheOptions.ContainerName = Configuration["CosmosCacheContainer"];
The following code shows how to add an in-memory well partitioned token cache to
``` ### Disabling legacy token cache+ MSAL has some internal code specifically to enable the ability to interact with legacy ADAL cache. When MSAL and ADAL aren't used side by side (therefore the legacy cache isn't used), the related legacy cache code is unnecessary. MSAL [4.25.0](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/releases/tag/4.25.0) adds the ability to disable legacy ADAL cache code and improve cache usage performance. See pull request [#2309](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/pull/2309) for performance comparison before and after disabling the legacy cache. Call `.WithLegacyCacheCompatibility(false)` on an application builder like below. ```csharp
var app = ConfidentialClientApplicationBuilder
.Build(); ```
+### Disabling cache synchronization
+
+By default, MSAL will lock cache access at the confidential client application level between cache reads and cache writes. This lock can be an issue if the cache serializer takes a long time until a timeout happens, which can be the case with Redis caches. You can set the `WithCacheSynchronization` flag to false to enable an optimistic cache locking strategy, which may result in better performance, especially when ConfidentialClientApplication objects are reused across requests.
+
+```csharp
+var app = ConfidentialClientApplicationBuilder
+ .Create(clientId)
+ .WithClientSecret(clientSecret)
+ .WithCacheSynchronization(false)
+ .Build();
+```
+
+### Monitor cache hit ratios and cache performance
+
+MSAL exposes important metrics as part of [AuthenticationResult.AuthenticationResultMetadata](/dotnet/api/microsoft.identity.client.authenticationresultmetadata.md) object:
+
+| Metric | Meaning | When to trigger an alarm? |
+| :-: | :-: | :--: |
+| `DurationTotalInMs` | Total time spent in MSAL, including network calls and cache | Alarm on overall high latency (> 1 s). Value depends on token source. From the cache: one cache access. From AAD: two cache accesses + one HTTP call. First ever call (per-process) will take longer because of one extra HTTP call. |
+| `DurationInCacheInMs` | Time spent loading or saving the token cache, which is customized by the app developer (for example, save to Redis).| Alarm on spikes. |
+| `DurationInHttpInMs`| Time spent making HTTP calls to AAD. | Alarm on spikes.|
+| `TokenSource` | Indicates the source of the token. Tokens are retrieved from the cache much faster (for example, ~100 ms versus ~700 ms). Can be used to monitor and alarm the cache hit ratio. | Use with `DurationTotalInMs` |
+ ### Samples - Using the token cache serializers in a .NET Framework and .NET Core applications is showed-cased in this sample [ConfidentialClientTokenCache](https://github.com/Azure-Samples/active-directory-dotnet-v1-to-v2/tree/master/ConfidentialClientTokenCache)
The following samples illustrate token cache serialization.
| Sample | Platform | Description| | | -- | -- | |[active-directory-dotnet-desktop-msgraph-v2](https://github.com/azure-samples/active-directory-dotnet-desktop-msgraph-v2) | Desktop (WPF) | Windows Desktop .NET (WPF) application calling the Microsoft Graph API. ![Diagram shows a topology with Desktop App WPF TodoListClient flowing to Azure AD by acquiring a token interactively and to Microsoft Graph.](media/msal-net-token-cache-serialization/topology.png)|
-|[active-directory-dotnet-v1-to-v2](https://github.com/Azure-Samples/active-directory-dotnet-v1-to-v2) | Desktop (Console) | Set of Visual Studio solutions illustrating the migration of Azure AD v1.0 applications (using ADAL.NET) to Microsoft identity platform applications (using MSAL.NET). In particular, see [Token Cache Migration](https://github.com/Azure-Samples/active-directory-dotnet-v1-to-v2/blob/master/TokenCacheMigration/README.md)|
+|[active-directory-dotnet-v1-to-v2](https://github.com/Azure-Samples/active-directory-dotnet-v1-to-v2) | Desktop (Console) | Set of Visual Studio solutions illustrating the migration of Azure AD v1.0 applications (using ADAL.NET) to Microsoft identity platform applications (using MSAL.NET). In particular, see [Token Cache Migration](https://github.com/Azure-Samples/active-directory-dotnet-v1-to-v2/blob/master/TokenCacheMigration/README.md) and [Confidential client token cache](https://github.com/Azure-Samples/active-directory-dotnet-v1-to-v2/tree/master/ConfidentialClientTokenCache) |
+[ms-identity-aspnet-webapp-openidconnect](https://github.com/Azure-Samples/ms-identity-aspnet-webapp-openidconnect) | ASP.NET (net472) | Example of token cache serialization in an ASP.NET MVC application (using MSAL.NET). See in particular [MsalAppBuilder](https://github.com/Azure-Samples/ms-identity-aspnet-webapp-openidconnect/blob/master/WebApp/Utils/MsalAppBuilder.cs)
api-management Api Management Api Import Restrictions https://github.com/MicrosoftDocs/azure-docs/commits/master/articles/api-management/api-management-api-import-restrictions.md
If you're receiving errors importing your OpenAPI document, make sure you've val
### <a name="open-api-general"> </a>General - Required parameters across both path and query must have unique names. (In OpenAPI a parameter name only needs to be unique within a location, for example path, query, header. However, in API Management we allow operations to be discriminated by both path and query parameters (which OpenAPI doesn't support). That's why we require parameter names to be unique within the entire URL template.)
+- When imported inline to API Management, an OpenAPI specification can be up to 4 MB in size. The size limit doesn't apply when an OpenAPI document is provided via a URL to a location accessible from your API Management service.
- `\$ref` pointers can't reference external files. - `x-ms-paths` and `x-servers` are the only supported extensions. - Custom extensions are ignored on import and aren't saved or preserved for export.
api-management Api Management Revisions https://github.com/MicrosoftDocs/azure-docs/commits/master/articles/api-management/api-management-revisions.md
When you create a revision, you can set a description for your own tracking purp
When you set a revision as current you can also optionally specify a public change log note. The change log is included in the developer portal for your API users to view. You can modify your change log note using the `Update-AzApiManagementApiRelease` PowerShell cmdlet.
+> [!NOTE]
+> Certain API properties such as **Display name** and the **API suffix** can only be updated in the current revision.
+ ## Versions and revisions Versions and revisions are distinct features. Each version can have multiple revisions, just like a non-versioned API. You can use revisions without using versions, or the other way around. Typically versions are used to separate API versions with breaking changes, while revisions can be used for minor and non-breaking changes to an API.
api-management Import Api From Oas https://github.com/MicrosoftDocs/azure-docs/commits/master/articles/api-management/import-api-from-oas.md
In this article, you learn how to:
> [!div class="checklist"] > * Import an "OpenAPI specification" back-end API > * Test the API in the Azure portal
-> * Test the API in the Developer portal
## Prerequisites
applied-ai-services Resource Customer Stories https://github.com/MicrosoftDocs/azure-docs/commits/master/articles/applied-ai-services/form-recognizer/resource-customer-stories.md
The following customers and partners have adopted Form Recognizer across a wide
|<font size=5>Blue Prism</font>| [**Blue Prism**](https://www.blueprism.com/)ΓÇÖs Decipher is a new AI-powered document processing capability thatΓÇÖs directly embedded into the companyΓÇÖs connected-RPA platform. Decipher works with Form Recognizer, part of Microsoft Azure Cognitive Services, to help organizations process any form faster and with less human effort. One of Blue PrismΓÇÖs customers has been testing the solution to automate invoice handling as part of its procurement process. | [Customer story](https://customers.microsoft.com/story/737482-blue-prism-partner-professional-services-azure) | |<font size=5>Chevron</font>| [**Chevron**](https://www.chevron.com//)'s Canada Business Unit is now using Form Recognizer (part of Microsoft Azure Cognitive Services) together with UiPathΓÇÖs robotic process automation platform to automate the extraction of data and move it into back-end systems for analysis. Subject matter experts will have more time to focus on higher-value activities and information will flow more rapidly, accelerating operational control and enabling the company to analyze its business with greater speed, accuracy, and depth. | [Customer story](https://customers.microsoft.com/story/chevron-mining-oil-gas-azure-cognitive-services)| |<font size=5>Cross Masters</font>|"At [**Cross Masters**](https://crossmasters.com/), using cutting-edge AI technologies is not only a passion, it is an essential part of our work culture that requires continuous innovation. One of our latest success stories is automation of manual paperwork, required to process thousands of invoices. Thanks to Microsoft Form RecognizerΓÇÖs AI engine we were able to develop a unique customized solution that provides to our clients market insights from large set of collected invoices. What we find the most convenient is human-beating-extraction quality and continuous introduction of new features, such as model composing or table labeling. Thus assuring our clientΓÇÖs market advantage and helping our product to be the best-in-class solution" says Jan Hornych, Head of Marketing Automation, Cross Masters | [Blog](https://techcommunity.microsoft.com/t5/azure-ai/form-recognizer-now-reads-more-languages-processes-ids-and/ba-p/2179428)|
+|<font size=5>EY</font>| [**EY**](https://ey.com/) organization exists to build a better working world, helping to create long-term value for clients, people, and society and build trust in the capital markets. Enabled by data and technology, diverse EY teams in over 150 countries provide trust through assurance and help clients grow, transform, and operate. Working across assurance, consulting, law, strategy, tax, and transactions, EY teams ask better questions to find new answers for the complex issues facing our world today. The EY Technology team collaborated with Microsoft to build a platform that hastens invoice extraction and contract comparison processes. Using Azure Form Recognizer (Form Recognizer) and the Azure Custom Vision API (Vision), EY teams have been able to automate and improve the Optical Character Recognition (OCR) and document handling processes for its consulting, tax, audit, and transactions services clients. | [Customer story](https://customers.microsoft.com/en-us/story/1404985164224935715-ey-professional-services-azure-form-recognizer)|
|<font size=5>Financial Fabric</font>| [**Financial Fabric**](https://www.financialfabric.com//), a Microsoft Cloud Solution Provider, delivers data architecture, science, and analytics services to investment managers at hedge funds, family offices, and corporate treasuries. Its daily processes involve extracting and normalizing data from thousands of complex financial documents, such as bank statements and legal agreements. The company then provides custom analytics to help its clients make better investment decisions. Extracting this data previously took days or weeksΓÇöbut by using Form Recognizer, part of Microsoft Azure Cognitive Services, Financial Fabric has reduced the time it takes to go from extraction to analysis to just minutes. | [Customer story](https://customers.microsoft.com/story/financial-fabric-banking-capital-markets-azure)| |<font size=5>GEP</font>| [**GEP**](https://www.gep.com/) has developed an invoice processing solution for a client using Form Recognizer. ΓÇ£At GEP, we are seeing AI and automation make a profound impact on procurement and the supply chain. By combining our AI solution with Microsoft Form Recognizer, we automated the processing of 4,000 invoices a day for a client, saving them tens of thousands of hours of manual effort, while improving accuracy, controls and compliance on a global scale,ΓÇ¥ said Sarateudu Sethi, GEPΓÇÖs Vice President of Artificial Intelligence. | [Blog](https://techcommunity.microsoft.com/t5/azure-ai/form-recognizer-now-reads-more-languages-processes-ids-and/ba-p/2179428)|
+|<font size=5>HCA Healthcare</font>| [**HCA Healthcare**](https://hcahealthcare.com/) is one of the nationΓÇÖs leading providers of healthcare with over 180 hospitals and 2,000 sites of care located throughout the United States, serving approximately 35 million patients each year. Now, they are partnering with Microsoft and leveraging Azure Form Recognizer to simplify and improve the patient onboarding experience, as well as cut down on administrative time spent entering repetitive data into the care centerΓÇÖs system. | [Customer story](https://customers.microsoft.com/en-us/story/1404891793134114534-hca-healthcare-healthcare-provider-azure)|
|<font size=5>Instabase</font>| [**Instabase**](https://instabase.com/) is a horizontal application platform that provides best-in-class machine learning processes to help retrieve, organize, identify, and understand complex masses of unorganized data and bring it into business workflows as organized information. The platform provides a repository of pluggable applications to orchestrate and harness that information and the means to rapidly extend and enhance them as required. Instabase applications are fully containerized for widespread, infrastructure-agnostic deployment. | [Customer story](https://customers.microsoft.com/en-gb/story/1376278902865681018-instabase-partner-professional-services-azure)| |<font size=5>WEX</font>| [**WEX**](https://www.wexinc.com/) has developed a tool to process Explanation of Benefits documents using Form Recognizer. Matt Dallahan, Senior Vice President of Product Management and Strategy, said ΓÇ£The technology is truly amazing. I was initially worried that this type of solution would not be feasible, but I soon realized that the Form Recognizer can read virtually any document with accuracy.ΓÇ¥ | [Blog](https://techcommunity.microsoft.com/t5/azure-ai/form-recognizer-now-reads-more-languages-processes-ids-and/ba-p/2179428)| |<font size=5>Wilson Allen</font> | [**Wilson Allen**](https://wilsonallen.com/) took advantage of AI container support for Microsoft Azure Cognitive Services and created a powerful AI solution that can help firms around the world find unprecedented levels of insight in previously siloed and unstructured data. Now, its clients can use this data to support business development and foster client relationships. | [Customer story](https://customers.microsoft.com/story/814361-wilson-allen-partner-professional-services-azure)|
azure-cache-for-redis Cache Best Practices Connection https://github.com/MicrosoftDocs/azure-docs/commits/master/articles/azure-cache-for-redis/cache-best-practices-connection.md
Avoid creating many connections at the same time when reconnecting after a conne
If you're reconnecting many client instances, consider staggering the new connections to avoid a steep spike in the number of connected clients. > [!NOTE]
-> When you use the `StackExchange.Redis` client library, set `abortConnect` to `false` in your connection string. We recommend letting the `ConnectionMultiplexer` handle reconnection. For more information, see [StackExchange.Redis best practices](/cache-management-faq.md#stackexchangeredis-best-practices).
+> When you use the `StackExchange.Redis` client library, set `abortConnect` to `false` in your connection string. We recommend letting the `ConnectionMultiplexer` handle reconnection. For more information, see [StackExchange.Redis best practices](/azure/azure-cache-for-redis/cache-planning-faq#stackexchangeredis-best-practices).
## Avoid leftover connections
Caches have limits on the number of client connections per cache tier. Ensure th
## Advance maintenance notification
-Use notifications to learn of upcoming maintenance. For more information, see [Can I be notified in advance of a planned maintenance](/cache-failover.md#can-i-be-notified-in-advance-of-a-planned-maintenance).
+Use notifications to learn of upcoming maintenance. For more information, see [Can I be notified in advance of a planned maintenance?](cache-failover.md#can-i-be-notified-in-advance-of-a-planned-maintenance).
## Schedule maintenance window
-Adjust your cache settings to accommodate maintenance. For more information about creating a maintenance window to reduce any negative effects to your cache, see [Schedule updates](/azure-cache-for-redis/cache-administration.md#schedule-updates).
+Adjust your cache settings to accommodate maintenance. For more information about creating a maintenance window to reduce any negative effects to your cache, see [Schedule updates](cache-administration.md#schedule-updates).
## More design patterns for resilience
-Apply design patterns for resiliency. For more information, see [recommended design patterns](/cache-failover.md#how-do-i-make-my-application-resilient)
+Apply design patterns for resiliency. For more information, see [How do I make my application resilient?](cache-failover.md#how-do-i-make-my-application-resilient).
## Idle timeout
azure-government Compare Azure Government Global Azure https://github.com/MicrosoftDocs/azure-docs/commits/master/articles/azure-government/compare-azure-government-global-azure.md
Title: Compare Azure Government and global Azure | Microsoft Docs
+ Title: Compare Azure Government and global Azure
description: Describe feature differences between Azure Government and global Azure.-
-cloud: gov
++ --- Previously updated : 08/26/2021 Last updated : 08/27/2021 # Compare Azure Government and global Azure
Microsoft's goal for Azure Government is to match service availability in Azure.
In general, service availability in Azure Government implies that all corresponding service features are available to you. Variations to this approach and other applicable limitations are tracked and explained in this article based on the main service categories outlined in the [online directory of Azure services](https://azure.microsoft.com/services/). Other considerations for service deployment and usage in Azure Government are also provided.
-## AI + Machine Learning
+## AI + machine learning
This section outlines variations and considerations when using **Azure Bot Service**, **Azure Machine Learning**, and **Cognitive Services** in the Azure Government environment. For service availability, see [Products available by region](https://azure.microsoft.com/global-infrastructure/services/?products=machine-learning-service,bot-service,cognitive-services&regions=non-regional,usgov-non-regional,us-dod-central,us-dod-east,usgov-arizona,usgov-texas,usgov-virginia).
For more information, see [How do I create a bot that uses US Government data ce
For feature variations and limitations, see [Azure Machine Learning sovereign cloud parity](../machine-learning/reference-machine-learning-cloud-parity.md).
-### [Content Moderator](../cognitive-services/content-moderator/overview.md)
+### [Cognitive
The following Content Moderator **features are not currently available** in Azure Government: - Review UI and Review APIs.
-### [Language Understanding](../cognitive-services/luis/what-is-luis.md)
+### [Cognitive
The following Language Understanding **features are not currently available** in Azure Government: - Speech Requests - Prebuilt Domains
-### [Speech service](../cognitive-services/speech-service/overview.md)
+### [Cognitive
For feature variations and limitations, including API endpoints, see [Speech service in sovereign clouds](../cognitive-services/Speech-Service/sovereign-clouds.md).
-### [Translator](../cognitive-services/translator/translator-info-overview.md)
+### [Cognitive
The following Translator **features are not currently available** in Azure Government:
The following Translator **features are not currently available** in Azure Gover
This section outlines variations and considerations when using Analytics services in the Azure Government environment. For service availability, see [Products available by region](https://azure.microsoft.com/global-infrastructure/services/?products=data-share,power-bi-embedded,analysis-services,event-hubs,data-lake-analytics,storage,data-catalog,data-factory,synapse-analytics,stream-analytics,databricks,hdinsight&regions=non-regional,usgov-non-regional,us-dod-central,us-dod-east,usgov-arizona,usgov-texas,usgov-virginia).
-### [HDInsight](../hdinsight/hadoop/apache-hadoop-introduction.md)
+### [Azure HDInsight](../hdinsight/hdinsight-overview.md)
The following HDInsight **features are not currently available** in Azure Government:
This section outlines variations and considerations when using Internet of Thing
If you are using the IoT Hub connection string (instead of the Event Hub-compatible settings) with the Microsoft Azure Service Bus .NET client library to receive telemetry or operations monitoring events, then be sure to use `WindowsAzure.ServiceBus` NuGet package version 4.1.2 or higher.
-## Management and Governance
+## Management and governance
This section outlines variations and considerations when using Management and Governance services in the Azure Government environment. For service availability, see [Products available by region](https://azure.microsoft.com/global-infrastructure/services/?products=managed-applications,azure-policy,network-watcher,monitor,traffic-manager,automation,scheduler,site-recovery,cost-management,backup,blueprints,advisor&regions=non-regional,usgov-non-regional,us-dod-central,us-dod-east,usgov-arizona,usgov-texas,usgov-virginia). > [!NOTE] >This article has been updated to use the new Azure PowerShell Az module. You can still use the AzureRM module, which will continue to receive bug fixes until at least December 2020. To learn more about the new Az module and AzureRM compatibility, see [**Introducing the new Azure PowerShell Az module**](/powershell/azure/new-azureps-module-az). For Az module installation instructions, see [**Install Azure PowerShell**](/powershell/azure/install-az-ps).
-### [Application Insights](../azure-monitor/overview.md)
-
-This section describes the supplemental configuration that is required to use Application Insights (part of Azure Monitor) in Azure Government.
-
-**Enable Application Insights for [ASP.NET](#web) & [ASP.NET Core](#web) with Visual Studio**
-
-In Azure Government, you can enable Application Insights with a [codeless agent](../azure-monitor/app/azure-web-apps.md) for your Azure App Services hosted applications or via the traditional **Add Applications Insights Telemetry** button in Visual Studio, which requires a small manual workaround. If you are experiencing the associated issue, you may see error messages like "There is no Azure subscription associated with this account" or "The selected subscription does not support Application Insights" even though the `microsoft.insights` resource provider has a status of registered for the subscription. To mitigate this issue, you must perform the following steps:
-
-1. Switch Visual Studio to [target the Azure Government cloud](./documentation-government-welcome.md).
-2. Create (or if already existing, set) the User Environment variable for `AzureGraphApiVersion` as follows:
-
- - Variable name: `AzureGraphApiVersion`
- - Variable value: `2014-04-01`
-
- To create a User Environment variable, go to **Control Panel > System > Advanced system settings > Advanced > Environment Variables**.
-
-3. Make the appropriate Application Insights SDK endpoint modifications for either [ASP.NET](#web) or [ASP.NET Core](#web) depending on your project type.
-
-**Snapshot Debugger** is now available for Azure Government customers. To use Snapshot Debugger, the only other prerequisite is to ensure that you are using [Snapshot Collector version 1.3.5](https://www.nuget.org/packages/Microsoft.ApplicationInsights.SnapshotCollector/1.3.5-pre-1906.403) or later. Then follow the standard [Snapshot Debugger documentation](../azure-monitor/app/snapshot-debugger.md).
-
-**SDK endpoint modifications** - In order to send data from Application Insights to the Azure Government region, you will need to modify the default endpoint addresses that are used by the Application Insights SDKs. Each SDK requires slightly different modifications, as described in [Application Insights overriding default endpoints](../azure-monitor/app/custom-endpoints.md).
-
->[!NOTE]
->[**Connection strings**](../azure-monitor/app/sdk-connection-string.md?tabs=net) are the new preferred method of setting custom endpoints within Application Insights.
-
-**Firewall exceptions** - Application Insights uses several IP addresses. You might need to know these addresses if the app that you are monitoring is hosted behind a firewall.
-
->[!NOTE]
->Although these addresses are static, it's possible that we will need to change them from time to time. All Application Insights traffic represents outbound traffic except for availability monitoring and webhooks, which require inbound firewall rules.
-
-You need to open some **outgoing ports** in your server's firewall to allow the Application Insights SDK and/or Status Monitor to send data to the portal:
-
-|Purpose|URL|IP address|Ports|
-|-||-|--|
-|Telemetry|dc.applicationinsights.us|23.97.4.113|443|
- ### [Azure Advisor](../advisor/advisor-overview.md) The following Azure Advisor recommendation **features are not currently available** in Azure Government:
The following Azure Lighthouse **features are not currently available** in Azure
- Managed Service offers published to Azure Marketplace
-### [Azure Monitor](../azure-monitor/logs/data-platform-logs.md)
+### [Azure Monitor](../azure-monitor/overview.md)
The following Azure Monitor **features are not currently available** in Azure Government:
The following Azure Monitor **features behave differently** in Azure Government:
- Can I switch between Azure and Azure Government workspaces from the Operations Management Suite portal? - No. The portals for Azure and Azure Government are separate and do not share information.
+#### [Application Insights](../azure-monitor/app/app-insights-overview.md)
+
+This section describes the supplemental configuration that is required to use Application Insights (part of Azure Monitor) in Azure Government.
+
+**Enable Application Insights for [ASP.NET](#web) & [ASP.NET Core](#web) with Visual Studio**
+
+In Azure Government, you can enable Application Insights with a [codeless agent](../azure-monitor/app/azure-web-apps.md) for your Azure App Services hosted applications or via the traditional **Add Applications Insights Telemetry** button in Visual Studio, which requires a small manual workaround. If you are experiencing the associated issue, you may see error messages like "There is no Azure subscription associated with this account" or "The selected subscription does not support Application Insights" even though the `microsoft.insights` resource provider has a status of registered for the subscription. To mitigate this issue, you must perform the following steps:
+
+1. Switch Visual Studio to [target the Azure Government cloud](./documentation-government-welcome.md).
+2. Create (or if already existing, set) the User Environment variable for `AzureGraphApiVersion` as follows:
+
+ - Variable name: `AzureGraphApiVersion`
+ - Variable value: `2014-04-01`
+
+ To create a User Environment variable, go to **Control Panel > System > Advanced system settings > Advanced > Environment Variables**.
+
+3. Make the appropriate Application Insights SDK endpoint modifications for either [ASP.NET](#web) or [ASP.NET Core](#web) depending on your project type.
+
+**Snapshot Debugger** is now available for Azure Government customers. To use Snapshot Debugger, the only other prerequisite is to ensure that you are using [Snapshot Collector version 1.3.5](https://www.nuget.org/packages/Microsoft.ApplicationInsights.SnapshotCollector/1.3.5-pre-1906.403) or later. Then follow the standard [Snapshot Debugger documentation](../azure-monitor/app/snapshot-debugger.md).
+
+**SDK endpoint modifications** - In order to send data from Application Insights to the Azure Government region, you will need to modify the default endpoint addresses that are used by the Application Insights SDKs. Each SDK requires slightly different modifications, as described in [Application Insights overriding default endpoints](../azure-monitor/app/custom-endpoints.md).
+
+>[!NOTE]
+>[**Connection strings**](../azure-monitor/app/sdk-connection-string.md?tabs=net) are the new preferred method of setting custom endpoints within Application Insights.
+
+**Firewall exceptions** - Application Insights uses several IP addresses. You might need to know these addresses if the app that you are monitoring is hosted behind a firewall.
+
+>[!NOTE]
+>Although these addresses are static, it's possible that we will need to change them from time to time. All Application Insights traffic represents outbound traffic except for availability monitoring and webhooks, which require inbound firewall rules.
+
+You need to open some **outgoing ports** in your server's firewall to allow the Application Insights SDK and/or Status Monitor to send data to the portal:
+
+|Purpose|URL|IP address|Ports|
+|-||-|--|
+|Telemetry|dc.applicationinsights.us|23.97.4.113|443|
+ ## Media
In addition to the above, Microsoft also tags prefixes based on the service they
>[!NOTE] >Microsoft does not honor any BGP community values that you set on the routes advertised to Microsoft.
-### [Azure Private Link](../private-link/private-link-overview.md)
+### [Private Link](../private-link/private-link-overview.md)
For Private Link services availability, see [Azure Private Link availability](../private-link/availability.md).
azure-government Secure Azure Computing Architecture https://github.com/MicrosoftDocs/azure-docs/commits/master/articles/azure-government/compliance/secure-azure-computing-architecture.md
Title: Secure Azure Computing Architecture
-description: Learn about the Secure Azure Computing Architecture (SACA). Using SACA allows U.S. DoD and civilian customers to comply with the SCCA FRD.
+description: Learn about the Secure Azure Computing Architecture (SACA). Using SACA allows US DoD and civilian customers to comply with the SCCA FRD.
Previously updated : 4/9/2019 Last updated : 08/27/2021 # Secure Azure Computing Architecture
-U.S. Department of Defense (DoD) customers who deploy workloads to Azure have asked for guidance to set up secure virtual networks and configure the security tools and services that are stipulated by DoD standards and practice.
+US Department of Defense (DoD) customers who deploy workloads to Azure have asked for guidance to set up secure virtual networks and configure the security tools and services that are stipulated by DoD standards and practice.
-The Defense Information System Agency (DISA) published the [Secure Cloud Computing Architecture (SCCA) Functional Requirements Document (FRD)](https://rmf.org/wp-content/uploads/2018/05/SCCA_FRD_v2-9.pdf) in 2017. SCCA describes the functional objectives for securing the Defense Information System NetworkΓÇÖs (DISN) and commercial cloud provider connection points. SCCA also describes how mission owners secure cloud applications at the connection boundary. Every DoD entity that connects to the commercial cloud must follow the guidelines set forth in the SCCA FRD.
+In 2017, the Defense Information System Agency (DISA) published the [Secure Cloud Computing Architecture (SCCA) Functional Requirements Document (FRD)](https://rmf.org/wp-content/uploads/2018/05/SCCA_FRD_v2-9.pdf). SCCA describes the functional objectives for securing the Defense Information System NetworkΓÇÖs (DISN) and commercial cloud provider connection points. SCCA also describes how mission owners secure cloud applications at the connection boundary. Every DoD entity that connects to the commercial cloud must follow the guidelines set forth in the SCCA FRD.
The SCCA has four components:
The SCCA has four components:
- Virtual Datacenter Managed Services (VDMS) - Trusted Cloud Credential Manager (TCCM)
-Microsoft has developed a solution that meets the SCCA requirements for both IL4 and IL5 workloads that run in Azure. This Azure-specific solution is called the Secure Azure Computing Architecture (SACA). Customers who deploy SACA are in compliance with the SCCA FRD. They can enable DoD customers to move workloads into Azure after they're connected.
+Microsoft has developed a solution that helps customers meet the SCCA requirements for both [DoD IL4](/azure/compliance/offerings/offering-dod-il4) and [DoD IL5](/azure/compliance/offerings/offering-dod-il5) workloads that run in Azure. This Azure-specific solution is called the Secure Azure Computing Architecture (SACA), and it can help customers comply with the SCCA FRD. It can enable DoD customers to move workloads into Azure after they're connected.
-SCCA guidance and architectures are specific to DoD customers, but they also help civilian customers comply with trusted internet connection (TIC) guidance and help commercial customers that want to implement a secure DMZ to protect their Azure environments.
+SCCA guidance and architectures are specific to DoD customers, but they also help civilian customers comply with [Trusted Internet Connections](/azure/azure-government/compliance/compliance-tic) (TIC) guidance and help commercial customers that want to implement a secure DMZ to protect their Azure environments.
## Secure Cloud Computing Architecture components
As mentioned earlier, you can build this SACA reference by using a variety of ap
- [Azure Monitor](../../azure-monitor/overview.md) - [Azure Security Center](../../security-center/security-center-introduction.md)
- - [Azure Network Watcher](../../network-watcher/network-watcher-monitoring-overview.md)
+ - [Network Watcher](../../network-watcher/network-watcher-monitoring-overview.md)
- [Azure Key Vault](../../key-vault/general/overview.md) - [Azure Active Directory](../../active-directory/fundamentals/active-directory-whatis.md)
- - [Azure Application Gateway](../../application-gateway/overview.md)
+ - [Application Gateway](../../application-gateway/overview.md)
- [Azure Firewall](../../firewall/overview.md) - [Azure Front Door](../../frontdoor/front-door-overview.md)
- - [Azure security groups](../../virtual-network/network-security-groups-overview.md)
+ - [Network security groups](../../virtual-network/network-security-groups-overview.md)
- [Azure DDoS Protection](../../ddos-protection/ddos-protection-overview.md) - [Azure Sentinel](../../sentinel/overview.md) - Sizing - A sizing exercise must be completed. Look at the number of concurrent connections you might have through the SACA instance and the network throughput requirements.
- - This step is critical. It helps to size the VMs, ExpressRoute circuits, and identify the licenses that are required from the various vendors you use in your SACA deployment.
+ - This step is critical. It helps to size the VMs, Azure ExpressRoute circuits, and identify the licenses that are required from the various vendors you use in your SACA deployment.
- A good cost analysis canΓÇÖt be done without this sizing exercise. Correct sizing also allows for best performance. ## Most common deployment scenario
- Several Microsoft customers have gone through the full deployment or at least the planning stages of their SACA environments. Their experiences revealed insight into the most common deployment scenario. The following diagram shows the most common architecture:
+Several Microsoft customers have gone through the full deployment or at least the planning stages of their SACA environments. Their experiences revealed insight into the most common deployment scenario. The following diagram shows the most common architecture:
![SACA reference architecture diagram](media/sacav2commonscenario.png)
azure-government Documentation Government Impact Level 5 https://github.com/MicrosoftDocs/azure-docs/commits/master/articles/azure-government/documentation-government-impact-level-5.md
Title: Azure Government isolation guidelines for Impact Level 5 description: Guidance for configuring Azure Government services for DoD Impact Level 5 workloads-
-cloud: gov
- --+ Previously updated : 07/28/2021
-#Customer intent: As a DoD mission owner, I want to know how to implement a workload at Impact Level 5 in Microsoft Azure Government.
Last updated : 08/27/2021 # Isolation guidelines for Impact Level 5 workloads
Azure Government is available to US federal, state, local, and tribal government
## Principles and approach
-You need to address two key areas for Azure services in IL5 scope: compute isolation and storage isolation. We'll focus in this article on how Azure services can help isolate the compute and storage of IL5 data. The SRG allows for a shared management and network infrastructure. **This article is focused on Azure Government compute and storage isolation approaches for US Gov Arizona, US Gov Texas, and US Gov Virginia regions.** If an Azure service is available in Azure Government DoD regions and authorized at IL5, then it is by default suitable for IL5 workloads with no extra isolation configuration required. Azure Government DoD regions are reserved for DoD agencies and their partners, enabling physical separation from non-DoD tenants by design.
+You need to address two key areas for Azure services in IL5 scope: compute isolation and storage isolation. We'll focus in this article on how Azure services can help isolate the compute and storage of IL5 data. The SRG allows for a shared management and network infrastructure. **This article is focused on Azure Government compute and storage isolation approaches for US Gov Arizona, US Gov Texas, and US Gov Virginia regions.** If an Azure service is available in Azure Government DoD regions and authorized at IL5, then it is by default suitable for IL5 workloads with no extra isolation configuration required. Azure Government DoD regions are reserved for DoD agencies and their partners, enabling physical separation from non-DoD tenants by design. For more information, see [DoD in Azure Government](./documentation-government-overview-dod.md).
> [!IMPORTANT] > You are responsible for designing and deploying your applications to meet DoD IL5 compliance requirements. In doing so, you should not include sensitive or restricted information in Azure resource names, as explained in **[Considerations for naming Azure resources](./documentation-government-concept-naming-resources.md).**
For AI and machine learning services availability in Azure Government, see [Prod
- Configure encryption at rest of content in Cognitive Services Custom Vision [using customer-managed keys in Azure Key Vault](../cognitive-services/custom-vision-service/encrypt-data-at-rest.md#customer-managed-keys-with-azure-key-vault).
-### [Cognitive
+### [Cognitive
- Configure encryption at rest of content in the Face service by [using customer-managed keys in Azure Key Vault](../cognitive-services/face/encrypt-data-at-rest.md).
-### [Cognitive
+### [Cognitive
- Configure encryption at rest of content in the Language Understanding service by [using customer-managed keys in Azure Key Vault](../cognitive-services/luis/encrypt-data-at-rest.md).
For AI and machine learning services availability in Azure Government, see [Prod
- Configure encryption at rest of content in the Translator service by [using customer-managed keys in Azure Key Vault](../cognitive-services/translator/encrypt-data-at-rest.md).
-### [Cognitive
+### [Cognitive
- Configure encryption at rest of content in Speech Services by [using customer-managed keys in Azure Key Vault](../cognitive-services/speech-service/speech-encryption-of-data-at-rest.md).
For Analytics services availability in Azure Government, see [Products available
- Data in Azure Data Explorer clusters in Azure is secured and encrypted with Microsoft-managed keys by default. For extra control over encryption keys, you can supply customer-managed keys to use for data encryption and manage [encryption of your data](/azure/data-explorer/security#data-encryption) at the storage level with your own keys.
+### [Azure HDInsight](https://azure.microsoft.com/services/hdinsight/)
+
+- Azure HDInsight can be deployed to existing storage accounts that have enabled appropriate [Storage service encryption](#storage-encryption-with-key-vault-managed-keys), as discussed in the guidance for Azure Storage.
+- Azure HDInsight enables a database option for certain configurations. Ensure the appropriate database configuration for transparent data encryption (TDE) is enabled on the option you choose. This process is discussed in the guidance for [Azure SQL Database](#azure-sql-database).
+ ### [Azure Stream Analytics](https://azure.microsoft.com/services/stream-analytics/) - Configure encryption at rest of content in Azure Stream Analytics by [using customer-managed keys in Azure Key Vault](../stream-analytics/data-protection.md).
For Analytics services availability in Azure Government, see [Products available
- Configure encryption at rest of content in Azure Event Hubs by [using customer-managed keys in Azure Key Vault](../event-hubs/configure-customer-managed-key.md).
-### [HDInsight](https://azure.microsoft.com/services/hdinsight/)
--- Azure HDInsight can be deployed to existing storage accounts that have enabled appropriate [Storage service encryption](#storage-encryption-with-key-vault-managed-keys), as discussed in the guidance for Azure Storage.-- Azure HDInsight enables a database option for certain configurations. Ensure the appropriate database configuration for transparent data encryption (TDE) is enabled on the option you choose. This process is discussed in the guidance for [Azure SQL Database](#azure-sql-database).- ## Compute
For Containers services availability in Azure Government, see [Products availabl
For Databases services availability in Azure Government, see [Products available by region](https://azure.microsoft.com/global-infrastructure/services/?products=azure-sql,sql-server-stretch-database,redis-cache,database-migration,postgresql,mariadb,mysql,sql-database,cosmos-db&regions=non-regional,usgov-non-regional,us-dod-central,us-dod-east,usgov-arizona,usgov-texas,usgov-virginia). For a list of services in scope for DoD IL5 PA, see [Azure Government services by audit scope](./compliance/azure-services-in-fedramp-auditscope.md#azure-government-services-by-audit-scope). Guidance below is provided only for IL5 PA services that require extra configuration to support IL5 workloads.
-### [Azure API for FHIR](https://azure.microsoft.com/services/azure-api-for-fhir/)
-
-Azure API for FHIR supports Impact Level 5 workloads in Azure Government with this configuration:
--- Configure encryption at rest of content in Azure API for FHIR [using customer-managed keys in Azure Key Vault](../healthcare-apis/azure-api-for-fhir/customer-managed-key.md)- ### [Azure Cache for Redis](https://azure.microsoft.com/services/cache/) Azure Cache for Redis supports Impact Level 5 workloads in Azure Government with no extra configuration required.
Azure Cache for Redis supports Impact Level 5 workloads in Azure Government with
- Data encryption with customer-managed keys for Azure Database for PostgreSQL Single Server is set at the server level. For a given server, a customer-managed key, called the key encryption key (KEK), is used to encrypt the data encryption key (DEK) used by the service. For more information, see [Azure Database for PostgreSQL Single Server data encryption with a customer-managed key](../postgresql/concepts-data-encryption-postgresql.md).
+### [Azure Healthcare APIs](https://azure.microsoft.com/services/healthcare-apis/) (formerly Azure API for FHIR)
+
+Azure Healthcare APIs supports Impact Level 5 workloads in Azure Government with this configuration:
+
+- Configure encryption at rest of content in Azure Healthcare APIs [using customer-managed keys in Azure Key Vault](../healthcare-apis/azure-api-for-fhir/customer-managed-key.md)
+ ### [Azure SQL Database](https://azure.microsoft.com/services/sql-database/) - Add transparent data encryption with customer-managed keys via Azure Key Vault. For more information, see the [Azure SQL documentation](../azure-sql/database/transparent-data-encryption-byok-overview.md).
azure-monitor Container Insights Log Query https://github.com/MicrosoftDocs/azure-docs/commits/master/articles/azure-monitor/containers/container-insights-log-query.md
on ContainerID
// at this point before the next pipe, columns from both tables are available to be "projected". Due to both // tables having a "Name" column, we assign an alias as PodName to one column which we actually want | project TimeGenerated, PodName, LogEntry, LogEntrySource
-| extend TimeGenerated = TimeGenerated - 21600s | order by TimeGenerated desc
| summarize by TimeGenerated, LogEntry | order by TimeGenerated desc ```
azure-monitor Azure Cli Log Analytics Workspace Sample https://github.com/MicrosoftDocs/azure-docs/commits/master/articles/azure-monitor/logs/azure-cli-log-analytics-workspace-sample.md
+
+ Title: Managing Azure Monitor Logs in Azure CLI
+description: Learn how to use Azure CLI commands to manage a workspace in Azure Monitor Logs, including how workspaces interact with other Azure services.
+++ Last updated : 08/16/2021+++
+# Managing Azure Monitor Logs in Azure CLI
+
+Use the Azure CLI commands described here to manage your log analytics workspace in Azure Monitor.
+
+> [!NOTE]
+> On August 31, 2024, Microsoft will retire the Log Analytics agent. You can use the Azure Monitor agent after that time. For more information, see [Overview of Azure Monitor agents](../agents/agents-overview.md).
++
+## Create a workspace for Monitor Logs
+
+Run the [az group create](/cli/azure/group#az_group_create) command to create a resource group or use an existing resource group. To create a workspace, use the [az monitor log-analytics workspace create](/cli/azure/monitor/log-analytics/workspace#az_monitor_log_analytics_workspace_create) command.
+
+```azurecli
+az group create --name ContosoRG --location eastus2
+az monitor log-analytics workspace create --resource-group ContosoRG \
+ --workspace-name ContosoWorkspace
+```
+
+For more information about workspaces, see [Azure Monitor Logs overview](/azure/azure-monitor/logs/data-platform-logs).
+
+## List tables in your workspace
+
+Each workspace contains tables with columns that have multiple rows of data. Each table is defined by a unique set of columns of data provided by the data source.
+
+To see the tables in your workspace, use the [az monitor log-analytics workspace table list](/cli/azure/monitor/log-analytics/workspace/table#az_monitor_log_analytics_workspace_table_list) command:
+
+```azurecli
+az monitor log-analytics workspace table list --resource-group ContosoRG \
+ --workspace-name ContosoWorkspace --output table
+```
+
+The output value `table` presents the results in a more readable format. For more information, see [Output formatting](/cli/azure/use-cli-effectively#output-formatting).
+
+To change the retention time for a table, run the [az monitor log-analytics workspace table update](/cli/azure/monitor/log-analytics/workspace/table#az_monitor_log_analytics_workspace_table_update) command:
+
+```azurecli
+az monitor log-analytics workspace table update --resource-group ContosoRG \
+ --workspace-name ContosoWorkspace --name Syslog --retention-time 45
+```
+
+The retention time is between 30 and 730 days.
+
+For more information about tables, see [Data structure](/azure/azure-monitor/logs/data-platform-logs#data-structure).
+
+## Export data from selected tables
+
+You can continuously export data from selected tables to an Azure storage account or Azure Event Hubs. Use the [az monitor log-analytics workspace data-export create](/cli/azure/monitor/log-analytics/workspace/data-export#az_monitor_log_analytics_workspace_data_export_create) command:
+
+```azurecli
+az monitor log-analytics workspace data-export create --resource-group ContosoRG \
+ --workspace-name ContosoWorkspace --name DataExport --table Syslog \
+ --destination /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/ContosoRG/providers/Microsoft.Storage/storageAccounts/exportaccount \
+ --enable
+```
+
+To see your data exports, run the [az monitor log-analytics workspace data-export list](/cli/azure/monitor/log-analytics/workspace/data-export#az_monitor_log_analytics_workspace_data_export_list) command.
+
+```azurecli
+az monitor log-analytics workspace data-export list --resource-group ContosoRG \
+ --workspace-name ContosoWorkspace --output table
+```
+
+To delete a data export, run the [az monitor log-analytics workspace data-export delete](/cli/azure/monitor/log-analytics/workspace/data-export#az_monitor_log_analytics_workspace_data_export_delete) command. The `--yes` parameter skips confirmation.
+
+```azurecli
+az monitor log-analytics workspace data-export delete --resource-group ContosoRG \
+ --workspace-name ContosoWorkspace --name DataExport --yes
+```
+
+For more information about data export, see [Log Analytics workspace data export in Azure Monitor](/azure/azure-monitor/logs/logs-data-export).
+
+## Manage a linked service
+
+Linked services define a relation from the workspace to another Azure resource. Azure Monitor Logs and Azure resources use this connection in their operations. Example uses of linked services, including an automation account and a workspace association to customer-managed keys.
+
+To create a linked service, run the [az monitor log-analytics workspace linked-service create](/cli/azure/monitor/log-analytics/workspace/linked-service#az_monitor_log_analytics_workspace_linked_service_create) command:
+
+```azurecli
+az monitor log-analytics workspace linked-service create --resource-group ContosoRG \
+ --workspace-name ContosoWorkspace --name linkedautomation \
+ --resource-id /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/ContosoRG/providers/Microsoft.Web/sites/ContosoWebApp09
+
+az monitor log-analytics workspace linked-service list --resource-group ContosoRG \
+ --workspace-name ContosoWorkspace
+```
+
+To remove a linked service relation, run the [az monitor log-analytics workspace linked-service delete](/cli/azure/monitor/log-analytics/workspace/linked-service#az_monitor_log_analytics_workspace_linked_service_delete) command:
+
+```azurecli
+az monitor log-analytics workspace linked-service delete --resource-group ContosoRG \
+ --workspace-name ContosoWorkspace --name linkedautomation
+```
+
+For more information, see [az monitor log-analytics workspace linked-service](/cli/azure/monitor/log-analytics/workspace/linked-service).
+
+## Manage linked storage
+
+If you provide and manage your own storage account for log analytics, you can manage it with these Azure CLI commands.
+
+To link your workspace to a storage account, run the [az monitor log-analytics workspace linked-storage create](/cli/azure/monitor/log-analytics/workspace/linked-storage#az_monitor_log_analytics_workspace_linked_storage_create) command:
+
+```azurecli
+az monitor log-analytics workspace linked-storage create --resource-group ContosoRG \
+ --workspace-name ContosoWorkspace \
+ --storage-accounts /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/ContosoRG/providers/Microsoft.Storage/storageAccounts/contosostorage \
+ --type Alerts
+
+az monitor log-analytics workspace linked-storage list --resource-group ContosoRG \
+ --workspace-name ContosoWorkspace --output table
+```
+
+To remove the link to a storage account, run the [az monitor log-analytics workspace linked-storage delete](/cli/azure/monitor/log-analytics/workspace/linked-storage#az_monitor_log_analytics_workspace_linked_storage_delete) command:
+
+```azurecli
+az monitor log-analytics workspace linked-storage delete --resource-group ContosoRG \
+ --workspace-name ContosoWorkspace --type Alerts
+```
+
+For more information, see, [Using customer-managed storage accounts in Azure Monitor Log Analytics](/azure/azure-monitor/logs/private-storage).
+
+## Manage intelligence packs
+
+To see the available intelligence packs, run the [az monitor log-analytics workspace pack list](/cli/azure/monitor/log-analytics/workspace/pack#az_monitor_log_analytics_workspace_pack_list) command. The command also tells you whether the pack is enabled.
+
+```azurecli
+az monitor log-analytics workspace pack list --resource-group ContosoRG \
+ --workspace-name ContosoWorkspace
+```
+
+Use the [az monitor log-analytics workspace pack enable](/cli/azure/monitor/log-analytics/workspace/pack#az_monitor_log_analytics_workspace_pack_enable) or [az monitor log-analytics workspace pack disable](/cli/azure/monitor/log-analytics/workspace/pack#az_monitor_log_analytics_workspace_pack_disable) commands:
+
+```azurecli
+az monitor log-analytics workspace pack enable --resource-group ContosoRG \
+ --workspace-name ContosoWorkspace --name NetFlow
+
+az monitor log-analytics workspace pack disable --resource-group ContosoRG \
+ --workspace-name ContosoWorkspace --name NetFlow
+```
+
+## Manage saved searches
+
+To create a saved search, run the [az monitor log-analytics workspace saved-search](/cli/azure/monitor/log-analytics/workspace/saved-search#az_monitor_log_analytics_workspace_saved_search_create) command:
+
+```azurecli
+az monitor log-analytics workspace saved-search create --resource-group ContosoRG \
+ --workspace-name ContosoWorkspace --name SavedSearch01 \
+ --category "Log Management" --display-name SavedSearch01 \
+ --saved-query "AzureActivity | summarize count() by bin(TimeGenerated, 1h)" --fa Function01 --fp "a:string = value"
+```
+
+View your saved search by using the [az monitor log-analytics workspace saved-search show](/cli/azure/monitor/log-analytics/workspace/saved-search#az_monitor_log_analytics_workspace_saved_search_show) command. See all saved searches by using [az monitor log-analytics workspace saved-search list](/cli/azure/monitor/log-analytics/workspace/saved-search#az_monitor_log_analytics_workspace_saved_search_list).
+
+```azurecli
+az monitor log-analytics workspace saved-search show --resource-group ContosoRG \
+ --workspace-name ContosoWorkspace --name SavedSearch01
+az monitor log-analytics workspace saved-search list --resource-group ContosoRG \
+ --workspace-name ContosoWorkspace
+```
+
+To delete a saved search, run the [az monitor log-analytics workspace saved-search delete](/cli/azure/monitor/log-analytics/workspace/saved-search#az_monitor_log_analytics_workspace_saved_search_delete) command:
+
+```azurecli
+az monitor log-analytics workspace saved-search delete --resource-group ContosoRG \
+ --workspace-name ContosoWorkspace --name SavedSearch01 --yes
+```
+
+## Clean up deployment
+
+If you created a resource group to test these commands, you can remove the resource group and all its contents by using the [az group delete](/cli/azure/group#az-group-delete) command:
+
+```azurecli
+az group delete --name ContosoRG
+```
+
+If you want to remove a new workspace from an existing resource group, run the [az monitor log-analytics workspace delete](/cli/azure/monitor/log-analytics/workspace#az_monitor_log_analytics_workspace_delete) command:
+
+```azurecli
+az monitor log-analytics workspace delete --resource-group ContosoRG
+ --workspace-name ContosoWorkspace --yes
+```
+
+Log analytics workspaces have a soft delete option. You can recover a deleted workspace for two weeks after deletion. Run the [az monitor log-analytics workspace recover](/cli/azure/monitor/log-analytics/workspace#az_monitor_log_analytics_workspace_recover) command:
+
+```azurecli
+az monitor log-analytics workspace recover --resource-group ContosoRG
+ --workspace-name ContosoWorkspace
+```
+
+In the delete command, add the `--force` parameter to delete the workspace immediately.
+
+## Azure CLI commands used in this article
+
+- [az group create](/cli/azure/group#az_group_create)
+- [az group delete](/cli/azure/group#az-group-delete)
+- [az monitor log-analytics workspace create](/cli/azure/monitor/log-analytics/workspace#az_monitor_log_analytics_workspace_create)
+- [az monitor log-analytics workspace data-export create](/cli/azure/monitor/log-analytics/workspace/data-export#az_monitor_log_analytics_workspace_data_export_create)
+- [az monitor log-analytics workspace data-export delete](/cli/azure/monitor/log-analytics/workspace/data-export#az_monitor_log_analytics_workspace_data_export_delete)
+- [az monitor log-analytics workspace data-export list](/cli/azure/monitor/log-analytics/workspace/data-export#az_monitor_log_analytics_workspace_data_export_list)
+- [az monitor log-analytics workspace delete](/cli/azure/monitor/log-analytics/workspace#az_monitor_log_analytics_workspace_delete)
+- [az monitor log-analytics workspace linked-service create](/cli/azure/monitor/log-analytics/workspace/linked-service#az_monitor_log_analytics_workspace_linked_service_create)
+- [az monitor log-analytics workspace linked-service delete](/cli/azure/monitor/log-analytics/workspace/linked-service#az_monitor_log_analytics_workspace_linked_service_delete)
+- [az monitor log-analytics workspace linked-storage create](/cli/azure/monitor/log-analytics/workspace/linked-storage#az_monitor_log_analytics_workspace_linked_storage_create)
+- [az monitor log-analytics workspace linked-storage delete](/cli/azure/monitor/log-analytics/workspace/linked-storage#az_monitor_log_analytics_workspace_linked_storage_delete)
+- [az monitor log-analytics workspace pack disable](/cli/azure/monitor/log-analytics/workspace/pack#az_monitor_log_analytics_workspace_pack_disable)
+- [az monitor log-analytics workspace pack enable](/cli/azure/monitor/log-analytics/workspace/pack#az_monitor_log_analytics_workspace_pack_enable)
+- [az monitor log-analytics workspace pack list](/cli/azure/monitor/log-analytics/workspace/pack#az_monitor_log_analytics_workspace_pack_list)
+- [az monitor log-analytics workspace recover](/cli/azure/monitor/log-analytics/workspace#az_monitor_log_analytics_workspace_recover)
+- [az monitor log-analytics workspace saved-search delete](/cli/azure/monitor/log-analytics/workspace/saved-search#az_monitor_log_analytics_workspace_saved_search_delete)
+- [az monitor log-analytics workspace saved-search list](/cli/azure/monitor/log-analytics/workspace/saved-search#az_monitor_log_analytics_workspace_saved_search_list)
+- [az monitor log-analytics workspace saved-search show](/cli/azure/monitor/log-analytics/workspace/saved-search#az_monitor_log_analytics_workspace_saved_search_show)
+- [az monitor log-analytics workspace saved-search](/cli/azure/monitor/log-analytics/workspace/saved-search#az_monitor_log_analytics_workspace_saved_search_create)
+- [az monitor log-analytics workspace table list](/cli/azure/monitor/log-analytics/workspace/table#az_monitor_log_analytics_workspace_table_list)
+- [az monitor log-analytics workspace table update](/cli/azure/monitor/log-analytics/workspace/table#az_monitor_log_analytics_workspace_table_update)
+
+## Next steps
+
+[Overview of Log Analytics in Azure Monitor](log-analytics-overview.md)
azure-monitor Logs Dedicated Clusters https://github.com/MicrosoftDocs/azure-docs/commits/master/articles/azure-monitor/logs/logs-dedicated-clusters.md
The capabilities that require dedicated clusters are:
- **[Customer-managed Keys](../logs/customer-managed-keys.md)** - Encrypt the cluster data using keys that are provided and controlled by the customer. - **[Lockbox](../logs/customer-managed-keys.md#customer-lockbox-preview)** - Control Microsoft support engineers access requests to your data. - **[Double encryption](../../storage/common/storage-service-encryption.md#doubly-encrypt-data-with-infrastructure-encryption)** - Protects against a scenario where one of the encryption algorithms or keys may be compromised. In this case, the additional layer of encryption continues to protect your data.-- **[Availability Zones](../../availability-zones/az-overview.md)** - Protect your data from datacenter failures with Availability Zones on dedicated cluster. Availability zones are datacenters in separate physical locations and equipped with independent power, cooling, and networking. This independent infrastructure and physical separation of zones makes an incident far less likely since the workspace can rely on the resources from any of the zones.
+- **[Availability Zones](./availability-zones.md)** - Protect your data from datacenter failures with Availability Zones on dedicated cluster. Availability zones are datacenters in separate physical locations and equipped with independent power, cooling, and networking. This independent infrastructure and physical separation of zones makes an incident far less likely since the workspace can rely on the resources from any of the zones.
- **[Multi-workspace](../logs/cross-workspace-query.md)** - If a customer is using more than one workspace for production it might make sense to use dedicated cluster. Cross-workspace queries will run faster if all workspaces are on the same cluster. It might also be more cost effective to use dedicated cluster as the assigned commitment tier takes into account all cluster ingestion and applies to all its workspaces, even if some of them are small and not eligible for commitment tier discount. - ## Management Dedicated clusters are managed with an Azure resource that represents Azure Monitor Log clusters. All operations are done on this resource using PowerShell or the REST API.
You can have up to 2 active clusters per subscription per region. If the cluster
The user account that creates the clusters must have the standard Azure resource creation permission: `Microsoft.Resources/deployments/*` and cluster write permission `Microsoft.OperationalInsights/clusters/write` by having in their role assignments this specific action or `Microsoft.OperationalInsights/*` or `*/write`.
+**CLI**
+```azurecli
+az monitor log-analytics cluster create --no-wait --resource-group "resource-group-name" --name "cluster-name" --location "region-name" --sku-capacity "daily-ingestion-gigabyte"
+
+# Wait for job completion
+az resource wait --created --ids /subscriptions/subscription-id/resourceGroups/resource-group-name/providers/Microsoft.operationalinsights/clusters/cluster-name --include-response-body true
+```
+ **PowerShell** ```powershell
-New-AzOperationalInsightsCluster -ResourceGroupName {resource-group-name} -ClusterName {cluster-name} -Location {region-name} -SkuCapacity {daily-ingestion-gigabyte} -AsJob
+New-AzOperationalInsightsCluster -ResourceGroupName "resource-group-name" -ClusterName "cluster-name" -Location "region-name" -SkuCapacity "daily-ingestion-gigabyte" -AsJob
# Check when the job is done Get-Job -Command "New-AzOperationalInsightsCluster*" | Format-List -Property *
Content-type: application/json
Should be 202 (Accepted) and a header. -- ### Check cluster provisioning status
-The provisioning of the Log Analytics cluster takes a while to complete. Use one of the following methods to check the provisioning state:
-
-**PowerShell**
+The provisioning of the Log Analytics cluster takes a while to complete. Use one of the following methods to check the *ProvisioningState* property. The value is *ProvisioningAccount* while provisioning and *Succeeded* when completed.
-Run *Get-AzOperationalInsightsCluster* with the resource group name and check the *ProvisioningState* property. The value is *ProvisioningAccount* while provisioning and *Succeeded* when completed. Copy the Azure-AsyncOperation URL value from the response and follow the asynchronous operations status check.
+**CLI**
+```azurecli
+az monitor log-analytics cluster show --resource-group "resource-group-name" --name "cluster-name"
+```
- ```powershell
- Get-AzOperationalInsightsCluster -ResourceGroupName {resource-group-name}
- ```
+**PowerShell**
+```powershell
+Get-AzOperationalInsightsCluster -ResourceGroupName "resource-group-name" -ClusterName "cluster-name"
+```
**REST API** Send a GET request on the cluster resource and look at the *provisioningState* value. The value is *ProvisioningAccount* while provisioning and *Succeeded* when completed. ```rest
- GET https://management.azure.com/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.OperationalInsights/clusters/<cluster-name>?api-version=2021-06-01
+ GET https://management.azure.com/subscriptions/subscription-id/resourceGroups/resource-group-name/providers/Microsoft.OperationalInsights/clusters/cluster-name?api-version=2021-06-01
Authorization: Bearer <token> ```
The *principalId* GUID is generated by the managed identity service at cluster c
- ## Link a workspace to a cluster When a Log Analytics workspace is linked to a dedicated cluster, new data that is ingested into the workspace is routed to the new cluster while existing data remains on the existing cluster. If the dedicated cluster is encrypted using customer-managed keys (CMK), only new data is encrypted with the key. The system abstracts this difference, so you can query the workspace as usual while the system performs cross-cluster queries in the background.
Linking a workspace can be performed only after the completion of the Log Analyt
> [!WARNING] > Linking a workspace to a cluster requires syncing multiple backend components and assuring cache hydration. Since this operation may take up to two hours to complete, you should you run it asynchronously.
+Use the following commands to link a workspace to a cluster:
-**PowerShell**
+**CLI**
+```azurecli
+# Find cluster resource ID
+$clusterResourceId = az monitor log-analytics cluster list --resource-group "resource-group-name" --query "[?contains(name, "cluster-name")]" --query [].id --output table
+
+az monitor log-analytics workspace linked-service create --no-wait --name cluster --resource-group "resource-group-name" --workspace-name "workspace-name" --write-access-resource-id $clusterResourceId
+
+# Wait for job completion
+az resource wait --created --ids /subscriptions/subscription-id/resourceGroups/resource-group-name/providers/Microsoft.operationalinsights/clusters/cluster-name --include-response-body true
+```
-Use the following PowerShell command to link to a cluster:
+**PowerShell**
```powershell # Find cluster resource ID
-$clusterResourceId = (Get-AzOperationalInsightsCluster -ResourceGroupName {resource-group-name} -ClusterName {cluster-name}).id
+$clusterResourceId = (Get-AzOperationalInsightsCluster -ResourceGroupName "resource-group-name" -ClusterName "cluster-name").id
# Link the workspace to the cluster
-Set-AzOperationalInsightsLinkedService -ResourceGroupName {resource-group-name} -WorkspaceName {workspace-name} -LinkedServiceName cluster -WriteAccessResourceId $clusterResourceId -AsJob
+Set-AzOperationalInsightsLinkedService -ResourceGroupName "resource-group-name" -WorkspaceName "workspace-name" -LinkedServiceName cluster -WriteAccessResourceId $clusterResourceId -AsJob
# Check when the job is done Get-Job -Command "Set-AzOperationalInsightsLinkedService" | Format-List -Property *
When a cluster is configured with customer-managed keys, data ingested to the wo
```azurecli az monitor log-analytics workspace show --resource-group "resource-group-name" --workspace-name "workspace-name" ```+ **PowerShell** ```powershell
After you create your cluster resource and it is fully provisioned, you can edit
```azurecli az monitor log-analytics cluster list --resource-group "resource-group-name" ```+ **PowerShell** ```powershell
When the data volume to your linked workspaces change over time and you want to
**CLI** - ```azurecli
-az monitor log-analytics cluster update --name "cluster-name" --resource-group "resource-group-name" --sku-capacity 500
+az monitor log-analytics cluster update --resource-group "resource-group-name" --name "cluster-name" --sku-capacity 500
``` ### PowerShell
Content-type: application/json
- ### Update billingType in cluster The *billingType* property determines the billing attribution for the cluster and its data:
You can unlink a workspace from a cluster. After unlinking a workspace from the
Old data of the unlinked workspace might be left on the cluster. If this data is encrypted using customer-managed keys (CMK), the Key Vault secrets are kept. The system is abstracts this change from Log Analytics users. Users can just query the workspace as usual. The system performs cross-cluster queries on the backend as needed with no indication to users. > [!WARNING]
-> There is a limit of two linking operations for a specific workspace within a month. Take time to consider and plan unlinking actions accordingly.
+> There is a limit of two link operations for a specific workspace within a month. Take time to consider and plan unlinking actions accordingly.
+
+Use the following commands to unlink a workspace from cluster:
**CLI**
az monitor log-analytics workspace linked-service delete --resource-group "resou
**PowerShell**
-Use the following PowerShell command to unlink a workspace from cluster:
- ```powershell # Unlink a workspace from cluster
-Remove-AzOperationalInsightsLinkedService -ResourceGroupName {resource-group-name} -WorkspaceName {workspace-name} -LinkedServiceName cluster
+Remove-AzOperationalInsightsLinkedService -ResourceGroupName "resource-group-name" -WorkspaceName {workspace-name} -LinkedServiceName cluster
``` -- ## Delete cluster You must unlink all workspaces from a dedicated cluster before deleting it. This requires *write* permissions on the *luster resource to perform this operation.
Within the 14 days after deletion, the cluster resource name is reserved and can
> [!WARNING] > There is a limit of three clusters per subscription. Both active and soft-deleted clusters are counted as part of this. Customers should not create recurrent procedures that create and delete clusters. It has a significant impact on Log Analytics backend systems.
-**PowerShell**
+Use the following commands to delete a cluster:
-Use the following PowerShell command to delete a cluster:
+**CLI**
+```azurecli
+az monitor log-analytics cluster delete --resource-group "resource-group-name" --name $clusterName
+```
+
+**PowerShell**
```powershell Remove-AzOperationalInsightsCluster -ResourceGroupName "resource-group-name" -ClusterName "cluster-name"
azure-resource-manager Loop Modules https://github.com/MicrosoftDocs/azure-docs/commits/master/articles/azure-resource-manager/bicep/loop-modules.md
+
+ Title: Deploy multiple instances of modules in Bicep
+description: Use loops and arrays in a Bicep file to deploy multiple instances of modules.
++++ Last updated : 08/27/2021++
+# Module iteration in Bicep
+
+This article shows you how to create more than one instance of a [module](modules.md) in your Bicep file. You can add a loop to the `module` section of your file and dynamically set the number of modules to deploy. You also avoid repeating syntax in your Bicep file.
+
+You can also use a loop with [resources](loop-resources.md), [properties](loop-properties.md), [variables](loop-variables.md), and [outputs](loop-outputs.md).
+
+## Syntax
+
+Loops can be used declare multiple modules by:
+
+- Iterating over an array.
+
+ ```bicep
+ module <module-symbolic-name> '<module-file>' = [for <item> in <collection>: {
+ <module-properties>
+ }]
+ ```
+
+ You can retrieve the index while iterating through an array:
+
+ ```bicep
+ module <module-symbolic-name> 'module-file' = [for (<item>, <index>) in <collection>: {
+ <module-properties>
+ }]
+ ```
+
+- Using a loop index.
+
+ ```bicep
+ module <module-symbolic-name> '<module-file>' = [for <index> in range(<start>, <stop>): {
+ <module-properties>
+ }]
+ ```
+
+## Loop limits
+
+The Bicep file's loop iterations can't be a negative number or exceed 800 iterations.
+
+## Module iteration
+
+The following example creates the number of modules specified in the `storageCount` parameter. Each module creates a storage account.
+
+```bicep
+param location string = resourceGroup().location
+param storageCount int = 2
+
+var baseName = 'store${uniqueString(resourceGroup().id)}'
+
+module stgModule './storageAccount.bicep' = [for i in range(0, storageCount): {
+ name: '${i}storage${baseName}'
+ params: {
+ storageName: '${i}${baseName}'
+ location: location
+ }
+}]
+```
+
+Notice the index `i` is used in creating the storage account resource name. The storage account is passed as a parameter value to the module.
+
+The following example creates one storage account for each name provided in the `storageNames` parameter by calling a module.
+
+```bicep
+param rgLocation string = resourceGroup().location
+param storageNames array = [
+ 'contoso'
+ 'fabrikam'
+ 'coho'
+]
+
+module stgModule './storageAccount.bicep' = [for name in storageNames: {
+ name: '${name}${uniqueString(resourceGroup().id)}'
+ params: {
+ storageName: name
+ location: location
+ }
+}]
+
+```
+
+Directly referencing a resource module or module collection is not currently supported in output loops. In order to loop outputs, apply an array indexer to the expression. See an example in [Output iteration](loop-outputs.md#output-iteration).
+
+## Module iteration with condition
+
+The following example shows a Bicep file with a filtered module loop. Filters must be expressions that evaluate to a boolean value.
+
+```bicep
+param location string = resourceGroup().location
+param storageCount int = 2
+param createNewStorage bool = true
+
+var baseName = 'store${uniqueString(resourceGroup().id)}'
+
+module stgModule './storageAccount.bicep' = [for i in range(0, storageCount): if(createNewStorage) {
+ name: '${i}storage${baseName}'
+ params: {
+ storageName: '${i}${baseName}'
+ location: location
+ }
+}]
+```
+
+In the preceding example, the module is called only when the boolean value is `true`.
+
+Filters are also supported with [resource loops](loop-resources.md).
+
+## Deploy in batches
+
+By default, Resource Manager creates resources in parallel. When you use a loop to create multiple instances of a resource type, those instances are all deployed at the same time. The order in which they're created isn't guaranteed. There's no limit to the number of resources deployed in parallel, other than the total limit of 800 resources in the Bicep file.
+
+You might not want to update all instances of a resource type at the same time. For example, when updating a production environment, you may want to stagger the updates so only a certain number are updated at any one time. You can specify that a subset of the instances be batched together and deployed at the same time. The other instances wait for that batch to complete.
+
+To serially deploy instances of a module, add the [batchSize decorator](./file.md#resource-and-module-decorators). Set its value to the number of instances to deploy concurrently. A dependency is created on earlier instances in the loop, so it doesn't start one batch until the previous batch completes.
+
+```bicep
+param location string = resourceGroup().location
+
+@batchSize(2)
+module stgModule './storageAccount.bicep' = [for i in range(0, 4): {
+ name: '${i}storage${uniqueString(resourceGroup().id)}'
+ params: {
+ storageName: '${i}${baseName}'
+ location: location
+ }
+}]
+```
+
+For purely sequential deployment, set the batch size to 1.
+
+## Next steps
+
+- For other uses of the loop, see:
+ - [Resource iteration in Bicep files](loop-resources.md)
+ - [Property iteration in Bicep files](loop-properties.md)
+ - [Variable iteration in Bicep files](loop-variables.md)
+ - [Output iteration in Bicep files](loop-outputs.md)
+- If you want to learn about the sections of a Bicep file, see [Understand the structure and syntax of Bicep files](file.md).
+- For information about how to deploy multiple resources, see [Use Bicep modules](modules.md).
+- To set dependencies on resources that are created in a loop, see [Set resource dependencies](./resource-declaration.md#set-resource-dependencies).
+- To learn how to deploy with PowerShell, see [Deploy resources with Bicep and Azure PowerShell](deploy-powershell.md).
+- To learn how to deploy with Azure CLI, see [Deploy resources with Bicep and Azure CLI](deploy-cli.md).
azure-resource-manager Loop Outputs https://github.com/MicrosoftDocs/azure-docs/commits/master/articles/azure-resource-manager/bicep/loop-outputs.md
Last updated 06/01/2021
This article shows you how to create more than one value for an output in your Bicep file. You can add a loop to the file's `output` section and dynamically return several items during deployment.
-You can also use a loop with [resources](loop-resources.md), [properties in a resource](loop-properties.md), and [variables](loop-variables.md).
+You can also use a loop with [modules](loop-modules.md), [resources](loop-resources.md), [properties in a resource](loop-properties.md), and [variables](loop-variables.md).
## Syntax
Loops can be used to return many items during deployment by:
## Loop limits
-The Bicep file's loop iterations can't be a negative number or exceed 800 iterations. To deploy Bicep files, install the latest version of [Bicep tools](install.md).
+The Bicep file's loop iterations can't be a negative number or exceed 800 iterations.
## Output iteration
azure-resource-manager Loop Properties https://github.com/MicrosoftDocs/azure-docs/commits/master/articles/azure-resource-manager/bicep/loop-properties.md
This article shows you how to create more than one instance of a property in Bic
You can only use a loop with top-level resources, even when applying a loop to a property. To learn about changing a child resource to a top-level resource, see [Iteration for a child resource](loop-resources.md#iteration-for-a-child-resource).
-You can also use a loop with [resources](loop-resources.md), [variables](loop-variables.md), and [outputs](loop-outputs.md).
+You can also use a loop with [modules](loop-modules.md), [resources](loop-resources.md), [variables](loop-variables.md), and [outputs](loop-outputs.md).
## Syntax
Loops can be used to declare multiple properties by:
## Loop limits
-The Bicep file's loop iterations can't be a negative number or exceed 800 iterations. To deploy Bicep files, install the latest version of [Bicep tools](install.md).
+The Bicep file's loop iterations can't be a negative number or exceed 800 iterations.
## Property iteration
azure-resource-manager Loop Resources https://github.com/MicrosoftDocs/azure-docs/commits/master/articles/azure-resource-manager/bicep/loop-resources.md
Last updated 07/19/2021
This article shows you how to create more than one instance of a resource in your Bicep file. You can add a loop to the `resource` section of your file and dynamically set the number of resources to deploy. You also avoid repeating syntax in your Bicep file.
-You can also use a loop with [properties](loop-properties.md), [variables](loop-variables.md), and [outputs](loop-outputs.md).
+You can also use a loop with [modules](loop-modules.md), [properties](loop-properties.md), [variables](loop-variables.md), and [outputs](loop-outputs.md).
If you need to specify whether a resource is deployed at all, see [condition element](conditional-resource-deployment.md).
Loops can be used declare multiple resources by:
## Loop limits
-The Bicep file's loop iterations can't be a negative number or exceed 800 iterations. To deploy Bicep files, install the latest version of [Bicep tools](install.md).
+The Bicep file's loop iterations can't be a negative number or exceed 800 iterations.
## Resource iteration
resource parentResources 'Microsoft.Example/examples@2020-06-06' = [for parent i
}] ```
-Filters are also supported with module loops.
+Filters are also supported with [module loops](loop-modules.md).
## Deploy in batches
By default, Resource Manager creates resources in parallel. When you use a loop
You might not want to update all instances of a resource type at the same time. For example, when updating a production environment, you may want to stagger the updates so only a certain number are updated at any one time. You can specify that a subset of the instances be batched together and deployed at the same time. The other instances wait for that batch to complete.
-To serially deploy instances of a resource, add the [batchSize decorator](./file.md#resource-and-module-decorators). Set its value to the number of instances to deploy at a time. A dependency is created on earlier instances in the loop, so it doesn't start one batch until the previous batch completes.
+To serially deploy instances of a resource, add the [batchSize decorator](./file.md#resource-and-module-decorators). Set its value to the number of instances to deploy concurrently. A dependency is created on earlier instances in the loop, so it doesn't start one batch until the previous batch completes.
```bicep param rgLocation string = resourceGroup().location
resource storageAcct 'Microsoft.Storage/storageAccounts@2021-02-01' = [for i in
}] ```
+For purely sequential deployment, set the batch size to 1.
+ ## Iteration for a child resource You can't use a loop for a nested child resource. To create more than one instance of a child resource, change the child resource to a top-level resource.
azure-resource-manager Loop Variables https://github.com/MicrosoftDocs/azure-docs/commits/master/articles/azure-resource-manager/bicep/loop-variables.md
Last updated 06/01/2021
This article shows you how to create more than one value for a variable in your Bicep file. You can add a loop to the `variables` section and dynamically set the number of items for a variable during deployment. You also avoid repeating syntax in your Bicep file.
-You can also use copy with [resources](loop-resources.md), [properties in a resource](loop-properties.md), and [outputs](loop-outputs.md).
+You can also use copy with [modules](loop-modules.md), [resources](loop-resources.md), [properties in a resource](loop-properties.md), and [outputs](loop-outputs.md).
## Syntax
Loops can be used to declare multiple variables by:
## Loop limits
-The Bicep file's loop iterations can't be a negative number or exceed 800 iterations. To deploy Bicep files, install the latest version of [Bicep tools](install.md).
+The Bicep file's loop iterations can't be a negative number or exceed 800 iterations.
## Variable iteration
azure-resource-manager Deployment Script Template https://github.com/MicrosoftDocs/azure-docs/commits/master/articles/azure-resource-manager/templates/deployment-script-template.md
Previously updated : 04/15/2021- Last updated : 08/25/2021+
The deployment script resource is only available in the regions where Azure Cont
> [!IMPORTANT] > A storage account and a container instance are needed for script execution and troubleshooting. You have the options to specify an existing storage account, otherwise the storage account along with the container instance are automatically created by the script service. The two automatically created resources are usually deleted by the script service when the deployment script execution gets in a terminal state. You are billed for the resources until the resources are deleted. To learn more, see [Clean-up deployment script resources](#clean-up-deployment-script-resources).
-> [!IMPORTANT]
-> The deploymentScripts resource API version 2020-10-01 supports [OnBehalfofTokens(OBO)](../../active-directory/develop/v2-oauth2-on-behalf-of-flow.md). By using OBO, the deployment script service uses the deployment principal's token to create the underlying resources for running deployment scripts, which include Azure Container instance, Azure storage account, and role assignments for the managed identity. In older API version, the managed identity is used to create these resources.
-> Retry logic for Azure sign in is now built in to the wrapper script. If you grant permissions in the same template where you run deployment scripts. The deployment script service retries sign in for 10 minutes with 10-second interval until the managed identity role assignment is replicated.
+> [!NOTE]
+> Retry logic for Azure sign in is now built in to the wrapper script. If you grant permissions in the same template as your deployment scripts, the deployment script service retries sign in for 10 minutes with 10-second interval until the managed identity role assignment is replicated.
## Configure the minimum permissions
-For deployment script API version 2020-10-01 or later, the deployment principal is used to create underlying resources required for the deployment script resource to executeΓÇöa storage account and an Azure container instance. If the script needs to authenticate to Azure and perform Azure-specific actions, we recommend providing the script with a user-assigned managed identity. The managed identity must have the required access to complete the operation in the script.
+For deployment script API version 2020-10-01 or later, there are two principals involved in deployment script execution:
-To configure the least-privilege permissions, you need:
+- **Deployment principal** (the principal used to deploy the template): this principal is used to create underlying resources required for the deployment script resource to execute ΓÇö a storage account and an Azure container instance. To configure the least-privilege permissions, assign a custom role with the following properties to the deployment principal:
-- Assign a custom role with the following properties to the deployment principal:
+ ```json
+ {
+ "roleName": "deployment-script-minimum-privilege-for-deployment-principal",
+ "description": "Configure least privilege for the deployment principal in deployment script",
+ "type": "customRole",
+ "IsCustom": true,
+ "permissions": [
+ {
+ "actions": [
+ "Microsoft.Storage/storageAccounts/*",
+ "Microsoft.ContainerInstance/containerGroups/*",
+ "Microsoft.Resources/deployments/*",
+ "Microsoft.Resources/deploymentScripts/*"
+ ],
+ }
+ ],
+ "assignableScopes": [
+ "[subscription().id]"
+ ]
+ }
+ ```
- ```json
- {
- "roleName": "deployment-script-minimum-privilege-for-deployment-principal",
- "description": "Configure least privilege for the deployment principal in deployment script",
- "type": "customRole",
- "IsCustom": true,
- "permissions": [
- {
- "actions": [
- "Microsoft.Storage/storageAccounts/*",
- "Microsoft.ContainerInstance/containerGroups/*",
- "Microsoft.Resources/deployments/*",
- "Microsoft.Resources/deploymentScripts/*"
- ],
- }
- ],
- "assignableScopes": [
- "[subscription().id]"
- ]
- }
- ```
+ If the Azure Storage and the Azure Container Instance resource providers haven't been registered, you also need to add `Microsoft.Storage/register/action` and `Microsoft.ContainerInstance/register/action`.
+
+- **Deployment script principal**: This principal is only required if the deployment script needs to authenticate to Azure and call Azure CLI/PowerShell. There are two ways to specify the deployment script principal:
- If the Azure Storage and the Azure Container Instance resource providers haven't been registered, you also need to add `Microsoft.Storage/register/action` and `Microsoft.ContainerInstance/register/action`.
+ - Specify a user-assigned managed identity in the `identity` property (see [Sample templates](#sample-templates)). When specified, the script service calls `Connect-AzAccount -Identity` before invoking the deployment script. The managed identity must have the required access to complete the operation in the script. Currently, only user-assigned managed identity is supported for the `identity` property. To login with a different identity, use the second method in this list.
+ - Pass the service principal credentials as secure environment variables, and then can call [Connect-AzAccount](/powershell/module/az.accounts/connect-azaccount) or [az login](/cli/azure/reference-index?view=azure-cli-latest#az_login&preserve-view=true) in the deployment script.
-- If a managed identity is used, the deployment principal needs the **Managed Identity Operator** role (a built-in role) assigned to the managed identity resource.
+ If a managed identity is used, the deployment principal needs the **Managed Identity Operator** role (a built-in role) assigned to the managed identity resource.
## Sample templates
azure-resource-manager Template Tutorial Create First Template https://github.com/MicrosoftDocs/azure-docs/commits/master/articles/azure-resource-manager/templates/template-tutorial-create-first-template.md
New-AzResourceGroupDeployment `
To run this deployment command, you must have the [latest version](/cli/azure/install-azure-cli) of Azure CLI. ```azurecli
-templateFile="{provide-the-path-to-the-template-file}"
+$templateFile="{provide-the-path-to-the-template-file}"
az deployment group create \ --name blanktemplate \ --resource-group myResourceGroup \
azure-signalr Signalr Howto Troubleshoot Guide https://github.com/MicrosoftDocs/azure-docs/commits/master/articles/azure-signalr/signalr-howto-troubleshoot-guide.md
services.MapAzureSignalR(GetType().FullName, options =>
* ASP.NET "No server available" error [#279](https://github.com/Azure/azure-signalr/issues/279) * ASP.NET "The connection is not active, data cannot be sent to the service." error [#324](https://github.com/Azure/azure-signalr/issues/324)
-* "An error occurred while making the HTTP request to https://<API endpoint>. This error could be because the server certificate is not configured properly with HTTP.SYS in the HTTPS case. This error could also be caused by a mismatch of the security binding between the client and the server."
+* "An error occurred while making the HTTP request to `https://<API endpoint>`. This error could be because the server certificate is not configured properly with HTTP.SYS in the HTTPS case. This error could also be caused by a mismatch of the security binding between the client and the server."
### Root cause
To find the root cause of thread pool starvation:
<a name="view_request"></a>
-* How to view the outgoing request from client?
+### How to view the outgoing request from the client?
+ Take ASP.NET Core one for example (ASP.NET one is similar):
- * From browser:
- Take Chrome as an example, you can use **F12** to open the console window, and switch to **Network** tab. You might need to refresh the page using **F5** to capture the network from the very beginning.
+* From browser:
+ Take Chrome as an example, you can use **F12** to open the console window, and switch to **Network** tab. You might need to refresh the page using **F5** to capture the network from the very beginning.
- :::image type="content" source="./media/signalr-howto-troubleshoot-guide/chrome-network.gif" alt-text="Chrome View Network":::
+ :::image type="content" source="./media/signalr-howto-troubleshoot-guide/chrome-network.gif" alt-text="Chrome View Network":::
- * From C# client:
+* From C# client:
- You can view local web traffics using [Fiddler](https://www.telerik.com/fiddler). WebSocket traffics are supported since Fiddler 4.5.
+ You can view local web traffics using [Fiddler](https://www.telerik.com/fiddler). WebSocket traffics are supported since Fiddler 4.5.
- :::image type="content" source="./media/signalr-howto-troubleshoot-guide/fiddler-view-network-inline.png" alt-text="Fiddler View Network" lightbox="./media/signalr-howto-troubleshoot-guide/fiddler-view-network.png":::
+ :::image type="content" source="./media/signalr-howto-troubleshoot-guide/fiddler-view-network-inline.png" alt-text="Fiddler View Network" lightbox="./media/signalr-howto-troubleshoot-guide/fiddler-view-network.png":::
<a name="restart_connection"></a>
-* How to restart client connection?
+### How to restart client connection?
- Here are the [Sample codes](https://github.com/Azure/azure-signalr/tree/dev/samples) containing restarting connection logic with *ALWAYS RETRY* strategy:
+Here are the [Sample codes](https://github.com/Azure/azure-signalr/tree/dev/samples) containing restarting connection logic with *ALWAYS RETRY* strategy:
- * [ASP.NET Core C# Client](https://github.com/Azure/azure-signalr/tree/dev/samples/ChatSample/ChatSample.CSharpClient/Program.cs#L64)
+* [ASP.NET Core C# Client](https://github.com/Azure/azure-signalr/tree/dev/samples/ChatSample/ChatSample.CSharpClient/Program.cs#L64)
- * [ASP.NET Core JavaScript Client](https://github.com/Azure/azure-signalr/blob/release/1.0.0-preview1/samples/ChatSample/wwwroot/https://docsupdatetracker.net/index.html#L164)
+* [ASP.NET Core JavaScript Client](https://github.com/Azure/azure-signalr/blob/dev/samples/ChatSample/ChatSample.Net50/wwwroot/https://docsupdatetracker.net/index.html#L171)
- * [ASP.NET C# Client](https://github.com/Azure/azure-signalr/tree/dev/samples/AspNet.ChatSample/AspNet.ChatSample.CSharpClient/Program.cs#L78)
+* [ASP.NET C# Client](https://github.com/Azure/azure-signalr/tree/dev/samples/AspNet.ChatSample/AspNet.ChatSample.CSharpClient/Program.cs#L78)
- * [ASP.NET JavaScript Client](https://github.com/Azure/azure-signalr/tree/dev/samples/AspNet.ChatSample/AspNet.ChatSample.JavaScriptClient/wwwroot/https://docsupdatetracker.net/index.html#L71)
+* [ASP.NET JavaScript Client](https://github.com/Azure/azure-signalr/tree/dev/samples/AspNet.ChatSample/AspNet.ChatSample.JavaScriptClient/wwwroot/https://docsupdatetracker.net/index.html#L71)
[Having issues or feedback about the troubleshooting? Let us know.](https://aka.ms/asrs/survey/troubleshooting)
Take ASP.NET Core one for example (ASP.NET one is similar):
In this guide, you learned about how to handle the common issues. You could also learn more generic troubleshooting methods. > [!div class="nextstepaction"]
-> [How to troubleshoot connectivity and message delivery issues](./signalr-howto-troubleshoot-method.md)
+> [How to troubleshoot connectivity and message delivery issues](./signalr-howto-troubleshoot-method.md)
azure-video-analyzer Use Line Crossing https://github.com/MicrosoftDocs/azure-docs/commits/master/articles/azure-video-analyzer/video-analyzer-docs/use-line-crossing.md
In this message, notice these details:
* The number of `counterclockwiseTotal` crossings. * The `direction` contains the direction for this event.
+> [!NOTE]
+> If you deployed Azure resources using the one-click deployment for this tutorial, a Standard DS1 Virtual Machine is created. However, to get accurate results from resource-intensive AI models like YOLO, you may have to increase the VM size. [Resize the VM](../../virtual-machines/windows/resize-vm.md) to increase number of vcpus and memory based on your requirement. Then, reactivate the live pipeline to view inferences.
+ ## Customize for your own environment This tutorial will work with the provided sample video for which we have calculated the correct line coordinates of the line. When you examine the topology file you will see that the `lineCoordinates` parameter contains the following value:
azure-web-pubsub Overview https://github.com/MicrosoftDocs/azure-docs/commits/master/articles/azure-web-pubsub/overview.md
There are many different ways to program with Azure Web PubSub service, as some
- **Build serverless real-time applications**: Use Azure Functions' integration with Azure Web PubSub service to build serverless real-time applications in languages such as JavaScript, C#, Java and Python. - **Use WebSocket subprotocol to do client-side only Pub/Sub** - Azure Web PubSub service provides WebSocket subprotocols to empower authorized clients to publish to other clients in a convenience manner. - **Use provided SDKs to manage the WebSocket connections in self-host app servers** - Azure Web PubSub service provides SDKs in C#, JavaScript, Java and Python to manage the WebSocket connections easily, including broadcast messages to the connections, add connections to some groups, or close the connections, etc.-- **Send messages from server to clients via REST API** - Azure Web PubSub service provides REST API to enable applications to post messages to clients connected, in any REST capable programming languages.
+- **Send messages from server to clients via REST API** - Azure Web PubSub service provides REST API to enable applications to post messages to clients connected, in any REST capable programming languages.
+
+## Next steps
+
backup Offline Backup Azure Data Box https://github.com/MicrosoftDocs/azure-docs/commits/master/articles/backup/offline-backup-azure-data-box.md
Last updated 1/27/2020
# Azure Backup offline backup by using Azure Data Box
-You can use [Azure Data Box](../databox/data-box-overview.md) to seed your large initial Microsoft Azure Recovery Services (MARS) backups offline (without using network) to a Recovery Services vault. This process saves time and network bandwidth that would otherwise be consumed moving large amounts of backup data online over a high-latency network. This enhancement is currently in preview. Offline backup based on Azure Data Box provides two distinct advantages over [offline backup based on the Azure Import/Export service](./backup-azure-backup-import-export.md):
+You can use [Azure Data Box](../databox/data-box-overview.md) to seed your large initial Microsoft Azure Recovery Services (MARS) backups offline (without using network) to a Recovery Services vault. This process saves time and network bandwidth that would otherwise be consumed moving large amounts of backup data online over a high-latency network. Offline backup based on Azure Data Box provides two distinct advantages over [offline backup based on the Azure Import/Export service](./backup-azure-backup-import-export.md):
- There's no need to procure your own Azure-compatible disks and connectors. Azure Data Box ships the disks associated with the selected [Data Box SKU](https://azure.microsoft.com/services/databox/data/). - Azure Backup (MARS Agent) can directly write backup data onto the supported SKUs of Azure Data Box. This capability eliminates the need for you to provision a staging location for your initial backup data. You also don't need utilities to format and copy that data onto the disks.
cloud-services Cloud Services Guestos Msrc Releases https://github.com/MicrosoftDocs/azure-docs/commits/master/articles/cloud-services/cloud-services-guestos-msrc-releases.md
na Previously updated : 8/20/2021 Last updated : 8/27/2021
The following tables show the Microsoft Security Response Center (MSRC) updates
## August 2021 Guest OS
->[!NOTE]
-
->The August Guest OS is currently being rolled out to Cloud Service VMs that are configured for automatic updates. When the rollout is complete, this version will be made available for manual updates through the Azure portal and configuration files. The following patches are included in the August Guest OS. This list is subject to change.
| Product Category | Parent KB Article | Vulnerability Description | Guest OS | Date First Introduced | | | | | | |
-| Rel 21-08 | [5005030] | Latest Cumulative Update(LCU) | 6.34 | Aug 10 , 2021 |
-| Rel 21-08 | [5005036] | IE Cumulative Updates | 2.113, 3.100, 4.93 | Aug 10 , 2021 |
-| Rel 21-08 | [5004238] | Latest Cumulative Update(LCU) | 5.58 | July 13 , 2021 |
-| Rel 21-08 | [4578952] | .NET Framework 3.5 Security and Quality Rollup  | 2.113 | Feb 16, 2021 |
-| Rel 21-08 | [4578955] | .NET Framework 4.5.2 Security and Quality Rollup  | 2.113 | Jun 8, 2021 |
-| Rel 21-08 | [4578953] | .NET Framework 3.5 Security and Quality Rollup  | 4.93 | Feb 16, 2021 |
-| Rel 21-08 | [4578956] | .NET Framework 4.5.2 Security and Quality Rollup  | 4.93 | Feb 16, 2021 |
-| Rel 21-08 | [4578950] | .NET Framework 3.5 Security and Quality Rollup  | 3.100 | Feb 16, 2021 |
-| Rel 21-08 | [4578954] | . NET Framework 4.5.2 Security and Quality Rollup  | 3.100 | Feb 16, 2021 |
-| Rel 21-08 | [5004335] | . NET Framework 3.5 and 4.7.2 Cumulative Update  | 6.34 | Aug 10, 2021 |
-| Rel 21-08 | [5005088] | Monthly Rollup  | 2.113 | Aug 10, 2021 |
-| Rel 21-08 | [5005099] | Monthly Rollup  | 3.100 | Aug 10, 2021 |
-| Rel 21-08 | [5005076] | Monthly Rollup  | 4.93 | Aug 10, 2021 |
-| Rel 21-08 | [5001401] | Servicing Stack update  | 3.100 | Apr 13, 2021 |
-| Rel 21-08 | [5001403] | Servicing Stack update  | 4.93 | Apr 13, 2021 |
-| Rel 21-08 OOB | [4578013] | Standalone Security Update  | 4.93 | Aug 19, 2020 |
-| Rel 21-08 | [5001402] | Servicing Stack update  | 5.58 | Apr 13, 2021 |
-| Rel 21-08 | [5004378] | Servicing Stack update  | 2.113 | July 13, 2021 |
-| Rel 21-08 | [5005112] | Servicing Stack update  | 6.34 | Aug 10, 2021 |
-| Rel 21-08 | [4494175] | Microcode  | 5.58 | Sep 1, 2020 |
-| Rel 21-08 | [4494174] | Microcode  | 6.34 | Sep 1, 2020 |
+| Rel 21-08 | [5005030] | Latest Cumulative Update(LCU) | [6.34] | Aug 10 , 2021 |
+| Rel 21-08 | [5005036] | IE Cumulative Updates | [2.113], [3.100], [4.93] | Aug 10 , 2021 |
+| Rel 21-08 | [5004238] | Latest Cumulative Update(LCU) | [5.58] | July 13 , 2021 |
+| Rel 21-08 | [4578952] | .NET Framework 3.5 Security and Quality Rollup  | [2.113] | Feb 16, 2021 |
+| Rel 21-08 | [4578955] | .NET Framework 4.5.2 Security and Quality Rollup  | [2.113] | Jun 8, 2021 |
+| Rel 21-08 | [4578953] | .NET Framework 3.5 Security and Quality Rollup  | [4.93] | Feb 16, 2021 |
+| Rel 21-08 | [4578956] | .NET Framework 4.5.2 Security and Quality Rollup  | [4.93] | Feb 16, 2021 |
+| Rel 21-08 | [4578950] | .NET Framework 3.5 Security and Quality Rollup  | [3.100] | Feb 16, 2021 |
+| Rel 21-08 | [4578954] | . NET Framework 4.5.2 Security and Quality Rollup  | [3.100] | Feb 16, 2021 |
+| Rel 21-08 | [5004335] | . NET Framework 3.5 and 4.7.2 Cumulative Update  | [6.34] | Aug 10, 2021 |
+| Rel 21-08 | [5005088] | Monthly Rollup  | [2.113] | Aug 10, 2021 |
+| Rel 21-08 | [5005099] | Monthly Rollup  | [3.100] | Aug 10, 2021 |
+| Rel 21-08 | [5005076] | Monthly Rollup  | [4.93] | Aug 10, 2021 |
+| Rel 21-08 | [5001401] | Servicing Stack update  | [3.100] | Apr 13, 2021 |
+| Rel 21-08 | [5001403] | Servicing Stack update  | [4.93] | Apr 13, 2021 |
+| Rel 21-08 OOB | [4578013] | Standalone Security Update  | [4.93] | Aug 19, 2020 |
+| Rel 21-08 | [5001402] | Servicing Stack update  | [5.58] | Apr 13, 2021 |
+| Rel 21-08 | [5004378] | Servicing Stack update  | [2.113] | July 13, 2021 |
+| Rel 21-08 | [5005112] | Servicing Stack update  | [6.34] | Aug 10, 2021 |
+| Rel 21-08 | [4494175] | Microcode  | [5.58] | Sep 1, 2020 |
+| Rel 21-08 | [4494174] | Microcode  | [6.34] | Sep 1, 2020 |
[5005030]: https://support.microsoft.com/kb/5005030 [5005036]: https://support.microsoft.com/kb/5005036
The following tables show the Microsoft Security Response Center (MSRC) updates
[5005112]: https://support.microsoft.com/kb/5005112 [4494175]: https://support.microsoft.com/kb/4494175 [4494174]: https://support.microsoft.com/kb/4494174
+[2.113]: ./cloud-services-guestos-update-matrix.md#family-2-releases
+[3.100]: ./cloud-services-guestos-update-matrix.md#family-3-releases
+[4.93]: ./cloud-services-guestos-update-matrix.md#family-4-releases
+[5.58]: ./cloud-services-guestos-update-matrix.md#family-5-releases
+[6.34]: ./cloud-services-guestos-update-matrix.md#family-6-releases
## July 2021 Guest OS
cloud-services Cloud Services Guestos Update Matrix https://github.com/MicrosoftDocs/azure-docs/commits/master/articles/cloud-services/cloud-services-guestos-update-matrix.md
na Previously updated : 8/13/2021 Last updated : 8/27/2021 # Azure Guest OS releases and SDK compatibility matrix
Unsure about how to update your Guest OS? Check [this][cloud updates] out.
## News updates
+###### **August 27, 2021**
+The August Guest OS has released.
+ ###### **August 13, 2021** The July Guest OS has released.
The September Guest OS has released.
| Configuration string | Release date | Disable date | | | | |
+| WA-GUEST-OS-6.34_202108-01 | August 27, 2021 | Post 6.36 |
| WA-GUEST-OS-6.33_202107-01 | August 13, 2021 | Post 6.35 |
-| WA-GUEST-OS-6.32_202106-01 | July 1, 2021 | Post 6.34 |
+|~~WA-GUEST-OS-6.32_202106-01~~| July 1, 2021 | August 27, 2021 |
|~~WA-GUEST-OS-6.31_202105-0~~| May 26, 2021 | August 13, 2021 | |~~WA-GUEST-OS-6.30_202104-01~~| April 30, 2021 | July 1, 2021 | |~~WA-GUEST-OS-6.29_202103-01~~| March 28, 2021 | May 26, 2021 |
The September Guest OS has released.
| Configuration string | Release date | Disable date | | | | |
+| WA-GUEST-OS-5.58_202108-01 | August 27, 2021 | Post 5.60 |
| WA-GUEST-OS-5.57_202107-01 | August 13, 2021 | Post 5.59 |
-| WA-GUEST-OS-5.56_202106-01 | July 1, 2021 | Post 5.58 |
+|~~WA-GUEST-OS-5.56_202106-01~~| July 1, 2021 | August 27, 2021 |
|~~WA-GUEST-OS-5.55_202105-01~~| May 26, 2021 | August 13, 2021 | |~~WA-GUEST-OS-5.54_202104-01~~| April 30, 2021 | July 1, 2021 | |~~WA-GUEST-OS-5.53_202103-01~~| March 28, 2021 | May 26, 2021 |
The September Guest OS has released.
| Configuration string | Release date | Disable date | | | | |
+| WA-GUEST-OS-4.93_202108-01 | August 27, 2021 | Post 4.95 |
| WA-GUEST-OS-4.92_202107-01 | August 13, 2021 | Post 4.94 |
-| WA-GUEST-OS-4.91_202106-01 | July 1, 2021 | Post 4.93 |
+|~~WA-GUEST-OS-4.91_202106-01~~| July 1, 2021 | August 27, 2021 |
|~~WA-GUEST-OS-4.90_202105-01~~| May 26, 2021 | August 13, 2021 | |~~WA-GUEST-OS-4.89_202104-01~~| April 30, 2021 | July 1, 2021 | |~~WA-GUEST-OS-4.88_202103-01~~| March 28, 2021 | May 26, 2021 |
The September Guest OS has released.
| Configuration string | Release date | Disable date | | | | |
+| WA-GUEST-OS-3.100_202108-01 | August 27, 2021 | Post 3.102 |
| WA-GUEST-OS-3.99_202107-01 | August 13, 2021 | Post 3.101 |
-| WA-GUEST-OS-3.98_202106-01 | July 1, 2021 | Post 3.100 |
+|~~WA-GUEST-OS-3.98_202106-01~~| July 1, 2021 | August 27, 2021 |
|~~WA-GUEST-OS-3.97_202105-01~~| May 26, 2021 | August 13, 2021 | |~~WA-GUEST-OS-3.96_202104-01~~| April 30, 2021 | July 1, 2021 | |~~WA-GUEST-OS-3.95_202103-01~~| March 28, 2021 | May 26, 2021 |
The September Guest OS has released.
| Configuration string | Release date | Disable date | | | | |
+| WA-GUEST-OS-2.113_202108-01 | August 27, 2021 | Post 2.115 |
| WA-GUEST-OS-2.112_202107-01 | August 13, 2021 | Post 2.114 |
-| WA-GUEST-OS-2.111_202106-01 | July 1, 2021 | Post 2.113 |
+|~~WA-GUEST-OS-2.111_202106-01~~| July 1, 2021 | August 27, 2021 |
|~~WA-GUEST-OS-2.110_202105-01~~| May 26, 2021 | August 13, 2021 | |~~WA-GUEST-OS-2.109_202104-01~~| April 30, 2021 | July 1, 2021 | |~~WA-GUEST-OS-2.108_202103-01~~| March 28, 2021 | May 26, 2021 |
data-factory Whats New https://github.com/MicrosoftDocs/azure-docs/commits/master/articles/data-factory/whats-new.md
This page is updated monthly, so revisit it regularly.
<br> <table> <tr><td><b>Service Category</b></td><td><b>Service improvements</b></td><td><b>Details</b></td></tr>
+ <tr><td><b>Continuous integration and delivery (CI/CD)</b></td><td>CICD Improvements with GitHub support in Azure Government and Azure China</td><td>We have added support for GitHub in Azure for U.S. Government and Azure China.<br><a href="https://techcommunity.microsoft.com/t5/azure-data-factory/cicd-improvements-with-github-support-in-azure-government-and/ba-p/2686918">Learn more</a></td></tr>
<tr><td rowspan=2><b>Data Movement</b></td><td>Azure Cosmos DB's API for MongoDB connector supports version 3.6 & 4.0 in Azure Data Factory</td><td>Azure Data Factory Cosmos DBΓÇÖs API for MongoDB connector now supports server version 3.6 & 4.0.<br><a href="connector-azure-cosmos-db-mongodb-api.md">Learn more</a></td></tr> <tr><td>Enhance using COPY statement to load data into Azure Synapse Analytics</td><td>The Azure Data Factory Azure Synapse Analytics connector now supports staged copy and copy source with *.* as wildcardFilename for COPY statement.<br><a href="connector-azure-sql-data-warehouse.md#use-copy-statement">Learn more</a></td></tr> <tr><td><b>Data Flow</b></td><td>REST endpoints are available as source and sink in Data Flow</td><td>Data flows in Azure Data Factory and Azure Synapse Analytics now support REST endpoints as both a source and sink with full support for both JSON and XML payloads.<br><a href="https://techcommunity.microsoft.com/t5/azure-data-factory/rest-source-and-sink-now-available-for-data-flows/ba-p/2596484">Learn more</a></td></tr>
defender-for-iot How To Configure With Sentinel https://github.com/MicrosoftDocs/azure-docs/commits/master/articles/defender-for-iot/organizations/how-to-configure-with-sentinel.md
After connecting a **Subscription**, the hub data is available in Azure Sentinel
In this document, you learned how to connect Defender for IoT to Azure Sentinel. To learn more about threat detection and security data access, see the following articles: -- Learn how to use Azure Sentinel to [Quickstart: Get started with Azure Sentinel](/azure/defender-for-iot/organizations/articles/sentinel/get-visibility.md).
+- Learn how to use Azure Sentinel to [Quickstart: Get started with Azure Sentinel](/azure/sentinel/get-visibility).
healthcare-apis Deploy Iot Connector In Azure https://github.com/MicrosoftDocs/azure-docs/commits/master/articles/healthcare-apis/iot/deploy-iot-connector-in-azure.md
Previously updated : 07/12/2021 Last updated : 08/27/2021 # Deploy the IoT Connector in the Azure portal
+> [!IMPORTANT]
+> Azure Healthcare APIs is currently in PREVIEW. The [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/) include additional legal terms that apply to Azure features that are in beta, preview, or otherwise not yet released into general availability.
+ In this quickstart, you'll learn how to deploy the IoT Connector in the Azure portal. Configuring an IoT Connector will enable you to ingest data from Internet of Things (IoT) into your FHIR service using an Event Hub.
-## Prerequisite
+## Prerequisites
-Before getting started, you should have already deployed the Azure Healthcare APIs. For more information about deploying Azure Healthcare APIs, see **Deploy workspace in the Azure portal**.
+It's important that you have the following prerequisites completed before you begin the steps of creating an IoT Connector instance in Azure Healthcare APIs.
-## Deploy IoT Connector
+* [Azure account](https://azure.microsoft.com/free/search/?OCID=AID2100131_SEM_c4b0772dc7df1f075552174a854fd4bc:G:s&ef_id=c4b0772dc7df1f075552174a854fd4bc:G:s&msclkid=c4b0772dc7df1f075552174a854fd4bc)
+* [Resource group deployed in the Azure portal](https://docs.microsoft.com/azure/azure-resource-manager/management/manage-resource-groups-portal)
+* [Event Hubs namespace and Event Hub deployed in the Azure portal](https://docs.microsoft.com/azure/event-hubs/event-hubs-create)
+* [Workspace deployed in Azure Healthcare APIs](../workspace-overview.md)
+* [FHIR service deployed in Azure Healthcare APIs](../fhir/fhir-portal-quickstart.md)
-1. In the [Azure portal](https://portal.azure.com), browse to the **Resource group** page.
-2. Select the name of your Healthcare APIs workspace.
- [ ![Select workspace resource group](media/select-workspace-resource-group.png) ](media/select-workspace-resource-group.png#lightbox)
+## Deploy IoT Connector
+
+1. Sign in the [Azure portal](https://portal.azure.com), and then enter your Healthcare APIs workspace resource name in the **Search** bar field.
+
+ [ ![Screenshot of entering the workspace resource name in the search bar field.](media/select-workspace-resource-group.png) ](media/select-workspace-resource-group.png#lightbox)
-3. Under Services, select the **IoT Connector** blade.
+2. Select the **IoT Connectors** blade.
- [ ![IoT Connector](media/iot-connector-blade.png) ](media/iot-connector-blade.png#lightbox)
+ [ ![Screenshot of IoT Connectors blade.](media/iot-connector-blade.png) ](media/iot-connector-blade.png#lightbox)
-4. Next, select **Add IoT Connector**.
+3. Next, select **Add IoT Connector**.
- [ ![Add IoT Connector](media/add-iot-connector.png) ](media/add-iot-connector.png#lightbox)
+ [ ![Screenshot of add IoT Connectors](media/add-iot-connector.png) ](media/add-iot-connector.png#lightbox)
## Configure IoT Connector to ingest data
-1. Under the **Basics** tab, enter the Instance Details.
+Under the **Basics** tab, complete the required fields under **Instance details**.
+
+[ ![IoT configure instance details.](media/basics-instance-details.png) ](media/basics-instance-details.png#lightbox)
+
+1. Enter the **IoT Connector name**.
+
+ The **IoT Connector name** is a friendly name for the IoT Connector. Enter a unique name for your IoT Connector. As an example, you can name it `healthdemo-iot`.
+
+2. Enter the **Event Hub name**.
+
+ The Event Hub name is the name of the **Event Hubs Instance** that you've deployed.
+
+ For information about Azure Event Hubs, see [Quickstart: Create an Event Hub using Azure portal](https://docs.microsoft.com/azure/event-hubs/event-hubs-create#create-an-event-hubs-namespace).
+
+3. Enter the **Consumer Group**.
+
+ The Consumer Group name is located by using the **Search** bar to go to the Event Hubs instance that you've deployed and by selecting the **Consumer groups** blade.
+
+ [ ![Consumer group name.](media/consumer-group-name.png) ](media/consumer-group-name.png#lightbox)
+
+ For information about Consumer Groups, see [Features and terminology in Azure Event Hubs](../../event-hubs/event-hubs-features.md?WT.mc_id=Portal-Microsoft_Healthcare_APIs#event-consumers).
+
+4. Enter the name of the **Fully Qualified Namespace**.
+
+ The **Fully Qualified Namespace** is the **Host name** located on your Event Hubs Namespace's **Overview** page.
+
+ [ ![Fully qualified namespace.](media/event-hub-hostname.png) ](media/event-hub-hostname.png#lightbox)
+
+ For more information about Event Hubs Namespaces, see [Namespace](../../event-hubs/event-hubs-features.md?WT.mc_id=Portal-Microsoft_Healthcare_APIs#namespace) in the Features and terminology in Azure Event Hubs document.
+
+5. Select **Next: Device mapping >**.
+
+ Proceed to the next section about entering device mapping properties and for information the Device Mapper tool. Otherwise, proceed to the section [Configure Destination](#configure-destination).
+
+## Configure Device mapping properties
+
+ The Device Mapper is a tool to visualize the mapping configuration for normalizing a device's input data, and then transform it to FHIR resources. Developers can use this tool to edit and test devices, FHIR mappings, and export the data to upload to an IoT Connector in the Azure portal. This tool also helps developers understand their device's mapping configurations.
+
+For more information, see the open source documentation [Device Content Mapping](https://github.com/microsoft/iomt-fhir/blob/master/docs/Configuration.md#device-content-mapping).
+
+1. Under the **Device Mapping** tab, enter the device mapping JSON code associated with your IoT Connector.
+
+ [ ![Configure device mapping.](media/configure-device-mapping.png) ](media/configure-device-mapping.png#lightbox)
+
+2. Select **Next: Destination >** to configure the destination properties associated with your IoT Connector.
+
+## Configure Destination
+
+Under the **Destination** tab, enter the destination properties associated with the IoT Connector.
+
+ [ ![Configure destination properties.](media/configure-destination-properties.png) ](media/configure-destination-properties.png#lightbox)
+
+1. Enter the Azure Resource ID of the **FHIR Server**.
+
+ The **FHIR Server** name (also known as the **FHIR service**) is located by using the **Search** bar to go to the FHIR service that you've deployed and by selecting the **Properties** blade. Copy and paste the **Resource ID** string to the **FHIR Server** text field.
+
+ [ ![Enter FHIR server name.](media/fhir-service-resource-id.png) ](media/fhir-service-resource-id.png#lightbox)
+
+2. Enter the **Destination Name**.
- [ ![IoT configure instance details](media/basics-instance-details.png) ](media/basics-instance-details.png#lightbox)
+ The **Destination Name** is a friendly name for the destination. Enter a unique name for your destination. As an example, you can name it `iotmedicdevice`.
-2. Enter a name for the IoT Connector.
+3. Select **Create** or **Lookup** for the **Resolution Type**.
-3. Enter a name for the Event Hub.
-For more information about Event Hubs, see [Azure Event Hubs overview](../../event-hubs/index.yml).
+ > [!NOTE]
+ > For the IoT Connector destination to create a valid observation resource in the FHIR Server, a device resource and patient resource **must** exist in the FHIR Server, so the observation can properly reference the device that created the data, and the patient the data was measured from. There are two modes the IoT Connector can use to resolve the device and patient resources.
-4. Enter a name for the Consumer Group.
-For more information about Consumer Groups, see [Features and terminology in Azure Event Hubs](../../event-hubs/event-hubs-features.md?WT.mc_id=Portal-Microsoft_Healthcare_APIs#event-consumers).
+ **Create**
-5. Enter a namespace for the IoT Connector.
-For more information about Event Hub namespaces, see [Namespace](../../event-hubs/event-hubs-features.md?WT.mc_id=Portal-Microsoft_Healthcare_APIs#namespace) in the Features and terminology in Azure Event Hubs document].
+ The IoT Connector destination attempts to retrieve a device resource from the FHIR Server using the device identifier included in the Event Hub message. It also attempts to retrieve a patient resource from the FHIR Server using the patient identifier included in the Event Hub message. If either resource is not found, new resources will be created (device, patient, or both) containing just the identifier contained in the Event Hub message. When you use the **Create** option, both a device identifier and a patient identifier can be configured in the device mapping. In other words, when the IoT Connector destination is in **Create** mode, it can function normally **without** adding device and patient resources to the FHIR Server.
-6. To review and create the IoT Connector, select **Review + create**, or select **Next: Destination >**. To enter the destination mapping properties associated with the IoT Connector, refer to the instructions in the following section.
+ **Lookup**
-## Configure destination mapping properties
+ The IoT Connector destination attempts to retrieve a device resource from the FHIR Server using the device identifier included in the event hub message. If the device resource is not found, this will cause an error, and the data won't be processed. For **Lookup** to function properly, a device resource with an identifier matching the device identifier included in the event hub message **must** exist and the device resource **must** have a reference to a patient resource that also exists. In other words, when the IoT Connector destination is in the Lookup mode, device and patient resources **must** be added to the FHIR Server before data can be processed.
-1. Under the **Destination** tab, enter the destination mapping properties associated with the IoT Connector.
+ For more information, see the open source documentation [FHIR Mapping](https://github.com/microsoft/iomt-fhir/blob/master/docs/Configuration.md#fhir-mapping).
- [ ![Configure destination properties](media/configure-destination-properties.png) ](media/configure-destination-properties.png#lightbox)
+4. Under **Destination Mapping**, enter the JSON code inside the code editor.
-2. Enter the name of the **FHIR Server**.
+ For information about the Mapper Tool, see [IoMT Connector Data Mapper Tool](https://github.com/microsoft/iomt-fhir/tree/master/tools/data-mapper).
-3. Enter the **Destination Name**.
+5. You may select **Review + create**, or you can select **Next: Tags >** if you want to configure tags.
-4. Select **Create** or **Lookup** for the **ResolutionType**.
+## (Optional) Configure Tags
-5. Under **Destination Mapping**, enter the JSON code inside the code editor.
-For more information about the Mapper Tool, see [IoMT Connector Data Mapper Tool](https://github.com/microsoft/iomt-fhir/tree/master/tools/data-mapper).
+Tags are name and value pairs used for categorizing resources. For more information about tags, see [Use tags to organize your Azure resources and management hierarchy](../../azure-resource-manager/management/tag-resources.md).
-6.To review and create the IoT Connector, select **Review + create**, or select **Next: Device Mapping >**.
-To enter the device mapping properties associated with the IoT Connector, refer to the instructions in the following section.
+Under the **Tags** tab, enter the tag properties associated with the IoT Connector.
-## Configure device mapping properties
+ [ ![Tag properties.](media/tag-properties.png) ](media/tag-properties.png#lightbox)
+
+1. Enter a **Name**.
+2. Enter a **Value**.
+3. Select **Review + create**.
-1. Under the **Device Mapping** tab, enter the device mapping JSON code associated with the IoT Connector.
+ You should notice a **Validation success** message like what's shown in the image below.
- [ ![Configure device mapping](media/configure-device-mapping.png) ](media/configure-device-mapping.png#lightbox)
-2. To review and create the IoT Connector, select **Review + create**, or select **Next: Tags >**.
+ [ ![Validation success message.](media/iot-connector-validation-success.png) ](media/iot-connector-validation-success.png#lightbox)
-To enter the tagging properties associated with the IoT Connector, refer to the instructions in the following section.
+ > [!NOTE]
+ > If your IoT Connector didnΓÇÖt validate, review the validation failure message, and troubleshoot the issue. ItΓÇÖs recommended that you review the properties under each IoT Connector tab that you've configured.
-## Configure tags
+4. Next, select **Create**.
-1. Under the **Tags** tab, enter the tag properties associated with the IoT Connector.
+ The newly deployed IoT Connector will display inside your Azure resource group.
- [ ![Tag properties](media/tag-properties.png) ](media/tag-properties.png#lightbox)
+ [ ![Deployed IoT Connector listed in the Azure Recent resources list.](media/azure-resources-iot-connector-deployed.png) ](media/azure-resources-iot-connector-deployed.png#lightbox)
-2. Enter a **Name**.
-3. Enter a **Value**.
-4. Select **Review + create**.
-5. When you notice the green validation checkmark, select **Create** to deploy the IoT Connector.
+ Now that your IoT Connector has been deployed, we're going to walk through the steps of assigning permissions to access the Event Hub and the FHIR service.
-Tags are name/value pairs used for categorizing resources. For more information about tags, see [Use tags to organize your Azure resources and management hierarchy](../../azure-resource-manager/management/tag-resources.md).
+## Granting IoT Connector access
+
+To ensure that your IoT Connector works properly, it must have granted access permissions to the Event Hub and FHIR service.
+
+### Accessing the IoT Connector from the Event Hub
+
+1. In the **Azure Resource group** list, select the name of your **Event Hubs Namespace**.
+
+2. Select the **Access control (IAM)** blade, and then select **+ Add**.
+
+ [ ![Screenshot of access control of event hubs namespace.](media/access-control-blade-add.png) ](media/access-control-blade-add.png#lightbox)
+
+3. Select **Add role assignment**.
+
+ [ ![Screenshot of add role assignment.](media/event-hub-add-role-assignment.png) ](media/event-hub-add-role-assignment.png#lightbox)
+
+4. Select the **Role**, and then select **Azure Event Hubs Data Receiver**.
+
+ [ ![Screenshot of add role assignment required fields.](media/event-hub-add-role-assignment-fields.png) ](media/event-hub-add-role-assignment-fields.png#lightbox)
++
+ The Azure Event Hubs Data Receiver role allows the IoT Connector that's being assigned this role to receive data from this Event Hub.
+
+ For more information about application roles, see [Authentication & Authorization for the Healthcare APIs (preview)](.././authentication-authorization.md).
+
+5. Select **Assign access to**, and keep the default option selected **User, group, or service principal**.
+
+6. In the **Select** field, enter the security principal for your IoT Connector.
+
+ `<your workspace name>/iotconnectors/<your IoT connector name>`
+
+ When you deploy an IoT Connector, it creates a managed identity. The managed identify name is a concatenation of the workspace name, resource type (that's the IoT Connector), and the name of the IoT Connector.
+
+7. Select **Save**.
+
+ After the role assignment has been successfully added to the Event Hub, a notification will display a green check mark with the text "Add Role assignment." This message indicates that the IoT Connector can now read from the Event Hub.
+
+ [ ![Screenshot of added role assignment message.](media/event-hub-added-role-assignment.png) ](media/event-hub-added-role-assignment.png#lightbox)
+
+For more information about authoring access to Event Hubs resources, see [Authorize access with Azure Active Directory](../../event-hubs/authorize-access-azure-active-directory.md).
+
+### Accessing the IoT Connector from the FHIR service
+
+1. In the **Azure Resource group list**, select the name of your **FHIR service**.
+
+2. Select the **Access control (IAM)** blade, and then select **+ Add**.
+
+3. Select **Add role assignment**.
+
+ [ ![Screenshot of add role assignment for the FHIR service.](media/fhir-service-add-role-assignment.png) ](media/fhir-service-add-role-assignment.png#lightbox)
+
+4. Select the **Role**, and then select **FHIR Data Writer**.
+
+ The FHIR Data Writer role provides read and write access that the IoT Connector uses to function. Because the IoT Connector is deployed as a separate resource, the FHIR service will receive requests from the IoT Connector. If the FHIR service doesnΓÇÖt know who's making the request, or if it doesn't have the assigned role, it will deny the request as unauthorized.
+
+ For more information about application roles, see [Authentication & Authorization for the Healthcare APIs (preview)](.././authentication-authorization.md).
+
+5. In the **Select** field, enter the security principal for your IoT Connector.
+
+ `<your workspace name>/iotconnectors/<your IoT connector name>`
+
+6. Select **Save**.
+
+ [ ![Screenshot of FHIR service added role assignment message.](media/fhir-service-added-role-asignment.png) ](media/fhir-service-added-role-asignment.png#lightbox)
+
+ For more information about assigning roles to the FHIR service, see [Configure Azure RBAC for the FHIR service](../fhir/configure-azure-rbac-for-fhir.md).
## Next steps
+In this article, you've learned how to deploy an IoT Connector in the Azure portal. For an overview of the IoT Connector, see
+ >[!div class="nextstepaction"] >[IoT Connector overview](iot-connector-overview.md)
healthcare-apis Device Data Through Iot Hub https://github.com/MicrosoftDocs/azure-docs/commits/master/articles/healthcare-apis/iot/device-data-through-iot-hub.md
# Tutorial: Receive device data through Azure IoT Hub
+> [!IMPORTANT]
+> Azure Healthcare APIs is currently in PREVIEW. The [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/) include additional legal terms that apply to Azure features that are in beta, preview, or otherwise not yet released into general availability.
+ Azure IoT Connector for Fast Healthcare Interoperability Resources (FHIR&#174;)* provides you the capability to ingest data from Internet of Medical Things (IoMT) devices into FHIR service. Azure IoT Connector for FHIR can also work with devices provisioned and managed through Azure IoT Hub. This tutorial provides the procedure to connect and route device data from Azure IoT Hub to Azure IoT Connector for FHIR. ## Prerequisites
healthcare-apis How To Use Device Mapping Iot https://github.com/MicrosoftDocs/azure-docs/commits/master/articles/healthcare-apis/iot/how-to-use-device-mapping-iot.md
Previously updated : 07/12/2021 Last updated : 08/06/2021 # How to use the device mapping template
+> [!IMPORTANT]
+> Azure Healthcare APIs is currently in PREVIEW. The [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/) include additional legal terms that apply to Azure features that are in beta, preview, or otherwise not yet released into general availability.
+ The IoT Connector requires two types of JSON-based mapping templates. The first type, **Device mapping**, is responsible for mapping the device payloads sent to the `devicedata` Azure Event Hub end point. It extracts types, device identifiers, measurement date time, and the measurement value(s). The second type, **FHIR mapping**, controls the mapping for FHIR resource. It allows configuration of the length of the observation period, FHIR data type used to store the values, and terminology code(s).
healthcare-apis How To Use Fhir Mapping Iot https://github.com/MicrosoftDocs/azure-docs/commits/master/articles/healthcare-apis/iot/how-to-use-fhir-mapping-iot.md
Previously updated : 07/12/2021 Last updated : 08/06/2021 # How to use the FHIR mapping template
+> [!IMPORTANT]
+> Azure Healthcare APIs is currently in PREVIEW. The [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/) include additional legal terms that apply to Azure features that are in beta, preview, or otherwise not yet released into general availability.
+ This article describes how to configure the IoT Connector using the FHIR mapping template. ## FHIR mapping
healthcare-apis Iot Connector Overview https://github.com/MicrosoftDocs/azure-docs/commits/master/articles/healthcare-apis/iot/iot-connector-overview.md
Previously updated : 07/12/2021 Last updated : 08/06/2021 # What is the IoT Connector?
+> [!IMPORTANT]
+> Azure Healthcare APIs is currently in PREVIEW. The [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/) include additional legal terms that apply to Azure features that are in beta, preview, or otherwise not yet released into general availability.
+ IoT Connector is an optional feature of Azure Healthcare APIs that provides the capability to ingest data from Internet of Medical Things (IoMT) devices. This article provides an overview of data flow in Azure API for IoT Connector. You'll learn about different data processing stages within the IoT Connector service that transforms device data into FHIR-based [Observation](https://www.hl7.org/fhir/observation.html) resources.
healthcare-apis Iot Data Flow https://github.com/MicrosoftDocs/azure-docs/commits/master/articles/healthcare-apis/iot/iot-data-flow.md
Previously updated : 11/13/2020 Last updated : 08/06/2021 # IoT connector for FHIR: data flow
+> [!IMPORTANT]
+> Azure Healthcare APIs is currently in PREVIEW. The [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/) include additional legal terms that apply to Azure features that are in beta, preview, or otherwise not yet released into general availability.
+ This article provides an overview of data flow in Azure IoT Connector for Fast Healthcare Interoperability Resources (FHIR&#174;)*. You'll learn about different data processing stages within Azure IoT Connector for FHIR that transform device data into FHIR-based [Observation](https://www.hl7.org/fhir/observation.html) resources. Diagram above shows common data flows using Azure IoT Connector for FHIR.
healthcare-apis Iot Metrics Diagnostics Export https://github.com/MicrosoftDocs/azure-docs/commits/master/articles/healthcare-apis/iot/iot-metrics-diagnostics-export.md
Previously updated : 11/13/2020 Last updated : 08/06/2021 # Export IoT Connector Metrics through Diagnostic settings
+> [!IMPORTANT]
+> Azure Healthcare APIs is currently in PREVIEW. The [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/) include additional legal terms that apply to Azure features that are in beta, preview, or otherwise not yet released into general availability.
+ In this article, you'll learn how to export Azure IoT Connector for Fast Healthcare Interoperability Resources (FHIR&#174;)* Metrics logs. The feature that enables Metrics logging is the [**Diagnostic settings**](../../azure-monitor/essentials/diagnostic-settings.md) in the Azure portal. ## Enable Metrics logging for the Azure IoT Connector for FHIR (preview)
healthcare-apis Iot Troubleshoot Guide https://github.com/MicrosoftDocs/azure-docs/commits/master/articles/healthcare-apis/iot/iot-troubleshoot-guide.md
Previously updated : 07/20/2021 Last updated : 08/06/2021 # Azure IoT Connector for FHIR (preview) troubleshooting guide
+> [!IMPORTANT]
+> Azure Healthcare APIs is currently in PREVIEW. The [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/) include additional legal terms that apply to Azure features that are in beta, preview, or otherwise not yet released into general availability.
+ This article provides steps for troubleshooting common Azure IoT Connector for Fast Healthcare Interoperability Resources (FHIR&#174;) error messages and conditions. You'll also learn how to create copies of the Azure IoT Connector for FHIR (preview) Conversion Mapping JSON templates such as Device and FHIR. Also, you can use the Conversion Mapping JSON templates for editing and archiving outside of the Azure portal. > [!NOTE]
iot-hub-device-update Import Schema https://github.com/MicrosoftDocs/azure-docs/commits/master/articles/iot-hub-device-update/import-schema.md
az account get-access-token --resource 'https://api.adu.microsoft.com/'
_Using user credentials_ ```powershell
-$clientId = '1e5942b3-36f1-43eb-88d9-98c12d95000bΓÇÖ
-$tenantId = '72f988bf-86f1-41af-91ab-2d7cd011db47ΓÇÖ
+$clientId = '<app_id>ΓÇÖ
+$tenantId = '<tenant_id>ΓÇÖ
$authority = "https://login.microsoftonline.com/$tenantId/v2.0" $Scope = 'https://api.adu.microsoft.com/user_impersonation'
iot-hub Iot Hub Csharp Csharp File Upload https://github.com/MicrosoftDocs/azure-docs/commits/master/articles/iot-hub/iot-hub-csharp-csharp-file-upload.md
ms.devlang: csharp Previously updated : 07/18/2021 Last updated : 08/24/2021
[!INCLUDE [iot-hub-file-upload-language-selector](../../includes/iot-hub-file-upload-language-selector.md)]
-This tutorial shows you how to use the file upload capabilities of IoT Hub by using the .NET file upload sample.
+This tutorial shows you how to use the file upload feature of IoT Hub with the Azure IoT .NET device and service SDKs.
-The [Send telemetry from a device to an IoT hub](../iot-develop/quickstart-send-telemetry-iot-hub.md?pivots=programming-language-csharp) quickstart and [Send cloud-to-device messages with IoT Hub](iot-hub-csharp-csharp-c2d.md) tutorial show the basic device-to-cloud and cloud-to-device messaging functionality of IoT Hub. The [Configure Message Routing with IoT Hub](tutorial-routing.md) tutorial describes a way to reliably store device-to-cloud messages in Microsoft Azure Blob storage. However, in some scenarios you can't easily map the data your devices send into the relatively small device-to-cloud messages that IoT Hub accepts. For example:
+The [Send telemetry from a device to an IoT hub](../iot-develop/quickstart-send-telemetry-iot-hub.md?pivots=programming-language-csharp) quickstart and [Send cloud-to-device messages with IoT Hub](iot-hub-csharp-csharp-c2d.md) tutorial show the basic device-to-cloud and cloud-to-device messaging functionality of IoT Hub. The [Configure Message Routing with IoT Hub](tutorial-routing.md) tutorial describes a way to reliably store device-to-cloud messages in Microsoft Azure blob storage. However, in some scenarios you can't easily map the data your devices send into the relatively small device-to-cloud messages that IoT Hub accepts. For example:
* Large files that contain images
The [Send telemetry from a device to an IoT hub](../iot-develop/quickstart-send-
These files are typically batch processed in the cloud using tools such as [Azure Data Factory](../data-factory/introduction.md) or the [Hadoop](../hdinsight/index.yml) stack. When you need to upload files from a device, however, you can still use the security and reliability of IoT Hub. This tutorial shows you how.
+At the end of this tutorial you run two .NET console apps:
+
+* **FileUploadSample**. This device app uploads a file to storage using a SAS URI provided by your IoT hub. You'll run this app from the Azure IoT C# samples repository that you download in the prerequisites.
+
+* **ReadFileUploadNotification**. This service app receives file upload notifications from your IoT hub. You'll create this app.
+ > [!NOTE] > IoT Hub supports many device platforms and languages, including C, Java, Python, and JavaScript, through Azure IoT device SDKs. Refer to the [Azure IoT Developer Center](https://azure.microsoft.com/develop/iot) for step-by-step instructions on how to connect your device to Azure IoT Hub.
These files are typically batch processed in the cloud using tools such as [Azur
## Prerequisites
-* Visual Studio Code
- * An active Azure account. If you don't have an account, you can create a [free account](https://azure.microsoft.com/pricing/free-trial/) in just a couple of minutes. * The sample applications you run in this article are written using C#. For the Azure IoT C# samples, we recommend you have the .NET Core SDK 3.1 or greater on your development machine.
These files are typically batch processed in the cloud using tools such as [Azur
[!INCLUDE [iot-hub-associate-storage](../../includes/iot-hub-include-associate-storage.md)]
-## Examine the application
+## Upload file from a device app
+
+In this article, you'll use a sample from the Azure IoT C# samples repository you downloaded earlier as the device app. You can open the files below using Visual Studio, Visual Studio Code, or a text editor of your choice.
+
+The sample is located in the **azure-iot-samples-csharp-master\iot-hub\Samples\device\FileUploadSample** under the folder where you extracted the Azure IoT C# samples.
+
+Examine the code in **FileUpLoadSample.cs**. This file contains the main sample logic. After creating an IoT Hub device client, it follows the standard three-part procedure for uploading files from a device:
+
+1. The code calls the **GetFileUploadSasUriAsync** method on the device client to get a SAS URI from the IoT hub:
+
+ ```csharp
+ var fileUploadSasUriRequest = new FileUploadSasUriRequest
+ {
+ BlobName = fileName
+ };
+
+ // Lines removed for clarity
+
+ FileUploadSasUriResponse sasUri = await _deviceClient.GetFileUploadSasUriAsync(fileUploadSasUriRequest);
+ Uri uploadUri = sasUri.GetBlobUri();
+ ```
+
+1. The code uses the SAS URI to upload the file to Azure storage. In this sample, it uses the SAS URI to create an Azure storage block blob client and uploads the file:
+
+ ```csharp
+ var blockBlobClient = new BlockBlobClient(uploadUri);
+ await blockBlobClient.UploadAsync(fileStreamSource, new BlobUploadOptions());
+ ```
+
+1. The code notifies the IoT hub that it has completed the upload. This tells the IoT hub that it can release resources associated with the upload (the SAS URI). If file upload notifications are enabled, the IoT hub will send a notification message to backend services.
+
+ ```csharp
+ var successfulFileUploadCompletionNotification = new FileUploadCompletionNotification
+ {
+ // Mandatory. Must be the same value as the correlation id returned in the sas uri response
+ CorrelationId = sasUri.CorrelationId,
+
+ // Mandatory. Will be present when service client receives this file upload notification
+ IsSuccess = true,
+
+ // Optional, user defined status code. Will be present when service client receives this file upload notification
+ StatusCode = 200,
+
+ // Optional, user-defined status description. Will be present when service client receives this file upload notification
+ StatusDescription = "Success"
+ };
+
+ await _deviceClient.CompleteFileUploadAsync(successfulFileUploadCompletionNotification);
+ ```
+
+If you examine the **parameter.cs** file, you'll see that:
+
+- The sample requires you to pass a parameter, *p*, which takes a device connection string.
+
+- By default, the device sample uses the MQTT protocol to communicate with IoT Hub. You can use the parameter *t* to change this transport protocol. Be aware that, regardless of this selection, the Azure blob client always uses HTTPS as the protocol to upload the file Azure storage.
+
+## Get the IoT hub connection string
+
+In this article, you create a backend service to receive file upload notification messages from your IoT hub. To receive file upload notification messages, your service needs the **service connect** permission. By default, every IoT Hub is created with a shared access policy named **service** that grants this permission.
++
+## Receive a file upload notification
+
+In this section, you create a C# console app that receives file upload notification messages from your IoT hub.
+
+1. Open a command window and go to the folder where you want to create the project. Create a folder named **ReadFileUploadNotifications** and change directories to that folder.
+
+ ```cmd/sh
+ mkdir ReadFileUploadNotification
+ cd ReadFileUploadNotification
+ ```
+
+1. Run the following command to create a C# console project. After running the command, the folder will contain a **Program.cs** file and a **ReadFileUploadNotification.csproj** file.
+
+ ```cmd/sh
+ dotnet new console --language c#
+ ```
+
+1. Run the following command to add the **Microsoft.Azure.Devices** package to the project file. This package is the Azure IoT .NET service SDK.
-In Visual Studio Code, open the *azure-iot-samples-csharp-master\iot-hub\Samples\device\FileUploadSample* folder in your .NET samples download. The folder contains a file named *parameters.cs*. If you open that file, you'll see that the parameter *p* is required and contains the device connection string. You copied and saved this connection string when you registered the device. The parameter *t* can be specified if you want to change the transport protocol. The default protocol is mqtt. The file *program.cs* contains the *main* function. The *FileUploadSample.cs* file contains the primary sample logic. *TestPayload.txt* is the file to be uploaded to your blob container.
+ ```cmd/sh
+ dotnet add package Microsoft.Azure.Devices
+ ```
-## Run the application
+1. Open the **Program.cs** file and add the following statement at the top of the file:
+
+ ```csharp
+ using Microsoft.Azure.Devices;
+ ```
+1. Add the following fields to the **Program** class. Replace the `{iot hub connection string}` placeholder value with the IoT hub connection string that you copied previously in [Get the IoT hub connection string](#get-the-iot-hub-connection-string):
+
+ ```csharp
+ static ServiceClient serviceClient;
+ static string connectionString = "{iot hub connection string}";
+ ```
+
+1. Add the following method to the **Program** class:
+
+ ```csharp
+ private async static void ReceiveFileUploadNotificationAsync()
+ {
+ var notificationReceiver = serviceClient.GetFileNotificationReceiver();
+ Console.WriteLine("\nReceiving file upload notification from service");
+ while (true)
+ {
+ var fileUploadNotification = await notificationReceiver.ReceiveAsync();
+ if (fileUploadNotification == null) continue;
+ Console.ForegroundColor = ConsoleColor.Yellow;
+ Console.WriteLine("Received file upload notification: {0}",
+ string.Join(", ", fileUploadNotification.BlobName));
+ Console.ResetColor();
+ await notificationReceiver.CompleteAsync(fileUploadNotification);
+ }
+ }
+ ```
-Now you are ready to run the application.
+ Note this receive pattern is the same one used to receive cloud-to-device messages from the device app.
+
+1. Finally, replace the lines in the **Main** method with the following:
+
+ ```csharp
+ Console.WriteLine("Receive file upload notifications\n");
+ serviceClient = ServiceClient.CreateFromConnectionString(connectionString);
+ ReceiveFileUploadNotificationAsync();
+ Console.WriteLine("Press Enter to exit\n");
+ Console.ReadLine();
+ ```
+
+## Run the applications
+
+Now you're ready to run the applications.
+
+1. First, run the service app to receive file upload notifications from the IoT hub. At your command prompt in the **ReadFileUploadNotification** folder, run the following commands:
-1. Open a terminal window in Visual Studio Code.
-1. Type the following commands:
```cmd/sh dotnet restore
- dotnet run --p "{Your device connection string}"
+ dotnet run
```
+
+ The app starts and waits for a file upload notification from your IoT hub:
-The output should resemble the following:
+ ```cmd/sh
+ Receive file upload notifications
-```cmd/sh
- Uploading file TestPayload.txt
- Getting SAS URI from IoT Hub to use when uploading the file...
- Successfully got SAS URI (https://contosostorage.blob.core.windows.net/contosocontainer/MyDevice%2FTestPayload.txt?sv=2018-03-28&sr=b&sig=x0G1Baf%2BAjR%2BTg3nW34zDNKs07p6dLzkxvZ3ZSmjIhw%3D&se=2021-05-04T16%3A40%3A52Z&sp=rw) from IoT Hub
- Uploading file TestPayload.txt using the Azure Storage SDK and the retrieved SAS URI for authentication
- Successfully uploaded the file to Azure Storage
- Notified IoT Hub that the file upload succeeded and that the SAS URI can be freed.
- Time to upload file: 00:00:01.5077954.
- Done.
-```
+
+ Receiving file upload notification from service
+ Press Enter to exit
+ ```
+++
+1. Next, run the device app to upload the file to Azure storage. Open a new command prompt and change folders to the **azure-iot-samples-csharp-master\iot-hub\Samples\device\FileUploadSample** under the folder where you expanded the Azure IoT C# samples. Run the following commands. Replace the `{Your device connection string}` placeholder value in the second command with the device connection string you copied previously in [Register a new device in the IoT hub](#register-a-new-device-in-the-iot-hub).
+
+ ```cmd/sh
+ dotnet restore
+ dotnet run --p "{Your device connection string}"
+ ```
+
+ The following output is from the device app after the upload has completed:
+
+ ```cmd/sh
+ Uploading file TestPayload.txt
+ Getting SAS URI from IoT Hub to use when uploading the file...
+ Successfully got SAS URI (https://contosostorage.blob.core.windows.net/contosocontainer/MyDevice%2FTestPayload.txt?sv=2018-03-28&sr=b&sig=x0G1Baf%2BAjR%2BTg3nW34zDNKs07p6dLzkxvZ3ZSmjIhw%3D&se=2021-05-04T16%3A40%3A52Z&sp=rw) from IoT Hub
+ Uploading file TestPayload.txt using the Azure Storage SDK and the retrieved SAS URI for authentication
+ Successfully uploaded the file to Azure Storage
+ Notified IoT Hub that the file upload succeeded and that the SAS URI can be freed.
+ Time to upload file: 00:00:01.5077954.
+ Done.
+ ```
+
+1. Notice that the service app shows that it has received the file upload notification:
+
+ ```cmd/sh
+ Receive file upload notifications
+
+
+ Receiving file upload notification from service
+ Press Enter to exit
+
+ Received file upload notification: myDeviceId/TestPayload.txt
+ ```
## Verify the file upload
-Perform the following steps to verify that *TestPayload.txt* was uploaded to your container:
+You can use the portal to view the uploaded file in the storage container you configured:
-1. In the left pane of your storage account, select **Containers** under **Data Storage**.
-1. Select to container to which you uploaded *TestPayload.txt*.
+1. Navigate to your storage account in Azure portal.
+1. On the left pane of your storage account, select **Containers**.
+1. Select the container you uploaded the file to.
1. Select the folder named after your device.
-1. Select *TestPayload.txt*.
-1. Download the file to view its contents locally.
+1. Select the blob that you uploaded your file to. In this article, it's the blob named **TestPayload.txt**.
+
+ :::image type="content" source="./media/iot-hub-csharp-csharp-file-upload/view-uploaded-file.png" alt-text="Screenshot of selecting the uploaded file in the Azure portal.":::
+
+1. View the blob properties on the page that opens. You can select **Download** to download the file and view its contents locally.
## Next steps
-In this tutorial, you learned how to use the file upload capabilities of IoT Hub to simplify file uploads from devices. You can continue to explore IoT Hub features and scenarios with the following articles:
+In this tutorial, you learned how to use the file upload feature of IoT Hub to simplify file uploads from devices. You can continue to explore this feature with the following articles:
-* [Create an IoT hub programmatically](iot-hub-rm-template-powershell.md)
+* [Overview of file uploads with IoT Hub](iot-hub-devguide-file-upload.md)
-* [Introduction to C SDK](iot-hub-device-sdk-c-intro.md)
+* [Configure IoT Hub file uploads](iot-hub-configure-file-upload.md)
-* [Azure IoT SDKs](iot-hub-devguide-sdks.md)
+* [Azure blob storage documentation](/azure/storage/blobs/storage-blobs-introduction)
-To further explore the capabilities of IoT Hub, see:
+* [Azure blob storage API reference](/azure/storage/blobs/reference)
-* [Deploying AI to edge devices with Azure IoT Edge](../iot-edge/quickstart-linux.md)
+* [Azure IoT SDKs](iot-hub-devguide-sdks.md)
private-link Private Link Service Overview https://github.com/MicrosoftDocs/azure-docs/commits/master/articles/private-link/private-link-service-overview.md
Complete alias: *Prefix*. {GUID}.*region*.azure.privatelinkservice
The Private Link service provides you with three options in the **Visibility** setting to control the exposure of your service. Your visibility setting determines whether a consumer can connect to your service. Here are the visibility setting options, from most restrictive to least restrictive: -- **Role-based access control only**: If your service is for private consumption from different VNets that you own, you can use RBAC as an access control mechanism inside subscriptions that are associated with the same Active Directory tenant.
+- **Role-based access control only**: If your service is for private consumption from different VNets that you own, you can use RBAC as an access control mechanism inside subscriptions that are associated with the same Active Directory tenant. Note: Cross tenant visibility is permitted through RBAC.
- **Restricted by subscription**: If your service will be consumed across different tenants, you can restrict the exposure to a limited set of subscriptions that you trust. Authorizations can be pre-approved. - **Anyone with your alias**: If you want to make your service public and allow anyone with your Private Link service alias to request a connection, select this option.
sentinel Authenticate Playbooks To Sentinel https://github.com/MicrosoftDocs/azure-docs/commits/master/articles/sentinel/authenticate-playbooks-to-sentinel.md
The Azure Sentinel connector in Logic Apps, and its component triggers and actio
This authentication method allows you to give permissions directly to the playbook (a Logic App workflow resource), so that Azure Sentinel connector actions taken by the playbook will operate on the playbook's behalf, as if it were an independent object with its own permissions on Azure Sentinel. Using this method lowers the number of identities you have to manage.
+> [!NOTE]
+> To give a managed identity access to other resources (like your Azure Sentinel workspace), your signed-in user must have a role with permissions to write role assignments, such as Owner or User Access Administrator of the Azure Sentinel workspace.
+ To authenticate with managed identity: + 1. [Enable managed identity](../logic-apps/create-managed-service-identity.md#enable-system-assigned-identity-in-azure-portal) on the Logic Apps workflow resource. To summarize: - On the logic app menu, under **Settings**, select **Identity**. Select **System assigned > On > Save**. When Azure prompts you to confirm, select **Yes**. - Your logic app can now use the system-assigned identity, which is registered with Azure AD and is represented by an object ID.
-1. [Give that identity access](../logic-apps/create-managed-service-identity.md#give-identity-access-to-resources) to the Azure Sentinel workspace, by assigning it the [Azure Sentinel Contributor](../role-based-access-control/built-in-roles.md#azure-sentinel-contributor) role.
-
- Learn more about the available [roles in Azure Sentinel](./roles.md).
-
+1. [Give that identity access](../logic-apps/create-managed-service-identity.md#give-identity-access-to-resources) to the Azure Sentinel workspace:
+ 1. From the Azure Sentinel menu, select **Settings**.
+ 1. Select the **Workspace settings** tab. From the workspace menu, select **Access control (IAM)**.
+ 1. From the button bar at the top, select **Add** and choose **Add role assignment**. If the **Add role assignment** option is disabled, you don't have permissions to assign roles.
+ 1. In the new panel that appears, assign the appropriate role:
+
+ | Role | Situation |
+ | | |
+ | [**Azure Sentinel Responder**](../role-based-access-control/built-in-roles.md#azure-sentinel-responder) | Playbook has steps which update incidents or watchlists |
+ | [**Azure Sentinel Reader**](../role-based-access-control/built-in-roles.md#azure-sentinel-reader) | Playbook only receives incidents |
+ |
+
+ Learn more about the available [roles in Azure Sentinel](./roles.md).
+ 1. Under **Assign access to**, choose **Logic App**.
+ 1. Choose the subscription the playbook belongs to, and select the playbook name.
+ 1. Select **Save**.
+
+
1. Enable the managed identity authentication method in the Azure Sentinel Logic Apps connector: 1. In the Logic Apps designer, add an Azure Sentinel Logic Apps connector step. If the connector is already enabled for an existing connection, click the **Change connection** link.
In order to change the authorization of an existing connection, enter the connec
## Next steps In this article, you learned about the different methods of authenticating a Logic Apps-based playbook to Azure Sentinel.-- Learn more about how to [use triggers and actions in playbooks](playbook-triggers-actions.md).
+- Learn more about how to [use triggers and actions in playbooks](playbook-triggers-actions.md).
synapse-analytics Apache Spark Development Using Notebooks https://github.com/MicrosoftDocs/azure-docs/commits/master/articles/synapse-analytics/spark/apache-spark-development-using-notebooks.md
Synapse team brought the new notebooks component into Synapse Studio to provide
|Outline (Table of Content)| Not supported |&#9745;| |Variable explorer| Not supported |&#9745;| |Format text cell with toolbar buttons|&#9745;| Not available |
-|Undo cell operation| &#9745;| &#9745;|
|Code cell commenting| Not supported | &#9745;|
Synapse team brought the new notebooks component into Synapse Studio to provide
There are two ways to create a notebook. You can create a new notebook or import an existing notebook to a Synapse workspace from the **Object Explorer**. Synapse notebooks recognize standard Jupyter Notebook IPYNB files.
-![create import notebook](./media/apache-spark-development-using-notebooks/synapse-create-import-notebook-2.png)
+![Screenshot of create new or import notebook](./media/apache-spark-development-using-notebooks/synapse-create-import-notebook-2.png)
## Develop notebooks
There are multiple ways to add a new cell to your notebook.
1. Expand the upper left **+ Cell** button, and select **Add code cell** or **Add text cell**.
- ![add-cell-with-cell-button](./media/apache-spark-development-using-notebooks/synapse-add-cell-1.png)
+ ![Screenshot of add-cell-with-cell-button](./media/apache-spark-development-using-notebooks/synapse-add-cell-1.png)
2. Hover over the space between two cells and select **Add code** or **Add text**.
- ![add-cell-between-space](./media/apache-spark-development-using-notebooks/synapse-add-cell-2.png)
+ ![Screenshot of add-cell-between-space](./media/apache-spark-development-using-notebooks/synapse-add-cell-2.png)
3. Use [Shortcut keys under command mode](#shortcut-keys-under-command-mode). Press **A** to insert a cell above the current cell. Press **B** to insert a cell below the current cell.
There are multiple ways to add a new cell to your notebook.
# [Preview Notebook](#tab/preview) 1. Expand the upper left **+ Cell** button, and select **code cell** or **Markdown cell**.
- ![add-azure-notebook-cell-with-cell-button](./media/apache-spark-development-using-notebooks/synapse-azure-notebook-add-cell-1.png)
+ ![Screenshot of add-azure-notebook-cell-with-cell-button](./media/apache-spark-development-using-notebooks/synapse-azure-notebook-add-cell-1.png)
2. Select the plus sign at the beginning of a cell and select **Code cell** or **Markdown cell**.
- ![add-azure-notebook-cell-between-space](./media/apache-spark-development-using-notebooks/synapse-azure-notebook-add-cell-2.png)
+ ![Screenshot of add-azure-notebook-cell-between-space](./media/apache-spark-development-using-notebooks/synapse-azure-notebook-add-cell-2.png)
3. Use [aznb Shortcut keys under command mode](#shortcut-keys-under-command-mode). Press **A** to insert a cell above the current cell. Press **B** to insert a cell below the current cell.
Synapse notebooks support four Apache Spark languages:
You can set the primary language for new added cells from the dropdown list in the top command bar.
- ![default-synapse-language](./media/apache-spark-development-using-notebooks/synapse-default-language.png)
+ ![Screenshot of default-synapse-language](./media/apache-spark-development-using-notebooks/synapse-default-language.png)
<h3 id="use-multiple-languages">Use multiple languages</h3>
You can use multiple languages in one notebook by specifying the correct languag
The following image is an example of how you can write a PySpark query using the **%%pyspark** magic command or a SparkSQL query with the **%%sql** magic command in a **Spark(Scala)** notebook. Notice that the primary language for the notebook is set to pySpark.
- ![Synapse spark magic commands](./media/apache-spark-development-using-notebooks/synapse-spark-magics.png)
+ ![Screenshot of Synapse spark magic commands](./media/apache-spark-development-using-notebooks/synapse-spark-magics.png)
<h3 id="use-temp-tables-to-reference-data-across-languages">Use temp tables to reference data across languages</h3>
The IntelliSense features are at different levels of maturity for different lang
Synapse notebooks provide code snippets that make it easier to enter common used code patterns, such as configuring your Spark session, reading data as a Spark DataFrame, or drawing charts with matplotlib etc.
-Snippets appear in [IntelliSense](#ide-style-intellisense) mixed with other suggestions. The code snippets contents align with the code cell language. You can see available snippets by typing **Snippet** or any keywords appear in the snippet title in the code cell editor. For example, by typing **read** you can see the list of snippets to read data from various data sources.
+Snippets appear in [Shortcut keys of IDE style IntelliSense](#ide-style-intellisense) mixed with other suggestions. The code snippets contents align with the code cell language. You can see available snippets by typing **Snippet** or any keywords appear in the snippet title in the code cell editor. For example, by typing **read** you can see the list of snippets to read data from various data sources.
-![Synapse code snippets](./media/apache-spark-development-using-notebooks/synapse-code-snippets.gif#lightbox)
+![Animated GIF of Synapse code snippets](./media/apache-spark-development-using-notebooks/synapse-code-snippets.gif#lightbox)
<h3 id="format-text-cell-with-toolbar-buttons">Format text cell with toolbar buttons</h3>
Snippets appear in [IntelliSense](#ide-style-intellisense) mixed with other sugg
You can use the format buttons in the text cells toolbar to do common markdown actions. It includes bolding text, italicizing text, inserting code snippets, inserting unordered list, inserting ordered list and inserting image from URL.
- ![Synapse text cell toolbar](./media/apache-spark-development-using-notebooks/synapse-text-cell-toolbar.png)
+ ![Screenshot of Synapse text cell toolbar](./media/apache-spark-development-using-notebooks/synapse-text-cell-toolbar.png)
# [Preview Notebook](#tab/preview)
Format button toolbar is not available for the preview notebook experience yet.
# [Classical Notebook](#tab/classical)
-Select the **Undo** button or press **Ctrl+Z** to revoke the most recent cell operations. Now you can undo up to the latest 20 historical cell operations.
+Select the **Undo** / **Redo** button or press **Ctrl+Z** / **Ctrl+Y** to revoke the most recent cell operations. Now you can undo/redo up to the latest 20 historical cell operations.
- ![Synapse undo cells](./media/apache-spark-development-using-notebooks/synapse-undo-cells.png)
+ ![Screenshot of Synapse undo cells](./media/apache-spark-development-using-notebooks/synapse-undo-cells.png)
# [Preview Notebook](#tab/preview)
-Select the **Undo** button or press **Z** to revoke the most recent cell operations. Now you can undo up to the latest 10 historical cell operations.
+Select the **Undo** / **Redo** button or press **Z** / **Shift+Z** to revoke the most recent cell operations. Now you can undo/redo up to the latest 10 historical cell operations.
- ![Synapse undo cells of aznb](./media/apache-spark-development-using-notebooks/synapse-undo-cells-aznb.png)
+ ![Screenshot of Synapse undo cells of aznb](./media/apache-spark-development-using-notebooks/synapse-undo-cells-aznb.png)
Supported undo cell operations: + Insert/Delete cell: You could revoke the delete operations by selecting **Undo**, the text content will be kept along with the cell.
We support commenting on code cell in Preview Notebook for now.
1. Select **Comments** button on the notebook toolbar to open **Comments** pane.
- ![Synapse comment button](./media/apache-spark-development-using-notebooks/synapse-comments-button.png)
+ ![Screenshot of Synapse comment button](./media/apache-spark-development-using-notebooks/synapse-comments-button.png)
2. Select code in the code cell, click **New** in the **Comments** pane, add comments then click **Post comment** button to save.
- ![Synapse new comment](./media/apache-spark-development-using-notebooks/synapse-new-comments.png)
+ ![Screenshot of Synapse new comment](./media/apache-spark-development-using-notebooks/synapse-new-comments.png)
3. You could perform **Edit comment**, **Resolve thread**, or **Delete thread** by clicking the **More** button besides your comment.
- ![Synapse edit comment](./media/apache-spark-development-using-notebooks/synapse-edit-comments.png)
+ ![Screenshot of Synapse edit comment](./media/apache-spark-development-using-notebooks/synapse-edit-comments.png)
Select the ellipses (...) to access the other cell actions menu at the far right
You can also use [shortcut keys under command mode](#shortcut-keys-under-command-mode). Press **Ctrl+Alt+Γåæ** to move up the current cell. Press **Ctrl+Alt+Γåô** to move the current cell down.
- ![move-a-cell](./media/apache-spark-development-using-notebooks/synapse-move-cells.png)
+ ![Screenshot of move-a-cell](./media/apache-spark-development-using-notebooks/synapse-move-cells.png)
# [Preview Notebook](#tab/preview) Click on the left-hand side of a cell and drag it to the desired position.
- ![Synapse move cells](./media/apache-spark-development-using-notebooks/synapse-azure-notebook-drag-drop-cell.gif)
+ ![Animated GIF of Synapse move cells](./media/apache-spark-development-using-notebooks/synapse-azure-notebook-drag-drop-cell.gif)
To delete a cell, select the ellipses (...) to access the other cell actions men
You can also use [shortcut keys under command mode](#shortcut-keys-under-command-mode). Press **D,D** to delete the current cell.
- ![delete-a-cell](./media/apache-spark-development-using-notebooks/synapse-delete-cell.png)
+ ![Screenshot of delete-a-cell](./media/apache-spark-development-using-notebooks/synapse-delete-cell.png)
# [Preview Notebook](#tab/preview)
To delete a cell, select the delete button at the right hand of the cell.
You can also use [shortcut keys under command mode](#shortcut-keys-under-command-mode). Press **Shift+D** to delete the current cell.
- ![azure-notebook-delete-a-cell](./media/apache-spark-development-using-notebooks/synapse-azure-notebook-delete-cell.png)
+ ![Screenshot of azure-notebook-delete-a-cell](./media/apache-spark-development-using-notebooks/synapse-azure-notebook-delete-cell.png)
You can also use [shortcut keys under command mode](#shortcut-keys-under-command
Select the arrow button at the bottom of the current cell to collapse it. To expand it, select the arrow button while the cell is collapsed.
- ![collapse-cell-input](./media/apache-spark-development-using-notebooks/synapse-collapse-cell-input.gif)
+ ![Animated GIF of collapse-cell-input](./media/apache-spark-development-using-notebooks/synapse-collapse-cell-input.gif)
# [Preview Notebook](#tab/preview) Select the **More commands** ellipses (...) on the cell toolbar and **input** to collapse current cell's input. To expand it, Select the **input hidden** while the cell is collapsed.
- ![azure-notebook-collapse-cell-input](./media/apache-spark-development-using-notebooks/synapse-azure-notebook-collapse-cell-input.gif)
+ ![Animated GIF of azure-notebook-collapse-cell-input](./media/apache-spark-development-using-notebooks/synapse-azure-notebook-collapse-cell-input.gif)
Select the **More commands** ellipses (...) on the cell toolbar and **input** to
Select the **collapse output** button at the upper left of the current cell output to collapse it. To expand it, select the **Show cell output** while the cell output is collapsed.
- ![collapse-cell-output](./media/apache-spark-development-using-notebooks/synapse-collapse-cell-output.gif)
+ ![Animated GIF of collapse-cell-output](./media/apache-spark-development-using-notebooks/synapse-collapse-cell-output.gif)
# [Preview Notebook](#tab/preview) Select the **More commands** ellipses (...) on the cell toolbar and **output** to collapse current cell's output. To expand it, select the same button while the cell's output is hidden.
- ![azure-notebook-collapse-cell-output](./media/apache-spark-development-using-notebooks/synapse-azure-notebook-collapse-cell-output.gif)
+ ![Animated GIF of azure-notebook-collapse-cell-output](./media/apache-spark-development-using-notebooks/synapse-azure-notebook-collapse-cell-output.gif)
Not supported.
The Outlines (Table of Contents) presents the first markdown header of any markdown cell in a sidebar window for quick navigation. The Outlines sidebar is resizable and collapsible to fit the screen in the best ways possible. You can select the **Outline** button on the notebook command bar to open or hide sidebar
-![azure-notebook-outline](./media/apache-spark-development-using-notebooks/synapse-azure-notebook-outline.png)
+![Screenshot of azure-notebook-outline](./media/apache-spark-development-using-notebooks/synapse-azure-notebook-outline.png)
There are several ways to run the code in a cell.
1. Hover on the cell you want to run and select the **Run Cell** button or press **Ctrl+Enter**.
- ![run-cell-1](./media/apache-spark-development-using-notebooks/synapse-run-cell.png)
+ ![Screenshot of run-cell-1](./media/apache-spark-development-using-notebooks/synapse-run-cell.png)
2. Use [Shortcut keys under command mode](#shortcut-keys-under-command-mode). Press **Shift+Enter** to run the current cell and select the cell below. Press **Alt+Enter** to run the current cell and insert a new cell below.
There are several ways to run the code in a cell.
### Run all cells Select the **Run All** button to run all the cells in current notebook in sequence.
- ![run-all-cells](./media/apache-spark-development-using-notebooks/synapse-run-all.png)
+ ![Screenshot of run-all-cells](./media/apache-spark-development-using-notebooks/synapse-run-all.png)
### Run all cells above or below
Select the **Run All** button to run all the cells in current notebook in sequen
To Access the other cell actions menu at the far right, select the ellipses (**...**). Then, select **Run cells above** to run all the cells above the current in sequence. Select **Run cells below** to run all the cells below the current in sequence.
- ![run-cells-above-or-below](./media/apache-spark-development-using-notebooks/synapse-run-cells-above-or-below.png)
+ ![Screenshot of run-cells-above-or-below](./media/apache-spark-development-using-notebooks/synapse-run-cells-above-or-below.png)
# [Preview Notebook](#tab/preview) Expand the dropdown list from **Run all** button, then select **Run cells above** to run all the cells above the current in sequence. Select **Run cells below** to run all the cells below the current in sequence.
- ![azure-notebook-run-cells-above-or-below](./media/apache-spark-development-using-notebooks/synapse-aznb-run-cells-above-or-below.png)
+ ![Screenshot of azure-notebook-run-cells-above-or-below](./media/apache-spark-development-using-notebooks/synapse-aznb-run-cells-above-or-below.png)
Expand the dropdown list from **Run all** button, then select **Run cells above*
# [Classical Notebook](#tab/classical) Select the **Cancel All** button to cancel the running cells or cells waiting in the queue.
- ![cancel-all-cells](./media/apache-spark-development-using-notebooks/synapse-cancel-all.png)
+ ![Screenshot of cancel-all-cells](./media/apache-spark-development-using-notebooks/synapse-cancel-all.png)
# [Preview Notebook](#tab/preview) Select the **Cancel All** button to cancel the running cells or cells waiting in the queue.
- ![azure-notebook-cancel-all-cells](./media/apache-spark-development-using-notebooks/synapse-aznb-cancel-all.png)
+ ![Screenshot of azure-notebook-cancel-all-cells](./media/apache-spark-development-using-notebooks/synapse-aznb-cancel-all.png)
Not supported.
# [Preview Notebook](#tab/preview)
-You can use ```%run <notebook path>``` magic command to reference another notebook within current notebook's context. All the variables defined in the reference notebook are available in the current notebook. ```%run``` magic command supports nested calls but not support recursive calls. You will receive an exception if the statement depth is larger than five. ```%run``` command currently only supports to pass a notebook path as parameter.
+You can use ```%run <notebook path>``` magic command to reference another notebook within current notebook's context. All the variables defined in the reference notebook are available in the current notebook. ```%run``` magic command supports nested calls but not support recursive calls. You will receive an exception if the statement depth is larger than **five**.
-Example: ``` %run /path/notebookA ```.
+Example:
+``` %run /<path>/Notebook1 { "parameterInt": 1, "parameterFloat": 2.5, "parameterBool": true, "parameterString": "abc" } ```.
Notebook reference works in both interactive mode and Synapse pipeline. > [!NOTE]
-> The referenced notebooks are required to be published. You need to publish the notebooks to reference them. Synapse Studio does not recognize the unpublished notebooks from the Git repo.
+> - ```%run``` command currently only supports to pass a absolute path or notebook name only as parameter, relative path is not supported.
+> - ```%run``` command currently only supports to 4 parameter value types: `int`, `float`, `bool`, `string`, variable replacement operation is not supported.
+> - The referenced notebooks are required to be published. You need to publish the notebooks to reference them. Synapse Studio does not recognize the unpublished notebooks from the Git repo.
+> - Referenced notebooks do not support statement that depth is larger than **five**.
>
Synapse notebook provides a built-in variables explorer for you to see the list
You can select the **Variables** button on the notebook command bar to open or hide the variable explorer.
-![azure-notebook-variable-explorer](./media/apache-spark-development-using-notebooks/synapse-azure-notebook-variable-explorer.png)
+![Screenshot of azure-notebook-variable-explorer](./media/apache-spark-development-using-notebooks/synapse-azure-notebook-variable-explorer.png)
You can select the **Variables** button on the notebook command bar to open or h
A step-by-step cell execution status is displayed beneath the cell to help you see its current progress. Once the cell run is complete, an execution summary with the total duration and end time are shown and kept there for future reference.
-![cell-status](./media/apache-spark-development-using-notebooks/synapse-cell-status.png)
+![Screenshot of cell-status](./media/apache-spark-development-using-notebooks/synapse-cell-status.png)
### Spark progress indicator
Synapse notebook is purely Spark based. Code cells are executed on the serverles
The number of tasks per each job or stage help you to identify the parallel level of your spark job. You can also drill deeper to the Spark UI of a specific job (or stage) via selecting the link on the job (or stage) name.
-![spark-progress-indicator](./media/apache-spark-development-using-notebooks/synapse-spark-progress-indicator.png)
+![Screenshot of spark-progress-indicator](./media/apache-spark-development-using-notebooks/synapse-spark-progress-indicator.png)
### Spark session config You can specify the timeout duration, the number, and the size of executors to give to the current Spark session in **Configure session**. Restart the Spark session is for configuration changes to take effect. All cached notebook variables are cleared.
-[![session-management](./media/apache-spark-development-using-notebooks/synapse-azure-notebook-spark-session-management.png)](./media/apache-spark-development-using-notebooks/synapse-azure-notebook-spark-session-management.png#lightbox)
+[![Screenshot of session-management](./media/apache-spark-development-using-notebooks/synapse-azure-notebook-spark-session-management.png)](./media/apache-spark-development-using-notebooks/synapse-azure-notebook-spark-session-management.png#lightbox)
#### Spark session config magic command You can also specify spark session settings via a magic command **%%configure**. The spark session needs to restart to make the settings effect. We recommend you to run the **%%configure** at the beginning of your notebook. Here is a sample, refer to https://github.com/cloudera/livy#request-body for full list of valid parameters.
You can also specify spark session settings via a magic command **%%configure**.
```json %%configure {
- // refer to https://github.com/cloudera/livy#request-body for a list of valid parameters to config the session.
- "driverMemory":"2g",
- "driverCores":3,
- "executorMemory":"2g",
- "executorCores":2,
- "jars":["myjar1.jar","myjar.jar"],
+ //You can get a list of valid parameters to config the session from https://github.com/cloudera/livy#request-body.
+ "driverMemory":"28g", // Recommended values: ["28g", "56g", "112g", "224g", "400g", "472g"]
+ "driverCores":4, // Recommended values: [4, 8, 16, 32, 64, 80]
+ "executorMemory":"28g",
+ "executorCores":4,
+ "jars":["abfs[s]://<file_system>@<account_name>.dfs.core.windows.net/<path>/myjar.jar","wasb[s]://<containername>@<accountname>.blob.core.windows.net/<path>/myjar1.jar"],
"conf":{
- "spark.driver.maxResultSize":"10g"
+ //Example of standard spark property, to find more available properties please visit:https://spark.apache.org/docs/latest/configuration.html#application-properties.
+ "spark.driver.maxResultSize":"10g",
+ //Example of customized property, you can specify count of lines that Spark SQL returns by configuring "livy.rsc.sql.num-rows".
+ "livy.rsc.sql.num-rows":"3000"
} } ``` > [!NOTE]
+> - "DriverMemory" and "ExecutorMemory" are recommended to set as same value in %%configure, so do "driverCores" and "executorCores".
> - You can use Spark session config magic command in Synapse pipelines. It only takes effect when it's called in the top level. The %%configure used in referenced notebook is going to be ignored. > - The Spark configuration properties has to be used in the "conf" body. We do not support top level reference for the Spark configuration properties. >
df = spark.read.option("header", "true") \
You can access data in the primary storage account directly. There's no need to provide the secret keys. In Data Explorer, right-click on a file and select **New notebook** to see a new notebook with data extractor autogenerated.
-![data-to-cell](./media/apache-spark-development-using-notebooks/synapse-data-to-cell.png)
+![Screenshot of data-to-cell](./media/apache-spark-development-using-notebooks/synapse-data-to-cell.png)
## IPython Widgets
Widgets are eventful python objects that have a representation in the browser, o
3. Run the cell, the widget will display at the output area.
- ![ipython widgets slider](./media/apache-spark-development-using-notebooks/ipython-widgets-slider.png)
+ ![Screenshot of ipython widgets slider](./media/apache-spark-development-using-notebooks/ipython-widgets-slider.png)
4. You can use multiple `display()` calls to render the same widget instance multiple times, but they will remain in sync with each other.
Widgets are eventful python objects that have a representation in the browser, o
display(slider) ```
- ![ipython widgets sliders](./media/apache-spark-development-using-notebooks/ipython-widgets-multiple-sliders.png)
+ ![Screenshot of ipython widgets sliders](./media/apache-spark-development-using-notebooks/ipython-widgets-multiple-sliders.png)
5. To render two widgets independent of each other, create two widget instances:
Widgets are eventful python objects that have a representation in the browser, o
|Container/Layout widgets|Box, HBox, VBox, GridBox, Accordion, Tabs, Stacked|
-### Know issue
+### Known limitations
-The following widgets are not supported yet, you could follow workaround as below:
-
-|Functionality|Workaround|
-|--|--|
-|`Output` widget|You can use `print()` function instead to write text into stdout.|
-|`widgets.jslink()`|You can use `widgets.link()` function to link two similar widgets.|
-|`FileUpload` widget| Not support yet.|
+1. The following widgets are not supported yet, you could follow the corresponding workaround as below:
+ |Functionality|Workaround|
+ |--|--|
+ |`Output` widget|You can use `print()` function instead to write text into stdout.|
+ |`widgets.jslink()`|You can use `widgets.link()` function to link two similar widgets.|
+ |`FileUpload` widget| Not support yet.|
-
+2. Global `display` function provided by Synapse does not support displaying multiple widgets in 1 call (i.e. `display(a, b)`), which is different from IPython `display` function.
+3. If you close a notebook that contains IPython Widget, you will not be able to see or interact with it until you execute the corresponding cell again.
+ ## Save notebooks You can save a single notebook or all notebooks in your workspace. 1. To save changes you made to a single notebook, select the **Publish** button on the notebook command bar.
- ![publish-notebook](./media/apache-spark-development-using-notebooks/synapse-publish-notebook.png)
+ ![Screenshot of publish-notebook](./media/apache-spark-development-using-notebooks/synapse-publish-notebook.png)
2. To save all notebooks in your workspace, select the **Publish all** button on the workspace command bar.
- ![publish-all](./media/apache-spark-development-using-notebooks/synapse-publish-all.png)
+ ![Screenshot of publish-all](./media/apache-spark-development-using-notebooks/synapse-publish-all.png)
In the notebook properties, you can configure whether to include the cell output when saving.
- ![notebook-properties](./media/apache-spark-development-using-notebooks/synapse-notebook-properties.png)
+ ![Screenshot of notebook-properties](./media/apache-spark-development-using-notebooks/synapse-notebook-properties.png)
## Magic commands You can use familiar Jupyter magic commands in Synapse notebooks. Review the following list as the current available magic commands. Tell us [your use cases on GitHub](https://github.com/MicrosoftDocs/azure-docs/issues/new) so that we can continue to build out more magic commands to meet your needs.
Available cell magics:
Select the **Add to pipeline** button on the upper right corner to add a notebook to an existing pipeline or create a new pipeline.
-![Add notebook to pipeline](./media/apache-spark-development-using-notebooks/add-to-pipeline.png)
+![Screenshot of Add notebook to pipeline](./media/apache-spark-development-using-notebooks/add-to-pipeline.png)
### Designate a parameters cell
Select the **Add to pipeline** button on the upper right corner to add a noteboo
To parameterize your notebook, select the ellipses (...) to access the other cell actions menu at the far right. Then select **Toggle parameter cell** to designate the cell as the parameters cell.
-![toggle-parameter](./media/apache-spark-development-using-notebooks/toggle-parameter-cell.png)
+![Screenshot of toggle-parameter](./media/apache-spark-development-using-notebooks/toggle-parameter-cell.png)
# [Preview Notebook](#tab/preview) To parameterize your notebook, select the ellipses (...) to access the **more commands** at the cell toolbar. Then select **Toggle parameter cell** to designate the cell as the parameters cell.
-![azure-notebook-toggle-parameter](./media/apache-spark-development-using-notebooks/azure-notebook-toggle-parameter-cell.png)
+![Screenshot of azure-notebook-toggle-parameter](./media/apache-spark-development-using-notebooks/azure-notebook-toggle-parameter-cell.png)
Azure Data Factory looks for the parameters cell and treats this cell as default
Once you've created a notebook with parameters, you can execute it from a pipeline with the Synapse Notebook activity. After you add the activity to your pipeline canvas, you will be able to set the parameters values under **Base parameters** section on the **Settings** tab.
-![Assign a parameter](./media/apache-spark-development-using-notebooks/assign-parameter.png)
+![Screenshot of Assign a parameter](./media/apache-spark-development-using-notebooks/assign-parameter.png)
When assigning parameter values, you can use the [pipeline expression language](../../data-factory/control-flow-expression-language-functions.md) or [system variables](../../data-factory/control-flow-system-variables.md).
Similar to Jupyter Notebooks, Synapse notebooks have a modal user interface. Th
1. A cell is in command mode when there is no text cursor prompting you to type. When a cell is in Command mode, you can edit the notebook as a whole but not type into individual cells. Enter command mode by pressing `ESC` or using the mouse to select outside of a cell's editor area.
- ![command-mode](./media/apache-spark-development-using-notebooks/synapse-command-mode-2.png)
+ ![Screenshot of command-mode](./media/apache-spark-development-using-notebooks/synapse-command-mode-2.png)
2. Edit mode is indicated by a text cursor prompting you to type in the editor area. When a cell is in edit mode, you can type into the cell. Enter edit mode by pressing `Enter` or using the mouse to select on a cell's editor area.
- ![edit-mode](./media/apache-spark-development-using-notebooks/synapse-edit-mode-2.png)
+ ![Screenshot of edit-mode](./media/apache-spark-development-using-notebooks/synapse-edit-mode-2.png)
### Shortcut keys under command mode