+| setting.operatingMode ¹| No | For a sign-in page, this property controls the behavior of the username field, such as input validation and error messages. Expected values: `Username` or `Email`. Check out the [Live demo](https://github.com/azure-ad-b2c/unit-tests/tree/main/technical-profiles/self-asserted#operating-mode) of this metadata. |

+| setting.retryLimit | No | Controls the number of times a user can try to provide the data that is checked against a validation technical profile. For example, a user tries to sign-up with an account that already exists and keeps trying until the limit reached. Check out the [Live demo](https://github.com/azure-ad-b2c/unit-tests/tree/main/technical-profiles/self-asserted#retry-limit) of this metadata.|

+| setting.showCancelButton | No | Displays the cancel button. Possible values: `true` (default), or `false`. Check out the [Live demo](https://github.com/azure-ad-b2c/unit-tests/tree/main/technical-profiles/self-asserted#show-the-cancel-button) of this metadata.|

+| setting.showContinueButton | No | Displays the continue button. Possible values: `true` (default), or `false`. Check out the [Live demo](https://github.com/azure-ad-b2c/unit-tests/tree/main/technical-profiles/self-asserted#show-the-continue-button) of this metadata. |

+| setting.showSignupLink ²| No | Displays the sign-up button. Possible values: `true` (default), or `false`. Check out the [Live demo](https://github.com/azure-ad-b2c/unit-tests/tree/main/technical-profiles/self-asserted#show-sign-up-link) of this metadata. |

+| setting.forgotPasswordLinkLocation ²| No| Displays the forgot password link. Possible values: `AfterLabel` (default) displays the link directly after the label or after the password input field when there is no label, `AfterInput` displays the link after the password input field, `AfterButtons` displays the link on the bottom of the form after the buttons, or `None` removes the forgot password link. Check out the [Live demo](https://github.com/azure-ad-b2c/unit-tests/tree/main/technical-profiles/self-asserted#forgot-password-link-location) of this metadata.|

+| setting.enableRememberMe ²| No| Displays the [Keep me signed in](session-behavior.md?pivots=b2c-custom-policy#enable-keep-me-signed-in-kmsi) checkbox. Possible values: `true` , or `false` (default). [Live demo](https://github.com/azure-ad-b2c/unit-tests/tree/main/technical-profiles/self-asserted#enable-remember-me-kmsi) of this metadata. |

+| setting.inputVerificationDelayTimeInMilliseconds ³| No| Improves user experience, by waiting for the user to stop typing, and then validate the value. Default value 2000 milliseconds. Check out the [Live demo](https://github.com/azure-ad-b2c/unit-tests/tree/main/technical-profiles/self-asserted#input-verification-delay-time-in-milliseconds) of this metadata. |

+ Title: "Quickstart: Add sign in with Microsoft to an Android app | Azure"

+description: In this quickstart, learn how Android applications can call an API that requires access tokens issued by the Microsoft identity platform.

+#Customer intent: As an application developer, I want to learn how Android native apps can call protected APIs that require login and access tokens using the Microsoft identity platform.

+# Quickstart: Sign in users and call the Microsoft Graph API from an Android app

+In this quickstart, you download and run a code sample that demonstrates how an Android application can sign in users and get an access token to call the Microsoft Graph API.

+See [How the sample works](#how-the-sample-works) for an illustration.

+Applications must be represented by an app object in Azure Active Directory so that the Microsoft identity platform can provide tokens to your application.

+## Prerequisites

+* An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).

+* Android Studio

+* Android 16+

+### Step 1: Configure your application in the Azure portal

+For the code sample in this quickstart to work, add a **Redirect URI** compatible with the Auth broker.

+> [!div id="makechanges" class="nextstepaction" class="configure-app-button"]

+> [Make these changes for me]()

+> [!div id="appconfigured" class="alert alert-info"]

+>  Your application is configured with these attributes

+### Step 2: Download the project

+Run the project using Android Studio.

+> [!div class="nextstepaction"]

+> [Download the code sample](https://github.com/Azure-Samples/ms-identity-android-java/archive/master.zip)

+### Step 3: Your app is configured and ready to run

+We have configured your project with values of your app's properties and it's ready to run.

+The sample app starts on the **Single Account Mode** screen. A default scope, **user.read**, is provided by default, which is used when reading your own profile data during the Microsoft Graph API call. The URL for the Microsoft Graph API call is provided by default. You can change both of these if you wish.

+

+Use the app menu to change between single and multiple account modes.

+In single account mode, sign in using a work or home account:

+1. Select **Get graph data interactively** to prompt the user for their credentials. You'll see the output from the call to the Microsoft Graph API in the bottom of the screen.

+2. Once signed in, select **Get graph data silently** to make a call to the Microsoft Graph API without prompting the user for credentials again. You'll see the output from the call to the Microsoft Graph API in the bottom of the screen.

+In multiple account mode, you can repeat the same steps. Additionally, you can remove the signed-in account, which also removes the cached tokens for that account.

+> [!div class="sxs-lookup"]

+> > [!NOTE]

+> > `Enter_the_Supported_Account_Info_Here`

+## How the sample works

+

+The code is organized into fragments that show how to write a single and multiple accounts MSAL app. The code files are organized as follows:

+| File | Demonstrates |

+|||

+| MainActivity | Manages the UI |

+| MSGraphRequestWrapper | Calls the Microsoft Graph API using the token provided by MSAL |

+| MultipleAccountModeFragment | Initializes a multi-account application, loads a user account, and gets a token to call the Microsoft Graph API |

+| SingleAccountModeFragment | Initializes a single-account application, loads a user account, and gets a token to call the Microsoft Graph API |

+| res/auth_config_multiple_account.json | The multiple account configuration file |

+| res/auth_config_single_account.json | The single account configuration file |

+| Gradle Scripts/build.grade (Module:app) | The MSAL library dependencies are added here |

+We'll now look at these files in more detail and call out the MSAL-specific code in each.

+### Adding MSAL to the app

+MSAL ([com.microsoft.identity.client](https://javadoc.io/doc/com.microsoft.identity.client/msal)) is the library used to sign in users and request tokens used to access an API protected by Microsoft identity platform. Gradle 3.0+ installs the library when you add the following to **Gradle Scripts** > **build.gradle (Module: app)** under **Dependencies**:

+```java

+dependencies {

+ ...

+ implementation 'com.microsoft.identity.client:msal:2.+'

+ ...

+}

+```

+This instructs Gradle to download and build MSAL from maven central.

+You must also add references to maven to the **allprojects** > **repositories** portion of the **build.gradle (Module: app)** like so:

+```java

+allprojects {

+ repositories {

+ mavenCentral()

+ google()

+ mavenLocal()

+ maven {

+ url 'https://pkgs.dev.azure.com/MicrosoftDeviceSDK/DuoSDK-Public/_packaging/Duo-SDK-Feed/maven/v1'

+ }

+ maven {

+ name "vsts-maven-adal-android"

+ url "https://identitydivision.pkgs.visualstudio.com/_packaging/AndroidADAL/maven/v1"

+ credentials {

+ username System.getenv("ENV_VSTS_MVN_ANDROIDADAL_USERNAME") != null ? System.getenv("ENV_VSTS_MVN_ANDROIDADAL_USERNAME") : project.findProperty("vstsUsername")

+ password System.getenv("ENV_VSTS_MVN_ANDROIDADAL_ACCESSTOKEN") != null ? System.getenv("ENV_VSTS_MVN_ANDROIDADAL_ACCESSTOKEN") : project.findProperty("vstsMavenAccessToken")

+ }

+ }

+ jcenter()

+ }

+}

+```

+### MSAL imports

+The imports that are relevant to the MSAL library are `com.microsoft.identity.client.*`. For example, you'll see `import com.microsoft.identity.client.PublicClientApplication;` which is the namespace for the `PublicClientApplication` class, which represents your public client application.

+### SingleAccountModeFragment.java

+This file demonstrates how to create a single account MSAL app and call a Microsoft Graph API.

+Single account apps are only used by a single user. For example, you might just have one account that you sign into your mapping app with.

+#### Single account MSAL initialization

+In `auth_config_single_account.json`, in `onCreateView()`, a single account `PublicClientApplication` is created using the config information stored in the `auth_config_single_account.json` file. This is how you initialize the MSAL library for use in a single-account MSAL app:

+```java

+...

+// Creates a PublicClientApplication object with res/raw/auth_config_single_account.json

+PublicClientApplication.createSingleAccountPublicClientApplication(getContext(),

+ R.raw.auth_config_single_account,

+ new IPublicClientApplication.ISingleAccountApplicationCreatedListener() {

+ @Override

+ public void onCreated(ISingleAccountPublicClientApplication application) {

+ /**

+ * This test app assumes that the app is only going to support one account.

+ * This requires "account_mode" : "SINGLE" in the config json file.

+ **/

+ mSingleAccountApp = application;

+ loadAccount();

+ }

+ @Override

+ public void onError(MsalException exception) {

+ displayError(exception);

+ }

+ });

+```

+#### Sign in a user

+In `SingleAccountModeFragment.java`, the code to sign in a user is in `initializeUI()`, in the `signInButton` click handler.

+Call `signIn()` before trying to acquire tokens. `signIn()` behaves as though `acquireToken()` is called, resulting in an interactive prompt for the user to sign in.

+Signing in a user is an asynchronous operation. A callback is passed that calls the Microsoft Graph API and update the UI once the user signs in:

+```java

+mSingleAccountApp.signIn(getActivity(), null, getScopes(), getAuthInteractiveCallback());

+```

+#### Sign out a user

+In `SingleAccountModeFragment.java`, the code to sign out a user is in `initializeUI()`, in the `signOutButton` click handler. Signing a user out is an asynchronous operation. Signing the user out also clears the token cache for that account. A callback is created to update the UI once the user account is signed out:

+```java

+mSingleAccountApp.signOut(new ISingleAccountPublicClientApplication.SignOutCallback() {

+ @Override

+ public void onSignOut() {

+ updateUI(null);

+ performOperationOnSignOut();

+ }

+ @Override

+ public void onError(@NonNull MsalException exception) {

+ displayError(exception);

+ }

+});

+```

+#### Get a token interactively or silently

+To present the fewest number of prompts to the user, you'll typically get a token silently. Then, if there's an error, attempt to get to token interactively. The first time the app calls `signIn()`, it effectively acts as a call to `acquireToken()`, which will prompt the user for credentials.

+Some situations when the user may be prompted to select their account, enter their credentials, or consent to the permissions your app has requested are:

+* The first time the user signs in to the application

+* If a user resets their password, they'll need to enter their credentials

+* If consent is revoked

+* If your app explicitly requires consent

+* When your application is requesting access to a resource for the first time

+* When MFA or other Conditional Access policies are required

+The code to get a token interactively, that is with UI that will involve the user, is in `SingleAccountModeFragment.java`, in `initializeUI()`, in the `callGraphApiInteractiveButton` click handler:

+```java

+/**

+ * If acquireTokenSilent() returns an error that requires an interaction (MsalUiRequiredException),

+ * invoke acquireToken() to have the user resolve the interrupt interactively.

+ *

+ * Some example scenarios are

+ * - password change

+ * - the resource you're acquiring a token for has a stricter set of requirement than your Single Sign-On refresh token.

+ * - you're introducing a new scope which the user has never consented for.

+ **/

+mSingleAccountApp.acquireToken(getActivity(), getScopes(), getAuthInteractiveCallback());

+```

+If the user has already signed in, `acquireTokenSilentAsync()` allows apps to request tokens silently as shown in `initializeUI()`, in the `callGraphApiSilentButton` click handler:

+```java

+/**

+ * Once you've signed the user in,

+ * you can perform acquireTokenSilent to obtain resources without interrupting the user.

+ **/

+ mSingleAccountApp.acquireTokenSilentAsync(getScopes(), AUTHORITY, getAuthSilentCallback());

+```

+#### Load an account

+The code to load an account is in `SingleAccountModeFragment.java` in `loadAccount()`. Loading the user's account is an asynchronous operation, so callbacks to handle when the account loads, changes, or an error occurs is passed to MSAL. The following code also handles `onAccountChanged()`, which occurs when an account is removed, the user changes to another account, and so on.

+```java

+private void loadAccount() {

+ ...

+ mSingleAccountApp.getCurrentAccountAsync(new ISingleAccountPublicClientApplication.CurrentAccountCallback() {

+ @Override

+ public void onAccountLoaded(@Nullable IAccount activeAccount) {

+ // You can use the account data to update your UI or your app database.

+ updateUI(activeAccount);

+ }

+ @Override

+ public void onAccountChanged(@Nullable IAccount priorAccount, @Nullable IAccount currentAccount) {

+ if (currentAccount == null) {

+ // Perform a cleanup task as the signed-in account changed.

+ performOperationOnSignOut();

+ }

+ }

+ @Override

+ public void onError(@NonNull MsalException exception) {

+ displayError(exception);

+ }

+ });

+```

+#### Call Microsoft Graph

+When a user is signed in, the call to Microsoft Graph is made via an HTTP request by `callGraphAPI()` that is defined in `SingleAccountModeFragment.java`. This function is a wrapper that simplifies the sample by doing some tasks such as getting the access token from the `authenticationResult` and packaging the call to the MSGraphRequestWrapper, and displaying the results of the call.

+```java

+private void callGraphAPI(final IAuthenticationResult authenticationResult) {

+ MSGraphRequestWrapper.callGraphAPIUsingVolley(

+ getContext(),

+ graphResourceTextView.getText().toString(),

+ authenticationResult.getAccessToken(),

+ new Response.Listener<JSONObject>() {

+ @Override

+ public void onResponse(JSONObject response) {

+ /* Successfully called graph, process data and send to UI */

+ ...

+ }

+ },

+ new Response.ErrorListener() {

+ @Override

+ public void onErrorResponse(VolleyError error) {

+ ...

+ }

+ });

+}

+```

+### auth_config_single_account.json

+This is the configuration file for an MSAL app that uses a single account.

+See [Understand the Android MSAL configuration file ](msal-configuration.md) for an explanation of these fields.

+Note the presence of `"account_mode" : "SINGLE"`, which configures this app to use a single account.

+`"client_id"` is preconfigured to use an app object registration that Microsoft maintains.

+`"redirect_uri"`is preconfigured to use the signing key provided with the code sample.

+```json

+{

+ "client_id" : "0984a7b6-bc13-4141-8b0d-8f767e136bb7",

+ "authorization_user_agent" : "DEFAULT",

+ "redirect_uri" : "msauth://com.azuresamples.msalandroidapp/1wIqXSqBj7w%2Bh11ZifsnqwgyKrY%3D",

+ "account_mode" : "SINGLE",

+ "broker_redirect_uri_registered": true,

+ "authorities" : [

+ {

+ "type": "AAD",

+ "audience": {

+ "type": "AzureADandPersonalMicrosoftAccount",

+ "tenant_id": "common"

+ }

+ }

+ ]

+}

+```

+### MultipleAccountModeFragment.java

+This file demonstrates how to create a multiple account MSAL app and call a Microsoft Graph API.

+An example of a multiple account app is a mail app that allows you to work with multiple user accounts such as a work account and a personal account.

+#### Multiple account MSAL initialization

+In the `MultipleAccountModeFragment.java` file, in `onCreateView()`, a multiple account app object (`IMultipleAccountPublicClientApplication`) is created using the config information stored in the `auth_config_multiple_account.json file`:

+```java

+// Creates a PublicClientApplication object with res/raw/auth_config_multiple_account.json

+PublicClientApplication.createMultipleAccountPublicClientApplication(getContext(),

+ R.raw.auth_config_multiple_account,

+ new IPublicClientApplication.IMultipleAccountApplicationCreatedListener() {

+ @Override

+ public void onCreated(IMultipleAccountPublicClientApplication application) {

+ mMultipleAccountApp = application;

+ loadAccounts();

+ }

+ @Override

+ public void onError(MsalException exception) {

+ ...

+ }

+ });

+```

+The created `MultipleAccountPublicClientApplication` object is stored in a class member variable so that it can be used to interact with the MSAL library to acquire tokens and load and remove the user account.

+#### Load an account

+Multiple account apps usually call `getAccounts()` to select the account to use for MSAL operations. The code to load an account is in the `MultipleAccountModeFragment.java` file, in `loadAccounts()`. Loading the user's account is an asynchronous operation. So a callback handles the situations when the account is loaded, changes, or an error occurs.

+```java

+/**

+ * Load currently signed-in accounts, if there's any.

+ **/

+private void loadAccounts() {

+ if (mMultipleAccountApp == null) {

+ return;

+ }

+ mMultipleAccountApp.getAccounts(new IPublicClientApplication.LoadAccountsCallback() {

+ @Override

+ public void onTaskCompleted(final List<IAccount> result) {

+ // You can use the account data to update your UI or your app database.

+ accountList = result;

+ updateUI(accountList);

+ }

+ @Override

+ public void onError(MsalException exception) {

+ displayError(exception);

+ }

+ });

+}

+```

+#### Get a token interactively or silently

+Some situations when the user may be prompted to select their account, enter their credentials, or consent to the permissions your app has requested are:

+* The first time users sign in to the application

+* If a user resets their password, they'll need to enter their credentials

+* If consent is revoked

+* If your app explicitly requires consent

+* When your application is requesting access to a resource for the first time

+* When MFA or other Conditional Access policies are required

+Multiple account apps should typically acquire tokens interactively, that is with UI that involves the user, with a call to `acquireToken()`. The code to get a token interactively is in the `MultipleAccountModeFragment.java` file in `initializeUI()`, in the `callGraphApiInteractiveButton` click handler:

+```java

+/**

+ * Acquire token interactively. It will also create an account object for the silent call as a result (to be obtained by getAccount()).

+ *

+ * If acquireTokenSilent() returns an error that requires an interaction,

+ * invoke acquireToken() to have the user resolve the interrupt interactively.

+ *

+ * Some example scenarios are

+ * - password change

+ * - the resource you're acquiring a token for has a stricter set of requirement than your SSO refresh token.

+ * - you're introducing a new scope which the user has never consented for.

+ **/

+mMultipleAccountApp.acquireToken(getActivity(), getScopes(), getAuthInteractiveCallback());

+```

+Apps shouldn't require the user to sign in every time they request a token. If the user has already signed in, `acquireTokenSilentAsync()` allows apps to request tokens without prompting the user, as shown in the `MultipleAccountModeFragment.java` file, in`initializeUI()` in the `callGraphApiSilentButton` click handler:

+```java

+/**

+ * Performs acquireToken without interrupting the user.

+ *

+ * This requires an account object of the account you're obtaining a token for.

+ * (can be obtained via getAccount()).

+ */

+mMultipleAccountApp.acquireTokenSilentAsync(getScopes(),

+ accountList.get(accountListSpinner.getSelectedItemPosition()),

+ AUTHORITY,

+ getAuthSilentCallback());

+```

+#### Remove an account

+The code to remove an account, and any cached tokens for the account, is in the `MultipleAccountModeFragment.java` file in `initializeUI()` in the handler for the remove account button. Before you can remove an account, you need an account object, which you obtain from MSAL methods like `getAccounts()` and `acquireToken()`. Because removing an account is an asynchronous operation, the `onRemoved` callback is supplied to update the UI.

+```java

+/**

+ * Removes the selected account and cached tokens from this app (or device, if the device is in shared mode).

+ **/

+mMultipleAccountApp.removeAccount(accountList.get(accountListSpinner.getSelectedItemPosition()),

+ new IMultipleAccountPublicClientApplication.RemoveAccountCallback() {

+ @Override

+ public void onRemoved() {

+ ...

+ /* Reload account asynchronously to get the up-to-date list. */

+ loadAccounts();

+ }

+ @Override

+ public void onError(@NonNull MsalException exception) {

+ displayError(exception);

+ }

+ });

+```

+### auth_config_multiple_account.json

+This is the configuration file for a MSAL app that uses multiple accounts.

+See [Understand the Android MSAL configuration file ](msal-configuration.md) for an explanation of the various fields.

+Unlike the [auth_config_single_account.json](#auth_config_single_accountjson) configuration file, this config file has `"account_mode" : "MULTIPLE"` instead of `"account_mode" : "SINGLE"` because this is a multiple account app.

+`"client_id"` is preconfigured to use an app object registration that Microsoft maintains.

+`"redirect_uri"`is preconfigured to use the signing key provided with the code sample.

+```json

+{

+ "client_id" : "0984a7b6-bc13-4141-8b0d-8f767e136bb7",

+ "authorization_user_agent" : "DEFAULT",

+ "redirect_uri" : "msauth://com.azuresamples.msalandroidapp/1wIqXSqBj7w%2Bh11ZifsnqwgyKrY%3D",

+ "account_mode" : "MULTIPLE",

+ "broker_redirect_uri_registered": true,

+ "authorities" : [

+ {

+ "type": "AAD",

+ "audience": {

+ "type": "AzureADandPersonalMicrosoftAccount",

+ "tenant_id": "common"

+ }

+ }

+ ]

+}

+```

+## Next steps

+Move on to the Android tutorial in which you build an Android app that gets an access token from the Microsoft identity platform and uses it to call the Microsoft Graph API.

+> [!div class="nextstepaction"]

+> [Tutorial: Sign in users and call the Microsoft Graph from an Android application](tutorial-v2-android.md)

+ Title: "Quickstart: Add sign in with Microsoft to an iOS or macOS app | Azure"

+description: In this quickstart, learn how an iOS or macOS app can sign in users, get an access token from the Microsoft identity platform, and call the Microsoft Graph API.

+#Customer intent: As an application developer, I want to learn how to sign in users and call Microsoft Graph from my iOS or macOS application.

+# Quickstart: Sign in users and call the Microsoft Graph API from an iOS or macOS app

+In this quickstart, you download and run a code sample that demonstrates how a native iOS or macOS application can sign in users and get an access token to call the Microsoft Graph API.

+The quickstart applies to both iOS and macOS apps. Some steps are needed only for iOS apps and will be indicated as such.

+## Prerequisites

+* An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).

+* XCode 10+

+* iOS 10+

+* macOS 10.12+

+## How the sample works

+

+#### Step 1: Configure your application

+For the code sample for this quickstart to work, add a **Redirect URI** compatible with the Auth broker.

+> [!div id="makechanges" class="nextstepaction" class="configure-app-button"]

+> [Make this change for me]()

+> [!div id="appconfigured" class="alert alert-info"]

+>  Your application is configured with these attributes

+#### Step 2: Download the sample project

+> [!div class="nextstepaction"]

+> [Download the code sample for iOS]()

+> [!div class="nextstepaction"]

+> [Download the code sample for macOS]()

+#### Step 3: Install dependencies

+1. Extract the zip file.

+2. In a terminal window, navigate to the folder with the downloaded code sample and run `pod install` to install the latest MSAL library.

+#### Step 4: Your app is configured and ready to run

+We have configured your project with values of your app's properties and it's ready to run.

+> [!NOTE]

+> `Enter_the_Supported_Account_Info_Here`

+1. If you're building an app for [Azure AD national clouds](/graph/deployments#app-registration-and-token-service-root-endpoints), replace the line starting with 'let kGraphEndpoint' and 'let kAuthority' with correct endpoints. For global access, use default values:

+ ```swift

+ let kGraphEndpoint = "https://graph.microsoft.com/"

+ let kAuthority = "https://login.microsoftonline.com/common"

+ ```

+1. Other endpoints are documented [here](/graph/deployments#app-registration-and-token-service-root-endpoints). For example, to run the quickstart with Azure AD Germany, use following:

+ ```swift

+ let kGraphEndpoint = "https://graph.microsoft.de/"

+ let kAuthority = "https://login.microsoftonline.de/common"

+ ```

+3. Open the project settings. In the **Identity** section, enter the **Bundle Identifier** that you entered into the portal.

+4. Right-click **Info.plist** and select **Open As** > **Source Code**.

+5. Under the dict root node, replace `Enter_the_bundle_Id_Here` with the ***Bundle Id*** that you used in the portal. Notice the `msauth.` prefix in the string.

+ ```xml

+ <key>CFBundleURLTypes</key>

+ <array>

+ <dict>

+ <key>CFBundleURLSchemes</key>

+ <array>

+ <string>msauth.Enter_the_Bundle_Id_Here</string>

+ </array>

+ </dict>

+ </array>

+ ```

+6. Build and run the app!

+## More Information

+Read these sections to learn more about this quickstart.

+### Get MSAL

+MSAL ([MSAL.framework](https://github.com/AzureAD/microsoft-authentication-library-for-objc)) is the library used to sign in users and request tokens used to access an API protected by Microsoft identity platform. You can add MSAL to your application using the following process:

+```

+$ vi Podfile

+```

+Add the following to this podfile (with your project's target):

+```

+use_frameworks!

+target 'MSALiOS' do

+ pod 'MSAL'

+end

+```

+Run CocoaPods installation command:

+`pod install`

+### Initialize MSAL

+You can add the reference for MSAL by adding the following code:

+```swift

+import MSAL

+```

+Then, initialize MSAL using the following code:

+```swift

+let authority = try MSALAADAuthority(url: URL(string: kAuthority)!)

+let msalConfiguration = MSALPublicClientApplicationConfig(clientId: kClientID, redirectUri: nil, authority: authority)

+self.applicationContext = try MSALPublicClientApplication(configuration: msalConfiguration)

+```

+> |Where: | Description |

+> |||

+> | `clientId` | The Application ID from the application registered in *portal.azure.com* |

+> | `authority` | The Microsoft identity platform. In most of cases this will be `https://login.microsoftonline.com/common` |

+> | `redirectUri` | The redirect URI of the application. You can pass 'nil' to use the default value, or your custom redirect URI. |

+### For iOS only, additional app requirements

+Your app must also have the following in your `AppDelegate`. This lets MSAL SDK handle token response from the Auth broker app when you do authentication.

+```swift

+func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {

+ return MSALPublicClientApplication.handleMSALResponse(url, sourceApplication: options[UIApplication.OpenURLOptionsKey.sourceApplication] as? String)

+}

+```

+> [!NOTE]

+> On iOS 13+, if you adopt `UISceneDelegate` instead of `UIApplicationDelegate`, place this code into the `scene:openURLContexts:` callback instead (See [Apple's documentation](https://developer.apple.com/documentation/uikit/uiscenedelegate/3238059-scene?language=objc)).

+> If you support both UISceneDelegate and UIApplicationDelegate for compatibility with older iOS, MSAL callback needs to be placed into both places.

+```swift

+func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {

+ guard let urlContext = URLContexts.first else {

+ return

+ }

+ let url = urlContext.url

+ let sourceApp = urlContext.options.sourceApplication

+ MSALPublicClientApplication.handleMSALResponse(url, sourceApplication: sourceApp)

+}

+```

+Finally, your app must have an `LSApplicationQueriesSchemes` entry in your ***Info.plist*** alongside the `CFBundleURLTypes`. The sample comes with this included.

+ ```xml

+ <key>LSApplicationQueriesSchemes</key>

+ <array>

+ <string>msauthv2</string>

+ <string>msauthv3</string>

+ </array>

+ ```

+### Sign in users & request tokens

+MSAL has two methods used to acquire tokens: `acquireToken` and `acquireTokenSilent`.

+#### acquireToken: Get a token interactively

+Some situations require users to interact with Microsoft identity platform. In these cases, the end user may be required to select their account, enter their credentials, or consent to your app's permissions. For example,

+* The first time users sign in to the application

+* If a user resets their password, they'll need to enter their credentials

+* When your application is requesting access to a resource for the first time

+* When MFA or other Conditional Access policies are required

+```swift

+let parameters = MSALInteractiveTokenParameters(scopes: kScopes, webviewParameters: self.webViewParamaters!)

+self.applicationContext!.acquireToken(with: parameters) { (result, error) in /* Add your handling logic */}

+```

+> |Where:| Description |

+> |||

+> | `scopes` | Contains the scopes being requested (that is, `[ "user.read" ]` for Microsoft Graph or `[ "<Application ID URL>/scope" ]` for custom web APIs (`api://<Application ID>/access_as_user`) |

+#### acquireTokenSilent: Get an access token silently

+Apps shouldn't require their users to sign in every time they request a token. If the user has already signed in, this method allows apps to request tokens silently.

+```swift

+self.applicationContext!.getCurrentAccount(with: nil) { (currentAccount, previousAccount, error) in

+ guard let account = currentAccount else {

+ return

+ }

+ let silentParams = MSALSilentTokenParameters(scopes: self.kScopes, account: account)

+ self.applicationContext!.acquireTokenSilent(with: silentParams) { (result, error) in /* Add your handling logic */}

+}

+```

+> |Where: | Description |

+> |||

+> | `scopes` | Contains the scopes being requested (that is, `[ "user.read" ]` for Microsoft Graph or `[ "<Application ID URL>/scope" ]` for custom web APIs (`api://<Application ID>/access_as_user`) |

+> | `account` | The account a token is being requested for. This quickstart is about a single account application. If you want to build a multi-account app you'll need to define logic to identify which account to use for token requests using `accountsFromDeviceForParameters:completionBlock:` and passing correct `accountIdentifier` |

+## Next steps

+Move on to the step-by-step tutorial in which you build an iOS or macOS app that gets an access token from the Microsoft identity platform and uses it to call the Microsoft Graph API.

+> [!div class="nextstepaction"]

+> [Tutorial: Sign in users and call Microsoft Graph from an iOS or macOS app](tutorial-v2-ios.md)

+>This information last updated on February 16th, 2022.<br/>You can also download a CSV version of this table [here](https://download.microsoft.com/download/e/3/e/e3e9faf2-f28b-490a-9ada-c6089a1fc5b0/Product%20names%20and%20service%20plan%20identifiers%20for%20licensing.csv).

+| Common Data Service Database Capacity for Government | CDS_DB_CAPACITY_GOV | eddf428b-da0e-4115-accf-b29eb0b83965 | CDS_DB_CAPACITY_GOV (1ddffef6-4f69-455e-89c7-d5d72105f915)<br/>EXCHANGE_S_FOUNDATION_GOV (922ba911-5694-4e99-a794-73aed9bfeec8) | Common Data Service for Apps Database Capacity for Government (1ddffef6-4f69-455e-89c7-d5d72105f915)<br/>Exchange Foundation for Government (922ba911-5694-4e99-a794-73aed9bfeec8)|

+| Exchange Online (Plan 1) for GCC | EXCHANGESTANDARD_GOV | f37d5ebf-4bf1-4aa2-8fa3-50c51059e983 | EXCHANGE_S_STANDARD_GOV (e9b4930a-925f-45e2-ac2a-3f7788ca6fdd)<br/>INTUNE_O365 (882e1d05-acd1-4ccb-8708-6ee03664b117) | Exchange Online (Plan 1) for Government (e9b4930a-925f-45e2-ac2a-3f7788ca6fdd)<br/>Mobile Device Management for Office 365 (882e1d05-acd1-4ccb-8708-6ee03664b117) |

+| Exchange Online Protection | EOP_ENTERPRISE | 45a2423b-e884-448d-a831-d9e139c52d2f | EOP_ENTERPRISE (326e2b78-9d27-42c9-8509-46c827743a17) | Exchange Online Protection (326e2b78-9d27-42c9-8509-46c827743a17) |

+| Microsoft 365 Apps for Faculty | OFFICESUBSCRIPTION_FACULTY | 12b8c807-2e20-48fc-b453-542b6ee9d171 | EXCHANGE_S_FOUNDATION (113feb6c-3fe4-4440-bddc-54d774bf0318)<br/>OFFICESUBSCRIPTION (43de0ff5-c92c-492b-9116-175376d08c38)<br/>RMS_S_BASIC (31cf2cfc-6b0d-4adc-a336-88b724ed8122)<br/>OFFICE_FORMS_PLAN_2 (9b5de886-f035-4ff2-b3d8-c9127bea3620)<br/>MICROSOFT_SEARCH (94065c59-bc8e-4e8b-89e5-5138d471eaff)<br/>INTUNE_O365 (882e1d05-acd1-4ccb-8708-6ee03664b117)<br/>SHAREPOINTWAC_EDU (e03c7e47-402c-463c-ab25-949079bedb21)<br/>ONEDRIVESTANDARD (13696edf-5a08-49f6-8134-03083ed8ba30)<br/>SWAY (a23b959c-7ce8-4e57-9140-b90eb88a9e97)<br/>WHITEBOARD_PLAN2 (94a54592-cd8b-425e-87c6-97868b000b91) | Exchange Foundation (113feb6c-3fe4-4440-bddc-54d774bf0318)<br/>Microsoft 365 Apps for Enterprise (43de0ff5-c92c-492b-9116-175376d08c38)<br/>Microsoft Azure Rights Management Service (31cf2cfc-6b0d-4adc-a336-88b724ed8122)<br/>Microsoft Forms (Plan 2) (9b5de886-f035-4ff2-b3d8-c9127bea3620)<br/>Microsoft Search (94065c59-bc8e-4e8b-89e5-5138d471eaff)<br/>Mobile Device Management for Office 365 (882e1d05-acd1-4ccb-8708-6ee03664b117)<br/>Office for the Web for Education (e03c7e47-402c-463c-ab25-949079bedb21)<br/>OneDrive for Business (Plan 1) (13696edf-5a08-49f6-8134-03083ed8ba30)<br/>Sway (a23b959c-7ce8-4e57-9140-b90eb88a9e97)<br/>Whiteboard (Plan 2) (94a54592-cd8b-425e-87c6-97868b000b91) |

+| Microsoft 365 Business Voice | BUSINESS_VOICE_MED2 | a6051f20-9cbc-47d2-930d-419183bf6cf1 | MCOMEETADV (3e26ee1f-8a5f-4d52-aee2-b81ce45c8f40)<br/>MCOPSTN1 (4ed3ff63-69d7-4fb7-b984-5aec7f605ca8)<br/>MCOEV (4828c8ec-dc2e-4779-b502-87ac9ce28ab7) | Microsoft 365 Audio Conferencing (3e26ee1f-8a5f-4d52-aee2-b81ce45c8f40)<br/>Microsoft 365 Domestic Calling Plan (4ed3ff63-69d7-4fb7-b984-5aec7f605ca8)<br/>Microsoft 365 Phone System (4828c8ec-dc2e-4779-b502-87ac9ce28ab7) |

+| Microsoft 365 F3 GCC | M365_F1_GOV | 2a914830-d700-444a-b73c-e3f31980d833 | AAD_PREMIUM (41781fb2-bc02-4b7c-bd55-b576c07bb09d)<br/>RMS_S_PREMIUM_GOV (1b66aedf-8ca1-4f73-af76-ec76c6180f98)<br/>RMS_S_ENTERPRISE_GOV (6a76346d-5d6e-4051-9fe3-ed3f312b5597)<br/>DYN365_CDS_O365_F1_GCC (29007dd3-36c0-4cc2-935d-f5bca2c2c473)<br/>CDS_O365_F1_GCC (5e05331a-0aec-437e-87db-9ef5934b5771)<br/>EXCHANGE_S_DESKLESS_GOV (88f4d7ef-a73b-4246-8047-516022144c9f)<br/>FORMS_GOV_F1 (bfd4133a-bbf3-4212-972b-60412137c428)<br/>MFA_PREMIUM (8a256a2b-b617-496d-b51b-e76466e88db0)<br/>INTUNE_A (c1ec4a95-1f05-45b3-a911-aa3fa01094f5)<br/>MICROSOFT_SEARCH (94065c59-bc8e-4e8b-89e5-5138d471eaff)<br/>STREAM_O365_K_GOV (d65648f1-9504-46e4-8611-2658763f28b8)<br/>TEAMS_GOV (304767db-7d23-49e8-a945-4a7eb65f9f28)<br/>INTUNE_O365 (882e1d05-acd1-4ccb-8708- 6ee03664b117)<br/>PROJECTWORKMANAGEMENT_GOV (5b4ef465-7ea1-459a-9f91-033317755a51)<br/>SHAREPOINTWAC_GOV (8f9f0f3b-ca90-406c-a842-95579171f8ec)<br/>OFFICEMOBILE_SUBSCRIPTION_GOV (4ccb60ee-9523-48fd-8f63-4b090f1ad77a)<br/>POWERAPPS_O365_S1_GOV (49f06c3d-da7d-4fa0-bcce-1458fdd18a59)<br/>FLOW_O365_S1_GOV (5d32692e-5b24-4a59-a77e-b2a8650e25c1)<br/>SHAREPOINTDESKLESS_GOV (b1aeb897-3a19-46e2-8c27-a609413cf193)<br/>MCOIMP_GOV (8a9f17f1-5872-44e8-9b11-3caade9dc90f)<br/>BPOS_S_TODO_FIRSTLINE (80873e7a-cd2a-4e67-b061-1b5381a676a5)<br/>WHITEBOARD_FIRSTLINE1 (36b29273-c6d0-477a-aca6-6fbe24f538e3) | Azure Active Directory Premium P1 (41781fb2-bc02-4b7c-bd55-b576c07bb09d)<br/>Azure Information Protection Premium P1 for GCC (1b66aedf-8ca1-4f73-af76-ec76c6180f98)<br/>Azure Rights Management (6a76346d-5d6e-4051-9fe3-ed3f312b5597)<br/>Common Data Service - O365 F1 GCC (29007dd3-36c0-4cc2-935d-f5bca2c2c473)<br/>Common Data Service for Teams_F1 GCC (5e05331a-0aec-437e-87db-9ef5934b5771)<br/>Exchange Online (Kiosk) for Government (88f4d7ef-a73b-4246-8047-516022144c9f)<br/>Forms for Government (Plan F1) (bfd4133a-bbf3-4212-972b-60412137c428)<br/>Microsoft Azure Multi-Factor Authentication (8a256a2b-b617-496d-b51b-e76466e88db0)<br/>Microsoft Intune (c1ec4a95-1f05-45b3-a911-aa3fa01094f5)<br/>Microsoft Search (94065c59-bc8e-4e8b-89e5-5138d471eaff)<br/>Microsoft Stream for O365 for Government (F1) (d65648f1-9504-46e4-8611-2658763f28b8)<br/>Microsoft Teams for Government (304767db-7d23-49e8-a945-4a7eb65f9f28)<br/>Mobile Device Management for Office 365 (882e1d05-acd1-4ccb-8708-6ee03664b117)<br/>Office 365 Planner for Government (5b4ef465-7ea1-459a-9f91-033317755a51)<br/>Office for the Web for Government (8f9f0f3b-ca90-406c-a842-95579171f8ec)<br/>Office Mobile Apps for Office 365 for GCC (4ccb60ee-9523-48fd-8f63-4b090f1ad77a)<br/>Power Apps for Office 365 F3 for Government (49f06c3d-da7d-4fa0-bcce-1458fdd18a59)<br/>Power Automate for Office 365 F3 for Government (5d32692e-5b24-4a59-a77e-b2a8650e25c1)<br/>SharePoint KioskG (b1aeb897-3a19-46e2-8c27-a609413cf193)<br/>Skype for Business Online (Plan 1) for Government (8a9f17f1-5872-44e8-9b11-3caade9dc90f)<br/>To-Do (Firstline) (80873e7a-cd2a-4e67-b061-1b5381a676a5)<br/>Whiteboard (Firstline) (36b29273-c6d0-477a-aca6-6fbe24f538e3) |

+| Microsoft Defender for Office 365 (Plan 1) GCC | ATP_ENTERPRISE_GOV | d0d1ca43-b81a-4f51-81e5-a5b1ad7bb005 | ATP_ENTERPRISE_GOV (493ff600-6a2b-4db6-ad37-a7d4eb214516) | Microsoft Defender for Office 365 (Plan 1) for Government (493ff600-6a2b-4db6-ad37-a7d4eb214516) |

+| Microsoft Workplace Analytics | WORKPLACE_ANALYTICS | 3d957427-ecdc-4df2-aacd-01cc9d519da8 | WORKPLACE_ANALYTICS (f477b0f0-3bb1-4890-940c-40fcee6ce05f)<br/>WORKPLACE_ANALYTICS_INSIGHTS_BACKEND (ff7b261f-d98b-415b-827c-42a3fdf015af)<br/>WORKPLACE_ANALYTICS_INSIGHTS_USER (b622badb-1b45-48d5-920f-4b27a2c0996c) | Microsoft Workplace Analytics (f477b0f0-3bb1-4890-940c-40fcee6ce05f)<br/>Microsoft Workplace Analytics Insights Backend (ff7b261f-d98b-415b-827c-42a3fdf015af)<br/>Microsoft Workplace Analytics Insights User (b622badb-1b45-48d5-920f-4b27a2c0996c) |

+| Nonprofit Portal | NONPROFIT_PORTAL | aa2695c9-8d59-4800-9dc8-12e01f1735af | EXCHANGE_S_FOUNDATION (113feb6c-3fe4-4440-bddc-54d774bf0318)<br/>NONPROFIT_PORTAL (7dbc2d88-20e2-4eb6-b065-4510b38d6eb2) | Exchange Foundation (113feb6c-3fe4-4440-bddc-54d774bf0318)<br/>Nonprofit Portal (7dbc2d88-20e2-4eb6-b065-4510b38d6eb2)|

+| Office 365 A1 for faculty | STANDARDWOFFPACK_FACULTY | 94763226-9b3c-4e75-a931-5c89701abe66 | AAD_BASIC_EDU (1d0f309f-fdf9-4b2a-9ae7-9c48b91f1426)<br/>DYN365_CDS_O365_P1 (40b010bb-0b69-4654-ac5e-ba161433f4b4)<br/>EducationAnalyticsP1 (a9b86446-fa4e-498f-a92a-41b447e03337)<br/>EXCHANGE_S_STANDARD 9aaf7827-d63c-4b61-89c3-182f06f82e5c)<br/>INFORMATION_BARRIERS (c4801e8a-cb58-4c35-aca6-f2dcc106f287)<br/>RMS_S_ENTERPRISE (bea4c11e-220a-4e6d-8eb8-8ea15d019f90)<br/>OFFICE_FORMS_PLAN_2 (9b5de886-f035-4ff2-b3d8-c9127bea3620)<br/>KAIZALA_O365_P2 (54fc630f-5a40-48ee-8965-af0503c1386e)<br/>PROJECTWORKMANAGEMENT (b737dad2-2f6c-4c65-90e3-ca563267e8b9)<br/>MICROSOFT_SEARCH (94065c59-bc8e-4e8b-89e5-5138d471eaff)<br/>Deskless (8c7d2df8-86f0-4902-b2ed-a0458298f3b3)<br/>STREAM_O365_E3 (9e700747-8b1d-45e5-ab8d-ef187ceec156)<br/>TEAMS1 (57ff2da0-773e-42df-b2af-ffb7a2317929)<br/>INTUNE_O365 (882e1d05-acd1-4ccb-8708-6ee03664b117)<br/>Nucleus (db4d623d-b514-490b-b7ef-8885eee514de)<br/>SHAREPOINTWAC_EDU (e03c7e47-402c-463c-ab25-949079bedb21)<br/>OFFICEMOBILE_SUBSCRIPTION (c63d4d19-e8cb-460e-b37c-4d6c34603745)<br/>POWERAPPS_O365_P2 (c68f8d98-5534-41c8-bf36-22fa496fa792)<br/>FLOW_O365_P2 (76846ad7-7776-4c40-a281-a386362dd1b9)<br/>PROJECT_O365_P1 (a55dfd10-0864-46d9-a3cd-da5991a3e0e2)<br/>SCHOOL_DATA_SYNC_P1 (c33802dd-1b50-4b9a-8bb9-f13d2cdeadac)<br/>SHAREPOINTSTANDARD_EDU (0a4983bb-d3e5-4a09-95d8-b2d0127b3df5)<br/>MCOSTANDARD (0feaeb32-d00e-4d66-bd5a-43b5b83db82c)<br/>SWAY (a23b959c-7ce8-4e57-9140-b90eb88a9e97)<br/>BPOS_S_TODO_2 (c87f142c-d1e9-4363-8630-aaea9c4d9ae5)<br/>VIVA_LEARNING_SEEDED (b76fb638-6ba6-402a-b9f9-83d28acb3d86)<br/>WHITEBOARD_PLAN1 (b8afc642-032e-4de5-8c0a-507a7bba7e5d)<br/>YAMMER_EDU (2078e8df-cff6-4290-98cb-5408261a760a) | Azure Active Directory Basic for Education (1d0f309f-fdf9-4b2a-9ae7-9c48b91f1426)<br/>Common Data Service - O365 P1 (40b010bb-0b69-4654-ac5e-ba161433f4b4)<br/>Education Analytics (a9b86446-fa4e-498f-a92a-41b447e03337)<br/>Exchange Online (Plan 1) (9aaf7827-d63c-4b61-89c3-182f06f82e5c)<br/>Information Barriers (c4801e8a-cb58-4c35-aca6-f2dcc106f287)<br/>Microsoft Azure Active Directory Rights (bea4c11e-220a-4e6d-8eb8-8ea15d019f90)<br/>Microsoft Forms (Plan 2) (9b5de886-f035-4ff2-b3d8-c9127bea3620)<br/>Microsoft Kaizala Pro Plan 2 (54fc630f-5a40-48ee-8965-af0503c1386e)<br/>Microsoft Planner (b737dad2-2f6c-4c65-90e3-ca563267e8b9)<br/>Microsoft Search (94065c59-bc8e-4e8b-89e5-5138d471eaff)<br/>Microsoft StaffHub (8c7d2df8-86f0-4902-b2ed-a0458298f3b3)<br/>Microsoft Stream for Office 365 E3 (9e700747-8b1d-45e5-ab8d-ef187ceec156)<br/>Microsoft Teams (57ff2da0-773e-42df-b2af-ffb7a2317929)<br/>Mobile Device Management for Office 365 (882e1d05-acd1-4ccb-8708-6ee03664b117)<br/>Nucleus (db4d623d-b514-490b-b7ef-8885eee514de)<br/>Office for the Web for Education (e03c7e47-402c-463c-ab25-949079bedb21)<br/>Office Mobile Apps for Office 365 (c63d4d19-e8cb-460e-b37c-4d6c34603745)<br/>Power Apps for Office 365 (c68f8d98-5534-41c8-bf36-22fa496fa792)<br/>Power Automate for Office 365 (76846ad7-7776-4c40-a281-a386362dd1b9)<br/>Project for Office (Plan E1) (a55dfd10-0864-46d9-a3cd-da5991a3e0e2)<br/>School Data Sync (Plan 1) (c33802dd-1b50-4b9a-8bb9-f13d2cdeadac)<br/>SharePoint (Plan 1) for Education (0a4983bb-d3e5-4a09-95d8-b2d0127b3df5)<br/>Skype for Business Online (Plan 2) (0feaeb32-d00e-4d66-bd5a-43b5b83db82c)<br/>Sway (a23b959c-7ce8-4e57-9140-b90eb88a9e97)<br/>To-Do (Plan 2) (c87f142c-d1e9-4363-8630-aaea9c4d9ae5)<br/>Viva Learning Seeded (b76fb638-6ba6-402a-b9f9-83d28acb3d86)<br/>Whiteboard (Plan 1) (b8afc642-032e-4de5-8c0a-507a7bba7e5d)<br/>Yammer for Academic (2078e8df-cff6-4290-98cb-5408261a760a) |

+| Office 365 A1 Plus for faculty | STANDARDWOFFPACK_IW_FACULTY | 78e66a63-337a-4a9a-8959-41c6654dfb56 | AAD_BASIC_EDU (1d0f309f-fdf9-4b2a-9ae7-9c48b91f1426)<br/>DYN365_CDS_O365_P1 (40b010bb-0b69-4654-ac5e-ba161433f4b4)<br/>EducationAnalyticsP1 (a9b86446-fa4e-498f-a92a-41b447e03337)<br/>EXCHANGE_S_STANDARD (9aaf7827-d63c-4b61-89c3-182f06f82e5c)<br/>INFORMATION_BARRIERS (c4801e8a-cb58-4c35-aca6-f2dcc106f287)<br/>OFFICESUBSCRIPTION (43de0ff5-c92c-492b-9116-175376d08c38)<br/>RMS_S_ENTERPRISE (bea4c11e-220a-4e6d-8eb8-8ea15d019f90)<br/>OFFICE_FORMS_PLAN_2 (9b5de886-f035-4ff2-b3d8-c9127bea3620)<br/>KAIZALA_O365_P2 (54fc630f-5a40-48ee-8965-af0503c1386e)<br/>PROJECTWORKMANAGEMENT (b737dad2-2f6c-4c65-90e3-ca563267e8b9)<br/>MICROSOFT_SEARCH (94065c59-bc8e-4e8b-89e5-5138d471eaff)<br/>Deskless (8c7d2df8-86f0-4902-b2ed-a0458298f3b3)<br/>STREAM_O365_E3 (9e700747-8b1d-45e5-ab8d-ef187ceec156)<br/>TEAMS1 (57ff2da0-773e-42df-b2af-ffb7a2317929)<br/>INTUNE_O365 (882e1d05-acd1-4ccb-8708-6ee03664b117)<br/>SHAREPOINTWAC_EDU (e03c7e47-402c-463c-ab25-949079bedb21)<br/>POWERAPPS_O365_P2 (c68f8d98-5534-41c8-bf36-22fa496fa792)<br/>FLOW_O365_P2 (76846ad7-7776-4c40-a281-a386362dd1b9)<br/>PROJECT_O365_P1 (a55dfd10-0864-46d9-a3cd-da5991a3e0e2)<br/>SCHOOL_DATA_SYNC_P1 (c33802dd-1b50-4b9a-8bb9-f13d2cdeadac)<br/>SHAREPOINTSTANDARD_EDU (0a4983bb-d3e5-4a09-95d8-b2d0127b3df5)<br/>MCOSTANDARD (0feaeb32-d00e-4d66-bd5a-43b5b83db82c)<br/>SWAY (a23b959c-7ce8-4e57-9140-b90eb88a9e97)<br/>BPOS_S_TODO_2 (c87f142c-d1e9-4363-8630-aaea9c4d9ae5)<br/>VIVA_LEARNING_SEEDED (b76fb638-6ba6-402a-b9f9-83d28acb3d86)<br/>WHITEBOARD_PLAN1 (b8afc642-032e-4de5-8c0a-507a7bba7e5d)<br/>YAMMER_EDU (2078e8df-cff6-4290-98cb-5408261a760a) | Azure Active Directory Basic for Education (1d0f309f-fdf9-4b2a-9ae7-9c48b91f1426)<br/>Common Data Service - O365 P1 (40b010bb-0b69-4654-ac5e-ba161433f4b4)<br/>Education Analytics (a9b86446-fa4e-498f-a92a-41b447e03337)<br/>Exchange Online (Plan 1) (9aaf7827-d63c-4b61-89c3-182f06f82e5c)<br/>Information Barriers (c4801e8a-cb58-4c35-aca6-f2dcc106f287)<br/>Microsoft 365 Apps for Enterprise (43de0ff5-c92c-492b-9116-175376d08c38)<br/>Microsoft Azure Active Directory Rights (bea4c11e-220a-4e6d-8eb8-8ea15d019f90)<br/>Microsoft Forms (Plan 2) (9b5de886-f035-4ff2-b3d8-c9127bea3620)<br/>Microsoft Kaizala Pro Plan 2 (54fc630f-5a40-48ee-8965-af0503c1386e)<br/>Microsoft Planner (b737dad2-2f6c-4c65-90e3-ca563267e8b9)<br/>Microsoft Search (94065c59-bc8e-4e8b-89e5-5138d471eaff)<br/>Microsoft StaffHub (8c7d2df8-86f0-4902-b2ed-a0458298f3b3)<br/>Microsoft Stream for Office 365 E3 (9e700747-8b1d-45e5-ab8d-ef187ceec156)<br/>Microsoft Teams (57ff2da0-773e-42df-b2af-ffb7a2317929)<br/>Mobile Device Management for Office 365 (882e1d05-acd1-4ccb-8708-6ee03664b117)<br/>Office for the Web for Education (e03c7e47-402c-463c-ab25-949079bedb21)<br/>Power Apps for Office 365 (c68f8d98-5534-41c8-bf36-22fa496fa792)<br/>Power Automate for Office 365 (76846ad7-7776-4c40-a281-a386362dd1b9)<br/>Project for Office (Plan E1) (a55dfd10-0864-46d9-a3cd-da5991a3e0e2)<br/>School Data Sync (Plan 1) (c33802dd-1b50-4b9a-8bb9-f13d2cdeadac)<br/>SharePoint (Plan 1) for Education (0a4983bb-d3e5-4a09-95d8-b2d0127b3df5)<br/>Skype for Business Online (Plan 2) (0feaeb32-d00e-4d66-bd5a-43b5b83db82c)<br/>Sway (a23b959c-7ce8-4e57-9140-b90eb88a9e97)<br/>To-Do (Plan 2) (c87f142c-d1e9-4363-8630-aaea9c4d9ae5)<br/>Viva Learning Seeded (b76fb638-6ba6-402a-b9f9-83d28acb3d86)<br/>Whiteboard (Plan 1) (b8afc642-032e-4de5-8c0a-507a7bba7e5d)<br/>Yammer for Academic (2078e8df-cff6-4290-98cb-5408261a760a) |

+| Office 365 A1 for students | STANDARDWOFFPACK_STUDENT | 314c4481-f395-4525-be8b-2ec4bb1e9d91 | AAD_BASIC_EDU (1d0f309f-fdf9-4b2a-9ae7-9c48b91f1426)<br/>DYN365_CDS_O365_P1 (40b010bb-0b69-4654-ac5e-ba161433f4b4)<br/>EducationAnalyticsP1 (a9b86446-fa4e-498f-a92a-41b447e03337)<br/>EXCHANGE_S_STANDARD (9aaf7827-d63c-4b61-89c3-182f06f82e5c)<br/>INFORMATION_BARRIERS (c4801e8a-cb58-4c35-aca6-f2dcc106f287)<br/>RMS_S_ENTERPRISE (bea4c11e-220a-4e6d-8eb8-8ea15d019f90)<br/>OFFICE_FORMS_PLAN_2 (9b5de886-f035-4ff2-b3d8-c9127bea3620)<br/>KAIZALA_O365_P2 (54fc630f-5a40-48ee-8965-af0503c1386e)<br/>PROJECTWORKMANAGEMENT (b737dad2-2f6c-4c65-90e3-ca563267e8b9)<br/>MICROSOFT_SEARCH (94065c59-bc8e-4e8b-89e5-5138d471eaff)<br/>Deskless (8c7d2df8-86f0-4902-b2ed-a0458298f3b3)<br/>STREAM_O365_E3 (9e700747-8b1d-45e5-ab8d-ef187ceec156)<br/>TEAMS1 (57ff2da0-773e-42df-b2af-ffb7a2317929)<br/>INTUNE_O365 (882e1d05-acd1-4ccb-8708-6ee03664b117)<br/>SHAREPOINTWAC_EDU (e03c7e47-402c-463c-ab25-949079bedb21)<br/>OFFICEMOBILE_SUBSCRIPTION (c63d4d19-e8cb-460e-b37c-4d6c34603745)<br/>POWERAPPS_O365_P2 (c68f8d98-5534-41c8-bf36-22fa496fa792)<br/>FLOW_O365_P2 (76846ad7-7776-4c40-a281-a386362dd1b9)<br/>PROJECT_O365_P1 (a55dfd10-0864-46d9-a3cd-da5991a3e0e2)<br/>SCHOOL_DATA_SYNC_P1 (c33802dd-1b50-4b9a-8bb9-f13d2cdeadac)<br/>SHAREPOINTSTANDARD_EDU (0a4983bb-d3e5-4a09-95d8-b2d0127b3df5)<br/>MCOSTANDARD (0feaeb32-d00e-4d66-bd5a-43b5b83db82c)<br/>SWAY (a23b959c-7ce8-4e57-9140-b90eb88a9e97)<br/>BPOS_S_TODO_2 (c87f142c-d1e9-4363-8630-aaea9c4d9ae5)<br/>WHITEBOARD_PLAN1 (b8afc642-032e-4de5-8c0a-507a7bba7e5d)<br/>YAMMER_EDU (2078e8df-cff6-4290-98cb-5408261a760a) | Azure Active Directory Basic for Education (1d0f309f-fdf9-4b2a-9ae7-9c48b91f1426)<br/>Common Data Service - O365 P1 (40b010bb-0b69-4654-ac5e-ba161433f4b4)<br/>Education Analytics (a9b86446-fa4e-498f-a92a-41b447e03337)<br/>Exchange Online (Plan 1) (9aaf7827-d63c-4b61-89c3-182f06f82e5c)<br/>Information Barriers (c4801e8a-cb58-4c35-aca6-f2dcc106f287)<br/>Microsoft Azure Active Directory Rights (bea4c11e-220a-4e6d-8eb8-8ea15d019f90)<br/> Microsoft Forms (Plan 2) (9b5de886-f035-4ff2-b3d8-c9127bea3620)<br/>Microsoft Kaizala Pro Plan 2 (54fc630f-5a40-48ee-8965-af0503c1386e)<br/>Microsoft Planner (b737dad2-2f6c-4c65-90e3-ca563267e8b9)<br/>Microsoft Search (94065c59-bc8e-4e8b-89e5-5138d471eaff)<br/>Microsoft StaffHub (8c7d2df8-86f0-4902-b2ed-a0458298f3b3)<br/>Microsoft Stream for Office 365 E3 (9e700747-8b1d-45e5-ab8d-ef187ceec156)<br/>Microsoft Teams (57ff2da0-773e-42df-b2af-ffb7a2317929)<br/>Mobile Device Management for Office 365 (882e1d05-acd1-4ccb-8708-6ee03664b117)<br/>Office for the Web for Education (e03c7e47-402c-463c-ab25-949079bedb21)<br/>Office Mobile Apps for Office 365 (c63d4d19-e8cb-460e-b37c-4d6c34603745)<br/>Power Apps for Office 365 (c68f8d98-5534-41c8-bf36-22fa496fa792)<br/>Power Automate for Office 365 (76846ad7-7776-4c40-a281-a386362dd1b9)<br/>Project for Office (Plan E1) (a55dfd10-0864-46d9-a3cd-da5991a3e0e2)<br/>School Data Sync (Plan 1) (c33802dd-1b50-4b9a-8bb9-f13d2cdeadac)<br/>SharePoint (Plan 1) for Education (0a4983bb-d3e5-4a09-95d8-b2d0127b3df5)<br/>Skype for Business Online (Plan 2) (0feaeb32-d00e-4d66-bd5a-43b5b83db82c)<br/>Sway (a23b959c-7ce8-4e57-9140-b90eb88a9e97)<br/>To-Do (Plan 2) (c87f142c-d1e9-4363-8630-aaea9c4d9ae5)<br/>Whiteboard (Plan 1) (b8afc642-032e-4de5-8c0a-507a7bba7e5d)<br/>Yammer for Academic (2078e8df-cff6-4290-98cb-5408261a760a) |

+| Office 365 A1 Plus for students | STANDARDWOFFPACK_IW_STUDENT | e82ae690-a2d5-4d76-8d30-7c6e01e6022e | AAD_BASIC_EDU (1d0f309f-fdf9-4b2a-9ae7-9c48b91f1426)<br/> DYN365_CDS_O365_P1 (40b010bb-0b69-4654-ac5e-ba161433f4b4)<br/>EducationAnalyticsP1 (a9b86446-fa4e-498f-a92a-41b447e03337)<br/>EXCHANGE_S_STANDARD (9aaf7827-d63c-4b61-89c3-182f06f82e5c)<br/>INFORMATION_BARRIERS (c4801e8a-cb58-4c35-aca6-f2dcc106f287)<br/>OFFICESUBSCRIPTION (43de0ff5-c92c-492b-9116-175376d08c38)<br/>RMS_S_ENTERPRISE (bea4c11e-220a-4e6d-8eb8-8ea15d019f90)<br/>OFFICE_FORMS_PLAN_2 (9b5de886-f035-4ff2-b3d8-c9127bea3620)<br/>KAIZALA_O365_P2 (54fc630f-5a40-48ee-8965-af0503c1386e)<br/>PROJECTWORKMANAGEMENT (b737dad2-2f6c-4c65-90e3-ca563267e8b9)<br/>MICROSOFT_SEARCH (94065c59-bc8e-4e8b-89e5-5138d471eaff)<br/>Deskless (8c7d2df8-86f0-4902-b2ed-a0458298f3b3)<br/>STREAM_O365_E3 (9e700747-8b1d-45e5-ab8d-ef187ceec156)<br/>TEAMS1 (57ff2da0-773e-42df-b2af-ffb7a2317929)<br/>INTUNE_O365 (882e1d05-acd1-4ccb-8708-6ee03664b117)<br/>SHAREPOINTWAC_EDU (e03c7e47-402c-463c-ab25-949079bedb21)<br/>POWERAPPS_O365_P2 (c68f8d98-5534-41c8-bf36-22fa496fa792)<br/>FLOW_O365_P2 (76846ad7-7776-4c40-a281-a386362dd1b9)<br/>PROJECT_O365_P1 (a55dfd10-0864-46d9-a3cd-da5991a3e0e2)<br/>SCHOOL_DATA_SYNC_P1 (c33802dd-1b50-4b9a-8bb9-f13d2cdeadac)<br/>SHAREPOINTSTANDARD_EDU (0a4983bb-d3e5-4a09-95d8-b2d0127b3df5)<br/>MCOSTANDARD (0feaeb32-d00e-4d66-bd5a-43b5b83db82c)<br/>SWAY (a23b959c-7ce8-4e57-9140-b90eb88a9e97)<br/>BPOS_S_TODO_2 (c87f142c-d1e9-4363-8630-aaea9c4d9ae5)<br/>WHITEBOARD_PLAN1 (b8afc642-032e-4de5-8c0a-507a7bba7e5d)<br/>YAMMER_EDU (2078e8df-cff6-4290-98cb-5408261a760a) | Azure Active Directory Basic for Education (1d0f309f-fdf9-4b2a-9ae7-9c48b91f1426)<br/>Common Data Service - O365 P1 (40b010bb-0b69-4654-ac5e-ba161433f4b4)<br/>Education Analytics (a9b86446-fa4e-498f-a92a-41b447e03337)<br/>Exchange Online (Plan 1) (9aaf7827-d63c-4b61-89c3-182f06f82e5c)<br/>Information Barriers (c4801e8a-cb58-4c35-aca6-f2dcc106f287)<br/>Microsoft 365 Apps for Enterprise (43de0ff5-c92c-492b-9116-175376d08c38)<br/>Microsoft Azure Active Directory Rights (bea4c11e-220a-4e6d-8eb8-8ea15d019f90)<br/>Microsoft Forms (Plan 2) (9b5de886-f035-4ff2-b3d8-c9127bea3620)<br/>Microsoft Kaizala Pro Plan 2 (54fc630f-5a40-48ee-8965-af0503c1386e)<br/>Microsoft Planner (b737dad2-2f6c-4c65-90e3-ca563267e8b9)<br/>Microsoft Search (94065c59-bc8e-4e8b-89e5-5138d471eaff)<br/>Microsoft StaffHub (8c7d2df8-86f0-4902-b2ed-a0458298f3b3)<br/>Microsoft Stream for Office 365 E3 (9e700747-8b1d-45e5-ab8d-ef187ceec15 6)<br/>Microsoft Teams (57ff2da0-773e-42df-b2af-ffb7a2317929)<br/>Mobile Device Management for Office 365 (882e1d05-acd1-4ccb-8708-6ee03664b117)<br/>Office for the Web for Education (e03c7e47-402c-463c-ab25-949079bedb21)<br/>Power Apps for Office 365 (c68f8d98-5534-41c8-bf36-22fa496fa792)<br/>Power Automate for Office 365 (76846ad7-7776-4c40-a281-a386362dd1b9)<br/>Project for Office (Plan E1) (a55dfd10-0864-46d9-a3cd-da5991a3e0e2)<br/>School Data Sync (Plan 1) (c33802dd-1b50-4b9a-8bb9-f13d2cdeadac)<br/>SharePoint (Plan 1) for Education (0a4983bb-d3e5-4a09-95d8-b2d0127b3df5)<br/>Skype for Business Online (Plan 2) (0feaeb32-d00e-4d66-bd5a-43b5b83db82c)<br/>Sway (a23b959c-7ce8-4e57-9140-b90eb88a9e97)<br/>To-Do (Plan 2) (c87f142c-d1e9-4363-8630-aaea9c4d9ae5)<br/>Whiteboard (Plan 1) (b8afc642-032e-4de5-8c0a-507a7bba7e5d)<br/>Yammer for Academic (2078e8df-cff6-4290-98cb-5408261a760a) |

+| Office 365 G1 GCC | STANDARDPACK_GOV | 3f4babde-90ec-47c6-995d-d223749065d1 | DYN365_CDS_O365_P1_GCC (8eb5e9bc-783f-4425-921a-c65f45dd72c6)<br/>CDS_O365_P1_GCC (959e5dec-6522-4d44-8349-132c27c3795a)<br/>EXCHANGE_S_STANDARD_GOV (e9b4930a-925f-45e2-ac2a-3f7788ca6fdd)<br/>FORMS_GOV_E1 (f4cba850-4f34-4fd2-a341-0fddfdce1e8f)<br/>MYANALYTICS_P2_GOV (6e5b7995-bd4f-4cbd-9d19-0e32010c72f0)<br/>MICROSOFT_SEARCH (94065c59-bc8e-4e8b-89e5-5138d471eaff)<br/>STREAM_O365_E1_GOV (15267263-5986-449d-ac5c-124f3b49b2d6)<br/>TEAMS_GOV (304767db-7d23-49e8-a945-4a7eb65f9f28)<br/>INTUNE_O365 (882e1d05-acd1-4ccb-8708-6ee03664b117)<br/>PROJECTWORKMANAGEMENT_GOV (5b4ef465-7ea1-459a-9f91-033317755a51)<br/>SHAREPOINTWAC_GOV (8f9f0f3b-ca90-406c-a842-95579171f8ec)<br/>OFFICEMOBILE_SUBSCRIPTION_GOV (4ccb60ee-9523-48fd-8f63-4b090f1ad77a)<br/>POWERAPPS_O365_P1_GOV (c42aa49a-f357-45d5-9972-bc29df885fee)<br/>FLOW_O365_P1_GOV (ad6c8870-6356-474c-901c-64d7da8cea48)<br/>SharePoint Plan 1G (f9c43823-deb4-46a8-aa65-8b551f0c4f8a)<br/>MCOSTANDARD_GOV (a31ef4a2-f787-435e-8335-e47eb0cafc94)<br/>BPOS_S_TODO_1 (5e62787c-c316-451f-b873-1d05acd4d12c)<br/>WHITEBOARD_PLAN1 (b8afc642-032e-4de5-8c0a-507a7bba7e5d) | Common Data Service - O365 P1 GCC (8eb5e9bc-783f-4425-921a-c65f45dd72c6)<br/>Common Data Service for Teams_P1 GCC (959e5dec-6522-4d44-8349-132c27c3795a)<br/>Exchange Online (Plan 1) for Government (e9b4930a-925f-45e2-ac2a-3f7788ca6fdd)<br/>Forms for Government (Plan E1) (f4cba850-4f34-4fd2-a341-0fddfdce1e8f)<br/>Insights by MyAnalytics for Government (6e5b7995-bd4f-4cbd-9d19-0e32010c72f0)<br/>Microsoft Search (94065c59-bc8e-4e8b-89e5-5138d471eaff)<br/>Microsoft Stream for O365 for Government (E1) (15267263-5986-449d-ac5c-124f3b49b2d6)<br/>Microsoft Teams for Government(304767db-7d23-49e8-a945- 4a7eb65f9f28)<br/>Mobile Device Management for Office 365 (882e1d05-acd1-4ccb-8708-6ee03664b117)<br/>Office 365 Planner for Government (5b4ef465-7ea1-459a-9f91-033317755a51)<br/>Office for the Web for Government (8f9f0f3b-ca90-406c-a842-95579171f8ec)<br/>Office Mobile Apps for Office 365 for GCC (4ccb60ee-9523-48fd-8f63-4b090f1ad77a)<br/> Power Apps for Office 365 for Government (c42aa49a-f357-45d5-9972-bc29df885fee)<br/>Power Automate for Office 365 for Government (ad6c8870-6356-474c-901c-64d7da8cea48)<br/>SharePoint Plan 1G (f9c43823-deb4-46a8-aa65-8b551f0c4f8a)<br/>Skype for Business Online (Plan 2) for Government (a31ef4a2-f787-435e-8335-e47eb0cafc94)<br/>To-Do (Plan 1) (5e62787c-c316-451f-b873-1d05acd4d12c)<br/>Whiteboard (Plan 1) (b8afc642-032e-4de5-8c0a-507a7bba7e5d) |

+| Office 365 Advanced Compliance for GCC | EQUIVIO_ANALYTICS_GOV | 1a585bba-1ce3-416e-b1d6-9c482b52fcf6 | LOCKBOX_ENTERPRISE_GOV (89b5d3b1-3855-49fe-b46c-87c66dbc1526)<br/>INFORMATION_BARRIERS (c4801e8a-cb58-4c35-aca6-f2dcc106f287)<br/>Content_Explorer (d9fa6af4-e046-4c89-9226-729a0786685d)<br/>ContentExplorer_Standard (2b815d45-56e4-4e3a-b65c-66cb9175b560)<br/>MIP_S_CLP2 (efb0351d-3b08-4503-993d-383af8de41e3)<br/>MIP_S_CLP1 (5136a095-5cf0-4aff-bec3-e84448b38ea5)<br/>M365_ADVANCED_AUDITING (2f442157-a11c-46b9-ae5b-6e39ff4e5849)<br/>MICROSOFT_COMMUNICATION_COMPLIANCE (a413a9ff-720c-4822-98ef-2f37c2a21f4c)<br/>COMMUNICATIONS_DLP (6dc145d6-95dd-4191-b9c3-185575ee6f6b)<br/>CUSTOMER_KEY (6db1f1db-2b46-403f-be40-e39395f08dbb)<br/>INFO_GOVERNANCE (e26c2fcc-ab91-4a61-b35c-03cdc8dddf66)<br/> RECORDS_MANAGEMENT (65cc641f-cccd-4643-97e0-a17e3045e541)<br/>EQUIVIO_ANALYTICS_GOV (d1cbfb67-18a8-4792-b643-630b7f19aad1)<br/>PREMIUM_ENCRYPTION (617b097b-4b93-4ede-83de-5f075bb5fb2f) | Customer Lockbox for Government (89b5d3b1-3855-49fe-b46c-87c66dbc1526)<br/>Information Barriers (c4801e8a-cb58-4c35-aca6-f2dcc106f287)<br/>Information Protection and Governance Analytics -Premium (d9fa6af4-e046-4c89-9226-729a0786685d)<br/>Information Protection and Governance Analytics ΓÇô Standard (2b815d45-56e4-4e3a-b65c-66cb9175b560)<br/>Information Protection for Office 365 ΓÇô Premium (efb0351d-3b08-4503-993d-383af8de41e3)<br/>Information Protection for Office 365 ΓÇô Standard (5136a095-5cf0-4aff-bec3-e84448b38ea5)<br/>Microsoft 365 Advanced Auditing (2f442157-a11c-46b9-ae5b-6e39ff4e5849)<br/>Microsoft 365 Communication Compliance (a413a9ff-720c-4822-98ef-2f37c2a21f4c)<br/>Microsoft Communications DLP (6dc145d6-95dd-4191-b9c3-185575ee6f6b)<br/>Microsoft Customer Key (6db1f1db-2b46-403f-be40-e39395f08dbb)<br/>Microsoft Information Governance (e26c2fcc-ab91-4a61-b35c-03cdc8dddf66)<br/>Microsoft Records Management (65cc641f-cccd-4643-97e0-a17e3045e541)<br/>Office 365 Advanced eDiscovery for Government (d1cbfb67-18a8-4792-b643-630b7f19aad1)<br/>Premium Encryption in Office 365 (617b097b-4b93-4ede-83de-5f075bb5fb2f) |

+| Power Apps per user plan for Government | POWERAPPS_PER_USER_GCC | 8e4c6baa-f2ff-4884-9c38-93785d0d7ba1 | CDSAICAPACITY_PERUSER (91f50f7b-2204-4803-acac-5cf5668b8b39)<br/>CDSAICAPACITY_PERUSER_NEW (74d93933-6f22-436e-9441-66d205435abb)<br/>DYN365_CDS_P2_GOV (37396c73-2203-48e6-8be1-d882dae53275)<br/>EXCHANGE_S_FOUNDATION_GOV (922ba911-5694-4e99-a794-73aed9bfeec8)<br/>POWERAPPS_PER_USER_GCC (8f55b472-f8bf-40a9-be30-e29919d4ddfe)<br/>Flow_PowerApps_PerUser_GCC (8e3eb3bd-bc99-4221-81b8-8b8bc882e128) | AI Builder capacity Per User add-on (91f50f7b-2204-4803-acac-5cf5668b8b39)<br/>AI Builder capacity Per User add-on (74d93933-6f22-436e-9441-66d205435abb)<br/>Common Data Service for Government (37396c73-2203-48e6-8be1-d882dae53275)<br/>Exchange Foundation for Government (922ba911-5694-4e99-a794-73aed9bfeec8)<br/>Power Apps per User Plan for Government (8f55b472-f8bf-40a9-be30-e29919d4ddfe)<br/>Power Automate for Power Apps per User Plan for GCC (8e3eb3bd-bc99-4221-81b8-8b8bc882e128) |

+| Power Apps Plan 1 for Government | POWERAPPS_P1_GOV | eca22b68-b31f-4e9c-a20c-4d40287bc5dd | DYN365_CDS_P1_GOV (ce361df2-f2a5-4713-953f-4050ba09aad8)<br/>EXCHANGE_S_FOUNDATION_GOV (922ba911-5694-4e99-a794-73aed9bfeec8)<br/>FLOW_P1_GOV (774da41c-a8b3-47c1-8322-b9c1ab68be9f)<br/>POWERAPPS_P1_GOV (5ce719f1-169f-4021-8a64-7d24dcaec15f) | Common Data Service for Government (ce361df2-f2a5-4713-953f-4050ba09aad8)<br/>Exchange Foundation for Government (922ba911-5694-4e99-a794-73aed9bfeec8)<br/>Power Automate (Plan 1) for Government (774da41c-a8b3-47c1-8322-b9c1ab68be9f)<br/>PowerApps Plan 1 for Government (5ce719f1-169f-4021-8a64-7d24dcaec15f) |

+| Power Apps Portals login capacity add-on Tier 2 (10 unit min) for Government | POWERAPPS_PORTALS_LOGIN_T2_GCC | 26c903d5-d385-4cb1-b650-8d81a643b3c4 | CDS_POWERAPPS_PORTALS_LOGIN_GCC (0f7b9a29-7990-44ff-9d05-a76be778f410)<br/>EXCHANGE_S_FOUNDATION_GOV (922ba911-5694-4e99-a794-73aed9bfeec8)<br/>POWERAPPS_PORTALS_LOGIN_GCC (bea6aef1-f52d-4cce-ae09-bed96c4b1811) | Common Data Service Power Apps Portals Login Capacity for GCC (0f7b9a29-7990-44ff-9d05-a76be778f410)<br/>Exchange Foundation for Government (922ba911-5694-4e99-a794-73aed9bfeec8)<br/>Power Apps Portals Login Capacity Add-On for Government (bea6aef1-f52d-4cce-ae09-bed96c4b1811) |

+| Power Apps Portals page view capacity add-on for Government | POWERAPPS_PORTALS_PAGEVIEW_GCC | 15a64d3e-5b99-4c4b-ae8f-aa6da264bfe7 | CDS_POWERAPPS_PORTALS_PAGEVIEW_GCC (352257a9-db78-4217-a29d-8b8d4705b014)<br/>EXCHANGE_S_FOUNDATION_GOV (922ba911-5694-4e99-a794-73aed9bfeec8)<br/>POWERAPPS_PORTALS_PAGEVIEW_GCC (483d5646-7724-46ac-ad71-c78b7f099d8d) | CDS PowerApps Portals page view capacity add-on for GCC (352257a9-db78-4217-a29d-8b8d4705b014)<br/>Exchange Foundation for Government (922ba911-5694-4e99-a794-73aed9bfeec8)<br/>Power Apps Portals Page View Capacity Add-On for Government (483d5646-7724-46ac-ad71-c78b7f099d8d) |

+| Power Automate per user plan for Government | FLOW_PER_USER_GCC | c8803586-c136-479a-8ff3-f5f32d23a68e | DYN365_CDS_P2_GOV (37396c73-2203-48e6-8be1-d882dae53275)<br/>EXCHANGE_S_FOUNDATION_GOV (922ba911-5694-4e99-a794-73aed9bfeec8)<br/>FLOW_PER_USER_GCC (769b8bee-2779-4c5a-9456-6f4f8629fd41) | Common Data Service for Government (37396c73-2203-48e6-8be1-d882dae53275)<br/>Exchange Foundation for Government (922ba911-5694-4e99-a794-73aed9bfeec8)<br/>Power Automate per User Plan for Government (769b8bee-2779-4c5a-9456-6f4f8629fd41) |

+| Power Automate Plan 1 for Government (Qualified Offer) | FLOW_P1_GOV | 2b3b0c87-36af-4d15-8124-04a691cc2546 | DYN365_CDS_P1_GOV (ce361df2-f2a5-4713-953f-4050ba09aad8)<br/>EXCHANGE_S_FOUNDATION_GOV (922ba911-5694-4e99-a794-73aed9bfeec8)<br/>FLOW_P1_GOV (774da41c-a8b3-47c1-8322-b9c1ab68be9f) | Common Data Service for Government (ce361df2-f2a5-4713-953f-4050ba09aad8)<br/>Exchange Foundation for Government (922ba911-5694-4e99-a794-73aed9bfeec8)<br/>Power Automate (Plan 1) for Government (774da41c-a8b3-47c1-8322-b9c1ab68be9f) |

+| Power BI Pro for GCC | POWERBI_PRO_GOV | f0612879-44ea-47fb-baf0-3d76d9235576 | EXCHANGE_S_FOUNDATION_GOV (922ba911-5694-4e99-a794-73aed9bfeec8)<br/>BI_AZURE_P_2_GOV (944e9726-f011-4353-b654-5f7d2663db76) | Exchange Foundation for Government (922ba911-5694-4e99-a794-73aed9bfeec8)</br>Power BI Pro for Government (944e9726-f011-4353-b654-5f7d2663db76) |

+| Project Online Essentials for GCC | PROJECTESSENTIALS_GOV | ca1a159a-f09e-42b8-bb82-cb6420f54c8e | EXCHANGE_S_FOUNDATION_GOV (922ba911-5694-4e99-a794-73aed9bfeec8)<br/>SHAREPOINTWAC_GOV (8f9f0f3b-ca90-406c-a842-95579171f8ec)<br/>PROJECT_ESSENTIALS_GOV (fdcb7064-f45c-46fa-b056-7e0e9fdf4bf3)<br/>SHAREPOINTENTERPRISE_GOV (153f85dd-d912-4762-af6c-d6e0fb4f6692) | Exchange Foundation for Government (922ba911-5694-4e99-a794-73aed9bfeec8)<br/>Office for the Web for Government (8f9f0f3b-ca90-406c-a842-95579171f8ec)<br/>Project Online Essentials for Government (fdcb7064-f45c-46fa-b056-7e0e9fdf4bf3)<br/>SharePoint Plan 2G (153f85dd-d912-4762-af6c-d6e0fb4f6692) |

+| Skype for Business PSTN Usage Calling Plan | MCOPSTNPP | 06b48c5f-01d9-4b18-9015-03b52040f51a | MCOPSTN3 (6b340437-d6f9-4dc5-8cc2-99163f7f83d6) | MCOPSTN3 (6b340437-d6f9-4dc5-8cc2-99163f7f83d6) |

+| Teams Rooms Premium | MTR_PREM | 4fb214cb-a430-4a91-9c91-4976763aa78f | MMR_P1 (bdaa59a3-74fd-4137-981a-31d4f84eb8a0)<br/>MCOMEETADV (3e26ee1f-8a5f-4d52-aee2-b81ce45c8f40)<br/>MCOEV (4828c8ec-dc2e-4779-b502-87ac9ce28ab7)<br/>INTUNE_A (c1ec4a95-1f05-45b3-a911-aa3fa01094f5)<br/>TEAMS1 (57ff2da0-773e-42df-b2af-ffb7a2317929)<br/>MCOSTANDARD (0feaeb32-d00e-4d66-bd5a-43b5b83db82c)<br/>WHITEBOARD_PLAN3 (4a51bca5-1eff-43f5-878c-177680f191af) | Meeting Room Managed Services (bdaa59a3-74fd-4137-981a-31d4f84eb8a0)<br/>Microsoft 365 Audio Conferencing (3e26ee1f-8a5f-4d52-aee2-b81ce45c8f40)<br/>Microsoft 365 Phone System (4828c8ec-dc2e-4779-b502-87ac9ce28ab7)<br/>Microsoft Intune (c1ec4a95-1f05-45b3-a911-aa3fa01094f5)<br/>Microsoft Teams (57ff2da0-773e-42df-b2af-ffb7a2317929)<br/>Skype for Business Online (Plan 2) (0feaeb32-d00e-4d66-bd5a-43b5b83db82c)<br/>Whiteboard (Plan 3) (4a51bca5-1eff-43f5-878c-177680f191af) |

+| Windows 10/11 Enterprise E5 (Original) | WIN_ENT_E5 | 1e7e1070-8ccb-4aca-b470-d7cb538cb07e | DATAVERSE_FOR_POWERAUTOMATE_DESKTOP (59231cdf-b40d-4534-a93e-14d0cd31d27e)<br/>EXCHANGE_S_FOUNDATION (113feb6c-3fe4-4440-bddc-54d774bf0318)<br/>WINDEFATP (871d91ec-ec1a-452b-a83f-bd76c7d770ef)<br/>POWERAUTOMATE_DESKTOP_FOR_WIN (2d589a15-b171-4e61-9b5f-31d15eeb2872)<br/>UNIVERSAL_PRINT_01 (795f6fe0-cc4d-4773-b050-5dde4dc704c9)<br/>WIN10_PRO_ENT_SUB (21b439ba-a0ca-424f-a6cc-52f954a5b111)<br/>WINDOWSUPDATEFORBUSINESS_DEPLOYMENTSERVICE (7bf960f6-2cd9-443a-8046-5dbff9558365) | Dataverse for PAD (59231cdf-b40d-4534-a93e-14d0cd31d27e)<br/>Exchange Foundation (113feb6c-3fe4-4440-bddc-54d774bf0318)<br/>Microsoft Defender for Endpoint (871d91ec-ec1a-452b-a83f-bd76c7d770ef)<br/>PAD for Windows (2d589a15-b171-4e61-9b5f-31d15eeb2872)<br/>Universal Print (795f6fe0-cc4d-4773-b050-5dde4dc704c9)<br/>Windows 10/11 Enterprise (Original) (21b439ba-a0ca-424f-a6cc-52f954a5b111)<br/> Windows Update for Business Deployment Service (7bf960f6-2cd9-443a-8046-5dbff9558365) |

+| Windows Store for Business EDU Faculty | WSFB_EDU_FACULTY | c7e9d9e6-1981-4bf3-bb50-a5bdfaa06fb2 | Windows Store for Business EDU Store_faculty (aaa2cd24-5519-450f-a1a0-160750710ca1) | Windows Store for Business EDU Store_faculty (aaa2cd24-5519-450f-a1a0-160750710ca1) |

+description: In this quickstart, you learn how to use PowerShell to send an invitation to an external Azure AD B2B collaboration user. You'll use the Microsoft Graph Identity Sign-ins and the Microsoft Graph Users PowerShell modules.

+There are many ways you can invite external partners to your apps and services with Azure Active Directory B2B collaboration. In the previous quickstart, you saw how to add guest users directly in the Azure Active Directory admin portal. You can also use PowerShell to add guest users, either one at a time or in bulk. In this quickstart, youΓÇÖll use the New-MgInvitation command to add one guest user to your Azure tenant.

+If you donΓÇÖt have an Azure subscription, create a [free account](https://azure.microsoft.com/free/?WT.mc_id=A261C142F) before you begin.

+Install the [Microsoft Graph Identity Sign-ins module](/powershell/module/microsoft.graph.identity.signins/?view=graph-powershell-beta) (Microsoft.Graph.Identity.SignIns) and the [Microsoft Graph Users module](/powershell/module/microsoft.graph.users/?view=graph-powershell-beta) (Microsoft.Graph.Users).

+Connect-MgGraph -Scopes user.readwrite.all

+1. To send an invitation to your test email account, run the following PowerShell command (replace **"John Doe"** and **john\@contoso.com** with your test email account name and email address):

+ New-MgInvitation -InvitedUserDisplayName "John Doe" -InvitedUserEmailAddress John@contoso.com -InviteRedirectUrl "https://myapplications.microsoft.com" -SendInvitationMessage:$true

+1. The command sends an invitation to the email address specified. Check the output, which should look similar to the following example:

+ 

+1. To verify that the invited user was added to Azure AD, run the following command (replace **john\@contoso.com** with your invited email):

+ Get-MgUser -Filter "Mail eq 'John@contoso.com'"

+1. Check the output to make sure the user you invited is listed, with a user principal name (UPN) in the format *emailaddress*#EXT#\@*domain*. For example, *john_contoso.com#EXT#\@fabrikam.onmicrosoft.com*, where fabrikam.onmicrosoft.com is the organization from which you sent the invitations.

+ 

+For example: `Remove-AzureADUser -UserId john_contoso.com#EXT#@fabrikam.onmicrosoft.com`

+description: In this tutorial, you learn how to use PowerShell and a CSV file to send bulk invitations to external Azure AD B2B collaboration users. You'll use the Microsoft.Graph.Users PowerShell module.

+If you use Azure Active Directory (Azure AD) B2B collaboration to work with external partners, you can invite multiple guest users to your organization at the same time. In this tutorial, you learn how to use the Azure portal to send bulk invitations to external users. Specifically, you'll follow these steps:

+- **Examples row**: We've included in the template a row of examples of values for each column. You must remove the examples row and replace it with your own entries.

+- We don't recommend adding new columns to the template. Any columns you add are ignored and not processed.

+10. To view the job status, select **Click here to view the status of each operation**. Or, you can select **Bulk operation results** in the **Activity** section. For details about each line item within the bulk operation, select the values under the **# Success**, **# Failure**, or **Total Requests** columns. If failures occurred, the reasons for failure will be listed.

+To view guest users with PowerShell, you'll need the [Microsoft.Graph.Users PowerShell Module](/powershell/module/microsoft.graph.users/?view=graph-powershell-beta). Then sign in using the `Connect-MgGraph` command with an admin account to consent to the required scopes:

+```powershell

+Connect-MgGraph -Scopes "User.Read.All"

+```

+ Get-MgUser -Filter "UserType eq 'Guest'"

+When no longer needed, you can delete the test user accounts in the directory in the Azure portal on the Users page by selecting the checkbox next to the guest user and then selecting **Delete**.

+ Remove-MgUser -UserId "<UPN>"

+For example: `Remove-MgUser -UserId "lstokes_fabrikam.com#EXT#@contoso.onmicrosoft.com"`

+[Jooto](../saas-apps/jooto-tutorial.md), [Proprli](https://app.proprli.com/), [Pace Scheduler](https://www.pacescheduler.com/accounts/login/), [DRTrack](../saas-apps/drtrack-tutorial.md), [Dining Sidekick](../saas-apps/dining-sidekick-tutorial.md), [Cryotos](https://app.cryotos.com/oauth2/authorization/azure-client), [Emergency Management Systems](https://secure.emsystems.com.au/), [Manifestly Checklists](../saas-apps/manifestly-checklists-tutorial.md), [eLearnPOSH](../saas-apps/elearnposh-tutorial.md), [Scuba Analytics](../saas-apps/scuba-analytics-tutorial.md), [Athena Systems Login Platform](../saas-apps/athena-systems-login-platform-tutorial.md), [TimeTrack](../saas-apps/timetrack-tutorial.md), [MiHCM](../saas-apps/mihcm-tutorial.md), [Health Note](https://auth.healthnote.works/oauth), [Active Directory SSO for DoubleYou](../saas-apps/active-directory-sso-for-doubleyou-tutorial.md), [Emplifi platform](../saas-apps/emplifi-platform-tutorial.md), [Flexera One](../saas-apps/flexera-one-tutorial.md), [Hypothesis](https://web.hypothes.is/help/authorizing-hypothesis-from-the-azure-ad-app-gallery/), [Recurly](../saas-apps/recurly-tutorial.md), [XpressDox AU Cloud](https://au.xpressdox.com/Authentication/Login.aspx), [Zoom for Intune](https://zoom.us/), [UPWARD AGENT](https://app.upward.jp/login/), [Linux Foundation ID](https://openprofile.dev/), [Asset Planner](../saas-apps/asset-planner-tutorial.md), [Kiho](https://v3.kiho.fi/index/sso), [chezie](https://app.chezie.co/), [Excelity HCM](../saas-apps/excelity-hcm-tutorial.md), [yuccaHR](https://app.yuccahr.com/), [Blue Ocean Brain](../saas-apps/blue-ocean-brain-tutorial.md), [EchoSpan](../saas-apps/echospan-tutorial.md), [Archie](../saas-apps/archie-tutorial.md), [Equifax Workforce Solutions](../saas-apps/equifax-workforce-solutions-tutorial.md), [Palantir Foundry](../saas-apps/palantir-foundry-tutorial.md), [ATP SpotLight and ChronicX](../saas-apps/atp-spotlight-and-chronicx-tutorial.md), [DigiSign](https://app.digisign.org/selfcare/sso), [mConnect](https://mconnect.skooler.com/), [BrightHR](https://login.brighthr.com/), [Mural Identity](../saas-apps/mural-identity-tutorial.md), [NordPass SSO](https://app.nordpass.com/login%20use%20%22Log%20in%20to%20business%22%20option), [CloudClarity](https://portal.cloudclarity.app/dashboard), [Twic](../saas-apps/twic-tutorial.md), [Eduhouse Online](https://app.eduhouse.fi/palvelu/kirjaudu/microsoft), [Bealink](../saas-apps/bealink-tutorial.md), [Time Intelligence Bot](https://teams.microsoft.com/), [SentinelOne](https://sentinelone.com/)

+| Access package| Global administrator<p>User administrator<p>Identity Governance administrator<p>Catalog owner (for the access package)<p>Access package manager (for the access package)| Global administrator<p>Global reader<p>User administrator<p>Identity Governance administrator<p>Catalog owner (for the access package)<p>Access package manager (for the access package)<p>Security reader |

+ Title: Configure group claims for applications by using Azure Active Directory | Microsoft Docs

+description: Get information on how to configure group claims for use with Azure AD.

+# Configure group claims for applications by using Azure Active Directory

+Azure Active Directory (Azure AD) can provide a user's group membership information in tokens for use within applications. This feature supports two main patterns:

+- Groups identified by their Azure AD object identifier (OID) attribute

+- Groups identified by the `sAMAccountName` or `GroupSID` attribute for Active Directory-synchronized groups and users

+## Important caveats for this functionality

+- Support for use of `sAMAccountName` and security identifier (SID) attributes synced from on-premises is designed to enable moving existing applications from Active Directory Federation Services (AD FS) and other identity providers. Groups managed in Azure AD don't contain the attributes necessary to emit these claims.

+- In larger organizations, the number of groups where a user is a member might exceed the limit that Azure AD will add to a token. Those limits are 150 groups for a SAML token and 200 for a JSON Web Token (JWT). Exceeding a limit can lead to unpredictable results.

+ If your users have large numbers of group memberships, we recommend using the option to restrict the groups emitted in claims to the relevant groups for the application. If assigning groups to your applications is not possible, you can configure a [group filter](#group-filtering) to reduce the number of groups emitted in the claim.

+- Group claims have a five-group limit if the token is issued through the implicit flow. Tokens requested via the implicit flow will have a `"hasgroups":true` claim only if the user is in more than five groups.

+- We recommend basing in-app authorization on application roles rather than groups when:

+ - You're developing a new application, or an existing application can be configured for it.

+ - Support for nested groups isn't required.

+

+ Using application roles limits the amount of information that needs to go into the token, is more secure, and separates user assignment from app configuration.

+Many applications that are configured to authenticate with AD FS rely on group membership information in the form of Windows Server Active Directory group attributes. These attributes are the group `sAMAccountName`, which might be qualified by domain name, or the Windows group security identifier (`GroupSID`). When the application is federated with AD FS, AD FS uses the `TokenGroups` function to retrieve the group memberships for the user.

+An app that has been moved from AD FS needs claims in the same format. Group and role claims emitted from Azure AD might contain the domain-qualified `sAMAccountName` attribute or the `GroupSID` attribute synced from Active Directory, rather than the group's Azure AD `objectID` attribute.

+- **Azure AD group ObjectId**: Available for all groups.

+- **sAMAccountName**: Available for groups synchronized from Active Directory.

+- **NetbiosDomain\sAMAccountName**: Available for groups synchronized from Active Directory.

+- **DNSDomainName\sAMAccountName**: Available for groups synchronized from Active Directory.

+- **On-premises group security identifier**: Available for groups synchronized from Active Directory.

+> `sAMAccountName` and on-premises `GroupSID` attributes are available only on group objects synced from Active Directory. They aren't available on groups created in Azure AD or Office 365. Applications configured in Azure AD to get synced on-premises group attributes get them for synced groups only.

+Applications can call the Microsoft Graph group's endpoint to obtain group information for the authenticated user. This call ensures that all the groups where a user is a member are available, even when a large number of groups is involved. Group enumeration is then independent of limitations on token size.

+However, if an existing application expects to consume group information via claims, you can configure Azure AD with various claim formats. Consider the following options:

+- When you're using group membership for in-application authorization, it's preferable to use the group `ObjectID` attribute. The group `ObjectID` attribute is immutable and unique in Azure AD. It's available for all groups.

+- If you're using the on-premises group `sAMAccountName` attribute for authorization, use domain-qualified names. It reduces the chance of names clashing. `sAMAccountName` might be unique within an Active Directory domain, but if more than one Active Directory domain is synchronized with an Azure AD tenant, there's a possibility for more than one group to have the same name.

+- Consider using [application roles](../../active-directory/develop/howto-add-app-roles-in-azure-ad-apps.md) to provide a layer of indirection between the group membership and the application. The application then makes internal authorization decisions based on role claims in the token.

+- If the application is configured to get group attributes that are synced from Active Directory and a group doesn't contain those attributes, it won't be included in the claims.

+- Group claims in tokens include nested groups, except when you're using the option to restrict the group claims to groups that are assigned to the application.

+ If a user is a member of GroupB, and GroupB is a member of GroupA, then the group claims for the user will contain both GroupA and GroupB. When an organization's users have large numbers of group memberships, the number of groups listed in the token can grow the token size. Azure AD limits the number of groups that it will emit in a token to 150 for SAML assertions and 200 for JWT. If a user is a member of a larger number of groups, the groups are omitted. A link to the Microsoft Graph endpoint to obtain group information is included instead.

+## Prerequisites for using group attributes synchronized from Active Directory

+Group membership claims can be emitted in tokens for any group if you use the `ObjectId` format. To use group claims in formats other than group `ObjectId`, the groups must be synchronized from Active Directory via Azure AD Connect.

+To configure Azure AD to emit group names for Active Directory groups:

+ Before Azure AD can emit the group names or on-premises group SID in group or role claims, you need to synchronize the required attributes from Active Directory. You must be running Azure AD Connect version 1.2.70 or later. Earlier versions of Azure AD Connect than 1.2.70 will synchronize the group objects from Active Directory, but they won't include the required group name attributes.

+2. **Configure the application registration in Azure AD to include group claims in tokens**

+ You can configure group claims in the **Enterprise Applications** section of the portal, or by using the application manifest in the **Application Registrations** section. To configure group claims in the application manifest, see [Configure the Azure AD application registration for group attributes](#configure-the-azure-ad-application-registration-for-group-attributes) later in this article.

+To configure group claims for a gallery or non-gallery SAML application via single sign-on (SSO):

+1. Open **Enterprise Applications**, select the application in the list, select **Single Sign On configuration**, and then select **User Attributes & Claims**.

+1. Select **Add a group claim**.

+ 

+1. Use the options to select which groups should be included in the token.

+ 

+ | Selection | Description |

+ |-|-|

+ | **All groups** | Emits security groups and distribution lists and roles. |

+ | **Security groups** | Emits security groups that the user is a member of in the groups claim. |

+ | **Directory roles** | If the user is assigned directory roles, they're emitted as a `wids` claim. (The group's claim won't be emitted.) |

+ | **Groups assigned to the application** | Emits only the groups that are explicitly assigned to the application and that the user is a member of. |

+ - For example, to emit all the security groups that the user is a member of, select **Security groups**.

+ 

+ To emit groups by using Active Directory attributes synced from Active Directory instead of Azure AD `objectID` attributes, select the required format from the **Source attribute** drop-down list. Only groups synchronized from Active Directory will be included in the claims.

+ 

+ - To emit only groups assigned to the application, select **Groups assigned to the application**.

+ 

+ Groups assigned to the application will be included in the token. Other groups that the user is a member of will be omitted. With this option, nested groups are not included and the user must be a direct member of the group assigned to the application.

+ To change the groups assigned to the application, select the application from the **Enterprise Applications** list. Then select **Users and Groups** from the application's left menu.

+ For more information about managing group assignment to applications, see [Assign a user or group to an enterprise app](../../active-directory/manage-apps/assign-user-or-group-access-portal.md).

+### Set advanced options

+You can modify the way that group claims are emitted by using the settings under **Advanced options**.

+If you select **Customize the name of the group claim**, you can specify a different claim type for group claims. Enter the claim type in the **Name** box and the optional namespace for the claim in the **Namespace** box.

+

+Some applications require the group membership information to appear in the role claim. You can optionally emit the user's groups as roles by selecting the **Emit groups as role claims** checkbox.

+

+> If you use the option to emit group data as roles, only groups will appear in the role claim. Any application roles that the user is assigned to won't appear in the role claim.

+Group filtering allows for fine control of the list of groups that's included as part of the group claim. When a filter is configured, only groups that match the filter will be included in the group's claim that's sent to that application. The filter will be applied against all groups regardless of the group hierarchy.

+You can configure filters to be applied to the group's display name or `SAMAccountName` attribute. The following filtering operations are supported:

+ - **Prefix**: Matches the start of the selected attribute.

+ - **Suffix**: Matches the end of the selected attribute.

+ - **Contains**: Matches any location in the selected attribute.

+ 

+Some applications might require the groups in a different format from how they're represented in Azure AD. To support this requirement, you can apply a transformation to each group that will be emitted in the group claim. You achieve it by allowing the configuration of a regular expression (regex) and a replacement value on custom group claims.

+\

+- **Regex pattern**: Use a regex to parse text strings according to the pattern that you set in this box. If the regex pattern that you outline evaluates to `true`, the regex replacement pattern will run.

+- **Regex replacement pattern**: Outline in regex notation how you want to replace your string if the regex pattern that you outlined evaluates to `true`. Use capture groups to match subexpressions in this replacement regex.

+For more information about regex replace and capture groups, see [The Regular Expression Object Model: The Captured Group](/dotnet/standard/base-types/the-regular-expression-object-model?WT.mc_id=Portal-fx#the-captured-group).

+> As described in the Azure AD documentation, you can't modify a restricted claim by using a policy. The data source can't be changed, and no transformation is applied when you're generating these claims. The group claim is still a restricted claim, so you need to customize the groups by changing the name. If you select a restricted name for the name of your custom group claim, the claim will be ignored at runtime.

+> You can also use the regex transform feature as a filter, because any groups that don't match the regex pattern will not be emitted in the resulting claim.

+### Edit the group claim configuration

+After you add a group claim configuration to the **User Attributes & Claims** configuration, the option to add a group claim will be unavailable. To change the group claim configuration, select the group claim in the **Additional claims** list.

+

+## Configure the Azure AD application registration for group attributes

+You can also configure group claims in the [optional claims](../../active-directory/develop/active-directory-optional-claims.md) section of the [application manifest](../../active-directory/develop/reference-app-manifest.md).

+1. In the portal, select **Azure Active Directory** > **Application Registrations** > **Select Application** > **Manifest**.

+2. Enable group membership claims by changing `groupMembershipClaims`.

+ Valid values are:

+ | Selection | Description |

+ |-|-|

+ | `All` | Emits security groups, distribution lists, and roles. |

+ | `SecurityGroup` | Emits security groups that the user is a member of in the group claim. |

+ | `DirectoryRole` | If the user is assigned directory roles, they're emitted as a `wids` claim. (A group claim won't be emitted.) |

+ | `ApplicationGroup` | Emits only the groups that are explicitly assigned to the application and that the user is a member of. |

+ | `None` | No groups are returned. (It's not case-sensitive, so `none` also works. It can be set directly in the application manifest.) |

+ By default, group `ObjectID` attributes will be emitted in the group claim value. To modify the claim value to contain on-premises group attributes, or to change the claim type to a role, use the `optionalClaims` configuration described in the next step.

+3. Set optional clams for group name configuration.

+ If you want the groups in the token to contain the on-premises Active Directory group attributes, specify which token-type optional claim should be applied in the `optionalClaims` section. You can list multiple token types:

+ - `idToken` for the OIDC ID token

+ - `accessToken` for the OAuth/OIDC access token

+ - `Saml2Token` for SAML tokens

+ > The `Saml2Token` type applies to tokens in both SAML1.1 and SAML2.0 format.

+ For each relevant token type, modify the group claim to use the `optionalClaims` section in the manifest. The `optionalClaims` schema is as follows:

+ | Optional claims schema | Value |

+ | `name` | Must be `"groups"`. |

+ | `source` | Not used. Omit or specify `null`. |

+ | `essential` | Not used. Omit or specify `false`. |

+ | `additionalProperties` | List of additional properties. Valid options are `"sam_account_name"`, `"dns_domain_and_sam_account_name"`, `"netbios_domain_and_sam_account_name"`, and `"emit_as_roles"`. |

+ In `additionalProperties`, only one of `"sam_account_name"`, `"dns_domain_and_sam_account_name"`, or `"netbios_domain_and_sam_account_name"` is required. If more than one is present, the first is used and any others are ignored.

+ Some applications require group information about the user in the role claim. To change the claim type to from a group claim to a role claim, add `"emit_as_roles"` to additional properties. The group values will be emitted in the role claim.

+ > If you use `"emit_as_roles"`, any configured application roles that the user is assigned to will not appear in the role claim.

+Emit groups as group names in OAuth access tokens in `DNSDomainName\sAMAccountName` format:

+Emit group names to be returned in `NetbiosDomain\sAMAccountName` format as the role claim in SAML and OIDC ID tokens:

+- [Add authorization using groups & group claims to an ASP.NET Core web app (code sample)](https://github.com/Azure-Samples/active-directory-aspnetcore-webapp-openidconnect-v2/blob/master/5-WebApp-AuthZ/5-2-Groups/README.md)

+After completing your [investigation](howto-identity-protection-investigate-risk.md), you need to take action to remediate the risk or unblock users. Organizations can enable automated remediation using their [risk policies](howto-identity-protection-configure-risk-policies.md). Organizations should try to close all risk detections that they're presented in a time period your organization is comfortable with. Microsoft recommends closing events quickly, because time matters when working with risk.

+ 1. If a risk policy or a Conditional Access policy wasn't triggered at part of the risk detection, and the risk wasn't [self-remediated](#self-remediation-with-risk-policy), then:

+If requiring a password reset using a user risk policy isn't an option, administrators can close all risk detections for a user with a manual password reset.

+- **Require the user to reset password** - Requiring the users to reset passwords enables self-recovery without contacting help desk or an administrator. This method only applies to users that are registered for Azure AD MFA and SSPR. For users that haven't been registered, this option isn't available.

+If a password reset isn't an option for you, you can choose to dismiss user risk detections.

+When you select **Dismiss user risk**, all events are closed and the affected user is no longer at risk. However, because this method doesn't have an impact on the existing password, it doesn't bring the related identity back into a safe state.

+You can close individual risk detections manually. By closing risk detections manually, you can lower the user risk level. Typically, risk detections are closed manually in response to a related investigation. For example, when talking to a user reveals that an active risk detection isn't required anymore.

+#### Deleted users

+It isn't possible for administrators to dismiss risk for users who have been deleted from the directory. To remove deleted users, open a Microsoft support case.

+| Azure Web PubSub Service | [Managed identities for Azure Web PubSub Service](../../azure-web-pubsub/howto-use-managed-identity.md) |

+- [Managed identities overview](Overview.md)

+ Title: 'Tutorial: Azure AD SSO integration with FENCE-Mobile RemoteManager SSO'

+description: Learn how to configure single sign-on between Azure Active Directory and FENCE-Mobile RemoteManager SSO.

+# Tutorial: Azure AD SSO integration with FENCE-Mobile RemoteManager SSO

+In this tutorial, you'll learn how to integrate FENCE-Mobile RemoteManager SSO with Azure Active Directory (Azure AD). When you integrate FENCE-Mobile RemoteManager SSO with Azure AD, you can:

+* Control in Azure AD who has access to FENCE-Mobile RemoteManager SSO.

+* Enable your users to be automatically signed-in to FENCE-Mobile RemoteManager SSO with their Azure AD accounts.

+* Manage your accounts in one central location - the Azure portal.

+## Prerequisites

+To get started, you need the following items:

+* An Azure AD subscription. If you don't have a subscription, you can get a [free account](https://azure.microsoft.com/free/).

+* FENCE-Mobile RemoteManager SSO single sign-on (SSO) enabled subscription.

+## Scenario description

+In this tutorial, you configure and test Azure AD SSO in a test environment.

+* FENCE-Mobile RemoteManager SSO supports **SP** initiated SSO.

+## Adding FENCE-Mobile RemoteManager SSO from the gallery

+To configure the integration of FENCE-Mobile RemoteManager SSO into Azure AD, you need to add FENCE-Mobile RemoteManager SSO from the gallery to your list of managed SaaS apps.

+1. Sign in to the Azure portal using either a work or school account, or a personal Microsoft account.

+1. On the left navigation pane, select the **Azure Active Directory** service.

+1. Navigate to **Enterprise Applications** and then select **All Applications**.

+1. To add new application, select **New application**.

+1. In the **Add from the gallery** section, type **FENCE-Mobile RemoteManager SSO** in the search box.

+1. Select **FENCE-Mobile RemoteManager SSO** from results panel and then add the app. Wait a few seconds while the app is added to your tenant.

+## Configure and test Azure AD SSO for FENCE-Mobile RemoteManager SSO

+Configure and test Azure AD SSO with FENCE-Mobile RemoteManager SSO using a test user called **B.Simon**. For SSO to work, you need to establish a link relationship between an Azure AD user and the related user in FENCE-Mobile RemoteManager SSO.

+To configure and test Azure AD SSO with FENCE-Mobile RemoteManager SSO, perform the following steps:

+1. **[Configure Azure AD SSO](#configure-azure-ad-sso)** - to enable your users to use this feature.

+ 1. **[Create an Azure AD test user](#create-an-azure-ad-test-user)** - to test Azure AD single sign-on with B.Simon.

+ 1. **[Assign the Azure AD test user](#assign-the-azure-ad-test-user)** - to enable B.Simon to use Azure AD single sign-on.

+1. **[Configure FENCE-Mobile RemoteManager SSO](#configure-fence-mobile-remotemanager-sso)** - to configure the single sign-on settings on application side.

+ 1. **[Create FENCE-Mobile RemoteManager SSO test user](#create-fence-mobile-remotemanager-sso-test-user)** - to have a counterpart of B.Simon in FENCE-Mobile RemoteManager SSO that is linked to the Azure AD representation of user.

+1. **[Test SSO](#test-sso)** - to verify whether the configuration works.

+## Configure Azure AD SSO

+Follow these steps to enable Azure AD SSO in the Azure portal.

+1. In the Azure portal, on the **FENCE-Mobile RemoteManager SSO** application integration page, find the **Manage** section and select **single sign-on**.

+1. On the **Select a single sign-on method** page, select **SAML**.

+1. On the **Set up single sign-on with SAML** page, click the pencil icon for **Basic SAML Configuration** to edit the settings.

+ 

+1. On the **Basic SAML Configuration** section, enter the values for the following fields:

+ a. In the **Identifier (Entity ID)** text box, type a URL using the following pattern:

+ `api://www.fence-mrm.bsc.fujitsu.com/<TID>/<GUID>`

+ b. In the **Reply URL** text box, type a URL using one of the following patterns:

+ | Reply URL |

+ | |

+ | `https://www.fence-mrm.bsc.fujitsu.com/SConsole/SSOServlet?tid=<TID>` |

+ | `https://ctl.fence-mrm.bsc.fujitsu.com/SControl/SSOServlet?tid=<TID>` |

+ | `https://www.fence-mrm.bsc.fujitsu.com/IMDMLogin/SSOServlet?tid=<TID>` |

+ |

+

+ c. In the **Sign on URL** text box, type a URL using the following pattern:

+ `https://www.fence-mrm.bsc.fujitsu.com/SConsole/login.jsf?tid=<TID>`

+ > [!NOTE]

+ > These values are not real. Update these values with the actual Identifier, Reply URL and Sign on URL. Contact [FENCE-Mobile RemoteManager SSO Client support team](mailto:fj-FMRM_Dev_Azure@dl.jp.fujitsu.com) to get these values. You can also refer to the patterns shown in the **Basic SAML Configuration** section in the Azure portal.

+1. On the **Set up single sign-on with SAML** page, in the **SAML Signing Certificate** section, find **Federation Metadata XML** and select **Download** to download the certificate and save it on your computer.

+ 

+1. On the **Set up FENCE-Mobile RemoteManager SSO** section, copy the appropriate URL(s) based on your requirement.

+ 

+### Create an Azure AD test user

+In this section, you'll create a test user in the Azure portal called B.Simon.

+1. From the left pane in the Azure portal, select **Azure Active Directory**, select **Users**, and then select **All users**.

+1. Select **New user** at the top of the screen.

+1. In the **User** properties, follow these steps:

+ 1. In the **Name** field, enter `B.Simon`.

+ 1. In the **User name** field, enter the username@companydomain.extension. For example, `B.Simon@contoso.com`.

+ 1. Select the **Show password** check box, and then write down the value that's displayed in the **Password** box.

+ 1. Click **Create**.

+### Assign the Azure AD test user

+In this section, you'll enable B.Simon to use Azure single sign-on by granting access to FENCE-Mobile RemoteManager SSO.

+1. In the Azure portal, select **Enterprise Applications**, and then select **All applications**.

+1. In the applications list, select **FENCE-Mobile RemoteManager SSO**.

+1. In the app's overview page, find the **Manage** section and select **Users and groups**.

+1. Select **Add user**, then select **Users and groups** in the **Add Assignment** dialog.

+1. In the **Users and groups** dialog, select **B.Simon** from the Users list, then click the **Select** button at the bottom of the screen.

+1. If you are expecting a role to be assigned to the users, you can select it from the **Select a role** dropdown. If no role has been set up for this app, you see "Default Access" role selected.

+1. In the **Add Assignment** dialog, click the **Assign** button.

+## Configure FENCE-Mobile RemoteManager SSO

+To configure single sign-on on **FENCE-Mobile RemoteManager SSO** side, you need to send the downloaded **Federation Metadata XML** and appropriate copied URLs from Azure portal to [FENCE-Mobile RemoteManager SSO support team](mailto:fj-FMRM_Dev_Azure@dl.jp.fujitsu.com). They set this setting to have the SAML SSO connection set properly on both sides.

+### Create FENCE-Mobile RemoteManager SSO test user

+In this section, you create a user called Britta Simon in FENCE-Mobile RemoteManager SSO. Work with [FENCE-Mobile RemoteManager SSO support team](mailto:fj-FMRM_Dev_Azure@dl.jp.fujitsu.com) to add the users in the FENCE-Mobile RemoteManager SSO platform. Users must be created and activated before you use single sign-on.

+## Test SSO

+In this section, you test your Azure AD single sign-on configuration with following options.

+* Click on **Test this application** in Azure portal. This will redirect to FENCE-Mobile RemoteManager SSO Sign-on URL where you can initiate the login flow.

+* Go to FENCE-Mobile RemoteManager SSO Sign-on URL directly and initiate the login flow from there.

+* You can use Microsoft My Apps. When you click the FENCE-Mobile RemoteManager SSO tile in the My Apps, this will redirect to FENCE-Mobile RemoteManager SSO Sign-on URL. For more information about the My Apps, see [Introduction to the My Apps](../user-help/my-apps-portal-end-user-access.md).

+## Next steps

+Once you configure FENCE-Mobile RemoteManager SSO you can enforce session control, which protects exfiltration and infiltration of your organizationΓÇÖs sensitive data in real time. Session control extends from Conditional Access. [Learn how to enforce session control with Microsoft Defender for Cloud Apps](/cloud-app-security/proxy-deployment-aad).

+ Title: 'Tutorial: Configure Gong for automatic user provisioning with Azure Active Directory | Microsoft Docs'

+description: Learn how to automatically provision and de-provision user accounts from Azure AD to Gong.

+documentationcenter: ''

+writer: Thwimmer

+ms.assetid: 6c8285d3-4f35-4325-9adb-d1a44668a03a

+ms.devlang: na

+# Tutorial: Configure Gong for automatic user provisioning

+This tutorial describes the steps you need to perform in both Gong and Azure Active Directory (Azure AD) to configure automatic user provisioning. When configured, Azure AD automatically provisions and de-provisions users and groups to [Gong](https://www.gong.io/) using the Azure AD Provisioning service. For important details on what this service does, how it works, and frequently asked questions, see [Automate user provisioning and deprovisioning to SaaS applications with Azure Active Directory](../app-provisioning/user-provisioning.md).

+## Capabilities supported

+> [!div class="checklist"]

+> * Create users in Gong.

+> * Remove users in Gong when they do not require access anymore.

+> * Keep user attributes synchronized between Azure AD and Gong.

+## Prerequisites

+The scenario outlined in this tutorial assumes that you already have the following prerequisites:

+* [An Azure AD tenant](../develop/quickstart-create-new-tenant.md).

+* A user account in Azure AD with [permission](../roles/permissions-reference.md) to configure provisioning (for example, Application Administrator, Cloud Application administrator, Application Owner, or Global Administrator).

+* A user account in Gong with **Technical Administrator** privileges.

+## Step 1. Plan your provisioning deployment

+1. Learn about [how the provisioning service works](../app-provisioning/user-provisioning.md).

+1. Determine who will be in [scope for provisioning](../app-provisioning/define-conditional-rules-for-provisioning-user-accounts.md).

+1. Determine what data to [map between Azure AD and Gong](../app-provisioning/customize-application-attributes.md).

+## Step 2. Configure Gong to support provisioning with Azure AD

+1. Go to your company settings page > **PEOPLE** area > **Team Member Provisioning**.

+1. Select **Azure AD** as the provisioning source.

+1. To assign data capture, workspace, and permission settings to Azure AD groups:

+ 1. In the **Assign settings** area, click **ADD ASSIGNMENT**.

+ 1. Give the assignment a name.

+ 1. In the **Azure AD groups** area, select the Azure AD group you want to define the settings for.

+ 1. In the **Data capture** area, select the home workspace and the data capture settings for people that belong to this group.

+ 1. In the **Workspaces and permissions** area, set the permissions profile for other workspaces in your org.

+ 1. In the **Update settings** area, define how settings can be managed for this assignment:

+ * Select **Manual editing** to manage data capture and permission settings for users in this assignment in Gong.

+ After you create the assignment: if you make changes to group settings in Azure AD, they will not be pushed to Gong. However, you can edit the group settings manually in Gong.

+ * (Recommended) Select **Automatic updates** to give Azure AD governance over data capture and permission settings in Gong.

+ Define data capture and permission settings in Gong only when creating an assignment. Thereafter, other changes will only be applied to users in groups with this assignment when pushed from Azure AD.

+ 1. Click **ADD ASSIGNMENT**.

+1. For org's that don't have assignments (step 3), select the permission profile to apply to for automatically provisioned users.

+ [More information on permission profiles](https://help.gong.io/hc/en-us/articles/360028568911#UUID-34baef91-0aba-1295-4032-ff49102cb182).

+1. In the **Manager's provisioning settings** area:

+ 1. Select **Notify direct managers with recorded teams when a new team member is imported** to keep your team managers in the loop.

+ 1. Select **Managers can turn data capture on or off for their team** to give your team managers some autonomy.

+ > [!TIP]

+ > For more information, see "What are Manager's provisioning settings" in the [FAQ for team member provisioning](https://help.gong.io/hc/en-us/articles/360042352912#UUID-0d3df83a-44d1-11b9-ddf5-3ec649c2f594) article.

+1. Click **Update** to save your settings.

+> [!NOTE]

+> If you later change the provisioning source from Azure AD and then want to return to Azure AD provisioning, you will need to re-authenticate to Azure AD .

+## Step 3. Add Gong from the Azure AD application gallery

+Add Gong from the Azure AD application gallery to start managing provisioning to Gong. If you have previously setup Gong for SSO, you can use the same application. However it is recommended that you create a separate app when testing out the integration initially. Learn more about adding an application from the gallery [here](../manage-apps/add-application-portal.md).

+## Step 4. Define who will be in scope for provisioning

+The Azure AD provisioning service allows you to scope who will be provisioned based on assignment to the application and or based on attributes of the user / group. If you choose to scope who will be provisioned to your app based on assignment, you can use the following [steps](../manage-apps/assign-user-or-group-access-portal.md) to assign users and groups to the application. If you choose to scope who will be provisioned based solely on attributes of the user or group, you can use a scoping filter as described [here](../app-provisioning/define-conditional-rules-for-provisioning-user-accounts.md).

+* When assigning users and groups to Gong, you must select a role other than **Default Access**. Users with the Default Access role are excluded from provisioning and will be marked as not effectively entitled in the provisioning logs. If the only role available on the application is the default access role, you can [update the application manifest](../develop/howto-add-app-roles-in-azure-ad-apps.md) to add more roles.

+* Start small. Test with a small set of users and groups before rolling out to everyone. When scope for provisioning is set to assigned users and groups, you can control this by assigning one or two users or groups to the app. When scope is set to all users and groups, you can specify an [attribute based scoping filter](../app-provisioning/define-conditional-rules-for-provisioning-user-accounts.md).

+## Step 5. Configure automatic user provisioning to Gong

+This section guides you through the steps to configure the Azure AD provisioning service to create, update, and disable users and/or groups in Gong based on user and/or group assignments in Azure AD.

+### To configure automatic user provisioning for Gong in Azure AD:

+1. Sign in to the [Azure portal](https://portal.azure.com). Select **Enterprise Applications**, then select **All applications**.

+ 

+1. In the applications list, select **Gong**.

+ 

+1. Select the **Provisioning** tab.

+ 

+1. Set the **Provisioning Mode** to **Automatic**.

+ 

+1. In the **Admin Credentials** section, click on Authorize, make sure that you enter your Taskize Connect account's Admin credentials. Click **Test Connection** to ensure Azure AD can connect to Taskize Connect. If the connection fails, ensure your Taskize Connect account has Admin permissions and try again.

+ 

+1. In the **Notification Email** field, enter the email address of a person or group who should receive the provisioning error notifications and select the **Send an email notification when a failure occurs** check box.

+ 

+1. Select **Save**.

+1. Under the **Mappings** section, select **Synchronize Azure Active Directory Users to Gong**.

+1. Review the user attributes that are synchronized from Azure AD to Gong in the **Attribute-Mapping** section. The attributes selected as **Matching** properties are used to match the user accounts in Gong for update operations. If you choose to change the [matching target attribute](../app-provisioning/customize-application-attributes.md), you will need to ensure that the Gong API supports filtering users based on that attribute. Select the **Save** button to commit any changes.

+ |Attribute|Type|Supported for filtering|Required by Gong|

+ |||||

+ |userName|String|&check;|&check;

+ |urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager|String||

+ |active|Boolean||

+ |title|String||

+ |emails[type eq "work"].value|String||

+ |name.givenName|String||&check;

+ |name.familyName|String||&check;

+ |phoneNumbers[type eq "work"].value|String||

+ |externalId|String||

+ |locale|String||

+ |timezone|String||

+ |urn:ietf:params:scim:schemas:extension:Gong:2.0:User:stateOrProvince|String||

+ |urn:ietf:params:scim:schemas:extension:Gong:2.0:User:country|String||

+1. To configure scoping filters, refer to the following instructions provided in the [Scoping filter tutorial](../app-provisioning/define-conditional-rules-for-provisioning-user-accounts.md).

+1. To enable the Azure AD provisioning service for Gong, change the **Provisioning Status** to **On** in the **Settings** section.

+ 

+1. Define the users and/or groups that you would like to provision to Gong by choosing the desired values in **Scope** in the **Settings** section.

+ 

+1. When you are ready to provision, click **Save**.

+ 

+This operation starts the initial synchronization cycle of all users and groups defined in **Scope** in the **Settings** section. The initial cycle takes longer to perform than subsequent cycles, which occur approximately every 40 minutes as long as the Azure AD provisioning service is running.

+## Step 6. Monitor your deployment

+Once you've configured provisioning, use the following resources to monitor your deployment:

+* Use the [provisioning logs](../reports-monitoring/concept-provisioning-logs.md) to determine which users have been provisioned successfully or unsuccessfully

+* Check the [progress bar](../app-provisioning/application-provisioning-when-will-provisioning-finish-specific-user.md) to see the status of the provisioning cycle and how close it is to completion

+* If the provisioning configuration seems to be in an unhealthy state, the application will go into quarantine. Learn more about quarantine states [here](../app-provisioning/application-provisioning-quarantine-status.md).

+## More resources

+* [Managing user account provisioning for Enterprise Apps](../app-provisioning/configure-automatic-user-provisioning-portal.md)

+* [What is application access and single sign-on with Azure Active Directory?](../manage-apps/what-is-single-sign-on.md)

+## Next steps

+* [Learn how to review logs and get reports on provisioning activity](../app-provisioning/check-status-user-account-provisioning.md)

+ Title: 'Tutorial: Azure AD SSO integration with hireEZ-SSO'

+description: Learn how to configure single sign-on between Azure Active Directory and hireEZ-SSO.

+# Tutorial: Azure AD SSO integration with hireEZ-SSO

+In this tutorial, you'll learn how to integrate hireEZ-SSO with Azure Active Directory (Azure AD). When you integrate hireEZ-SSO with Azure AD, you can:

+* Control in Azure AD who has access to hireEZ-SSO.

+* Enable your users to be automatically signed-in to hireEZ-SSO with their Azure AD accounts.

+* hireEZ-SSO single sign-on (SSO) enabled subscription.

+* hireEZ-SSO supports **SP and IDP** initiated SSO.

+## Add hireEZ-SSO from the gallery

+To configure the integration of hireEZ-SSO into Azure AD, you need to add hireEZ-SSO from the gallery to your list of managed SaaS apps.

+1. In the **Add from the gallery** section, type **hireEZ-SSO** in the search box.

+1. Select **hireEZ-SSO** from results panel and then add the app. Wait a few seconds while the app is added to your tenant.

+## Configure and test Azure AD SSO for hireEZ-SSO

+Configure and test Azure AD SSO with hireEZ-SSO using a test user called **B.Simon**. For SSO to work, you need to establish a link relationship between an Azure AD user and the related user in hireEZ-SSO.

+To configure and test Azure AD SSO with hireEZ-SSO, perform the following steps:

+1. **[Configure hireEZ-SSO](#configure-hireez-sso)** - to configure the single sign-on settings on application side.

+ 1. **[Create hireEZ-SSO test user](#create-hireez-sso-test-user)** - to have a counterpart of B.Simon in hireEZ-SSO that is linked to the Azure AD representation of user.

+1. In the Azure portal, on the **hireEZ-SSO** application integration page, find the **Manage** section and select **single sign-on**.

+ a. In the **Identifier** text box, type the URL:

+ `https://app.hireez.com/`

+

+ b. In the **Reply URL** text box, type a URL using the following pattern:

+ `https://api.hireez.com/v1/users/saml/login/<teamId>`

+ > The Reply URL value is not real. Update this value with the actual Reply URL. Contact [hireEZ-SSO Client support team](mailto:support@hiretual.com) to get these values. You can also refer to the patterns shown in the **Basic SAML Configuration** section in the Azure portal.

+1. Click the **Properties** tab on the left menu bar, copy the value of **User access URL**,and save it on your computer.

+ 

+In this section, you'll enable B.Simon to use Azure single sign-on by granting access to hireEZ-SSO.

+1. In the applications list, select **hireEZ-SSO**.

+## Configure hireEZ-SSO

+1. Log in to your hireEZ-SSO company site as an administrator.

+ > If your Single Sign-On configuration has any errors or you have trouble to login to hireEZ-SSO Web App/Extension after you connected Admin SP-Initiated Single Sign-On, please contact [hireEZ-SSO support team](mailto:support@hiretual.com).

+### Create hireEZ-SSO test user

+In this section, you create a user called Britta Simon in hireEZ-SSO. Work with [hireEZ-SSO support team](mailto:support@hiretual.com) to add the users in the hireEZ-SSO platform. Users must be created and activated before you use single sign-on.

+* Click on **Test this application** in Azure portal. This will redirect to hireEZ-SSO Sign on URL where you can initiate the login flow.

+* Go to hireEZ-SSO Sign-on URL directly and initiate the login flow from there.

+* Click on **Test this application** in Azure portal and you should be automatically signed in to the hireEZ-SSO for which you set up the SSO.

+You can also use Microsoft My Apps to test the application in any mode. When you click the hireEZ-SSO tile in the My Apps, if configured in SP mode you would be redirected to the application sign on page for initiating the login flow and if configured in IDP mode, you should be automatically signed in to the hireEZ-SSO for which you set up the SSO. For more information about the My Apps, see [Introduction to the My Apps](../user-help/my-apps-portal-end-user-access.md).

+Once you configure hireEZ-SSO you can enforce session control, which protects exfiltration and infiltration of your organizationΓÇÖs sensitive data in real time. Session control extends from Conditional Access. [Learn how to enforce session control with Microsoft Defender for Cloud Apps](/cloud-app-security/proxy-deployment-aad).

+Add ProdPad from the Azure AD application gallery to start managing provisioning to ProdPad. If you have previously setup [ProdPad for SSO](prodpad-tutorial.md), you can use the same application. However it is recommended that you create a separate app when testing out the integration initially. Learn more about adding an application from the gallery [here](../manage-apps/add-application-portal.md).

+## Troubleshooting Tips

+Reach out to [ProdPad support team](mailto:help@prodpad.com) in case of any issues.

+Reach out to your [Thrive LXP Client support team](mailto:support@thrivelearning.com) to generate your **Tenant url** and **Secret Token**. These values will be entered in the Tenant URL and Secret Token field in the Provisioning tab of your Thrive LXP application in the Azure portal.

+* Import of all roles will fail if any of the custom roles is either "agent" or "end-user". To avoid this, ensure that none of the roles being imported has the above display names.

+Accelerated networking greatly improves networking performance of virtual machines. Ideally, use proximity placement groups in conjunction with accelerated networking. By default, AKS uses accelerated networking on [supported virtual machine instances](../virtual-network/accelerated-networking-overview.md?toc=/azure/virtual-machines/linux/toc.json#limitations-and-constraints), which include most Azure virtual machine with two or more vCPUs.

+[az-group-delete]: /cli/azure/group#az_group_delete

+ Title: Use Azure Dedicated Hosts in Azure Kubernetes Service (AKS) (Preview)

+description: Learn how to create an Azure Dedicated Hosts Group and associate it with Azure Kubernetes Service (AKS)

+# Add Azure Dedicated Host to an Azure Kubernetes Service (AKS) cluster

+Azure Dedicated Host is a service that provides physical servers - able to host one or more virtual machines - dedicated to one Azure subscription. Dedicated hosts are the same physical servers used in our data centers, provided as a resource. You can provision dedicated hosts within a region, availability zone, and fault domain. Then, you can place VMs directly into your provisioned hosts, in whatever configuration best meets your needs.

+Using Azure Dedicated Hosts for nodes with your AKS cluster has the following benefits:

+* Hardware isolation at the physical server level. No other VMs will be placed on your hosts. Dedicated hosts are deployed in the same data centers and share the same network and underlying storage infrastructure as other, non-isolated hosts.

+* Control over maintenance events initiated by the Azure platform. While the majority of maintenance events have little to no impact on your virtual machines, there are some sensitive workloads where each second of pause can have an impact. With dedicated hosts, you can opt in to a maintenance window to reduce the impact to your service.

+## Before you begin

+* An Azure subscription. If you don't have an Azure subscription, you can create a [free account](https://azure.microsoft.com/free).

+* [Azure CLI installed](/cli/azure/install-azure-cli).

+### Install the `aks-preview` Azure CLI

+You also need the *aks-preview* Azure CLI extension version 0.5.54 or later. Install the *aks-preview* Azure CLI extension by using the [az extension add][az-extension-add] command. Or install any available updates by using the [az extension update][az-extension-update] command.

+```azurecli-interactive

+# Install the aks-preview extension

+az extension add --name aks-preview

+# Update the extension to make sure you have the latest version installed

+az extension update --name aks-preview

+```

+### Register the `DedicatedHostGroupPreview` preview feature

+To use the feature, you must also enable the `DedicatedHostGroupPreview` feature flag on your subscription.

+Register the `DedicatedHostGroupPreview` feature flag by using the [az feature register][az-feature-register] command, as shown in the following example:

+```azurecli-interactive

+az feature register --namespace "Microsoft.ContainerService" --name "DedicatedHostGroupPreview"

+```

+It takes a few minutes for the status to show *Registered*. Verify the registration status by using the [az feature list][az-feature-list] command:

+```azurecli-interactive

+az feature list -o table --query "[?contains(name, 'Microsoft.ContainerService/DedicatedHostGroupPreview')].{Name:name,State:properties.state}"

+```

+When ready, refresh the registration of the *Microsoft.ContainerService* resource provider by using the [az provider register][az-provider-register] command:

+```azurecli-interactive

+az provider register --namespace Microsoft.ContainerService

+```

+## Limitations

+The following limitations apply when you integrate Azure Dedicated Host with Azure Kubernetes Service:

+* An existing agentpool cannot be converted from non-ADH to ADH or ADH to non-ADH.

+* It is not supported to update agentpool from host group A to host group B.

+## Add a Dedicated Host Group to an AKS cluster

+A host group is a resource that represents a collection of dedicated hosts. You create a host group in a region and an availability zone, and add hosts to it. When planning for high availability, there are additional options. You can use one or both of the following options with your dedicated hosts:

+Span across multiple availability zones. In this case, you are required to have a host group in each of the zones you wish to use.

+Span across multiple fault domains which are mapped to physical racks.

+In either case, you are need to provide the fault domain count for your host group. If you do not want to span fault domains in your group, use a fault domain count of 1.

+You can also decide to use both availability zones and fault domains.

+Not all host SKUs are available in all regions, and availability zones. You can list host availability, and any offer restrictions before you start provisioning dedicated hosts.

+```azurecli-interactive

+az vm list-skus -l eastus2 -r hostGroups/hosts -o table

+```

+## Add Dedicated Hosts to the Host Group

+Now create a dedicated host in the host group. In addition to a name for the host, you are required to provide the SKU for the host. Host SKU captures the supported VM series as well as the hardware generation for your dedicated host.

+For more information about the host SKUs and pricing, see [Azure Dedicated Host pricing](https://azure.microsoft.com/pricing/details/virtual-machines/dedicated-host/).

+Use az vm host create to create a host. If you set a fault domain count for your host group, you will be asked to specify the fault domain for your host.

+In this example, we will use [az vm host group create](/cli/azure/vm/host/group#az_vm_host_group_create?view=azure-cli-latest&preserve-view=true) to create a host group using both availability zones and fault domains.

+```azurecli-interactive

+az vm host group create \

+--name myHostGroup \

+-g myDHResourceGroup \

+-z 1\

+--platform-fault-domain-count 2

+```

+## Create an AKS cluster using the Host Group

+Create an AKS cluster, and add the Host Group you just configured.

+```azurecli-interactive

+az aks create -g MyResourceGroup -n MyManagedCluster --location westus2 --kubernetes-version 1.20.13 --nodepool-name agentpool1 --node-count 1 --host-group-id <id> --node-vm-size Standard_D2s_v3 --enable-managed-identity --assign-identity <id>

+```

+## Add a Dedicated Host Nodepool to an existing AKS cluster

+Add a Host Group to an already existing AKS cluster.

+```azurecli-interactive

+az aks nodepool add --cluster-name MyManagedCluster --name agentpool3 --resource-group MyResourceGroup --node-count 1 --host-group-id <id> --node-vm-size Standard_D2s_v3

+```

+## Remove a Dedicated Host Nodepool from an AKS cluster

+```azurecli-interactive

+az aks nodepool delete --cluster-name MyManagedCluster --name agentpool3 --resource-group MyResourceGroup

+```

+## Next steps

+In this article, you learned how to create an AKS cluster with a Dedicated host, and to add a dedicated host to an existing cluster. For more information about Dedicated Hosts, see [dedicated-hosts](../virtual-machines/dedicated-hosts.md).

+<!-- LINKS - External -->

+[kubernetes-services]: https://kubernetes.io/docs/concepts/services-networking/service/

+<!-- LINKS - Internal -->

+[aks-support-policies]: support-policies.md

+[aks-faq]: faq.md

+[azure-cli-install]: /cli/azure/install-azure-cli

+[dedicated-hosts]: /azure/virtual-machines/dedicated-hosts.md

+ms.devlang: csharp

+ms.devlang: csharp

+ms.devlang: csharp

+ms.devlang: php

+ms.devlang: python

+ms.devlang: ruby

+## Private endpoint

+In order to enable Private Endpoints for apps hosted in your App Service Environment, you must first enable this feature at the App Service Environment level.

+You can activate it through the Azure portal: in the App Service Environment configuration pane turn **on** the setting `Allow new private endpoints`.

+Alternatively the following CLI can enable it:

+```azurecli-interactive

+az appservice ase update --name myasename --allow-new-private-endpoint-connections true

+```

+For more information about Private Endpoint and Web App, see [Azure Web App Private Endpoint][privateendpoint]

+- [Environment variables and app settings reference](../reference-app-settings.md)

+<!--Links-->

+[privateendpoint]: ../networking/private-endpoint.md

+

+The connection between the Private Endpoint and the Web App uses a secure [Private Link][privatelink]. Private Endpoint is only used for incoming flows to your Web App. Outgoing flows won't use this Private Endpoint. You can inject outgoing flows to your network in a different subnet through the [VNet integration feature][vnetintegrationfeature].

+Each slot of an app is configured separately. You can plug up to 100 Private Endpoints per slot. You can't share a Private Endpoint between slots.

+- The NIC of the Private Endpoint can't have an NSG associated.

+- The Subnet that hosts the Private Endpoint can have an NSG associated, but you must disable the network policies enforcement for the Private Endpoint: see [Disable network policies for private endpoints][disablesecuritype]. As a result, you can't filter by any NSG the access to your Private Endpoint.

+- When you enable Private Endpoint to your Web App, the [access restrictions][accessrestrictions] configuration of the Web App isn't evaluated.

+In the Web HTTP logs of your Web App, you'll find the client source IP. This feature is implemented using the TCP Proxy protocol, forwarding the client IP property up to the Web App. For more information, see [Getting connection Information using TCP Proxy v2][tcpproxy].

+|cloudservicename.cloudapp.net|A|40.122.110.154|<--This public IP isn't your Private Endpoint, you'll receive a 403 error|

+## App Service Environment v3 special consideration

+In order to enable Private Endpoint for apps hosted in an IsolatedV2 plan (App Service Environment v3), you have to enable the Private Endpoint support at the App Service Environment level.

+You can activate the feature by the Azure portal in the App Service Environment configuration pane, or through the following CLI:

+## Specific requirements

+If the Virtual Network is in a different subscription than the app, you must ensure that the subscription with the Virtual Network is registered for the Microsoft.Web resource provider. You can explicitly register the provider [by following this documentation][registerprovider], but it will also automatically be registered when creating the first web app in a subscription.

+* When you use Azure Function in Elastic Premium Plan with Private Endpoint, to run or execute the function in Azure Web portal, you must have direct network access or you'll receive an HTTP 403 error. In other words, your browser must be able to reach the Private Endpoint to execute the function from the Azure Web portal.

+* FTP access is provided through the inbound public IP address. Private Endpoint doesn't support FTP access to the Web App.

+* IP-Based SSL isn't supported with Private Endpoints.

+We're improving Private Link feature and Private Endpoint regularly, check [this article][pllimitations] for up-to-date information about limitations.

+[registerprovider]: ../../azure-resource-manager/management/resource-providers-and-types.md#register-resource-provider

+ms.devlang: php

+ms.devlang: ruby

+ms.devlang: csharp, javascript

+ms.devlang: csharp

+ms.devlang: csharp

+ms.devlang: csharp

+ms.devlang: csharp

+ms.devlang: java

+ms.devlang: javascript

+ms.devlang: php

+ms.devlang: python

+ms.devlang: ruby

+ > [How to train a model](how-to-guides/build-custom-model-v3.md)

+* Learn more about custom template models:

+ > [!div class="nextstepaction"]

+ > [Custom template models](concept-custom-template.md )

+* * Train a custom model:

+ > [How to train a model](how-to-guides/build-custom-model-v3.md)

+Custom models can be one of two types, [**custom template**](concept-custom-template.md ) or custom form and [**custom neural**](concept-custom-neural.md) or custom document models. The labeling and training process for both models is identical, but the models differ as follows:

+ The custom template or custom form model relies on a consistent visual template to extract the labeled data. The accuracy of your model is affected by variances in the visual structure of your documents. Structured forms such as questionnaires or applications are examples of consistent visual templates. Your training set will consist of structured documents where the formatting and layout are static and constant from one document instance to the next. Custom template models support key-value pairs, selection marks, tables, signature fields and regions and can be trained on documents in any of the [supported languages](language-support.md). For more information, *see* [custom template models](concept-custom-template.md ).

+The custom neural (custom document) model is a deep learning model type that relies on a base model trained on a large collection of documents. This model is then fine-tuned or adapted to your data when you train the model with a labeled dataset. Custom neural models support structured, semi-structured, and unstructured documents to extract fields. Custom neural models currently support English-language documents. When choosing between the two model types, start with a neural model if it meets your functional needs. See [neural models](concept-custom-neural.md) to learn more about custom document models.

+|Custom model| <ul><li>[Form Recognizer Studio](https://formrecognizer.appliedai.azure.com/studio/customform/projects)</li><li>[REST API](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-v3-0-preview-2/operations/AnalyzeDocument)</li><li>[C# SDK](quickstarts/try-v3-csharp-sdk.md)</li><li>[Python SDK](quickstarts/try-v3-python-sdk.md)</li></ul>|

+| 🆕[W-2 (preview)](#w-2-preview) | Extract employee, employer, wage information, etc. from US W-2 forms. |

+### W-2 (preview)

+The W-2 model analyzes and extracts key information reported in each box on a W-2 form. The model supports standard and customized forms from 2018 to the present, including both single form and multiple forms (copy A, B, C, D, 1, 2) on one page.

+***Sample W-2 document processed using [Form Recognizer Studio](https://formrecognizer.appliedai.azure.com/studio/prebuilt?formType=tax.us.w2)***:

+> [!div class="nextstepaction"]

+> [Learn more: W-2 model](concept-w2.md)

+ | ID document | Γ£ô | Γ£ô |Γ£ô| | ||

+ |🆕W-2 | ✓ | ✓ | ✓ | ✓ | ✓ ||

+* [**W-2 (preview)**](concept-w2.md) model supports employee, employer, wage information, etc. from US W-2 forms.

+# Form Recognizer W-2 model | Preview

+The Form W-2, Wage and Tax Statement, is a [US Internal Revenue Service (IRS) tax form](https://www.irs.gov/forms-pubs/about-form-w-2) completed by employers to report employees' salary, wages, compensation, and taxes withheld. Employers send a W-2 form to each employee on or before January 31 each year and employees use the form to prepare their tax returns. W-2 is a key document used in employee's federal and state taxes filing, as well as other processes like mortgage loan and Social Security Administration (SSA).

+A W-2 is a multipart form divided into state and federal sections and consists of more than 14 boxes, both numbered and lettered, that detail the employee's income from the previous year. The Form Recognizer W-2 model, combines Optical Character Recognition (OCR) with deep learning models to analyze and extract information reported in each box on a W-2 form. The model supports standard and customized forms from 2018 to the present, including both single form and multiple forms ([copy A, B, C, D, 1, 2](https://en.wikipedia.org/wiki/Form_W-2#Filing_requirements) on one page.

+1. You can analyze the sample W-2 document or select the **Γ₧ò Add** button to upload your own sample.

+| Employee.SocialSecurityNumber | a | String | Employee's Social Security Number (SSN). | 123-45-6789 |

+ Title: "Train a custom model in the Form Recognizer Studio"

+description: Learn how to build, label, and train a custom model in the Form Recognizer Studio.

+# Build your training data set for a custom model

+Form Recognizer models require as few as five training documents to get started. If you have at least five documents, you can get started training a custom model. You can train either a [custom template model (custom form)](../concept-custom-template.md) or a [custom neural model (custom document)](../concept-custom-neural.md). The training process is identical for both models and this document walks you through the process of training either model.

+## Custom model input requirements

+First, make sure your training data set follows the input requirements for Form Recognizer.

+## Training data tips

+Follow these tips to further optimize your data set for training:

+* If possible, use text-based PDF documents instead of image-based documents. Scanned PDFs are handled as images.

+* For forms with input fields, use examples that have all of the fields completed.

+* Use forms with different values in each field.

+* If your form images are of lower quality, use a larger data set (10-15 images, for example).

+## Upload your training data

+When you've put together the set of forms or documents that you'll use for training, you'll need to upload it to an Azure blob storage container. If you don't know how to create an Azure storage account with a container, following the [Azure Storage quickstart for Azure portal](../../../storage/blobs/storage-quickstart-blobs-portal.md). You can use the free pricing tier (F0) to try the service, and upgrade later to a paid tier for production.

+## Create a project in the Form Recognizer Studio

+The Form Recognizer Studio provides and orchestrates all the API calls required to create the files required to complete your dataset and train your model.

+1. Start by navigating to the [Form Recognizer Studio](https://formrecognizer.appliedai.azure.com/studio). If this is your first time using the Studio, you'll need to [initialize it for use](../quickstarts/try-v3-form-recognizer-studio.md). Follow the [additional prerequisite for custom projects](../quickstarts/try-v3-form-recognizer-studio.md#additional-prerequisites-for-custom-projects) to configure the Studio to access your training dataset.

+1. In the Studio select the **Custom models** tile, on the custom models page and select the **Create a project** button.

+ :::image type="content" source="../media/how-to/studio-create-project.png" alt-text="Screenshot: Create a project in the Form Recognizer Studio.":::

+ 1. On the create project dialog, provide a name for your project, optionally a description, and select continue.

+ 1. On the next step in the workflow, choose or create a Form Recognizer resource before you select continue.

+ > [!IMPORTANT]

+ > Custom neural models models are only available in a few regions. If you plan on training a neural model, please select or create a resource in one of [these supported regions](https://aka.ms/fr-neural#l#supported-regions).

+ :::image type="content" source="../media/how-to/studio-select-resource.png" alt-text="Screenshot: Select the Form Recognizer resource.":::

+1. Next select the storage account where you uploaded the dataset you wish to use to train your custom model. The **Folder path** should be empty if your training documents are in the root of the container. If your documents are in a sub-folder, enter the relative path from the container root in the **Folder path** field. Once your storage account is configured, select continue.

+ :::image type="content" source="../media/how-to/studio-select-storage.png" alt-text="Screenshot: Select the storage account.":::

+1. Finally, review your project settings and select **Create Project** to create a new project. You should now be in the labeling window and see the files in your dataset listed.

+## Label your data

+In your project, your first task is to label your dataset with the fields you wish to extract.

+You'll see the files you uploaded to storage on the left of your screen, with the first file ready to be labeled.

+1. To start labeling your dataset, create your first field by selecting the plus (Γ₧ò) button on the top-right of the screen to select a field type.

+ :::image type="content" source="../media/how-to/studio-create-label.png" alt-text="Screenshot: Create a label.":::

+1. Enter a name for the field.

+1. To assign a value to the field, simply choose a word or words in the document and select the field in either the dropdown or the field list on the right navigation bar. You'll see the labeled value below the field name in the list of fields.

+1. Repeat this process for all the fields you wish to label for your dataset

+1. Label the remaining documents in your dataset by selecting each document in the document list and selecting the text to be labeled

+You now have all the documents in your dataset labeled. If you look at the storage account, you'll find a *.labels.json* and *.ocr.json* files that correspond to each document in your training dataset and an additional fields.json file. This is the training dataset that will be submitted to train the model.

+## Train your model

+With your dataset labeled, you're now ready to train your model. Select the train button in the upper-right corner.

+1. On the train model dialog, provide a unique model ID and, optionally, a description.

+1. For the build mode, select the type of model you want to train. Learn more about the [model types and capabilities](../concept-custom.md).

+ :::image type="content" source="../media/how-to/studio-train-model.png" alt-text="Screenshot: Train model dialog":::

+1. Select **Train** to initiate the training process.

+1. Template models train in a few minutes. Neural models can take up to 30 minutes to train.

+1. Navigate to the *Models* menu to view the status of the train operation.

+## Test the model

+Once the model training is complete, you can test your model by selecting the model on the models list page.

+1. Select the model and select on the **Test** button.

+1. Select the `+ Add` button to select a file to test the model.

+1. With a file selected, choose the **Analyze** button to test the model.

+1. The model results are displayed in the main window and the fields extracted are listed in the right navigation bar.

+1. Validate your model by evaluating the results for each field.

+1. The right navigation bar also has the sample code to invoke your model and the JSON results from the API.

+Congratulations you've trained a custom model in the Form Recognizer Studio! Your model is ready for use with the REST API or the SDK to analyze documents.

+## Next steps

+> [!div class="nextstepaction"]

+> [Learn about custom model types](../concept-custom.md)

+> [!div class="nextstepaction"]

+> [Learn about accuracy and confidence with custom models](../concept-accuracy-confidence.md)

+|[**Custom model (updated)**](concept-custom.md) | Extraction and analysis of data from forms and documents specific to distinct business data and use cases.<ul><li>Custom model API v3.0 supports **signature detection for custom template (custom form) models**.</br></br></li><li>Custom model API v3.0 offers a new model type **Custom Neural** or custom document to analyze unstructured documents.</li></ul>| [**Form Recognizer Studio**](https://formrecognizer.appliedai.azure.com/studio/custommodel/projects)</li><li>[**REST API**](quickstarts/try-v3-rest-api.md)</li><li>[**C# SDK**](quickstarts/try-v3-csharp-sdk.md)</li><li>[**Python SDK**](quickstarts/try-v3-python-sdk.md)</li><li>[**Java SDK**](quickstarts/try-v3-java-sdk.md)</li><li>[**JavaScript**](quickstarts/try-v3-javascript-sdk.md)</li></ul>|

+| InvalidRequest | DocumentModelLimitNeural | Account cannot create more than 10 custom neural models per month. Please contact support to request additional capacity. |

+| NotFound | OperationNotFound | The requested operation was not found. The identifier may be invalid or the operation may have expired. |

+* [**Prebuilt model**](#prebuilt-model)ΓÇöAnalyze and extract common fields from specific document types using a prebuilt model.

+ 1. Select the Browse tab and type Azure.AI.FormRecognizer.

+ 1. Choose the **Include prerelease** checkbox and select version **4.0.0-beta.3*** from the dropdown menu and install the package in your project.

+ > * You can create a new file using PowerShell.

+ > * Open a PowerShell window in your project directory by holding down the Shift key and right-clicking the folder.

+* 🆕General document—Analyze and extract text, tables, structure, key-value pairs, and named entities.

+* 🆕 W-2—Analyze and extract fields from W-2 tax documents, using a pre-trained W-2 model.

+* [🆕 **Custom neural model**](concept-custom-neural.md) or custom document model is a new custom model to extract text and selection marks from structured forms, semi-strutured and **unstructured documents**.

+* [🆕 **W-2 prebuilt model**](concept-w2.md) is a new prebuilt model to extract fields from W-2 forms for tax reporting and income verification scenarios.

+* [🆕 **Read**](concept-read.md) API extracts printed text lines, words, text locations, detected languages, and handwritten text, if detected.

+* [**General document**](concept-general-document.md) pre-trained model is now updated to support selection marks in addition to API text, tables, structure, key-value pairs, and named entities from forms and documents.

+* [**Invoice API**](language-support.md#invoice-model) Invoice prebuilt model expands support to Spanish invoices.

+Get started with the new [REST API](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-v3-0-preview-2/operations/AnalyzeDocument), [Python](quickstarts/try-v3-python-sdk.md), or [.NET](quickstarts/try-v3-csharp-sdk.md) SDK for the v3.0 preview API.

+Subdomain => Immersive Reader resource subdomain (resource 'Name' if the resource was created in the Azure portal, or 'CustomSubDomain' option if the resource was created with Azure CLI PowerShell. Check the Azure portal for the subdomain on the Endpoint in the resource Overview page, for example, 'https://[SUBDOMAIN].cognitiveservices.azure.com/')

+The following tables describe the specific permissions given to each role. This can include Actions, which give permissions, and Not Actions, which restrict them.

+|Microsoft.Automation/automationAccounts/*|Create and manage resources of all types.|

+|Microsoft.Automation/automationAccounts/*|Create and manage resources of all types|

+>[!Note]

+> We have recently made a change in the built-in Reader role permission for the Automation account. [Learn more](#reader-role-access-permissions)

+|[Microsoft.Automation](/azure/role-based-access-control/resource-provider-operations#microsoftautomation)/automationAccounts/* | Create and manage resources of all types.|

+|[Microsoft.ResourceHealth](/azure/role-based-access-control/resource-provider-operations#microsoftresourcehealth)/availabilityStatuses/read| Gets the availability statuses for all resources in the specified scope.|

+|Microsoft.Automation/automationAccounts/hybridRunbookWorkerGroups/read | Reads a Hybrid Runbook Worker Group.|

+|Microsoft.Automation/automationAccounts/jobs/output/read | Gets the output of a job.|

+|Microsoft.HybridCompute/machines/extensions/write| Installs or Updates an Azure Arc extensions.|

+## Reader role access permissions

+>[!Important]

+> To strengthen the overall Azure Automation security posture, the built-in RBAC Reader would not have access to Automation account keys through the API call - `GET /AUTOMATIONACCOUNTS/AGENTREGISTRATIONINFORMATION`.

+The Built-in Reader role for the Automation Account can't use the `API ΓÇô GET /AUTOMATIONACCOUNTS/AGENTREGISTRATIONINFORMATION` to fetch the Automation Account keys. This is a high privilege operation providing sensitive information that could pose a security risk of an unwanted malicious actor with low privileges who can get access to automation account keys and can perform actions with elevated privilege level.

+To access the `API ΓÇô GET /AUTOMATIONACCOUNTS/AGENTREGISTRATIONINFORMATION`, we recommend that you switch to the built-in roles like Owner, Contributor or Automation Contributor to access the Automation account keys. These roles, by default, will have the *listKeys* permission. As a best practice, we recommend that you create a custom role with limited permissions to access the Automation account keys. For a custom role, you need to add

+`Microsoft.Automation/automationAccounts/listKeys/action` permission to the role definition.

+[Learn more](/azure/role-based-access-control/custom-roles) about how to create custom role from the Azure portal.

+

+## Manage Role permissions for Hybrid Worker Groups and Hybrid Workers

+You can create [Azure custom roles](/azure/role-based-access-control/custom-roles) in Automation and grant the following permissions to Hybrid Worker Groups and Hybrid Workers:

+- [Extension-based Hybrid Runbook Worker](/azure/automation/extension-based-hybrid-runbook-worker-install?tabs=windows#manage-role-permissions-for-hybrid-worker-groups-and-hybrid-workers)

+- [Agent-based Windows Hybrid Runbook Worker](/azure/automation/automation-windows-hrw-install#manage-role-permissions-for-hybrid-worker-groups-and-hybrid-workers)

+ - [Agent-based Linux Hybrid Runbook Worker](/azure/automation/automation-linux-hrw-install#manage-role-permissions-for-hybrid-worker-groups-and-hybrid-workers)

+ Title: Azure Automation security guidelines

+description: This article helps you with the guidelines that Azure Automation offers to ensure data privacy and data security.

+# Best practices for security in Azure Automation

+This article details the best practices to securely execute the automation jobs.

+[Azure Automation](/azure/automation/overview) provides you the platform to orchestrate frequent, time consuming, error-prone infrastructure management and operational tasks, as well as mission-critical operations. This service allows you to execute scripts, known as automation runbooks seamlessly across cloud and hybrid environments.

+The platform components of Azure Automation Service are actively secured and hardened. The service goes through robust security and compliance checks. [Azure security benchmark](/security/benchmark/azure/overview) details the best practices and recommendations to help improve the security of workloads, data, and services on Azure. Also see [Azure security baseline for Azure Automation](/security/benchmark/azure/baselines/automation-security-baseline?toc=/azure/automation/TOC.json).

+## Secure configuration of Automation account

+This section guides you in configuring your Automation account securely.

+### Permissions

+1. Follow the principle of least privilege to get the work done when granting access to Automation resources. Implement [Automation granular RBAC roles](/azure/automation/automation-role-based-access-control) and avoid assigning broader roles or scopes such as subscription level. When creating the custom roles, only include the permissions users need. By limiting roles and scopes, you limit the resources that are at risk if the security principal is ever compromised. For detailed information on role-based access control concepts, see [Azure role-based access control best practices](/azure/role-based-access-control/best-practices).

+1. Avoid roles that include Actions having a wildcard (_*_) as it implies full access to the Automation resource or a sub-resource, for example _automationaccounts/*/read_. Instead, use specific actions only for the required permission.

+1. Configure [Role based access at a runbook level](/azure/automation/automation-role-based-access-control) if the user doesn't require access to all the runbooks in the Automation account.

+1. Limit the number of highly privileged roles such as Automation Contributor to reduce the potential for breach by a compromised owner.

+1. Use [Azure AD Privileged Identity Management](/azure/active-directory/roles/security-planning#use-azure-ad-privileged-identity-management) to protect the privileged accounts from malicious cyber-attacks to increase your visibility into their use through reports and alerts.

+### Securing Hybrid Runbook worker role

+1. Install Hybrid workers using the [Hybrid Runbook Worker VM extension](/azure/automation/extension-based-hybrid-runbook-worker-install?tabs=windows), that doesn't have any dependency on the Log Analytics agent. We recommend this platform as it leverages Azure AD based authentication.

+ [Hybrid Runbook Worker](/azure/automation/automation-hrw-run-runbooks) feature of Azure Automation allows you to execute runbooks directly on the machine hosting the role in Azure or non-Azure machine to execute Automation jobs in the local environment.

+ - Use only high privilege users or [Hybrid worker custom roles](/azure/automation/extension-based-hybrid-runbook-worker-install?tabs=windows#manage-role-permissions-for-hybrid-worker-groups) for users responsible for managing operations such as registering or unregistering Hybrid workers and hybrid groups and executing runbooks against Hybrid runbook worker groups.

+ - The same user would also require VM contributor access on the machine hosting Hybrid worker role. Since the VM contributor is a high privilege role, ensure only a limited right set of users have access to manage Hybrid works, thereby reducing the potential for breach by a compromised owner.

+ Follow the [Azure RBAC best practices](/azure/role-based-access-control/best-practices).

+1. Follow the principle of least privilege and grant only the required permissions to users for runbook execution against a Hybrid worker. Don't provide unrestricted permissions to the machine hosting the hybrid runbook worker role. In case of unrestricted access, a user with VM Contributor rights or having permissions to run commands against the hybrid worker machine can use the Automation Account Run As certificate from the hybrid worker machine and could potentially allow a malicious user access as a subscription contributor. This could jeopardize the security of your Azure environment.

+ Use [Hybrid worker custom roles](/azure/automation/extension-based-hybrid-runbook-worker-install?tabs=windows#manage-role-permissions-for-hybrid-worker-groups) for users responsible to manage Automation runbooks against Hybrid runbook workers and Hybrid runbook worker groups.

+1. [Unregister](/azure/automation/extension-based-hybrid-runbook-worker-install?tabs=windows#delete-a-hybrid-runbook-worker) any unused or non-responsive hybrid workers.

+### Authentication certificate and identities

+1. For runbook authentication, we recommend that you use [Managed identities](/azure/automation/automation-security-overview#managed-identities) instead of Run As accounts. The Run As accounts are an administrative overhead and we plan to deprecate them. A managed identity from Azure Active Directory (Azure AD) allows your runbook to easily access other Azure AD-protected resources such as Azure Key Vault. The identity is managed by the Azure platform and does not require you to provision or rotate any secrets. For more information about managed identities in Azure Automation, see [Managed identities for Azure Automation](/azure/automation/automation-security-overview#managed-identities)

+ You can authenticate an Automation account using two types of managed identities:

+ - **System-assigned identity** is tied to your application and is deleted if your app is deleted. An app can only have one system-assigned identity.

+ - **User-assigned identity** is a standalone Azure resource that can be assigned to your app. An app can have multiple user-assigned identities.

+ Follow the [Managed identity best practice recommendations](/azure/active-directory/managed-identities-azure-resources/managed-identity-best-practice-recommendations#choosing-system-or-user-assigned-managed-identities) for more details.

+1. If you use Run As accounts as the authentication mechanism for your runbooks, ensure the following:

+ - Track the service principals in your inventory. Service principals often have elevated permissions.

+ - Delete any unused Run As accounts to minimize your exposed attack surface.

+ - [Renew the Run As certificate](/azure/automation/manage-runas-account#cert-renewal) periodically.

+ - Follow the RBAC guidelines to limit the permissions assigned to Run As account using this [script](/azure/automation/manage-runas-account#limit-run-as-account-permissions). Do not assign high privilege permissions like Contributor, Owner and so on.

+1. Rotate the [Azure Automation keys](/azure/automation/automation-create-standalone-account?tabs=azureportal#manage-automation-account-keys) periodically. The key regeneration prevents future DSC or hybrid worker node registrations from using previous keys. We recommend to use the [Extension based hybrid workers](/azure/automation/automation-hybrid-runbook-worker) that use Azure AD authentication instead of Automation keys. Azure AD centralizes the control and management of identities and resource credentials.

+### Data security

+1. Secure the assets in Azure Automation including credentials, certificates, connections and encrypted variables. These assets are protected in Azure Automation using multiple levels of encryption. By default, data is encrypted with Microsoft-managed keys. For additional control over encryption keys, you can supply customer-managed keys to use for encryption of Automation assets. These keys must be present in Azure Key Vault for Automation service to be able to access the keys. See [Encryption of secure assets using customer-managed keys](/azure/automation/automation-secure-asset-encryption).

+1. Don't print any credentials or certificate details in the job output. An Automation job operator who is the low privilege user can view the sensitive information.

+1. Maintain a valid [backup of Automation](/azure/automation/automation-managing-data#data-backup) configuration like runbooks and assets ensuring backups are validated and protected to maintain business continuity after an unexpected event.

+### Network isolation

+1. Use [Azure Private Link](/azure/automation/how-to/private-link-security) to securely connect Hybrid runbook workers to Azure Automation. Azure Private Endpoint is a network interface that connects you privately and securely to a an Azure Automation service powered by Azure Private Link. Private Endpoint uses a private IP address from your Virtual Network (VNet), to effectively bring the Automation service into your VNet.

+If you want to access and manage other services privately through runbooks from Azure VNet without the need to open an outbound connection to the internet, you can execute runbooks on a Hybrid Worker that is connected to the Azure VNet.

+### Policies for Azure Automation

+Review the Azure Policy recommendations for Azure Automation and act as appropriate. See [Azure Automation policies](/azure/automation/policy-reference).

+

+## Next steps

+* To learn how to use Azure role-based access control (Azure RBAC), see [Manage role permissions and security in Azure Automation](/automation/automation-role-based-access-control).

+* For information on how Azure protects your privacy and secures your data, see [Azure Automation data security](/azure/automation/automation-managing-data).

+* To learn about configuring the Automation account to use encryption, see [Encryption of secure assets in Azure Automation](/automation/automation-secure-asset-encryption).

+## Manage Role permissions for Hybrid Worker Groups and Hybrid Workers

+You can create custom Azure Automation roles and grant following permissions to Hybrid Worker Groups and Hybrid Workers. To learn more about how to create Azure Automation custom roles, see [Azure custom roles](../role-based-access-control/custom-roles.md).

+Microsoft.Automation/automationAccounts/hybridRunbookWorkerGroups/hybridRunbookWorkers/read | Reads a Hybrid Runbook Worker.

+Microsoft.Automation/automationAccounts/hybridRunbookWorkerGroups/hybridRunbookWorkers/write | Creates a Hybrid Runbook Worker.

+Microsoft.Automation/automationAccounts/hybridRunbookWorkerGroups/hybridRunbookWorkers/move/action | Moves Hybrid Runbook Worker from one Worker Group to another.

+Microsoft.Automation/automationAccounts/hybridRunbookWorkerGroups/hybridRunbookWorkers/delete | Deletes a Hybrid Runbook Worker.

+## February 2022

+### Permissions change in the built-in Reader role for the Automation Account.

+**Type:** New change

+To strengthen the overall Azure Automation security posture, the built-in RBAC Reader role would not have access to Automation account keys through the API call - `GET /automationAccounts/agentRegistrationInformation`. Read [here](/azure/automation/automation-role-based-access-control#reader) for more information.

+ms.devlang: csharp

+ms.devlang: java

+> To create a service principal and assign roles, your account must be a member of the **Owner** or **User Access Administrator** role in the subscription that you want to use for onboarding.

+4. Assign the **Azure Connected Machine Onboarding** role to the service principal for the designated resource group or subscription. This role contains only the permissions required to onboard a machine. Note that your account must be a member of the **Owner** or **User Access Administrator** role for the subscription to which the service principal will have access. For information on how to add role assignments, see [Assign Azure roles using the Azure portal](../../role-based-access-control/role-assignments-portal.md) or [Assign Azure roles using Azure CLI](../../role-based-access-control/role-assignments-cli.md).

+ms.devlang: javascript

+ms.devlang: powershell

+ms.devlang: typescript

+ms.devlang: csharp, javascript

+ms.devlang: java

+| [Azure Scheduler](../../scheduler/index.yml) (replaced by [Azure Logic Apps](https://azure.microsoft.com/services/logic-apps/)) | &#x2705; | &#x2705; |

+| [Azure Scheduler](../../scheduler/index.yml) (replaced by [Azure Logic Apps](https://azure.microsoft.com/services/logic-apps/)) | &#x2705; | &#x2705; | &#x2705; | &#x2705; | |

+[Azure Pipelines](/azure/devops/pipelines/get-started/what-is-azure-pipelines) is used by teams to configure continuous deployment for applications hosted in Azure subscriptions. We can use this service for applications running in Azure Government by defining [service connections](/azure/devops/pipelines/library/service-endpoints) for Azure Government.

+- [ASP.NET Core app](/azure/devops/pipelines/ecosystems/dotnet-core)

+- [Node.js app with Gulp](/azure/devops/pipelines/ecosystems/javascript)

+|Static Networks, LLC|

+ Title: Migrate from Application Insights instrumentation keys to connection strings

+# Migrate from Application Insights instrumentation keys to connection strings

+This process can be [automated in your Azure deployments](../../azure-resource-manager/templates/deploy-portal.md#deploy-resources-with-arm-templates-and-azure-portal). For example, the following ARM template shows how you can automatically include the correct connection string with an App Services deployment (be sure to include any other App Settings your app requires):

+- Confirm you're using a [supported SDK version](#supported-sdk-versions). If you use Application Insights integration in another Azure product offering, check its documentation on how to properly configure a connection string.

+- Confirm you aren't setting both an instrumentation key and connection string at the same time. Instrumentation key settings should be removed from your configuration.

+- Confirm your connection string is exactly as provided in the Azure portal.

+Global ingestion sends all telemetry data to a single endpoint, no matter where this data will be stored. Regional ingestion allows you to define specific endpoints per region for data ingestion, ensuring data stays within a specific region during processing and storage.

+This article describes how to proactively monitor and control Application Insights costs.

+[Monitoring usage and estimated costs](..//usage-estimated-costs.md) describes usage and estimated costs across Azure Monitor features using [Azure Cost Management + Billing](../logs/manage-cost-storage.md#viewing-log-analytics-usage-on-your-azure-bill).

+> All prices and costs in this article are for example purposes only.

+<! App Insights monitoring features (availability, performance, usage, etc. ) Supported languages, integration with specific tools (Azure DevOps, Jira, and PagerDuty, etc.) should be documented elsewhere. (e.g. platforms.md) -->

+The pricing for [Azure Application Insights][start] is a **Pay-As-You-Go** model based on data volume ingested and optionally for longer data retention. Each Application Insights resource is charged as a separate service and contributes to the bill for your Azure subscription. Data volume is measured as the size of the uncompressed JSON data package that's received by Application Insights from your application. Data volume is measured in GB (10^9 bytes). There's no data volume charge for using the [Live Metrics Stream](./live-stream.md). On your Azure bill or in [Azure Cost Management + Billing](../logs/manage-cost-storage.md#viewing-log-analytics-usage-on-your-azure-bill), your data ingestion and data retention for a classic Application Insights resource will be reported with a meter category of **Log Analytics**.

+[Multi-step web tests](./availability-multistep.md) incur extra charges. Multi-step web tests are web tests that perform a sequence of actions. There's no separate charge for *ping tests* of a single page. Telemetry from ping tests and multi-step tests is charged the same as other telemetry from your app.

+The Application Insights option to [Enable alerting on custom metric dimensions](./pre-aggregated-metrics-log-metrics.md#custom-metrics-dimensions-and-pre-aggregation) can also increase costs because this can result in the creation of more pre-aggregation metrics. [Learn more](./pre-aggregated-metrics-log-metrics.md) about log-based and pre-aggregated metrics in Application Insights and about [pricing](https://azure.microsoft.com/pricing/details/monitor/) for Azure Monitor custom metrics.

+In the Azure Monitoring Pricing calculator for Application Insights, click to enable the **Estimate data volume based on application activity**. Here you can provide inputs about your application (requests per month and page views per month, in case you'll collect client-side telemetry), and then the calculator will tell you the median and 90th percentile amount of data collected by similar applications. These applications span the range of Application Insights configuration (e.g some have default [sampling](./sampling.md), some have no sampling etc.), so you still have the control to reduce the volume of data you ingest far below the median level using sampling.

+With the ASP.NET SDK's [adaptive sampling](sampling.md#adaptive-sampling), the data volume is adjusted automatically to keep within a specified maximum rate of traffic for default Application Insights monitoring. If the application produces a low amount of telemetry, such as when debugging or due to low usage, items won't be dropped by the sampling processor as long as volume is below the configured events per second level. For a high volume application, with the default threshold of five events per second, adaptive sampling will limit the number of daily events to 432,000. Considering a typical average event size of 1 KB, this corresponds to 13.4 GB of telemetry per 31-day month per node hosting your application since the sampling is done local to each node.

+The easiest way to see the billed usage for a single Application Insights resource, which isn't a workspace-baed resource is to go to the resource's Overview page and click **View Cost** in the upper right corner. You might need elevated access to Cost Management data ([learn more](../../cost-management-billing/costs/assign-access-acm-data.md)).

+To learn more, Azure provides a great deal of useful functionality in the [Azure Cost Management + Billing](../../cost-management-billing/costs/quick-acm-cost-analysis.md?toc=/azure/billing/TOC.json) hub. For instance, the "Cost analysis" functionality enables you to view your spends for Azure resources. Adding a filter by resource type (to microsoft.insights/components for Application Insights) will allow you to track your spending. Then for "Group by" select "Meter category" or "Meter". Application Insights billed usage for data ingestion and data retention will show up as **Log Analytics** for the Meter category since Log Analytics backend for all Azure Monitor logs.

+In the downloaded spreadsheet, you can see usage per Azure resource per day. In this Excel spreadsheet, usage from your Application Insights resources can be found by first filtering on the "Meter Category" column to show "Application Insights" and "Log Analytics", and then adding a filter on the "Instance ID" column, which is "contains microsoft.insights/components". Most Application Insights usage is reported on meters with the Meter Category of Log Analytics, since there's a single logs backend for all Azure Monitor components. Only Application Insights resources on legacy pricing tiers and multi-step web tests are reported with a Meter Category of Application Insights. The usage is shown in the "Consumed Quantity" column and the unit for each entry is shown in the "Unit of Measure" column. More details are available to help you [understand your Microsoft Azure bill](../../cost-management-billing/understand/review-individual-bill.md).

+(All prices displayed in screenshots in this article are for example purposes only. For current prices in your currency and region, see [Application Insights pricing][pricing].)

+There are two approaches to investigating data volumes for Application Insights. The first uses aggregated information in the `systemEvents` table, and the second uses the `_BilledSize` property, which is available on each ingested event. `systemEvents` won't have data size information for [workspace-based-application-insights](#data-volume-for-workspace-based-application-insights-resources).

+This query can be used in an [Azure Log Alert](../alerts/alerts-unified-log.md) to set up alerting on data volumes.

+* **Limit Ajax calls**: You can [limit the number of Ajax calls that can be reported](./javascript.md#configuration) in every page view, or switch off Ajax reporting. Disabling Ajax calls will disable [JavaScript correlation](./javascript.md#enable-correlation).

+* **Throttling**: Throttling limits the data rate to 32,000 events per second, averaged over 1 minute per instrumentation key. The volume of data that your app sends is assessed every minute. If it exceeds the per-second rate averaged over the minute, the server refuses some requests. The SDK buffers the data and then tries to resend it. It spreads out a surge over several minutes. If your app consistently sends data at more than the throttling rate, some data will be dropped. (The ASP.NET, Java, and JavaScript SDKs try to resend data this way; other SDKs might drop throttled data.) If throttling occurs, a notification warning alerts you that this has occurred.

+You can use the daily volume cap to limit the data collected. However, if the cap is met, a loss of all telemetry sent from your application for the remainder of the day occurs. It *isn't advisable* to have your application hit the daily cap. You can't track the health and performance of your application after it reaches the daily cap.

+A several-day grace period begins when the retention is lowered before the oldest data is removed.

+For early adopters of Azure Application Insights, there are still two possible pricing tiers: Basic and Enterprise. The Basic pricing tier is the same as described above and is the default tier. It includes all Enterprise tier features, at no extra cost. The Basic tier bills primarily on the volume of data that's ingested.

+The Per Node (formerly Enterprise) tier has a per-node charge, and each node receives a daily data allowance. In the Per Node pricing tier, you're charged for data ingested above the included allowance. If you're using Operations Management Suite, you should choose the Per Node tier. In April 2018, we [introduced](https://azure.microsoft.com/blog/introducing-a-new-way-to-purchase-azure-monitoring-services/) a new pricing model for Azure monitoring. This model adopts a simple "pay-as-you-go" model across the complete portfolio of monitoring services. Learn more about the [new pricing model](..//usage-estimated-costs.md).

+As described below in more detail, the legacy Enterprise (Per Node) tier combines usage from across all Application Insights resources in a subscription to calculate the number of nodes and the data overage. Due to this combination process, **usage for all Application Insights resources in a subscription are reported against just one of the resources**. This makes reconciling your [billed usage](#viewing-application-insights-usage-on-your-azure-bill) with the usage you observe for each Application Insights resource complicated.

+Customers who purchase Operations Management Suite E1 and E2 can get Application Insights Per Node as an supplemental component at no extra cost as [previously announced](/archive/blogs/msoms/azure-application-insights-enterprise-as-part-of-operations-management-suite-subscription). Specifically, each unit of Operations Management Suite E1 and E2 includes an entitlement to one node of the Application Insights Per Node tier. Each Application Insights node includes up to 200 MB of data ingested per day (separate from Log Analytics data ingestion), with 90-day data retention at no extra cost. The tier is described in more detailed later in the article.

+ * Development machines, client browsers, and mobile devices don't count as nodes.

+[Sampling](./sampling.md) in Application Insights is the recommended way to reduce telemetry traffic, data costs, and storage costs.

+## Troubleshooting

+### Unexpected usage or estimated cost

+Lower your bill with updated versions of the ASP.NET Core SDK and Worker Service SDK, which [don't collect counters by default](eventcounters.md#default-counters-collected).

+### Microsoft Q&A question page

+If you have questions about how pricing works for Application Insights, you can post a question in our [Microsoft Q&A question page](/answers/topics/azure-monitor.html).

+* [**Subscription**](https://portal.azure.com) - To use Application Insights or other Azure resources, you sign in to an Azure subscription. Every resource group belongs to one Azure subscription, where you choose your price package. If it's an organization subscription, the owner may choose the members and their access permissions.

+1. Assign the Contributor role to the Role Based Access Control.

+ For detailed steps, see [Assign Azure roles using the Azure portal](../../role-based-access-control/role-assignments-portal.md).

+| [Application Insights Snapshot Debugger](../../role-based-access-control/built-in-roles.md#application-insights-snapshot-debugger) | Gives the user permission to use Application Insights Snapshot Debugger features. This role is included in neither the Owner nor Contributor roles. |

+For more information, [connection string configuration](./java-standalone-config.md#connection-string).

+1. Assign the Debugger role to the **Application Insights Snapshot**.

+ For detailed steps, see [Assign Azure roles using the Azure portal](../../role-based-access-control/role-assignments-portal.md).

+1. Assign the **Publisher** role to the **Monitoring Metrics** scope.

+ For detailed steps, see [Assign Azure roles using the Azure portal](../../role-based-access-control/role-assignments-portal.md).

+1. Assign the Contributor role to the Log Analytics scope.

+ For detailed steps, see [Assign Azure roles using the Azure portal](../../role-based-access-control/role-assignments-portal.md).

+In all pricing tiers, an event's data size is calculated from a string representation of the properties that are stored in Log Analytics for this event, regardless of whether the data is sent from an agent or added during the ingestion process. This includes any [custom fields](custom-fields.md) that are added as data is collected and then stored in Log Analytics. Several properties common to all data types, including some [Log Analytics Standard Properties](./log-standard-columns.md), are excluded in the calculation of the event size. This includes `_ResourceId`, `_SubscriptionId`, `_ItemId`, `_IsBillable`, `_BilledSize` and `Type`. All other properties stored in Log Analytics are included in the calculation of the event size. Some data types are free from data ingestion charges altogether, for example the [AzureActivity](/azure/azure-monitor/reference/tables/azureactivity), [Heartbeat](/azure/azure-monitor/reference/tables/heartbeat), [Usage](/azure/azure-monitor/reference/tables/usage) and [Operation](/azure/azure-monitor/reference/tables/operation) types. Some solutions have more solution-specific policies about free data ingestion, for instance [Azure Migrate](https://azure.microsoft.com/pricing/details/azure-migrate/) makes dependency visualization data free for the first 180-days of a Server Assessment. To determine whether an event was excluded from billing for data ingestion, you can use the [_IsBillable](log-standard-columns.md#_isbillable) property as shown [below]Fdata-volume-for-specific-events). Usage is reported in GB (10^9 bytes).

+<a name="export-usage"></a>

+<a name="download-usage"></a>

+[Microsoft Defender for Servers (part of Defender for Cloud)](../../security-center/index.yml) billing is closely tied to Log Analytics billing. Microsoft Defender for Servers [bills by the number of monitored services](https://azure.microsoft.com/pricing/details/azure-defender/) and provides 500 MB/server/day data allocation that is applied to the following subset of [security data types](/azure/azure-monitor/reference/tables/tables-category#security) (WindowsEvent, SecurityAlert, SecurityBaseline, SecurityBaselineSummary, SecurityDetection, SecurityEvent, WindowsFirewall, MaliciousIPCommunication, LinuxAuditLog, SysmonEvent, ProtectionStatus) and the Update and UpdateSummary data types when the Update Management solution isn't running on the workspace or solution targeting is enabled ([learn more](../../security-center/security-center-pricing.md#what-data-types-are-included-in-the-500-mb-data-daily-allowance)). The count of monitored servers is calculated on an hourly granularity. The daily data allocation contributions from each monitored server are aggregated at the workspace level. If the workspace is in the legacy Per Node pricing tier, the Microsoft Defender for Cloud and Log Analytics allocations are combined and applied jointly to all billable ingested data.

+To view the daily Defender for Servers data allocations for a workspace, you need to [export your usage details](#viewing-log-analytics-usage-on-your-azure-bill), open the usage spreadsheet and filter the meter category to "Insight and Analytics". You'll then see usage with the meter name "Data Included per Node" which has a zero price per GB. The consumed quantity column will show the number of GBs of Defender for Cloud data allocation for the day. (If the workspace is in the legacy Per Node Log Analytics pricing tier, this meter will also include the data allocations from this Log Analytics pricing tier.)

+<a name="allocations"></a>

+## Viewing data allocation benefits

+To view data allocation benefits from sources such as [Microsoft Defender for Servers](https://azure.microsoft.com/pricing/details/defender-for-cloud/), [Microsoft Sentinel benefit for Microsoft 365 E5, A5, F5 and G5 customers](https://azure.microsoft.com/offers/sentinel-microsoft-365-offer/), or the [Sentinel Free Trial](https://azure.microsoft.com/pricing/details/microsoft-sentinel/), you need to [export your usage details](#viewing-log-analytics-usage-on-your-azure-bill). Open the exported usage spreadsheet and filter the "Instance ID" column to your workspace. (To select all of your workspaces in the spreadsheet, filter the Instance ID column to "contains /workspaces/".) Next, filter the ResourceRate column to show only rows where this is equal to zero. Now you will see the data allocations from these various sources.

+> [!NOTE]

+> Data allocations from Defender for Servers 500 MB/server/day will appear in rows with the meter name "Data Included per Node" and the meter category to "Insight and Analytics" (the name of a legacy offer still used with this meter.) If the workspace is in the legacy Per Node Log Analytics pricing tier, this meter will also include the data allocations from this Log Analytics pricing tier.

+Add or remove items from your **Favorites** list in the Azure portal so that you can quickly go to the services you use most often. We've already added some common services to your **Favorites** list, but you'll likely want to customize it. You're the only one who sees the changes you make to **Favorites**.

+In this example, we'll add Cost Management + Billing to the **Favorites** list.

+ :::image type="content" source="media/azure-portal-add-remove-sort-favorites/azure-portal-favorites-new-all-services.png" alt-text="Screenshot showing All services in the Azure portal menu.":::

+ :::image type="content" source="media/azure-portal-add-remove-sort-favorites/azure-portal-favorites-find-service.png" alt-text="Screenshot showing a search in All services in the Azure portal.":::

+ :::image type="content" source="media/azure-portal-add-remove-sort-favorites/azure-portal-favorites-add.png" alt-text="Screenshot showing the star icon to add a service to Favorites in the Azure portal.":::

+ :::image type="content" source="media/azure-portal-add-remove-sort-favorites/azure-portal-favorites-remove.png" alt-text="Screenshot showing how to remove a service from Favorites in the Azure portal.":::

+You can change the order in which your favorite services are listed. Just select an item, then drag and drop it to another location under **Favorites**.

+- To create a project-focused workspace, see [Create and share dashboards in the Azure portal](../azure-portal/azure-portal-dashboards.md).

+- Explore the [Azure portal how-to video series](https://www.youtube.com/playlist?list=PLLasX02E8BPBKgXP4oflOL29TtqTzwhxR).

+description: Use button to deploy remote Azure Resource Manager templates.

+# Use a deployment button to deploy remote templates

+This article describes how to use the **Deploy to Azure** button to deploy remote ARM JSON templates from a GitHub repository or an Azure storage account. You can add the button directly to the _README.md_ file in your GitHub repository. Or, you can add the button to a web page that references the repository. This method doesn't support deploying remote [Bicep files](../bicep/overview.md).

+This section shows how to get the URLs for the templates stored in GitHub and Azure storage account, and how to format the URLs.

+### Template stored in GitHub

+To create the URL for your template, start with the raw URL to the template in your GitHub repo. To see the raw URL, select **Raw**.

+If you're using [Git with Azure Repos](/azure/devops/repos/git/) instead of a GitHub repo, you can still use the **Deploy to Azure** button. Make sure your repo is public. Use the [Items operation](/rest/api/azure/devops/git/items/get) to get the template. Your request should be in the following format:

+```http

+https://dev.azure.com/{organization-name}/{project-name}/_apis/git/repositories/{repository-name}/items?scopePath={url-encoded-path}&api-version=6.0

+```

+## Template stored in Azure storage account

+The format of the URLs for the templates stored in a public container is:

+```html

+https://{storage-account-name}.blob.core.windows.net/{container-name}/{template-file-name}

+```

+For example:

+```html

+https://demostorage0215.blob.core.windows.net/democontainer/azuredeploy.json

+```

+You can secure the template with SAS token. For more information, see [How to deploy private ARM template with SAS token](./secure-template-with-sas-token.md). The following url is an example with SAS token:

+```html

+https://demostorage0215.blob.core.windows.net/privatecontainer/azuredeploy.json?sv=2019-07-07&sr=b&sig=rnI8%2FvKoCHmvmP7XvfspfyzdHjtN4GPsSqB8qMI9FAo%3D&se=2022-02-16T17%3A47%3A46Z&sp=r

+```

+## Format the URL

+Once you have the URL, you need to convert the URL to a URL-encoded value. You can use an online encoder or run a command. The following PowerShell example shows how to URL encode a value.

+ Title: Configure a custom domain for Azure SignalR Service

+description: How to configure a custom domain for Azure SignalR Service

+# Configure a custom domain for Azure SignalR Service

+In addition to the default domain provided Azure SignalR Service, you can also add custom domains.

+## Prerequisites

+* Resource must be Premium tier

+* A custom certificate matching custom domain is stored in Azure Key Vault

+## Add a custom certificate

+Before you can add a custom domain, you need add a matching custom certificate first. A custom certificate is a sub resource of your Azure SignalR Service. It references a certificate in your Azure Key Vault. For security and compliance reasons, Azure SignalR Service doesn't permanently store your certificate. Instead it fetches it from your Key Vault on the fly and keeps it in memory.

+### Step 1: Grant your Azure SignalR Service resource access to Key Vault

+Azure SignalR Service uses Managed Identity to access your Key Vault. In order to authorize, it needs to be granted permissions.

+1. In the Azure portal, go to your Azure SignalR Service resource.

+1. In the menu pane, select **Identity**.

+1. Turn on either **System assigned** or **User assigned** identity. Click **Save**.

+ :::image type="content" alt-text="Screenshot of enabling managed identity." source="media\howto-custom-domain\portal-identity.png" :::

+1. Go to your Key Vault resource.

+1. In the menu pane, select **Access configuration**. Click **Go to access policies**.

+1. Click **Create**. Select **Secret Get** permission and **Certificate Get** permission. Click **Next**.

+ :::image type="content" alt-text="Screenshot of permissions selection in Key Vault." source="media\howto-custom-domain\portal-key-vault-permissions.png" :::

+1. Search for the Azure SignalR Service resource name or the user assigned identity name. Click **Next**.

+ :::image type="content" alt-text="Screenshot of principal selection in Key Vault." source="media\howto-custom-domain\portal-key-vault-principal.png" :::

+1. Skip **Application (optional)**. Click **Next**.

+1. In **Review + create**, click **Create**.

+### Step 2: Create a custom certificate

+1. In the Azure portal, go to your Azure SignalR Service resource.

+1. In the menu pane, select **Custom domain**.

+1. Under **Custom certificate**, click **Add**.

+ :::image type="content" alt-text="Screenshot of custom certificate management." source="media\howto-custom-domain\portal-custom-certificate-management.png" :::

+1. Fill in a name for the custom certificate.

+1. Click **Select from your Key Vault** to choose a Key Vault certificate. After selection the following **Key Vault Base URI**, **Key Vault Secret Name** should be automatically filled. Alternatively you can also fill in these fields manually.

+1. Optionally, you can specify a **Key Vault Secret Version** if you want to pin the certificate to a specific version.

+1. Click **Add**.

+ :::image type="content" alt-text="Screenshot of adding a custom certificate." source="media\howto-custom-domain\portal-custom-certificate-add.png" :::

+Azure SignalR Service will then fetch the certificate and validate its content. If everything is good, the **Provisioning State** will be **Succeeded**.

+ :::image type="content" alt-text="Screenshot of an added custom certificate." source="media\howto-custom-domain\portal-custom-certificate-added.png" :::

+## Create a custom domain CNAME

+To validate the ownership of your custom domain, you need to create a CNAME record for the custom domain and point it to the default domain of Azure SignalR Service.

+For example, if your default domain is `contoso.service.signalr.net`, and your custom domain is `contoso.example.com`, you need to create a CNAME record on `example.com` like:

+```

+contoso.example.com. 0 IN CNAME contoso.service.signalr.net.

+```

+If you're using Azure DNS Zone, see [manage DNS records](../dns/dns-operations-recordsets-portal.md) for how to add a CNAME record.

+ :::image type="content" alt-text="Screenshot of adding a CNAME record in Azure DNS Zone." source="media\howto-custom-domain\portal-dns-cname.png" :::

+If you're using other DNS providers, follow provider's guide to create a CNAME record.

+## Add a custom domain

+A custom domain is another sub resource of your Azure SignalR Service. It contains all configurations for a custom domain.

+1. In the Azure portal, go to your Azure SignalR Service resource.

+1. In the menu pane, select **Custom domain**.

+1. Under **Custom domain**, click **Add**.

+ :::image type="content" alt-text="Screenshot of custom domain management." source="media\howto-custom-domain\portal-custom-domain-management.png" :::

+1. Fill in a name for the custom domain. It's the sub resource name.

+1. Fill in the domain name. It's the full domain name of your custom domain, for example, `contoso.com`.

+1. Select a custom certificate that applies to this custom domain.

+1. Click **Add**.

+ :::image type="content" alt-text="Screenshot of adding a custom domain." source="media\howto-custom-domain\portal-custom-domain-add.png" :::

+## Verify a custom domain

+You can now access your Azure SignalR Service endpoint via the custom domain. To verify it, you can access the health API.

+Here's an example using cURL:

+#### [PowerShell](#tab/azure-powershell)

+```powershell

+PS C:\> curl.exe -v https://contoso.example.com/api/health

+...

+> GET /api/health HTTP/1.1

+> Host: contoso.example.com

+< HTTP/1.1 200 OK

+...

+PS C:\>

+```

+#### [Bash](#tab/azure-bash)

+```bash

+$ curl -vvv https://contoso.example.com/api/health

+...

+* SSL certificate verify ok.

+...

+> GET /api/health HTTP/2

+> Host: contoso.example.com

+...

+< HTTP/2 200

+...

+```

+--

+It should return `200` status code without any certificate error.

+## Next steps

+ms.devlang: csharp

+ms.devlang: java

+> The machines processing import/export requests submitted through portal or PowerShell need to store the bacpac file as well as temporary files generated by Data-Tier Application Framework (DacFX). The disk space required varies significantly among DBs with same size and can take up to 3 times of the database size. Machines running the import/export request only have 450GB local disk space. As result, some requests may fail with "There is not enough space on the disk" error. In this case, the workaround is to run sqlpackage.exe on a machine with enough local disk space. When importing/exporting databases larger than 150GB, use SqlPackage to avoid this issue.

+or the PowerShell [Stop-AzSqlDatabaseActivity command](/powershell/module/az.sql/Stop-AzSqlDatabaseActivity), here an example of powershell command.

+When a blockchain network is necessary for a multiple-party business process, the ability to query the data on the blockchain without sacrificing performance is a challenge.

+2. Navigate to the configuration page of the [server](logical-servers.md) you want to protect. In the security settings, select **Microsoft Defender for Cloud**.

+3. On the **Microsoft Defender for Cloud** configuration page:

+ 1. If Microsoft Defender for SQL hasn't yet been enabled, select **Enable Microsoft Defender for SQL**.

+ 1. Select **Configure**.

+

+ :::image type="content" source="media/azure-defender-for-sql/enable-microsoft-defender-sql.png" alt-text="Enable Microsoft Defender for SQL." lightbox="media/azure-defender-for-sql/enable-microsoft-defender-sql.png":::

+

+ 1. Under **ADVANCED THREAT PROTECTION SETTINGS**, select **Add your contact details to the subscription's email settings in Defender for Cloud**.

+ :::image type="content" source="media/azure-defender-for-sql/advanced-threat-protection-add-contact-details.png" alt-text="Select link to proceed to advanced threat protection settings." lightbox="media/azure-defender-for-sql/advanced-threat-protection-add-contact-details.png":::

+

+ 1. Provide the list of emails to receive notifications upon detection of anomalous database activities in the **Additional email addresses (separated by commas)** text box.

+ 1. Optionally customize the severity of alerts that will trigger notifications to be sent under **Notification types**.

+ 1. Select **Save**.

+ :::image type="content" source="media/azure-defender-for-sql/advanced-threat-protection-configure-emails.png" alt-text="Enter emails for Advanced Threat Protection notifications." lightbox="media/azure-defender-for-sql/advanced-threat-protection-configure-emails.png":::

+

+Learn more about Advanced Threat Protection and Microsoft Defender for SQL in the following articles:

+- [Advanced Threat Protection](threat-detection-overview.md)

+- [Advanced Threat Protection in SQL Managed Instance](../managed-instance/threat-detection-configure.md)

+- [Microsoft Defender for SQL](azure-defender-for-sql.md)

+- [Auditing for Azure SQL Database and Azure Synapse Analytics](auditing-overview.md)

+- [Microsoft Defender for Cloud](../../security-center/security-center-introduction.md)

+ There are multiple ways to establish connectivity between managed instances in different virtual networks, including:

+ * [Azure ExpressRoute](../../expressroute/expressroute-howto-circuit-portal-resource-manager.md)

+ * [Virtual network peering](../../virtual-network/virtual-network-peering-overview.md)

+ * VPN gateways

+This tutorial provides steps for creating and connecting VPN gateways. If you prefer to use ExpressRoute or VNet peering, replace the gateway steps accordingly, or

+skip ahead to [Step 7](#create-a-failover-group) if you already have ExpressRoute or global VNet peering configured.

+ > - Creating a managed instance can take a significant amount of time. As a result, this tutorial may take several hours to complete. For more information on provisioning times, see [SQL Managed Instance management operations](sql-managed-instance-paas-overview.md#management-operations).

+> Azure PowerShell currently doesn't support backup policies with hourly schedule. Please use Azure Portal to leverage this feature. [Learn more](manage-afs-backup.md#create-a-new-policy)

+1. In **Restore Virtual Machine** > **Create new** > **Restore Type**, select **Create new virtual machine**.

+1. In **Restore configuration** > **Create new** > **Restore Type**, select **Create new virtual machine**.

+>- For restoring disk from a Vault-Standard recovery point that is/was greater than 4 TB, Azure Backup doesn't restore the VHD files.

+>- For information on managed/premium disk performance after restored via Azure Backup, see the [Latency](../virtual-machines/premium-storage-performance.md#latency) section.

+- After the VM is restored, learn about [managing virtual machines](backup-azure-manage-vms.md)

+After the script is successfully downloaded, make sure you have the right machine to execute this script. The VM where you are planning to execute the script, should not have any of the following unsupported configurations. **If it does, then choose an alternate machine that meets the requirements**.

+- HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Disk\TimeOutValue ΓÇô change this from 60 to 2400 secs.

+- HKEY_LOCAL_MACHINE\SYSTEM\ControlSet001\Control\Class\{4d36e97b-e325-11ce-bfc1-08002be10318}\0003\Parameters\SrbTimeoutDelta ΓÇô change this from 15 to 2400 secs.

+- HKEY_LOCAL_MACHINE\SYSTEM\ControlSet001\Control\Class\{4d36e97b-e325-11ce-bfc1-08002be10318}\0003\Parameters\MaxRequestHoldTime - change this from 60 to 2400 secs.

+> Due to a security issue related to RBAC, we had to introduce a breaking change in the restore commands for SQL DB via PowerShell. Please upgrade to Az 6.0.0 version or above for the proper restore commands to be submitted via PowerShell. The latest PS commands are provided below.

+> Support for secondary region restores for SQL from PowerShell is available from Az 6.0.0

+ Title: Restore Azure blobs via Azure PowerShell

+description: Learn how to restore Azure blobs to any point-in-time using Azure PowerShell.

+# Restore Azure blobs to point-in-time using Azure PowerShell

+ms.devlang: csharp

+ms.devlang: csharp

+> An easier and faster way of generating your ARM template and parameter file is via the [Azure portal](https://portal.azure.com). You can [download the generated ARM template](generate-template-portal.md) via the portal to create your Cloud Service via PowerShell

+As a standard practice to manage your certificates, all the valid .pfx certificate files should be added to certificate store in Key Vault and update would work perfectly fine via any client - Portal, PowerShell or Rest API.

+LUIS authoring regions are supported by the LUIS portal. To publish a LUIS app to more than one region, you need at least one predection key per region.

+LUIS has the following authoring regions available with [paired fail-over regions](../../availability-zones/cross-region-replication-azure.md):

+LUIS has one portal you can use regardless of region, [www.luis.ai](https://www.luis.ai).

+Publishing regions are the regions where the application will be used in runtime. To use the application in a publishing region, you must create a resource in this region and assign your application to it. For example, if you create an app with the *westus* authoring region and publish it to the *eastus* and *brazilsouth* regions, the app will run in those two regions.

+A public app is published in all regions so that a user with a supported predection resource can access the app in all regions.

+When you first create our LUIS application, you are required to choose an [authoring region](#luis-authoring-regions). To use the application in runtime, you are required to create a resource in a publishing region.

+Your app can only be published to one of its corresponding authoring regions, which are listed in the tables below. If your app is currently in the wrong authoring region, export the app, and import it into the correct authoring region to match the required publishing region.

+Single data residency means that the data does not leave the boundaries of the region.

+> * Make sure to set `log=false` for [V3 APIs](https://westus.dev.cognitive.microsoft.com/docs/services/luis-endpoint-api-v3-0/operations/5cb0a91e54c9db63d589f433) to disable active learning. By default this value is `false`, to ensure that data does not leave the boundaries of the runtime region.

+> * If `log=true`, data is returned to the authoring region for active learning.

+Each region has a secondary region to fail over to. Failover will only happen in the same geographical region.

+Authoring regions have [paired fail-over regions](../../availability-zones/cross-region-replication-azure.md).

+The following publishing regions do not have a failover region:

+* Brazil South

+* Southeast Asia

+### Outbound access from App Service

+The QnA Maker App Service requires outbound access to the below endpoints. Please make sure theyΓÇÖre added to the allow list if there are any restrictions on the outbound traffic.

+- https://qnamakerstore.blob.core.windows.net

+- https://qnamaker-data.trafficmanager.net

+- https://qnamakerconfigprovider.trafficmanager.net

+* To train and deploy your models, see [Train your voice model](how-to-custom-voice-create-voice.md) and [Deploy and use your voice model](how-to-deploy-and-use-endpoint.md).

+# Train your voice model

+- [Deploy and use your voice model](how-to-deploy-and-use-endpoint.md)

+- [Text-to-Speech API reference](rest-text-to-speech.md)

+- [Train your voice model](how-to-custom-voice-create-voice.md)

+- [Deploy and use your voice model](how-to-deploy-and-use-endpoint.md)

+- [Prepare data for custom neural voice](how-to-custom-voice-prepare-data.md)

+- [Train your voice model](how-to-custom-voice-create-voice.md)

+- [Deploy and use your voice model](how-to-deploy-and-use-endpoint.md)

+ Title: How to deploy and use voice model - Speech service

+description: Learn about how to deploy and use a custom neural voice model.

+# Deploy and use your voice model

+After you've successfully created and trained your voice model, you deploy it to a custom neural voice endpoint. Use the custom neural voice endpoint instead of the usual text-to-speech endpoint for requests with the REST API. Use the speech studio to create a custom neural voice endpoint. Use the REST API to suspend or resume a custom neural voice endpoint.

+## Create a custom neural voice endpoint

+To create a custom neural voice endpoint:

+1. On the **Deploy model** tab, select **Deploy model**.

+1. Enter a **Name** and **Description** for your custom endpoint.

+1. Select a voice model that you want to associate with this endpoint.

+1. Select **Deploy** to create your endpoint.

+In the endpoint table, you now see an entry for your new endpoint. It might take a few minutes to instantiate a new endpoint. When the status of the deployment is **Succeeded**, the endpoint is ready for use.

+You can suspend and resume your endpoint if you don't use it all the time. When an endpoint is reactivated after suspension, the endpoint URL is retained, so you don't need to change your code in your apps.

+You can also update the endpoint to a new model. To change the model, make sure the new model is named the same as the one you want to update.

+> [!NOTE]

+>- Standard subscription (S0) users can create up to 50 endpoints, each with its own custom neural voice.

+>- To use your custom neural voice, you must specify the voice model name, use the custom URI directly in an HTTP request, and use the same subscription to pass through the authentication of the text-to-speech service.

+After your endpoint is deployed, the endpoint name appears as a link. Select the link to display information specific to your endpoint, such as the endpoint key, endpoint URL, and sample code.

+The custom endpoint is functionally identical to the standard endpoint that's used for text-to-speech requests. For more information, see the [Speech SDK](./get-started-text-to-speech.md) or [REST API](rest-text-to-speech.md).

+[Audio Content Creation](https://speech.microsoft.com/audiocontentcreation) is a tool that allows you to fine-tune audio output by using a friendly UI.

+## Copy your voice model to another project

+You can copy your voice model to another project for the same region or another region. For example, you can copy a neural voice model that was trained in one region, to a project for another region.

+> [!NOTE]

+> Custom neural voice training is only available in the these regions: East US, Southeast Asia, and UK South. But you can copy a neural voice model from those regions to other regions. For more information, see the [regions for custom neural voice](regions.md#text-to-speech).

+To copy your custom neural voice model to another project:

+1. On the **Train model** tab, select a voice model that you want to copy, and then select **Copy to project**.

+ :::image type="content" source="media/custom-voice/cnv-model-copy.png" alt-text="Copy to project":::

+1. Select the **Region**, **Speech resource**, and **Project** where you want to copy the model. You must have a speech resource and project in the target region, otherwise you need to create them first.

+ :::image type="content" source="media/custom-voice/cnv-model-copy-dialog.png" alt-text="Copy voice model":::

+1. Select **Submit** to copy the model.

+1. Select **View model** under the notification message for copy success.

+1. On the **Train model** tab, select the newly copied model and then select **Deploy model**.

+## Suspend and resume an endpoint

+You can suspend or resume an endpoint, to limit spend and conserve resources that aren't in use. You won't be charged while the endpoint is suspended. When you resume an endpoint, you can use the same endpoint URL in your application to synthesize speech.

+You can suspend and resume an endpoint in Speech Studio or via the REST API.

+> [!NOTE]

+> The suspend operation will complete almost immediately. The resume operation completes in about the same amount of time as a new deployment.

+### Suspend and resume an endpoint in Speech Studio

+This section describes how to suspend or resume a custom neural voice endpoint in the Speech Studio portal.

+#### Suspend endpoint

+1. To suspend and deactivate your endpoint, select **Suspend** from the **Deploy model** tab in [Speech Studio](https://aka.ms/custom-voice-portal).

+ :::image type="content" source="media/custom-voice/cnv-endpoint-suspend.png" alt-text="Screenshot of the select suspend endpoint option":::

+1. In the dialog box that appears, select **Submit**. After the endpoint is suspended, Speech Studio will show the **Successfully suspended endpoint** notification.

+#### Resume endpoint

+1. To resume and activate your endpoint, select **Resume** from the **Deploy model** tab in [Speech Studio](https://aka.ms/custom-voice-portal).

+ :::image type="content" source="media/custom-voice/cnv-endpoint-resume.png" alt-text="Screenshot of the select resume endpoint option":::

+1. In the dialog box that appears, select **Submit**. After you successfully reactivate the endpoint, the status will change from **Suspended** to **Succeeded**.

+### Suspend and resume endpoint via REST API

+This section will show you how to [get](#get-endpoint), [suspend](#suspend-endpoint), or [resume](#resume-endpoint) a custom neural voice endpoint via REST API.

+#### Application settings

+The application settings that you use as REST API [request parameters](#request-parameters) are available on the **Deploy model** tab in [Speech Studio](https://aka.ms/custom-voice-portal).

+* The **Endpoint key** shows the subscription key the endpoint is associated with. Use the endpoint key as the value of your `Ocp-Apim-Subscription-Key` request header.

+* The **Endpoint URL** shows your service region. Use the value that precedes `voice.speech.microsoft.com` as your service region request parameter. For example, use `eastus` if the endpoint URL is `https://eastus.voice.speech.microsoft.com/cognitiveservices/v1`.

+* The **Endpoint URL** shows your endpoint ID. Use the value appended to the `?deploymentId=` query parameter as the value of your endpoint ID request parameter.

+* The Azure region the endpoint is associated with.

+#### Get endpoint

+Get the endpoint by endpoint ID. The operation returns details about an endpoint such as model ID, project ID, and status.

+For example, you might want to track the status progression for [suspend](#suspend-endpoint) or [resume](#resume-endpoint) operations. Use the `status` property in the response payload to determine the status of the endpoint.

+The possible `status` property values are:

+| Status | Description |

+| - | |

+| `NotStarted` | The endpoint hasn't yet been deployed, and it's not available for speech synthesis. |

+| `Running` | The endpoint is in the process of being deployed or resumed, and it's not available for speech synthesis. |

+| `Succeeded` | The endpoint is active and available for speech synthesis. The endpoint has been deployed or the resume operation succeeded. |

+| `Failed` | The endpoint deploy or suspend operation failed. The endpoint can only be viewed or deleted in [Speech Studio](https://aka.ms/custom-voice-portal).|

+| `Disabling` | The endpoint is in the process of being suspended, and it's not available for speech synthesis. |

+| `Disabled` | The endpoint is inactive, and it's not available for speech synthesis. The suspend operation succeeded or the resume operation failed. |

+> [!Tip]

+> If the status is `Failed` or `Disabled`, check `properties.error` for a detailed error message. However, there won't be error details if the status is `Disabled` due to a successful suspend operation.

+##### Get endpoint example

+For information about endpoint ID, region, and subscription key parameters, see [request parameters](#request-parameters).

+HTTP example:

+```HTTP

+GET api/texttospeech/v3.0/endpoints/<YourEndpointId> HTTP/1.1

+Ocp-Apim-Subscription-Key: YourSubscriptionKey

+Host: <YourServiceRegion>.customvoice.api.speech.microsoft.com

+```

+cURL example:

+```Console

+curl -v -X GET "https://<YourServiceRegion>.customvoice.api.speech.microsoft.com/api/texttospeech/v3.0/endpoints/<YourEndpointId>" -H "Ocp-Apim-Subscription-Key: <YourSubscriptionKey >"

+```

+Response header example:

+```

+Status code: 200 OK

+```

+Response body example:

+```json

+{

+ "model": {

+ "id": "a92aa4b5-30f5-40db-820c-d2d57353de44"

+ },

+ "project": {

+ "id": "ffc87aba-9f5f-4bfa-9923-b98186591a79"

+ },

+ "properties": {},

+ "status": "Succeeded",

+ "lastActionDateTime": "2019-01-07T11:36:07Z",

+ "id": "e7ffdf12-17c7-4421-9428-a7235931a653",

+ "createdDateTime": "2019-01-07T11:34:12Z",

+ "locale": "en-US",

+ "name": "Voice endpoint",

+ "description": "Example for voice endpoint"

+}

+```

+#### Suspend endpoint

+You can suspend an endpoint to limit spend and conserve resources that aren't in use. You won't be charged while the endpoint is suspended. When you resume an endpoint, you can use the same endpoint URL in your application to synthesize speech.

+You suspend an endpoint with its unique deployment ID. The endpoint status must be `Succeeded` before you can suspend it.

+Use the [get endpoint](#get-endpoint) operation to poll and track the status progression from `Succeeded`, to `Disabling`, and finally to `Disabled`.

+##### Suspend endpoint example

+For information about endpoint ID, region, and subscription key parameters, see [request parameters](#request-parameters).

+HTTP example:

+```HTTP

+POST api/texttospeech/v3.0/endpoints/<YourEndpointId>/suspend HTTP/1.1

+Ocp-Apim-Subscription-Key: YourSubscriptionKey

+Host: <YourServiceRegion>.customvoice.api.speech.microsoft.com

+Content-Type: application/json

+Content-Length: 0

+```

+cURL example:

+```Console

+curl -v -X POST "https://<YourServiceRegion>.customvoice.api.speech.microsoft.com/api/texttospeech/v3.0/endpoints/<YourEndpointId>/suspend" -H "Ocp-Apim-Subscription-Key: <YourSubscriptionKey >" -H "content-type: application/json" -H "content-length: 0"

+```

+Response header example:

+```

+Status code: 202 Accepted

+```

+For more information, see [response headers](#response-headers).

+#### Resume endpoint

+When you resume an endpoint, you can use the same endpoint URL that you used before it was suspended.

+You resume an endpoint with its unique deployment ID. The endpoint status must be `Disabled` before you can resume it.

+Use the [get endpoint](#get-endpoint) operation to poll and track the status progression from `Disabled`, to `Running`, and finally to `Succeeded`. If the resume operation failed, the endpoint status will be `Disabled`.

+##### Resume endpoint example

+For information about endpoint ID, region, and subscription key parameters, see [request parameters](#request-parameters).

+HTTP example:

+```HTTP

+POST api/texttospeech/v3.0/endpoints/<YourEndpointId>/resume HTTP/1.1

+Ocp-Apim-Subscription-Key: YourSubscriptionKey

+Host: <YourServiceRegion>.customvoice.api.speech.microsoft.com

+Content-Type: application/json

+Content-Length: 0

+```

+cURL example:

+```Console

+curl -v -X POST "https://<YourServiceRegion>.customvoice.api.speech.microsoft.com/api/texttospeech/v3.0/endpoints/<YourEndpointId>/resume" -H "Ocp-Apim-Subscription-Key: <YourSubscriptionKey >" -H "content-type: application/json" -H "content-length: 0"

+```

+Response header example:

+```

+Status code: 202 Accepted

+```

+For more information, see [response headers](#response-headers).

+#### Parameters and response codes

+##### Request parameters

+You use these request parameters with calls to the REST API. See [application settings](#application-settings) for information about where to get your region, endpoint ID, and subscription key in Speech Studio.

+| Name | Location | Required | Type | Description |

+| | | -- | | |

+| `YourServiceRegion` | Path | `True` | string | The Azure region the endpoint is associated with. |

+| `YourEndpointId` | Path | `True` | string | The identifier of the endpoint. |

+| `Ocp-Apim-Subscription-Key` | Header | `True` | string | The subscription key the endpoint is associated with. |

+##### Response headers

+Status code: 202 Accepted

+| Name | Type | Description |

+| - | | -- |

+| `Location` | string | The location of the endpoint that can be used as the full URL to get endpoint. |

+| `Retry-After` | string | The total seconds of recommended interval to retry to get endpoint status. |

+##### HTTP status codes

+The HTTP status code for each response indicates success or common errors.

+| HTTP status code | Description | Possible reason |

+| - | -- | |

+| 200 | OK | The request was successful. |

+| 202 | Accepted | The request has been accepted and is being processed. |

+| 400 | Bad Request | The value of a parameter is invalid, or a required parameter is missing, empty, or null. One common issue is a header that is too long. |

+| 401 | Unauthorized | The request isn't authorized. Check to make sure your subscription key or [token](rest-speech-to-text.md#authentication) is valid and in the correct region. |

+| 429 | Too Many Requests | You've exceeded the quota or rate of requests allowed for your subscription. |

+| 502 | Bad Gateway | Network or server-side issue. May also indicate invalid headers. |

+## Next steps

+- [How to record voice samples](record-custom-voice-samples.md)

+- [Text-to-Speech API reference](rest-text-to-speech.md)

+- [Long Audio API](long-audio-api.md)

+Finally, create the *transcript* that associates each WAV file with a text version of the corresponding utterance. [Train your voice model](./how-to-custom-voice-create-voice.md) includes details of the required format. You can copy the text directly from your script. Then create a Zip file of the WAV files and the text transcript.

+> [Train your voice model](./how-to-custom-voice-create-voice.md)

+|`style="envious"`|Express a tone of admiration when you desire something that someone else has.|

+|`style="narration-relaxed"`|Express a soothing and melodious tone for content reading.|

+ "trainedModelLabel": "{MODEL-NAME}",

+ "deploymentName": {DEPLOYMENT-NAME}

+ "trainedModelLabel": "{MODEL-NAME}",

+ "deploymentName": "{DEPLOYMENT-NAME}"

+ "trainedModelLabel": "{MODEL-NAME}",

+ "deploymentName": "{DEPLOYMENT-NAME}"

+## Text Analytics for health features

+Text Analytics for health extracts and labels relevant medical information from unstructured texts such as doctor's notes, discharge summaries, clinical documents, and electronic health records.

+> [!VIDEO https://docs.microsoft.com/Shows/AI-Show/Introducing-Text-Analytics-for-Health/player]

+## Get started with Text analytics for health

+To use this feature, you submit raw unstructured text for analysis and handle the API output in your application. Analysis is performed as-is, with no additional customization to the model used on your data. There are three ways to use Text Analytics for health:

+|Development option |Description | Links |

+||||

+| Language Studio | A web-based platform that enables you to try Text Analytics for health without needing writing code. | ΓÇó [Language Studio website](https://language.cognitive.azure.com/tryout/healthAnalysis) <br> ΓÇó [Quickstart: Use the Language studio](../language-studio.md) |

+| REST API or Client library (Azure SDK) | Integrate Text Analytics for health into your applications using the REST API, or the client library available in a variety of languages. | ΓÇó [Quickstart: Use Text Analytics for health](quickstart.md) |

+| Docker container | Use the available Docker container to deploy this feature on-premises, letting you bring the service closer to your data for compliance, security, or other operational reasons. | ΓÇó [How to deploy on-premises](how-to/use-containers.md) |

+## Input requirements and service limits

+* Text Analytics for health takes raw unstructured text for analysis. See the [data and service limits](how-to/call-api.md#data-limits) in the how-to guide for more information.

+* Text Analytics for health works with a variety of written languages. See [language support](language-support.md) for more information.

+## Reference documentation and code samples

+As you use Text Analytics for health in your applications, see the following reference documentation and samples for Azure Cognitive Services for Language:

+|Development option / language |Reference documentation |Samples |

+||||

+|REST API | [REST API documentation](https://westus2.dev.cognitive.microsoft.com/docs/services/TextAnalytics-v3-2-Preview-2/operations/Analyze) | |

+|C# | [C# documentation](/dotnet/api/azure.ai.textanalytics?view=azure-dotnet-preview&preserve-view=true) | [C# samples](https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/textanalytics/Azure.AI.TextAnalytics/samples) |

+| Java | [Java documentation](/java/api/overview/azure/ai-textanalytics-readme?view=azure-java-preview&preserve-view=true) | [Java Samples](https://github.com/Azure/azure-sdk-for-java/tree/main/sdk/textanalytics/azure-ai-textanalytics/src/samples) |

+|JavaScript | [JavaScript documentation](/javascript/api/overview/azure/ai-text-analytics-readme?view=azure-node-preview&preserve-view=true) | [JavaScript samples](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/textanalytics/ai-text-analytics/samples/v5) |

+|Python | [Python documentation](/python/api/overview/azure/ai-textanalytics-readme?view=azure-python-preview&preserve-view=true) | [Python samples](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/textanalytics/azure-ai-textanalytics/samples) |

+> [!NOTE]

+> Azure Container Apps resources are in the process of migrating from the `Microsoft.Web` namespace to the `Microsoft.App` namespace. Refer to [Namespace migration from Microsoft.Web to Microsoft.App in March 2022](https://github.com/microsoft/azure-container-apps/issues/109) for more details.

+> [!NOTE]

+> Azure Container Apps resources are in the process of migrating from the `Microsoft.Web` namespace to the `Microsoft.App` namespace. Refer to [Namespace migration from Microsoft.Web to Microsoft.App in March 2022](https://github.com/microsoft/azure-container-apps/issues/109) for more details.

+| Environments per region | 2 |

+ms.devlang: csharp

+Azure Cosmos DB allows you to isolate and restrict the restore permissions for continuous backup account to a specific role or a principal. The owner of the account can trigger a restore and assign a role to other principals to perform the restore operation. These permissions can be applied at the subscription scope as shown in the following image:

+## Permissions on the source account

+> Assigning permissions at resource group scope is not supported.

+|Permission |Impact |

+|||

+|`Microsoft.DocumentDB/locations/restorableDatabaseAccounts/restore/action` </br> You can't choose resource group as the permission scope. |This permission is required on the source restorable database account scope to allow restore actions to be performed on it. |

+|`Microsoft.DocumentDB/locations/restorableDatabaseAccounts/read` </br> You can't choose resource group as the permission scope. |This permission is required on the source restorable database account scope to list the database accounts that can be restored. |

+|`Microsoft.DocumentDB/locations/restorableDatabaseAccounts/*/read` </br> You can't choose resource group as the permission scope. | This permission is required on the source restorable account scope to allow reading of restorable resources such as list of databases and containers for a restorable account. |

+## Permissions on the destination account

+Following permissions are required to perform the different activities pertaining to restore for continuous backup mode accounts:

+

+|Permission |Impact |

+|||

+|`Microsoft.Resources/deployments/validate/action`, `Microsoft.Resources/deployments/write` | These permissions are required for the ARM template deployment to create the restored account. See the sample permission [RestorableAction](#custom-restorable-action) below for how to set this role.

+|`Microsoft.DocumentDB/databaseAccounts/write` | This permission is required to restore an account into a resource group |

+

+ms.devlang: csharp

+For these queries to work, you must have an Azure Cosmos DB account and have graph data in the container. Don't have any of those? Complete the [5-minute quickstart](create-graph-dotnet.md) to create an account and populate your database. You can run the following queries using the [Gremlin console](https://tinkerpop.apache.org/docs/current/reference/#gremlin-console), or your favorite Gremlin driver.

+To build a solution with high-availability, you have to evaluate the reliability characteristics of all its components. Cosmos DB is designed to provide multiple features and configuration options to achieve high availability for all solutions' availability needs.

+We'll use the terms **RTO** (Recovery Time Objective), to indicate the time between the beginning of an outage impacting Cosmos DB and the recovery to full availability, and **RPO** (Recovery Point Objective), to indicate the time between the last write correctly restored and the time of the beginning of the outage affecting Cosmos DB.

+Cosmos DB is a managed multi-tenant service that manages all details of individual compute nodes transparently. Users don't have to worry about any kind of patching and planned maintenance. Cosmos DB guarantees SLAs for availability and P99 latency through all automatic maintenance operations performed by the system.

+Cosmos DB automatically mitigates replica outages by guaranteeing at least three replicas of your data in each Azure region for your account within a four replica quorum.

+This results in RTO = 0 and RPO = 0, for individual node outages, with no application changes or configurations required.

+In many Azure regions, it's possible to distribute your Cosmos DB cluster across **availability zones**, which results increased SLAs, as availability zones are physically separate and provide distinct power source, network, and cooling. See [Availability Zones](/azure/architecture/reliability/architect).

+When a Cosmos DB account is deployed using availability zones, Cosmos DB provides RTO = 0 and RPO = 0 even in a zone outage.

+When users deploy in a single Azure region, with no extra user input, Cosmos DB is resilient to node outages. Enabling redundancy across availability zones makes Cosmos DB resilient to zone outages at the cost of increased charges. Both SLAs and price are reported in the [SLAs section](#slas).

+Zone redundancy can only be configured when adding a new region to an Azure Cosmos account. For existing regions, zone redundancy can be enabled by removing the region then adding it back with the zone redundancy enabled. For a single region account, this requires adding a region to temporarily fail over to, then removing and adding the desired region with zone redundancy enabled.

+By default, a Cosmos DB account doesn't use multiple availability zones. You can enable deployment across multiple availability zones in the following ways:

+When a Cosmos DB account is deployed in a single region, generally no data loss occurs and data access is restored after Cosmos DB services recovers in the affected region. Data loss may occur only with an unrecoverable disaster in the Cosmos DB region.

+When a Cosmos DB account is deployed in multiple regions, data durability depends on the consistency level configured on the account. The following table details, for all consistency levels, the RPO of Cosmos DB account deployed in at least 2 regions.

+If your solution requires continuous availability during region outages, Cosmos DB can be configured to replicate your data across multiple regions and to transparently fail over to available regions when required.

+Service-managed failover allows Cosmos DB to fail over the write region of multi-region account, in order to preserve availability at the cost of data loss as per [durability section](#durability). Regional failovers are detected and handled in the Azure Cosmos DB client. They don't require any changes from the application.

+Azure Cosmos DB can be configured to accept writes in multiple regions. This is useful to reduce write latency in geographically distributed applications. When a Cosmos DB account is configured for multiple write regions, strong consistency isn't supported and write conflicts may arise. Refer to [Conflict types and resolution policies when using multiple write regions](./conflict-resolution-policies.md) for more information on how to resolve conflicts in multiple write region configurations.

+Given the internal Azure Cosmos DB architecture, using multiple write regions doesn't guarantee write availability during a region outage. The best configuration to achieve high availability during a region outage is single write region with service-managed failover.

+When a Cosmos DB account is configured with multi-region writes, one of the regions will act as an arbiter in case of write conflicts. When such conflicts happen, they're routed to this region for consistent resolution.

+| Single write region | Write region outage | Clients will redirect reads to other regions. <p/> **Without service-manages failover**, clients will experience write availability loss, until write availability is restored automatically when the outage ends. <p/> **With service-managed failover** clients will experience write availability loss until the services manages a failover to a new write region selected according to your preferences. | If strong consistency level isn't selected, some data may not have been replicated to the remaining active regions. This depends on the consistency level selected as described in [this section](consistency-levels.md#rto). If the affected region suffers permanent data loss, unreplicated data may be lost. | During the outage, ensure that there are enough provisioned RUs in the remaining regions to support read traffic. <p/> Do *not* trigger a manual failover during the outage, as it will not succeed. <p/> When the outage is over, re-adjust provisioned RUs as appropriate. Accounts using SQL APIs may also recover the non-replicated data in the failed region from your [conflicts feed](how-to-manage-conflicts.md#read-from-conflict-feed). |

+* Even in a rare and unfortunate event when the Azure region is permanently irrecoverable, there's no data loss if your multi-region Azure Cosmos account is configured with *Strong* consistency. In the rare event of a permanently irrecoverable write region, a multi-region Azure Cosmos account has the durability characteristics specified in the [Durability](#durability) section.

+* Note that manual failover shouldn't be triggered and will not succeed in presence of an outage of the source or destination region. This is because of a consistency check required by the failover procedure which requires connectivity between the regions.

+* When the previously impacted region is back online, any write data that wasn't replicated when the region failed, is made available through the [conflicts feed](how-to-manage-conflicts.md#read-from-conflict-feed). Applications can read the conflicts feed, resolve the conflicts based on the application-specific logic, and write the updated data back to the Azure Cosmos container as appropriate.

+* To ensure high write and read availability, configure your Azure Cosmos account to span at least two regions and three, if using strong consistency. Remember that the best configuration to achieve high availability for a region outage is single write region with service-managed failover. To learn more, see how to [configure your Azure Cosmos account with multiple write-regions](tutorial-global-distribution-sql-api.md).

+* For multi-region Azure Cosmos accounts that are configured with a single-write region, [enable service-managed failover by using Azure CLI or Azure portal](how-to-manage-database-account.md#automatic-failover). After you enable automatic failover, whenever there's a regional disaster, Cosmos DB will fail over your account without any user inputs.

+* Within a globally distributed database environment, there's a direct relationship between the consistency level and data durability in the presence of a region-wide outage. As you develop your business continuity plan, you need to understand the maximum acceptable time before the application fully recovers after a disruptive event. The time required for an application to fully recover is known as recovery time objective (RTO). You also need to understand the maximum period of recent data updates the application can tolerate losing when recovering after a disruptive event. The time period of updates that you might afford to lose is known as recovery point objective (RPO). To see the RPO and RTO for Azure Cosmos DB, see [Consistency levels and data durability](./consistency-levels.md#rto)

+| Single write region | Not enabled | In case of outage in a read region when not using strong consistency, all clients will redirect to other regions. No read or write availability loss. No data loss. When using strong consistency, read region outage can impact write availability if fewer than two read regions remaining.<p/> In case of an outage in the write region, clients will experience write availability loss. If strong consistency level isn't selected, some data may not have been replicated to the remaining active regions. This depends on the consistency level selected as described in [this section](consistency-levels.md#rto). If the affected region suffers permanent data loss, unreplicated data may be lost. <p/> Cosmos DB will restore write availability automatically when the outage ends. | During the outage, ensure that there are enough provisioned RUs in the remaining regions to support read traffic. <p/> Do *not* trigger a manual failover during the outage, as it will not succeed. <p/> When the outage is over, re-adjust provisioned RUs as appropriate. |

+| Single write region | Enabled | In case of outage in a read region when not using strong consistency, all clients will redirect to other regions. No read or write availability loss. No data loss. When using strong consistency, read region outage can impact write availability if fewer than two read regions remaining.<p/> In case of an outage in the write region, clients will experience write availability loss until Cosmos DB automatically elects a new region as the new write region according to your preferences. If strong consistency level isn't selected, some data may not have been replicated to the remaining active regions. This depends on the consistency level selected as described in [this section](consistency-levels.md#rto). If the affected region suffers permanent data loss, unreplicated data may be lost. | During the outage, ensure that there are enough provisioned RUs in the remaining regions to support read traffic. <p/> Do *not* trigger a manual failover during the outage, as it will not succeed. <p/> When the outage is over, you may move the write region back to the original region, and re-adjust provisioned RUs as appropriate. Accounts using SQL APIs may also recover the non-replicated data in the failed region from your [conflicts feed](how-to-manage-conflicts.md#read-from-conflict-feed). |

+| Multiple write regions | Not applicable | Recently updated data in the failed region may be unavailable in the remaining active regions. Eventual, consistent prefix, and session consistency levels guarantee a staleness of <15mins. Bounded staleness guarantees less than K updates or T seconds, depending on the configuration. If the affected region suffers permanent data loss, unreplicated data may be lost. | During the outage, ensure that there are enough provisioned RUs in the remaining regions to support additional traffic. <p/> When the outage is over, you may re-adjust provisioned RUs as appropriate. If possible, Cosmos DB will automatically recover non-replicated data in the failed region using the configured conflict resolution method for SQL API accounts, and Last Write Wins for accounts using other APIs. |

+ :::image type="content" source="./media/how-to-setup-rbac/concepts.svg" alt-text="RBAC concepts":::

+| `Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/upsert` | "Upsert" an item, which means to create or insert an item if it doesn't already exist, or to update or replace an item if it exists. |

+Azure Cosmos DB exposes two built-in role definitions:

+To use the Azure Cosmos DB RBAC in your application, you have to update the way you initialize the Azure Cosmos DB SDK. Instead of passing your account's primary key, you have to pass an instance of a `TokenCredential` class. This instance provides the Azure Cosmos DB SDK with the context required to fetch an Azure AD (AAD) token on behalf of the identity you wish to use.

+The way you create a `TokenCredential` instance is beyond the scope of this article. There are many ways to create such an instance depending on the type of Azure AD identity you want to use (user principal, service principal, group etc.). Most importantly, your `TokenCredential` instance must resolve to the identity (principal ID) that you've assigned your roles to. You can find examples of creating a `TokenCredential` class:

+When using the Azure Cosmos DB RBAC, [diagnostic logs](cosmosdb-monitor-resource-logs.md) get augmented with identity and authorization information for each data operation. This lets you perform detailed auditing and retrieve the Azure AD identity used for every data request sent to your Azure Cosmos DB account.

+- `aadPrincipalId_g` shows the principal ID of the Azure AD identity that was used to authenticate the request.

+### Use Azure Resource Manager templates

+ms.devlang: javascript

+MongoShell example:

+```

+ms.devlang: javascript

+Example - Normalized utilization is defined as the max of the RU/s utilization across all partition key ranges. For example, suppose your max throughput is 24,000 RU/s and you have three partition key ranges, P_1, P_2, and P_3 each capable of scaling to 8,000 RU/s. In a given second, if P_1 has used 6000 RUs, P_2 7000 RUs, and P_3 5000 RUs the normalized utilization is MAX(6000 RU / 8000 RU, 7000 RU / 8000 RU, 5000 RU / 8000 RU) = 0.875.

+Each physical partition consists of a set of replicas, also referred to as a [*replica set*](global-dist-under-the-hood.md). Each replica hosts an instance of the database engine. A replica set makes the data stored within the physical partition durable, highly available, and consistent. Each replica that makes up the physical partition inherits the partition's storage quota. All replicas of a physical partition collectively support the throughput that's allocated to the physical partition. Azure Cosmos DB automatically manages replica sets.

+ms.devlang: csharp

+ms.devlang: csharp

+One of the consistency levels in Azure Cosmos DB is *Session* consistency. This is the default level applied to Cosmos accounts by default. When working with Session consistency, each new write request to Azure Cosmos DB is assigned a new SessionToken. The CosmosClient will use this token internally with each read/query request to ensure that the set consistency level is maintained.

+In some scenarios you need to manage this Session yourself. Consider a web application with multiple nodes, each node will have its own instance of CosmosClient. If you wanted these nodes to participate in the same session (to be able read your own writes consistently across web tiers) you would have to send the SessionToken from FeedResponse<T> of the write action to the end-user using a cookie or some other mechanism, and have that token flow back to the web tier and ultimately the CosmosClient for subsequent reads. If you are using a round-robin load balancer which does not maintain session affinity between requests, such as the Azure Load Balancer, the read could potentially land on a different node to the write request, where the session was created.

+If you do not flow the Azure Cosmos DB SessionToken across as described above you could end up with inconsistent read results for a period of time.

+## Metadata operations

+Do not verify a Database and/or Container exists by calling `Create...IfNotExistsAsync` and/or `Read...Async` in the hot path and/or before doing an item operation. The validation should only be done on application startup when it is necessary, if you expect them to be deleted (otherwise it's not needed). These metadata operations will generate extra end-to-end latency, have no SLA, and their own separate [limitations](https://aka.ms/CosmosDB/sql/errors/metadata-429) that do not scale like data operations.

+ms.devlang: java

+ms.devlang: csharp

+Amortized cost breaks down reservation purchases into daily chunks and spreads them over the duration of the reservation term. Most reservation terms are one or three years. Let's look at a one-year reservation example. Instead of seeing a $365 purchase on January 1, you'll see a $1.00 purchase every day from January 1 to December 31. In addition to basic amortization, these costs are also reallocated and associated by using the specific resources that used the reservation. For example, if that $1.00 daily charge was split between two virtual machines, you'd see two $0.50 charges for the day. If part of the reservation isn't utilized for the day, you'd see one $0.50 charge associated with the applicable virtual machine and another $0.50 charge with a charge type of `UnusedReservation`. Unused reservation costs can be seen only when viewing amortized cost.

+If you buy a one-year reservation on May 26 with an upfront payment, the amortized cost is divided by 365 (assuming it's not a leap year) and spread from May 26 through May 25 of the next year. If you pay monthly, the monthly fee is divided by the number of days in that month and spread evenly across May 26 through June 25, with the next month's fee spread across June 26 through July 25.

+For most subscriptions you can download your invoice from the Azure portal. If you have a Microsoft Customer Agreement, see [Download invoices for a Microsoft Customer Agreement](#download-invoices-for-a-microsoft-customer-agreement).

+If you don't see an invoice for the last billing period, see the following section.

+## Azure Government support for invoices

+Azure Government users use the same agreement types as other Azure users.

+Azure Government billing billing owners can opt in to receive invoices by email. However, they can't allow others to get invoices by email.

+To download your invoice, follow the steps above at [Download invoices for an individual subscription](#download-invoices-for-an-individual-subscription).

+You may want to share the invoice for your subscription and support plan every month with your accounting team or send them to one of your other email addresses.

+## Azure Government support for invoices

+Azure Government users use the same agreement types as other Azure users.

+Azure Government billing billing owners can opt in to receive invoices by email. However, they can't allow others to get invoices by email.

+To download your invoice, follow the steps above at [Download your MOSP Azure subscription invoice](#download-your-mosp-azure-subscription-invoice).

+This article helps you get started adopting **Azure Data Catalog** in your organization. To successfully adopt **Azure Data Catalog**, focus on three key items: define your vision, identify key business use cases within your organization, and choose a pilot project.

+An **Azure Data Catalog** adoption plan describes how the benefits of using the service are communicated to stakeholders and users, and what kind of training you provide to users. One key success driver to adopt Data Catalog is how effectively you communicate the value of the service to users and stakeholders. The primary audiences in an initial adoption plan are the users of the service. No matter how much buy-in you get from stakeholders, if the users, or customers, of your Data Catalog offering don't incorporate it into their usage, the adoption won't be successful. Therefore, this article assumes you have stakeholder buy-in, and focuses on creating a plan for user adoption of Data Catalog.

+* **Vision Statement** - It helps concisely discuss the adoption plan with users, and stakeholders. It's your elevator pitch.

+Here are some tips to help you define your vision:

+Here's an example vision statement for a Data Catalog adoption plan for the fictitious company called Adventure Works:

+It's best to choose use cases that represent low hanging fruit: cases that are important yet have a high likelihood of success if solved with Data Catalog.

+* **Understand team culture related to change** - Many adoption challenges relate to resistance to change rather than the implementation of a new tool. How a team responds to change is important when identifying use cases since the existing process could be in place because "this is how we've always done it" or "if it isn't broken, why fix it?". Adopting any new tool or process is always easiest when the people affected understand the value to be realized from the change, and appreciate the importance of the problems to be solved.

+* **Keep focus related to data assets** - When discussing the business problems a team faces, you need to "cut through the weeds", and focus on what's relevant to using enterprise data assets more effectively.

+A key success factor is to simplify, and start small. A well-defined pilot with a constrained scope helps keep the project moving forward without getting bogged down with a project that is too complex, or which has too many participants. But it's also important to include a mix of users, from early adopters to skeptics. Users who embrace the solution help you refine your future communication and buzz plan. Skeptics help you identify and address blocking issues. As skeptics become champions, you can use their feedback to identify success drivers.

+One of the business problems that **Azure Data Catalog** solves is to connect **Data Producers** to **Data Consumers**. It does so by serving as a central repository for information about enterprise data sources. David registers Adventure Works and SQL Server data sources in Data Catalog. Using crowdsourcing any user who discovers this data source can share her opinions on the data, in addition to using the data they've discovered. For example, Nancy discovers the data sources by searching the catalog, and shares her specialized knowledge about the data. Now, others in the organization benefit from shared knowledge by searching the data catalog.

+Once you have identified and registered key data sources, it's possible to also import data source descriptions stored in other locations. The Data Catalog API allows developers to load descriptions and annotations from another location, such as the Excel Workbook that David created and maintains.

+At this point you have identified use cases for Data Catalog, and you've identified your first project. In addition, you've registered the key Adventure Works data sources and have added information from the existing Excel workbook using the tool that IT built. Now it's time to work with the pilot team to start the Data Catalog adoption process.

+* **Target training** - Business users don't need to know everything about Data Catalog, so target training to address specific team goals. Focus on what users do, and how some of their tasks might change, to incorporate **Azure Data Catalog** into their daily routine.

+Setting expectations and goals helps business users focus on specific deliverables. To keep the project on track, assign regular (for example: daily or weekly based on the scope and duration of the pilot) homework assignments. One of the most valuable capabilities of Data Catalog is crowdsourcing data assets so that business users can benefit from knowledge of enterprise data. A great homework assignment is for each pilot team member to register or annotate at least one data source they've used. See [Register a data source](data-catalog-get-started.md) and [How to annotate data sources](data-catalog-get-started.md).

+And, the ultimate test of the project is whether users can discover and understand the data sources they need to use. Pilot users should regularly test the catalog to ensure that the data sources they use for their day to day work are relevant. When a required data source is missing or not properly annotated, this should serve as a reminder to register more data sources or to provide more annotations. This practice doesn't only add value to the pilot effort but also builds effective habits that carry over to other teams after the pilot is complete.

+Once your pilot team is running fairly smoothly and you've achieved your initial goals, you should expand Data Catalog adoption to more teams. Apply and refine what you learned from your pilot project to expand Data Catalog throughout your organization.

+The early adopters who participated in the pilot can be helpful to communicate about the benefits of adopting Data Catalog. They can share with other teams how Data Catalog helped their team solve business problems, discover data sources more easily, and share insights about the data sources they use. For example, early adopters on the Adventure Works pilot team could show others how easy it's to find information about Adventure Works data assets that were once hard to find and understand.

+## Key concepts

+A **Catalog** is the top-level container for all the metadata that an organization stores. There's one **Catalog** allowed per Azure Account. Catalogs are tied to an Azure subscription, but only one **Catalog** can be created for any given Azure account, even though an account can have multiple subscriptions.

+**Users** are security principals that have permissions to perform actions (search the catalog, add, edit or remove items, etc.) in the Catalog.

+An **Asset** is the thing you add or remove from a Catalog. It's the unit of result you get back from **Search**.

+**Annotations** are items that represent metadata about Assets.

+A key aspect of Azure Data Catalog is how it supports the crowdsourcing of metadata in the system. As opposed to a wiki approach ΓÇô where there's only one opinion and the last writer wins ΓÇô the Azure Data Catalog model allows multiple opinions to live side by side in the system.

+|Property name |Data type |Comments|

+|-|--||

+|timestamp |DateTime |The last time the item was modified. This field is generated by the server when an item is inserted and every time an item is updated. The value of this property is ignored on input of publish operations. |

+|ID|Uri |Absolute url of the item (read-only). It's the unique addressable URI for the item. The value of this property is ignored on input of publish operations.|

+|type|String |The type of the asset (read-only).|

+|etag|String< |A string corresponding to the version of the item that can be used for optimistic concurrency control when performing operations that update items in the catalog. "*" can be used to match any value.|

+|Property name |Data type |Comments|

+|-|--||

+|fromSourceSystem |Boolean |Indicates whether item's data is derived from a source system (like SQL Server Database, Oracle Database) or authored by a user. |

+|Property name |Data type |Comments|

+|-|--||

+|name |String |A name derived from the data source location information |

+|dsl |DataSourceLocation |Uniquely describes the data source and is one of the identifiers for the asset. (See dual identity section). The structure of the dsl varies by the protocol and source type. |

+|dataSource |DataSourceInfo |More detail on the type of asset. |

+|lastRegisteredBy |SecurityPrincipal |Describes the user who most recently registered this asset. Contains both the unique ID for the user (the upn) and a display name (lastName and firstName). |

+|containerID |String |ID of the container asset for the data source. This property isn't supported for the Container type. |

+|Property name |Data type |Comments|

+|-|--||

+|key |String |A user specified key, which uniquely identifies the annotation in the current collection. The key length canΓÇÖt exceed 256 characters. |

+Root asset types are those types that represent the various types of data assets that can be registered in the catalog. For each root type, there's a view, which describes asset and annotations included in the view. View name should be used in the corresponding {view_name} url segment when publishing an asset using REST API.

+|Asset type (view name) |Additional properties |Data type|Allowed annotations|Comments|

+|-|--||||

+|Table ("tables") | ||Description|A Table represents any tabular data. For example: SQL Table, SQL View, Analysis Services Tabular Table, Analysis Services Multidimensional dimension, Oracle Table, etc.|

+||||FriendlyName||

+||||Tag||

+||||Schema||

+||||ColumnDescription||

+||||ColumnTag||

+||||Expert||

+||||Preview||

+||||AccessInstruction||

+||||TableDataProfile||

+||||ColumnDataProfile||

+||||ColumnDataClassification||

+||||Documentation||

+|Measure ("measures") |||Description|This type represents an Analysis Services measure.|

+||||FriendlyName||

+||||Tag||

+||||Expert||

+||||AccessInstruction||

+||||Documentation||

+||measure|Column||Metadata describing the measure.|

+||isCalculated |Boolean||Specifies if the measure is calculated or not.|

+||measureGroup |String||Specifies if the measure is calculated or not.|

+|KPI ("kpis") |||Description||

+||||FriendlyName||

+||||Tag||

+||||Expert||

+||||AccessInstruction||

+||||Documentation||

+||measureGroup|String||Physical container for measure.|

+||goalExpression|String||An MDX numeric expression or a calculation that returns the target value of the KPI.|

+||valueExpression|String||An MDX numeric expression that returns the actual value of the KPI.|

+||statusExpression|String||An MDX expression that represents the state of the KPI at a specified point in time.|

+||trendExpression|String||An MDX expression that evaluates the value of the KPI over time. The trend can be any time-based criterion that is useful in a specific business context.|

+|Report ("reports") |||Description|This type represents a SQL Server Reporting Services report.|

+||||FriendlyName||

+||||Tag||

+||||Expert||

+||||AccessInstruction||

+||||Documentation||

+||assetCreatedDate|String|||

+||assetCreatedDate|String|||

+||assetModifiedDate|String|||

+||assetModifiedBy|String|||

+|Report ("reports") |||Description|This type represents a container of other assets such as an SQL database, an Azure Blobs container, or an Analysis Services model.|

+||||Tag||

+||||Expert||

+||||AccessInstruction||

+||||Documentation||

+Annotation types represent types of metadata that can be assigned to other types within the catalog.

+|Annotation type (nested view name) |Additional properties |Data type|Comments|

+|-|--|||

+|Description ("descriptions") |||This property contains a description for an asset. Each user of the system can add their own description. Only that user can edit the Description object. (Admins and Asset owners can delete the Description object but not edit it). The system maintains users' descriptions separately. Thus there's an array of descriptions on each asset (one for each user who has contributed their knowledge about the asset, in addition to possibly one that contains information derived from the data source).|

+||description|string|A short description (2-3 lines) of the asset.|

+|Tag ("tags") |||This property defines a tag for an asset. Each user of the system can add multiple tags for an asset. Only the user who created Tag objects can edit them. (Admins and Asset owners can delete the Tag object but not edit it). The system maintains users' tags separately. Thus there's an array of Tag objects on each asset.|

+||tag|string|A tag describing the asset.|

+|FriendlyName ("friendlyName") |||This property contains a friendly name for an asset. FriendlyName is a singleton annotation - only one FriendlyName can be added to an asset. Only the user who created FriendlyName object can edit it. (Admins and Asset owners can delete the FriendlyName object but not edit it). The system maintains users' friendly names separately.|

+||friendlyName|string|A friendly name of the asset.|

+|FriendlyName ("friendlyName") |||This property contains a friendly name for an asset. FriendlyName is a singleton annotation - only one FriendlyName can be added to an asset. Only the user who created FriendlyName object can edit it. (Admins and Asset owners can delete the FriendlyName object but not edit it). The system maintains users' friendly names separately.|

+||friendlyName|string|A friendly name of the asset.|

+|Schema ("schema") |||The Schema describes the structure of the data. It lists the attribute (column, attribute, field, etc.) names, types as well other metadata. This information is all derived from the data source. Schema is a singleton annotation - only one Schema can be added for an asset.|

+||columns|Column[]|An array of column objects. They describe the column with information derived from the data source.|

+|ColumnDescription ("columnDescriptions") |||This property contains a description for a column. Each user of the system can add their own descriptions for multiple columns (at most one per column). Only the user who created ColumnDescription objects can edit them. (Admins and Asset owners can delete the ColumnDescription object but not edit it). The system maintains these user's column descriptions separately. Thus there's an array of ColumnDescription objects on each asset (one per column for each user who has contributed their knowledge about the column in addition to possibly one that contains information derived from the data source). The ColumnDescription is loosely bound to the Schema so it can get out of sync. The ColumnDescription might describe a column that no longer exists in the schema. It's up to the writer to keep description and schema in sync. The data source may also have columns description information and they're other ColumnDescription objects that would be created when running the tool.|

+||columnName|String|The name of the column this description refers to.|

+||description|String|A short description (2-3 lines) of the column.|

+|ColumnTag ("columnTags") |||This property contains a tag for a column. Each user of the system can add multiple tags for a given column and can add tags for multiple columns. Only the user who created ColumnTag objects can edit them. (Admins and Asset owners can delete the ColumnTag object but not edit it). The system maintains these users' column tags separately. Thus there's an array of ColumnTag objects on each asset. The ColumnTag is loosely bound to the schema so it can get out of sync. The ColumnTag might describe a column that no longer exists in the schema. It's up to the writer to keep column tag and schema in sync.|

+||columnName|String|The name of the column this tag refers to.|

+||tag|String|A tag describing the column.|

+|Expert ("experts") |||This property contains a user who is considered an expert in the data set. The expertsΓÇÖ opinions(descriptions) bubble to the top of the UX when listing descriptions. Each user can specify their own experts. Only that user can edit the experts' object. (Admins and Asset owners can delete the Expert objects but not edit it).|

+||expert|SecurityPrincipal||

+|Preview ("previews") |||The preview contains a snapshot of the top 20 rows of data for the asset. Preview only make sense for some types of assets (it makes sense for Table but not for Measure).|

+||preview|object[]|Array of objects that represent a column. Each object has a property mapping to a column with a value for that column for the row.|

+|AccessInstruction ("accessInstructions") ||||

+||mimeType|string|The mime type of the content.|

+||content|string|The instructions for how to get access to this data asset. The content could be a URL, an email address, or a set of instructions.|

+|TableDataProfile ("tableDataProfiles") ||||

+||numberOfRows|int|The number of rows in the data set.|

+||size|long|The size in bytes of the data set.|

+||schemaModifiedTime|string|The last time the schema was modified.|

+||dataModifiedTime|string|The last time the data set was modified (data was added, modified, or delete).|

+|ColumnsDataProfile ("columnsDataProfiles") ||||

+||columns|ColumnDataProfile[]|An array of column data profiles.|

+|ColumnDataClassification ("columnDataClassifications") ||||

+||columnName|String|The name of the column this classification refers to.|

+||classification|String|The classification of the data in this column.|

+|Documentation ("documentation") |||A given asset can have only one documentation associated with it.|

+||mimeType|string|The mime type of the content.|

+||content|string|The documentation content.|

+Common types can be used as the types for properties, but aren't Items.

+|Common type |Properties |Data type|Comments|

+|-|--|||

+|DataSourceInfo|sourceType|string|Describes the type of data source. For example: SQL Server, Oracle Database, etc. |

+||objectType|string|Describes the type of object in the data source. For example: Table, View for SQL Server.|

+|DataSourceLocation|protocol|string|Required. Describes a protocol used to communicate with the data source. For example: `tds` for SQL Server, `oracle` for Oracle, etc. Refer to [Data source reference specification - DSL Structure](data-catalog-dsr.md) for the list of currently supported protocols.|

+||address|Dictionary\<string,object\>|Required. Address is a set of data specific to the protocol that is used to identify the data source being referenced. The address data scoped to a particular protocol, meaning it's meaningless without knowing the protocol.|

+||authentication|string|Optional. The authentication scheme used to communicate with the data source. For example: windows, oauth, etc.|

+||connectionProperties|Dictionary\<string,object\>|Optional. Additional information on how to connect to a data source.|

+|DataSourceLocation|||The backend doesn't perform any validation of provided properties against Azure Active Directory during publishing.|

+||upn|string|Required. Unique email address of user. Must be specified if objectId isn't provided or in the context of "lastRegisteredBy" property, otherwise optional.|

+||objectId|Guid|Optional. User or security group Azure Active Directory identity. Optional. Must be specified if upn isn't provided, otherwise optional.|

+||firstName|string|First name of user (for display purposes). Optional. Only valid in the context of "lastRegisteredBy" property. CanΓÇÖt be specified when providing security principal for "roles", "permissions" and "experts".|

+||lastName|string|Last name of user (for display purposes). Optional. Only valid in the context of "lastRegisteredBy" property. CanΓÇÖt be specified when providing security principal for "roles", "permissions" and "experts".|

+|Column|name|string|Name of the column or attribute.|

+||type|string|Data type of the column or attribute. The Allowable types depend on data sourceType of the asset. Only a subset of types is supported.|

+||maxLength|int|The maximum length allowed for the column or attribute. Derived from data source. Only applicable to some source types.|

+||precision|int|The precision for the column or attribute. Derived from data source. Only applicable to some source types.|

+||isNullable|isNullable|Whether the column is allowed to have a null value or not. Derived from data source. Only applicable to some source types.|

+||expression|string|If the value is a calculated column, this field contains the expression that expresses the value. Derived from data source. Only applicable to some source types.|

+|ColumnDataProfile|columnName|string|Name of the column.|

+||type|string|The type of the column.|

+||min|string|The minimum value in the data set.|

+||max|string|The maximum value in the data set.|

+||avg|double|The average value in the data set.|

+||stdev|double|The standard deviation for the data set|

+||nullCount|int|The count of null values in the data set.|

+||distinctCount |int|The count of distinct values in the data set.|

+There are three different types of data source protocol specificiations. Listed below are the types, followed by a table of their properties.

+#### DataSourceProtocol

+|Properties |Data type|Comments|

+|--|||

+|namespace|string|The namespace of the protocol. Namespace must be from 1 to 255 characters long, contain one or more non-empty parts separated by dot (.). Each part must be from 1 to 255 characters long, start with a letter and contain only letters and numbers. |

+|name|string|The name of the protocol. Name must be from 1 to 255 characters long, start with a letter and contain only letters, numbers, and the dash (-) character.|

+|identityProperties|DataSourceProtocolIdentityProperty[]|List of identity properties, must contain at least one, but no more than 20 properties. For example: "server", "database", "schema", "object" are identity properties of the "tds" protocol.|

+|identitySets|DataSourceProtocolIdentitySet[]|List of identity sets. Defines sets of identity properties, which represent valid asset's identity. Must contain at least one, but no more than 20 sets. For example: {"server", "database", "schema" and "object"} is an identity set for the TDS protocol, which defines identity of SQL Server Table asset.|

+#### DataSourceProtocolIdentityProperty

+|Properties |Data type|Comments|

+|--|||

+|name|string|The name of the property. Name must be from 1 to 100 characters long, start with a letter and can contain only letters and numbers.|

+|type|string|The type of the property. Supported values: "bool", boolean", "byte", "guid", "int", "integer", "long", "string", "url"|

+|ignoreCase|bool|Indicates whether case should be ignored when using property's value. Can only be specified for properties with "string" type. Default value is false.|

+|urlPathSegmentsIgnoreCase|bool[]|Indicates whether case should be ignored for each segment of the url's path. Can only be specified for properties with "url" type. Default value is [false].|

+#### DataSourceProtocolIdentitySet

+|Properties |Data type|Comments|

+|--|||

+|name|string|The name of the identity set.|

+|properties|string[]|The list of identity properties included into this identity set. It canΓÇÖt contain duplicates. Each property referenced by identity set must be defined in the list of "identityProperties" of the protocol.|

+There are three roles: **Administrator**, **Owner**, and **Contributor**. Each role has its scope and rights, which are summarized in the following table.

+|Role |Scope |Rights|

+|-|--||

+|Administrator|Catalog (all assets/annotations in the Catalog)|Read, Delete, ViewRoles, ChangeOwnership, ChangeVisibility, ViewPermissions|

+|Owner|Each asset (root item)|Read, Delete, ViewRoles, ChangeOwnership, ChangeVisibility, ViewPermissions|

+|Contributor|Each individual asset and annotation|Read*, Update, Delete, ViewRoles|

+> [!NOTE]

+> *All the rights are revoked if the Read right on the item is revoked from the Contributor

+#### Body

+| Germany West Central (Public) | Γ£ô |

+| Japan West | Γ£ô |

+| South India | Γ£ô |

+| West India | Γ£ô |

+| West US 3 | Γ£ô |

+## Connection failed after granting permission in SharePoint Online List

+### Symptoms

+You granted permission to your data factory in SharePoint Online List, but you still fail with the following error message:

+`Failed to get metadata of odata service, please check if service url and credential is correct and your application has permission to the resource. Expected status code: 200, actual status code: Unauthorized, response is : {"error":"invalid_request","error_description":"Token type is not allowed."}.`

+### Cause

+The SharePoint Online List uses ACS to acquire the access token to grant access to other applications. But for the tenant built after November 7, 2018, ACS is disabled by default.

+### Recommendation

+You need to enable ACS to acquire the access token. Take the following steps:

+1. Download [SharePoint Online Management Shell](https://www.microsoft.com/download/details.aspx?id=35588#:~:text=The%20SharePoint%20Online%20Management%20Shell%20has%20a%20new,and%20saving%20the%20file%20to%20your%20hard%20disk.), and ensure that you have a tenant admin account.

+1. Run the following command in the SharePoint Online Management Shell. Replace `<tenant name>` with your tenant name and add `-admin` after it.

+ ```powershell

+ Connect-SPOService -Url https://<tenant name>-admin.sharepoint.com/

+ ```

+1. Enter your tenant admin information in the pop-up authentication window.

+1. Run the following command:

+ ```powershell

+ Set-SPOTenant -DisableCustomAppAuthentication $false

+ ```

+ :::image type="content" source="./media/connector-troubleshoot-guide/sharepoint-online-management-shell-command.png" alt-text="Diagram of Azure Data Lake Storage Gen1 connections for troubleshooting issues.":::

+1. Use ACS to get the access token.

+The 2202 release has the following features and enhancements:

+- **Clustering support** - This release introduces clustering support for Azure Stack Edge. You can now deploy a two-node device cluster in addition to a single node device. The clustering feature is in preview and is available only for the Azure Stack Edge Pro GPU devices.

+ For more information, see [What is clustering on Azure Stack Edge?](azure-stack-edge-gpu-clustering-overview.md).

+- **Password reset extension** - Starting this release, password reset extension for both Windows and Linux virtual machines (VMs) are enabled.

+- **VM improvements** - A new VM size F12 was added in this release.

+- **Multi-Access Edge Computing (MEC) and Virtual Network Functions (VNF) improvements**:

+ - In this release, VM create and delete for VNF create and delete were parallelized. This has significantly reduced the creation time for VNFs that contain multiple VMs.

+ - The VHD ingestion job resource clean up was moved out of VNF create and delete. This reduced the VNF creation and deletion times.

+- **Updates for Azure Arc and Edge container registry** - Azure Arc and Edge container registry versions were updated. For more information, see [About updates](azure-stack-edge-gpu-install-update.md#about-latest-update).

+- **Security fixes** - Starting this release, a pod security policy is set up on the Kubernetes cluster on your Azure Stack Edge device. If you are using root privileges in your containerized solution, you may experience some change in the behavior. No action is required on your part.

+## Issues fixed in 2202 release

+|**1.**|Azure Arc | In the previous releases, there was a bug in the proxy implementation that resulted in Azure Arc not functioning properly. In this version, a web proxy bypass list was added to the Azure Arc *no_proxy* list. |

+

+ For information on how to log into the `az cli`, [Start Cloud Shell in Azure portal](../cloud-shell/quickstart-powershell.md#start-cloud-shell). If using `az cli` on a local client to create the service principal, make sure that you are running version 2.25 or later.

+**To apply 2202 update, your device must be running 2106 or later.**

+- **Two-node** - For a two-node cluster, this is an optimized update. The two-node cluster may experience short, intermittent disruptions while the update is in progress. We recommend that you shouldn't perform any operations on the device node when update is in progress.

+### Environment hardening

+You can manually configure the Kubernetes workload add-on, or extension protection through the Recommendations page. This can be accomplished by remediating the `Azure Policy add-on for Kubernetes should be installed and enabled on your clusters` recommendation, or `Azure policy extension for Kubernetes should be installed and enabled on your clusters`.

+1. From the recommendations page, search for the recommendation `Azure Policy add-on for Kubernetes should be installed and enabled on your clusters`, or `Azure policy extension for Kubernetes should be installed and enabled on your clusters`.

+Learn more in [Workload protection best-practices using Kubernetes admission control](defender-for-containers-introduction.md#environment-hardening).

+Learn more in [Workload protection best-practices using Kubernetes admission control](defender-for-containers-introduction.md#environment-hardening).

+## February 2022

+Updates in February include:

+- [Kubernetes workload protection for Arc enabled K8s clusters](#kubernetes-workload-protection-for-arc-enabled-k8s-clusters)

+### Kubernetes workload protection for Arc enabled K8s clusters

+Defender for Containers for Kubernetes workloads previously only protected AKS. We have now extended the protective coverage to include Azure Arc enabled Kubernetes clusters.

+Learn how to [set up your Kubernetes workload protection](kubernetes-workload-protections.md#set-up-your-workload-protection) for AKS and Azure Arc enabled Kubernetes clusters.

+Looking to connect through Bastion, read "[Enable browser connection to DevTest Labs VMs with Azure Bastion](enable-browser-connection-lab-virtual-machines.md)".

+See the following article to learn more about Remote Desktop

+ms.devlang: csharp, javascript

+ms.devlang: csharp, javascript

+|Can't upgrade to Premium with Availability Zones in the Southeast Asia region.|You can't currently upgrade to Azure Firewall Premium with Availability Zones in the Southeast Asia region.|Deploy a new Premium firewall in Southeast Asia without Availability Zones, or deploy in a region that supports Availability Zones.|

+|IDPS Bypass list|If you enable IDPS (either ΓÇÿAlertΓÇÖ or ΓÇÿAlert and DenyΓÇÖ mode) and actively delete one or more existing rules in IDPS Bypass list, you may be subject to packet loss which is correlated to the deleted rules source/destination IP addresses. |A fix is being investigated.<br><br>You may respond to this issue by taking one of the following actions:<br><br>- Do a start/stop procedure as explained [here](firewall-faq.yml#how-can-i-stop-and-start-azure-firewall).<br>- Open a support ticket and we will re-image your effected firewall virtual machines.|

+|Availability Zones for Firewall Premium in the Southeast Asia region|You can't currently deploy Azure Firewall Premium with Availability Zones in the Southeast Asia region.|Deploy the firewall in Southeast Asia without Availability Zones, or deploy in a region that supports Availability Zones.|

+ - If **type** is a resource type underneath the **if** condition resource, the policy

+ policy queries within the same resource group or subscription as the evaluated resource depending on the **existenceScope**.

+ - If **type** is a resource type underneath the **if** condition resource, the policy

+ queries for resources of this **type** within the scope of the evaluated resource. Otherwise,

+ policy queries within the same resource group or subscription as the evaluated resource depending on the **existenceScope**.

+description: Understand how to find when a resource was changed and query the list of resource configuration changes at scale

+sometimes it isn't. With the last seven days of changes, Resource configuration changes enables you to:

+- Query changes at scale across your subscriptions, Management group, or tenant

+ state. Evaluation of these extra properties can provide insights into other properties that

+This article shows how to query Resource configuration changes through Resource Graph. To see this

+information in the Azure portal, see [Azure Resource Graph Explorer](../first-query-portal.md), Azure Policy's

+[Change history](../../policy/how-to/determine-non-compliance.md#change-history), or Azure Activity

+> Resource configuration changes is for Azure Resource Manager properties. For tracking changes inside

+> Resource configuration changes is in Public Preview and only supports changes to resource types from the [Resources table](..//reference/supported-tables-resources.md#resources) in Resource Graph. This does not yet include changes to the resource container resources, such as Management groups, Subscriptions, and Resource groups.

+When a resource is created, updated, or deleted, a new change resource (Microsoft.Resources/changes) is created to extend the modified resource and represent the changed properties.

+Example change resource property bag:

+ "targetResourceId": "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/myResourceGroup/providers/microsoft.compute/virtualmachines/myVM",

+ "targetResourceType": "microsoft.compute/virtualmachines",

+ "changeType": "Update",

+ "changeAttributes": {

+ "changesCount": 2,

+ "correlationId": "88420d5d-8d0e-471f-9115-10d34750c617",

+ "timestamp": "2021-12-07T09:25:41.756Z",

+ "previousResourceSnapshotId": "ed90e35a-1661-42cc-a44c-e27f508005be",

+ "newResourceSnapshotId": "6eac9d0f-63b4-4e7f-97a5-740c73757efb"

+ },

+ "changes": {

+ "properties.provisioningState": {

+ "newValue": "Succeeded",

+ "previousValue": "Updating",

+ "changeCategory": "System",

+ "propertyChangeType": "Update"

+ "tags.key1": {

+ "newValue": "NewTagValue",

+ "previousValue": "null",

+ "changeCategory": "User",

+ "propertyChangeType": "Insert"

+ }

+ }

+Each change resource has the following properties:

+- **targetResourceId** - The resourceID of the resource on which the change occurred.

+ - **targetResourceType** - The resource type of the resource on which the change occurred.

+- **changeType** - Describes the type of change detected for the entire change record. Values are: _Create_, _Update_, and _Delete_. The

+ **changes** property dictionary is only included when **changeType** is _Update_. For the _Delete_ case, the change resource will still be maintained as an extension of the deleted resource for seven days, even if the entire Resource group has been deleted. The change resource will not block deletions or impact any existing delete behavior.

+- **changes** - Dictionary of the resource properties (with property name as the key) that were updated as part of the change:

+ - **propertyChangeType** - Describes the type of change detected for the individual resource property.

+ - **previousValue** - The value of the resource property in the previous snapshot. Value is _null_ when **changeType** is _Insert_.

+ - **newValue** - The value of the resource property in the new snapshot. Value is _null_ when **changeType** is _Remove_.

+ - **changeCategory** - Describes if the property change was the result of a change in value (_User_) or a difference in referenced API versions (_System_). Values are: _System_ and _User_.

+- **changeAttributes** - Array of metadata related to the change:

+ - **changesCount** - The number of properties changed as part of this change record.

+ - **correlationId** - Contains the ID for tracking related events. Each deployment has a correlation ID, and all actions in a single template will share the same correlation ID.

+ - **timestamp** - The datetime of when the change was detected.

+ - **previousResourceSnapshotId** - Contains the ID of the resource snapshot that was used as the previous state of the resource.

+ - **newResourceSnapshotId** - Contains the ID of the resource snapshot that was used as the new state of the resource.

+## Resource Graph Query samples

+With Resource Graph, you can query the **ResourceChanges** table to filter or sort by any of the change resource properties:

+### All changes in the past one day

+```kusto

+ResourceChanges

+| extend changeTime = todatetime(properties.changeAttributes.timestamp), targetResourceId = tostring(properties.targetResourceId),

+changeType = tostring(properties.changeType), correlationId = properties.changeAttributes.correlationId, 

+changedProperties = properties.changes, changeCount = properties.changeAttributes.changesCount

+| where changeTime > ago(1d)

+| order by changeTime desc

+| project changeTime, targetResourceId, changeType, correlationId, changeCount, changedProperties

+### Resources deleted in a specific resource group

+```kusto

+ResourceChanges

+| where resourceGroup == "myResourceGroup"

+| extend changeTime = todatetime(properties.changeAttributes.timestamp), targetResourceId = tostring(properties.targetResourceId),

+changeType = tostring(properties.changeType), correlationId = properties.changeAttributes.correlationId

+| where changeType == "Delete"

+| order by changeTime desc

+| project changeTime, resourceGroup, targetResourceId, changeType, correlationId

+### Changes to a specific property value

+```kusto

+ResourceChanges

+| extend provisioningStateChange = properties.changes["properties.provisioningState"], changeTime = todatetime(properties.changeAttributes.timestamp), targetResourceId = tostring(properties.targetResourceId), changeType = tostring(properties.changeType)

+| where isnotempty(provisioningStateChange)and provisioningStateChange.newValue == "Succeeded"

+| order by changeTime desc

+| project changeTime, targetResourceId, changeType, provisioningStateChange.previousValue, provisioningStateChange.newValue

+### Query the latest resource configuration for resources created in the last seven days

+```kusto

+ResourceChanges

+| extend targetResourceId = tostring(properties.targetResourceId), changeType = tostring(properties.changeType), changeTime = todatetime(properties.changeAttributes.timestamp)

+| where changeTime > ago(7d) and changeType == "Create"

+| project targetResourceId, changeType, changeTime

+| join ( Resources | extend targetResourceId=id) on targetResourceId

+| order by changeTime desc

+| project changeTime, changeType, id, resourceGroup, type, properties

+```

+This table lists certain HDInsight 4.0 cluster types that have retired or will be retired soon.

+| HDInsight 4.0 Kafka | 2.1.0 * | Sep 30, 2022 | Oct 1, 2022 |

+* Customers cannot create new Kafka 2.1.0 clusters but existing 2.1.0 clusters will not be impacted and will get basic support till September 30, 2022.

+Patch is a valuable RESTful operation when you need to update only a portion of the FHIR resource. Using Patch allows you to specify the element(s) that you want to update in the resource without having to update the entire record. FHIR defines three types of ways to Patch resources in FHIR: JSON Patch, XML Patch, and FHIR Path Patch. Azure API for FHIR supports JSON Patch and Conditional JSON Patch (which allows you to Patch a resource based on a search criteria instead of an ID). To walk through some examples of using JSON Patch, refer to the sample [REST file](https://github.com/microsoft/fhir-server/blob/main/docs/rest/FhirPatchRequests.http).

+(FHIR&#174;) is a registered trademark of [HL7](https://hl7.org/fhir/) and is used with the permission of HL7.

+Patch is a valuable RESTful operation when you need to update only a portion of the FHIR resource. Using Patch allows you to specify the element(s) that you want to update in the resource without having to update the entire record. FHIR defines three types of ways to Patch resources in FHIR: JSON Patch, XML Patch, and FHIR Path Patch. The FHIR service support JSON Patch and Conditional JSON Patch (which allows you to Patch a resource based on a search criteria instead of an ID). To walk through some examples of using JSON Patch, refer to the sample [REST file](https://github.com/microsoft/fhir-server/blob/main/docs/rest/FhirPatchRequests.http).

+IoT Central is a ready-made environment for IoT solution development. It's an application platform as a service (aPaaS) IoT solution and its primary interface is a web UI. There's also a [REST API](#extend-with-rest-api) that lets you interact with your application programmatically.

+This article provides an overview of the key elements in an IoT Central solution architecture.

+Key capabilities in an IoT Central application include:

+- Use [mapping](howto-map-data.md) to transform complex device telemetry into structured data inside IoT Central.

+The [telemetry, properties, and commands](concepts-telemetry-properties-commands.md) that a device implements are collectively known as the device capabilities. You define these capabilities in a model that's shared between the device and the IoT Central application. In IoT Central, this model is part of the device template that defines a specific type of device. To learn more, see [Associate a device with a device template](concepts-get-connected.md#associate-a-device-with-a-device-template).

+## Export data

+Although IoT Central has built-in analytics features, you can export data to other services and applications.

+[Transformations](howto-transform-data-internally.md) in an IoT Central data export definition let you manipulate the format and structure of the device data before it's exported to a destination.

+Reasons to export data include:

+## Extend with REST API

+Build integrations that let other applications and services manage your application. For example, programmatically [manage the devices](howto-control-devices-with-rest-api.md) in your application or synchronize [user information](howto-manage-users-roles-with-rest-api.md) with an external system.

+1. Select **Customization > App appearance**.

+1. Select **Customization > App appearance.**

+1. Select **Edit** on the image tile that displays the Northwind brand image.

+> [IoT Central data integration](../core/overview-iot-central-solution-builder.md)

+Learn more about :

+> [IoT Central data integration](../core/overview-iot-central-solution-builder.md)

+Learn more about :

+> [IoT Central data integration](../core/overview-iot-central-solution-builder.md)

+Learn more about :

+> [IoT Central data integration](../core/overview-iot-central-solution-builder.md)

+ms.devlang: c

+ms.devlang: java

+ms.devlang: javascript

+ms.devlang: javascript

+ms.devlang: python

+ms.devlang: java

+ms.devlang: javascript

+ms.devlang: java

+ms.devlang: javascript

+ms.devlang: csharp

+ms.devlang: csharp

+ms.devlang: python

+ms.devlang: java

+ms.devlang: java

+ Title: Compare load test runs to find regressions

+description: 'Learn how you can visually compare multiple test runs with Azure Load Testing to identify and analyze performance regressions.'

+# Identify performance regressions by comparing test runs in Azure Load Testing Preview

+In this article, you'll learn how you can identify performance regressions by comparing test runs in the Azure Load Testing Preview dashboard. The dashboard overlays the client-side and server-side metric graphs for each run, which allows you to quickly analyze performance issues.

+You can compare load test runs for the following scenarios:

+- [Identify performance regressions](#identify-performance-regressions) between application builds or configurations. You could run a load test at each development sprint to ensure that the previous sprint didn't introduce performance issues.

+- [Identify which application component is responsible](#identify-the-root-cause) for a performance problem (root cause analysis). For example, an application redesign might result in slower application response times. Comparing load test runs might reveal that the root cause was a lack of database resources.

+## Select test runs

+To compare test runs in Azure Load Testing, you'll first have to select up to five runs within a load test. You can only compare runs that belong to the same load test.

+A test run needs to be in the *Done*, *Stopped*, or *Failed* state to compare it.

+Use the following steps to select the test runs:

+1. Select the test whose runs you want to compare by selecting its name.

+1. Select two or more test runs by selecting the corresponding checkboxes in the list.

+ You can choose a maximum of five test runs to compare.

+## Compare multiple test runs

+After you've selected the test runs you want to compare, you can visually compare the client-side and server-side metrics for each test run in the load test dashboard.

+1. Select the **Compare** button to open the load test dashboard.

+

+ Each test run is shown as an overlay in the different graphs.

+1. Optionally, use the filters to customize the graphs.

+ :::image type="content" source="media/how-to-compare-multiple-test-runs/compare-client-side-filters.png" alt-text="Screenshot of the client-side filter controls on the load test dashboard.":::

+ > The time filter is based on the duration of the tests. A value of zero indicates the start of the test, and the maximum value marks the duration of the longest test run.

+## Identify performance regressions

+You can compare multiple test runs to identify performance regressions. For example, before deploying a new application version in production, you can verify that the performance hasn't degraded.

+Use the client-side metrics, such as requests per second or response time, on the load test dashboard to quickly spot performance changes between different load test runs:

+1. Hover over the client-side metrics graphs to compare the values across the different test runs.

+ In the following screenshot, you notice that the metric values for **Requests per second** and **Response Time** are significantly different. This difference indicates that the application performance dropped significantly between the two test runs.

+ :::image type="content" source="media/how-to-compare-multiple-test-runs/compare-client-side-metrics.png" alt-text="Screenshot of the client-side metrics, highlighting the difference in requests per second and response time.":::

+1. Optionally, use the **Requests** filter to compare a specific application request in the JMeter script.

+ :::image type="content" source="media/how-to-compare-multiple-test-runs/compare-client-side-requests-filter.png" alt-text="Screenshot of the client-side 'requests' filter, which allows you to filter specific application requests.":::

+## Identify the root cause

+When there's a performance issue, you can use the server-side metrics to analyze what the root cause of the problem is. Azure Load Testing can [capture server-side resource metrics](./how-to-update-rerun-test.md) for Azure-hosted applications.

+1. Hover over the server-side metrics graphs to compare the values across the different test runs.

+ In the following screenshot, you notice from the **Response time** and **Requests** that the application performance has degraded. You can also see that for one test run, the database **RU Consumption** peeks at 100%. This indicates that the root cause is likely the database **Provisioned Throughput**.

+ :::image type="content" source="media/how-to-compare-multiple-test-runs/compare-server-side-metrics.png" alt-text="Screenshot of the server-side metrics, highlighting the difference in database resource consumption and provisioning throughput.":::

+1. Optionally, select **Configure metrics** to add or remove server-side metrics.

+ You can add more server-side metrics for the selected Azure app components to further investigate performance problems. The dashboard immediately shows the additional metrics data, and you don't have to rerun the load test.

+1. Optionally, use the **Resource** filter to hide or show all metric graphs for an Azure component.

+## Next steps

+- Learn more about [exporting the load test results for reporting](./how-to-export-test-results.md).

+- Learn more about [troubleshooting load test execution errors](./how-to-find-download-logs.md).

+- Learn more about [configuring automated performance testing with Azure Pipelines](./tutorial-cicd-azure-pipelines.md).

+ Title: Set up DevOps for Standard logic apps

+description: How to set up DevOps deployment for Standard logic app workflows in single-tenant Azure Logic Apps.

+# Set up DevOps deployment for Standard logic app workflows in single-tenant Azure Logic Apps

+This article shows how to deploy a Standard logic app project to single-tenant Azure Logic Apps from Visual Studio Code to your infrastructure by using DevOps tools and processes. Based on whether you prefer GitHub or Azure DevOps for deployment, choose the path and tools that work best for your scenario. You can use the included samples that contain example logic app projects plus examples for Azure deployment using either GitHub or Azure DevOps. For more information about DevOps for single-tenant, review [DevOps deployment overview for single-tenant Azure Logic Apps](devops-deployment-single-tenant-azure-logic-apps.md).

+- A Standard logic app project created with [Visual Studio Code and the Azure Logic Apps (Standard) extension](create-single-tenant-workflows-visual-studio-code.md#prerequisites).

+| Azure Resource Manager (ARM) template | Optional | This Azure resource defines a baseline infrastructure deployment that you can reuse or [export](../azure-resource-manager/templates/template-tutorial-export-template.md). |

+<a name="deploy-logic-app-resources"></a>

+## Deploy logic app resources (zip deploy)

+After you push your logic app project to your source repository, you can set up build and release pipelines that deploy logic apps to infrastructure either inside or outside Azure.

+### Build your project

+To set up a build pipeline based on your logic app project type, complete the corresponding actions in the following table:

+| Project type | Description and steps |

+|--|--|

+| Nuget-based | The NuGet-based project structure is based on the .NET Framework. To build these projects, make sure to follow the build steps for .NET Standard. For more information, review the documentation for [Create a NuGet package using MSBuild](/nuget/create-packages/creating-a-package-msbuild). |

+| Bundle-based | The extension bundle-based project isn't language-specific and doesn't require any language-specific build steps. You can use any method to zip your project files. <br><br>**Important**: Make sure that your .zip file contains the actual build artifacts, including all workflow folders, configuration files such as host.json, connections.json, and any other related files. |

+|||

+### Before release to Azure

+The managed API connections inside your logic app project's **connections.json** file are created specifically for local use in Visual Studio Code. Before you can release your project artiffacts from Visual Studio Code to Azure, you have to update these artifacts. To use the managed API connections in Azure, you have to update their authentication methods so that they're in the correct format to use in Azure.

+#### Update authentication type

+For each managed API connection that uses authentication, you have to update the **authentication** object from the local format in Visual Studio Code to the Azure portal format, as shown by the first and second code examples, respectively:

+**Visual Studio Code format**

+ "managedApiConnections": {

+ "sql": {

+ "api": {

+ "id": "/subscriptions/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/providers/Microsoft.Web/locations/westus/managedApis/sql"

+ },

+ "connection": {

+ "id": "/subscriptions/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/resourceGroups/ase/providers/Microsoft.Web/connections/sql-8"

+ },

+ "connectionRuntimeUrl": "https://xxxxxxxxxxxxxx.01.common.logic-westus.azure-apihub.net/apim/sql/xxxxxxxxxxxxxxxxxxxxxxxxx/",

+ "authentication": {

+ "type": "Raw",

+ "scheme": "Key",

+ "parameter": "@appsetting('sql-connectionKey')"

+ }

+ }

+**Azure portal format**

+```json

+{

+ "managedApiConnections": {

+ "sql": {

+ "api": {

+ "id": "/subscriptions/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/providers/Microsoft.Web/locations/westus/managedApis/sql"

+ },

+ "connection": {

+ "id": "/subscriptions/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/resourceGroups/ase/providers/Microsoft.Web/connections/sql-8"

+ },

+ "connectionRuntimeUrl": "https://xxxxxxxxxxxxxx.01.common.logic-westus.azure-apihub.net/apim/sql/xxxxxxxxxxxxxxxxxxxxxxxxx/",

+ "authentication": {

+ "type": "ManagedServiceIdentity",

+ }

+ }

+}

+```

+#### Create API connections as needed

+If you're deploying your logic app workflow to an Azure region or subscription different from your local development environment, you must also make sure to create these managed API connections before deployment. Azure Resource Manager template (ARM template) deployment is the easiest way to create managed API connections.

+

+The following example shows a SQL managed API connection resource definition in an ARM template:

+ "id": "/subscriptions/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/providers/Microsoft.Web/locations/{Azure-region-location}/managedApis/sql"

+To find the values that you need to use in the **properties** object for completing the connection resource definition, you can use the following API for a specific connector:

+`GET https://management.azure.com/subscriptions/{Azure-subscription-ID}/providers/Microsoft.Web/locations/{Azure-region-location}/managedApis/{connector-name}?api-version=2016-06-01`

+In the response, find the **connectionParameters** object, which contains all the information necessary for you to complete resource definition for that specific connector. The following example shows an example resource definition for a SQL managed connection:

+```json

+{

+ "type": "Microsoft.Web/connections",

+ "apiVersion": "2016ΓÇô06ΓÇô01",

+ "location": "[parameters('location')]",

+ "name": "[parameters('connectionName')]",

+ "properties": {

+ "displayName": "sqltestconnector",

+ "api": {

+ "id": "/subscriptions/{Azure-subscription-ID}/providers/Microsoft.Web/locations/{Azure-region-location}/managedApis/sql"

+ },

+ "parameterValues": {

+ "authType": "windows",

+ "database": "TestDB",

+ "password": "TestPassword",

+ "server": "TestServer",

+ "username": "TestUserName"

+ }

+ }

+}

+```

+As an alternative, you can capture and review the network trace for when you create a connection using the workflow designer in Azure Logic Apps. Find the `PUT` call that's sent to the connector's managed API as previously described, and review the request body for all the necessary information.

+To set up a release pipeline that deploys to Azure, follow the associated steps for GitHub, Azure DevOps, or Azure CLI.

+### After release to Azure

+Each API connection has access policies. After the zip deployment completes, you must open your logic app resource in the Azure portal, and create access policies for each API connection to set up permissions for the deployed logic app. The zip deployment doesn't create app settings for you. So, after deployment, you must create these app settings based on the **local.settings.json** file in your local Visual Studio Code project.

+|Object detection, instance segmentation| `min_size`<br>`max_size`<br>`box_score_thresh`<br>`nms_iou_thresh`<br>`box_detections_per_img` | 600<br>1333<br>0.3<br>0.5<br>100 |

+|Object detection using `yolov5`| `img_size`<br>`model_size`<br>`box_score_thresh`<br>`nms_iou_thresh` | 640<br>medium<br>0.1<br>0.5 |

+1. The `inputs.pipeline_sample_input_data` path (line 6) creates a key identifier and uploads the input data from the `local_path` directory (line 8). This identifier `${{inputs.pipeline_sample_input_data}}` is then used as the value of the `jobs.componentA_job.inputs.componentA_input` key (line 19). In other words, the pipeline's `pipeline_sample_input_data` input is passed to the `componentA_input` input of Component A.

+1. The `jobs.componentA_job.outputs.componentA_output` path (line 21) is used with the identifier `${{jobs.componentA_job.outputs.componentA_output}}` as the value for the next step's `jobs.componentB_job.inputs.componentB_input` key (line 27).

+1. As with Component A, the output of Component B (line 29) is used as the input to Component C (line 35).

+1. The pipeline's `outputs.final_pipeline_output` key (line 11) is the source of the identifier used as the value for the `jobs.componentC_job.outputs.componentC_output` key (line 37). In other words, Component C's output is the pipeline's final output.

+| provider-resource-path/ | workspaces/MyWorkspace/experiments/FirstExperiment/runs/1/ |

+| `nms_iou_thresh` | IOU threshold used during inference in non-maximum suppression post processing. <br> Must be a float in the range [0, 1]. | 0.5 |

+| `nms_iou_thresh` | IOU (intersection over union) threshold used in non-maximum suppression (NMS) for the prediction head. Used during inference. <br>Must be a float in the range [0, 1]. | 0.5 |

+ --base64-encoded-cassandra-yaml-fragment $ENCODED_FRAGMENT

+- Changing your encoder configuration after it has started pushing has negative effects on the event. Configuration changes can cause the event to become unstable. If you change your encoder configuration, you need to reset [Live Events](https://docs.microsoft.com/rest/api/media/live-events/reset) and restart the live event in order for the change to take place. If you stop and start the live event without resetting it, the live event will preserve the previous configuration.

+> Watch the physical condition of the machine (CPU / Memory / etc) as uploading fragments to cloud involves CPU and IO operations.

+> If you change any encoder configurations, reset [Live Events](https://docs.microsoft.com/rest/api/media/live-events/reset) the channels and the live event for the change to take place. If you stop and start the live event without resetting it, the live event will preserve the previous configuration.

+ Title: Media Services live streaming best practices guide

+description: This article describes best practices for achieving low-latency live streams with Azure Media Services.

+# Media Services live streaming best practices guide

+Customers often ask how they can reduce the latency of their live stream. There are many factors that

+determine the end-to-end latency of a stream. Here are some that you should consider:

+1. Delays on the contribution encoder side. When customers use an

+ encoding software such as OBS Studio, Wirecast, or others to send an

+ RTMP live stream to Media Services. Settings on this software is critical in affecting the end-to-end latency of a live

+ stream.

+2. Delays in the live streaming pipeline within Azure Media Services.

+3. CDN performance

+4. Buffering algorithms of the video player and network conditions on

+ the client side

+5. Timing of provisioning

+## Contribution encoder

+As a customer, you are in control of the settings of the source encoder

+settings before the RTMP stream reaches Media Services. Here are some

+recommendations for the settings that would give you the lowest possible

+latency:

+1. **Pick the same region physically** **closest to your contribution

+ encoder for your Media Services account.** This will ensure

+ that you have a great network connection to the Media Services

+ account.

+2. **Use a consistent fragment size.** We recommend a GOP size of 2

+ seconds. The default on some encoders, such as OBS, is 8 seconds.

+ Make sure that you change this setting.

+3. **Use the GPU encoder if your encoding software allows you to do

+ that.** This would allow you to offload CPU work to the GPU.

+4. **Use an encoding profile that is optimized for low-latency.** For

+ example, with OBS Studio, if you use the Nvidia H.264 encoder, you

+ may see the ΓÇ£zero latencyΓÇ¥ preset.

+5. **Send content that is no higher in resolution than what you plan to

+ stream.** For example, if you're using 720p standard encoding live

+ events, you send files that are already at 720p.

+6. **Keep your framerate at 30fps or lower unless using pass-through

+ live events.** While we support 60 fps input for live events, our

+ encoding live event output is still not above 30 fps.

+## Configuration of the Azure Media Services live event

+Here are some configurations that will help you reduce the latency in

+our pipeline:

+1. **Use the ΓÇÿLowLatencyΓÇÖ StreamOption on the live event.**

+2. **We recommend that you choose CMAF output for both HLS and DASH

+ playback.** This allows you to share the same fragments for both

+ formats. It increases your cache hit ratio when CDN is used. For example:

+

+| Type | Format | URL example |

+||||

+|HLS CMAF (recommended) | format=m3u8-cmaf | `https://amsv3account-usw22.streaming.media.azure.net/21b17732-0112-4d76-b526-763dcd843449/ignite.ism/manifest(format=m3u8-cmaf)` |

+| MPEG-DASH CMAF (recommended) | format=mpd-time-cmaf | `https://amsv3account-usw22.streaming.media.azure.net/21b17732-0112-4d76-b526-763dcd843449/ignite.ism/manifest(format=mpd-time-cmaf)` |

+3. **If you must choose TS output, use an HLS packing ratio of 1.** This

+allows us to pack only one fragment into one HLS segment. You won't

+get the full benefits of LL-HLS in native Apple players.

+## Player optimizations

+**When choosing and configuring a video player, make sure you use settings that are optimized for lower latency.**

+Media Services supports different streaming protocols outputs ΓÇô DASH,

+HLS with TS output and HLS with CMAF fragments. Depending on the

+playerΓÇÖs implementation, buffering decisions impact the latency a

+viewer observes. Poor network conditions or default algorithms that

+favor quality and stability of playback could cause players to decide to

+buffer more content upfront to prevent interruptions during playback.

+These buffers before and during the playback sessions would add to the

+end-to-end latency.

+When Azure Media Player is used, the *Low Latency Heuristics* profile

+optimizes the player to have the lowest possible latency on the player

+side.

+## CDN choice

+Streaming endpoints are the origin servers that deliver the live and VOD

+streaming content to the CDN or to the customer directly. If a live

+event expects a large audience, or the audience is geographically

+located far away from the streaming endpoint (origin) serving the

+content, it's *important* for the customer to shield the origin using a

+Content Delivery Network (CDN).

+We recommend using Azure CDN which is provided by Verizon (Standard or

+Premium). We've optimized the integration experience so that a

+customer could configure this CDN with a single select in the Azure portal. Be sure to turn on Origin Shield and Streaming Optimizations for

+your CDN endpoint whenever you start your streaming endpoint.

+Our customers also have good experiences bringing their own CDN. Ensure that measures are taken on the CDN to shield the origin from

+excessive traffic.

+## Streaming endpoint scaling

+> [!NOTE]

+> A **standard streaming endpoint/origins** is a *shared* resource

+that allows customers with low traffic volumes to stream content at

+a lower cost. You would **not** use a standard streaming endpoint to

+scale streaming units if you expect large traffic volumes or you plan to

+use a CDN.

+A **premium streaming endpoint/origin** offers more flexibility and

+isolation for customers to scale by adding or removing *dedicated*

+streaming units. A *streaming unit* is a compute resource allocated to a

+streaming endpoint. Each streaming unit can stream approximately 200

+Mbps of traffic.

+While you can concurrently stream many live events at once using

+the same streaming endpoint, the maximum default streaming units needed

+for one streaming endpoint is 10. You can open a support ticket to

+request more than the default 10.

+## Determine the premium streaming units needed

+There are three steps to determine the number of streaming endpoints and

+streaming units needed:

+1. Determine the total egress needed.

+2. Divide the total egress by 200, which is the maximum Mbps each streaming unit can stream.

+### Determine the total egress needed

+Determine the total egress needed by using the following formula.

+*Total egress needed = average bandwidth x number of concurrent viewers

+x percent* *handled by the streaming endpoint.*

+LetΓÇÖs take a look at each of the multipliers in turn.

+**Average bandwidth.** What is the *average* bitrate you plan to stream?

+In other words, if you're going to have multiple bitrates available

+what bit rate is the average of all the bitrates you're planning for?

+You can estimate this using one of the following methods:

+For a live event that *includes encoding*:

+ - If you donΓÇÖt know what your *average* bandwidth is going to be, you

+ could use our top bitrates as an estimate. Our *top* bitrates are:

+

+ - 5.5Mbps for the 1080p encoded live events, therefore, your

+ average bitrate is going to be somewhere around 3.5Mbps.

+ - Look at the encoding preset used for encoding the live event, for

+ example, the AdaptiveStreaming(H.264) preset. See this [output

+ example](encode-autogen-bitrate-ladder.md#output).

+For a live event that is simply using pass-through and not encoding:

+ - Check the encoding bitrate ladder used by your local encoder.

+**Number of concurrent viewers.** How many concurrent viewers are

+expected? This could be hard to estimate, but do your best based on your

+customer data. Are you streaming a conference to a global audience? Are

+you planning to live stream to sell a set of products to your customers?

+**Percent of traffic** **handled by** **the streaming endpoint.** This

+can also be expressed as ΓÇ£the percent of traffic NOT handled by the CDNΓÇ¥

+since that is the number that actually goes into the formula. So, with

+that in mind, what is the CDN offload you expect? If the CDN is expected

+to handle 90% of the live traffic, then only 10% of the traffic would be

+expected on the streaming endpoint. The number used in the formula is

+.10 which is the percentage of traffic expected on the streaming

+endpoint.

+### Determine the number of premium streaming units needed

+Premium streaming units needed = Average bandwidth x \# of viewers x

+Percentage of traffic not handled by the CDN / 200 Mbps

+### Example

+You've recently released a new product and want to present it to your

+established customers. You want low latency because you donΓÇÖt want to

+frustrate your already busy audience, so you'll use premium streaming

+endpoints and a CDN.

+You have approximately 100,000 customers, but they probably arenΓÇÖt all

+going to watch your live event. You guess that in the best case, only 1%

+of them will attend, which brings your expected concurrent viewers to

+1,000.

+*Number of concurrent users =* *1,000*

+You've decided that you're going to use Media Services to encode your

+live stream and won't be using pass-through. You donΓÇÖt know what the

+average bandwidth is going to be, but you do know that you'll deliver

+in 1080p (*top* bitrate of 5.5 Mbps), so your *average* bandwidth is

+estimated to be 3.5 Mbps for your calculations.

+*Average bandwidth =* *3.5*

+Since your audience is dispersed worldwide, you expect that the CDN will

+handle most (90%) of the live traffic. Therefore, the premium streaming

+endpoints will only handle 10% of the traffic.

+*Percent handled by the streaming endpoint =* *10% = 0.1*

+Using the formula provided above:

+*Total egress needed = average bandwidth x number of concurrent viewers

+x percent handled by the streaming endpoint.*

+*total egress needed* = 3.5 x 1,000 x 0.1

+*total egress needed* = 350 Mbps

+Dividing the total egress by 200 you determine that you need 1.75

+premium streaming units.

+*premium streaming units needed* = *total egress needed*/200Mpbs

+*premium streaming units needed* = 1.75

+We'll round up this number to 2, giving us 2 units needed.

+### Use the portal to estimate your needs

+The Azure portal can help you simplify the calculations. On the

+streaming page, you can use the calculator provided to see the estimated

+audience reach when you change the average bandwidth, CDN hit ratio and

+number of streaming units.

+1. From the media services account page, select **Steaming endpoints** from

+ the menu.

+2. Add a new streaming endpoint by selecting **Add streaming endpoint**.

+3. Give the streaming endpoint a name.

+4. Select **Premium streaming endpoint** for the streaming endpoint type.

+5. Since you're just getting an estimate at this point, donΓÇÖt start

+ the streaming endpoint after creation. Select **No**.

+6. Select *Standard Verizon* or *Premium Verizon* for your CDN pricing

+ tier. The profile name will change accordingly. Leave the name as it

+ is for this exercise.

+7. For the CDN profile, select **Create New**.

+8. Select **Create**. Once the endpoint has been deployed, the streaming

+ endpoints screen will appear.

+9. Select the streaming endpoint you just created. The streaming

+ endpoint screen will appear with audience reach estimates.

+10. The default setting for the streaming endpoint with 1 streaming unit

+ shows that it's estimated to stream to 571 concurrent viewers at

+ 3.5 Mbps using 90% of the CDN and 10% of the streaming endpoint.

+11. Change the percentage of the **Egress source** from 90% from CDN cache

+ to 0%. The calculator will estimate that you'll be able to stream

+ to 57 concurrent viewers at 3.5 Mbps at 200 Mbps **without** a CDN.

+12. Now change the **Egress source** back to 90%.

+13. Then, change the **streaming units** to 2. The calculator will estimate

+ that you'll be able to stream to 1143 concurrent viewers at

+ 3.5 Mbps with 4000Mpbs with the CDN handling 90% of the traffic.

+14. Select **Save**.

+15. You can start the streaming endpoint and try sending traffic to it.

+ The metrics at the bottom of the screen will track actual traffic.

+## Timing

+You may want to provision streaming units 1 hour ahead of the expected

+peak usage to ensure streaming units are ready.

+> [!NOTE]

+> If the sampling rate is low, such as 8khz, the encoded output will be lower than 128kbps.

+This transform allows you have input video / input audio streams copied from the input asset to the output asset without any changes. This can be of value with multi bitrate encoding output where the input video and/or audio would be part of the output. It simply writes the manifest and other files needed to stream content.

+This article shows you how with the Media Services 2020-05-01 v3 API.

+You can use Media Encoder Standard to generate a thumbnail sprite, which is a JPEG file that contains multiple small resolution thumbnails stitched together into a single (large) image, together with a VTT file. This VTT file specifies the time range in the input video that each thumbnail represents, together with the size and coordinates of that thumbnail within the large JPEG file. Video players use the VTT file and sprite image to show a 'visual' seekbar, providing a viewer with visual feedback when scrubbing back and forward along the video timeline.

+ Title: Quickstart Video on Demand with Media Services

+description: This article shows you how to do the basic steps for delivering video on demand (VOD) with Azure Media Services.

+# Quickstart Basic Video On Demand (VOD) with Media Services

+This article shows you how to do the basic steps for delivering a basic video on demand (VOD) application with Azure Media Services and a GitHub repository. All the steps happen with your web browser from our documentation, the Azure portal, and GitHub.

+## Prerequisites

+- [Create a Media Services account](account-create-how-to.md). When you set up the Media Services account, a storage account, a user managed identity, and a default streaming endpoint will also be created.

+- One MP4 video to use for this exercise.

+- Create a GitHub account if you don't have one already, and stay logged in.

+- Create an Azure [Static Web App](/azure/static-web-apps/get-started-portal?tabs=vanilla-javascript).

+> [!NOTE]

+> You will be switching between several browser tabs or windows during this process. The below steps assume that you have your browser set to open tabs. Keep them all open.

+## Upload videos

+You should have a media services account, a storage account, and a default streaming endpoint.

+1. In the portal, navigate to the Media Services account that you just created.

+1. Select **Assets**. Assets are the containers that are used to house your media content.

+1. Select **Upload**. The Upload new assets screen will appear.

+1. Select the storage account you created for the Media Services account from the **Storage account** dropdown menu. It should be selected by default.

+1. Select the **file folder icon** next to the Upload files field.

+1. Select the media files you want to use. An asset will be created for every video you upload. The name of the asset will start with the name of the video and will be appended with a unique identifier. You *could* upload the same video twice and it will be located in two different assets.

+1. You must agree to the statement "I have all the rights to use the content/file, and agree that it will be handled per the Online Services Terms and the Microsoft Privacy Statement." Select **I agree and upload.**

+1. Select **Continue upload and close**, or **Close** if you want to watch the video upload progress.

+1. Repeat this process for each of the files you want to stream.

+## Create a transform

+> [!IMPORTANT]

+> You must encode your files with a transform in order to stream them, even if they have been encoded locally. The Media Services encoding process creates the manifest files needed for streaming.

+You'll now create a transform that uses a Built-in preset, which is like a recipe for encoding.

+1. Select **Transforms + jobs**.

+1. Select **Add transform**. The Add transform screen will appear.

+1. Enter a transform name in the **Transform name** field.

+1. Select the **Encoding** radio button.

+1. Select ContentAwareEncoding from the **Built-in preset name** dropdown list.

+1. Select **Add**.

+Stay on this screen for the next steps.

+## Create a job

+Next, you'll create a job which is for telling Media Services which transform to run on files within an asset. The asset you choose will be the input asset. The job will create an output asset to contain the encoded files as well as the manifest.

+1. Select **Add job**. The Create a job screen will appear.

+1. For the **Input source**, the **Asset** radio button should be selected by default. If not, select it now.

+1. Select **Select an existing asset** and choose one of the assets that was just created when you uploaded your videos. The Select an asset screen will appear.

+1. Select one of the assets in the list. You can only select one at a time for the job.

+1. Select the **Use existing** radio button.

+1. Select the transform that you created earlier from the **Transform** dropdown list.

+1. Under Configure output, default settings will be autopopulated, for this exercise leave them as they are.

+1. Select **Create**.

+1. Select **Transforms + Jobs**.

+1. You'll see the name of the transform you chose for the job. Select the transform to see the status of the job.

+1. Select the job listed under **Name** in the table of jobs. The job detail screen will open.

+1. Select the output asset from the **Outputs** list. The asset screen will open.

+1. Select the link for the asset next to Storage container. A new browser tab will open and You'll see the results of the job that used the transform. There should be several files in the output asset including:

+ 1. Encoded video files with.mpi and .mp4 extensions.

+ 1. A *XXXX_metadata.json* file.

+ 1. A *XXXX_manifest.json* file.

+ 1. A *XXXX_.ism* file.

+ 1. A *XXXX.isc* file.

+ 1. A *ThumbnailXXXX.jpg* file.

+1. Once you've viewed what is in the output asset, close the tab. Go back to the asset browser tab.

+## Create a streaming locator

+In order to stream your videos you need a streaming locator.

+1. Select **New streaming locator**. The Add streaming locator screen will appear and a default name for the locator will appear. You can change it or leave it as is.

+1. Select *Predefined_ClearStreamingOnly* from the Streaming policy dropdown list. This is a streaming policy that says that the video will be streamed using DASH, HLS and Smooth with no content protection restrictions except that the video canΓÇÖt be downloaded by the viewer. No content key policy is required.

+1. Leave the rest of the settings as they are.

+1. Select **Add**. The video will start playing in the player on the screen, and the **Streaming URL** field will be populated.

+1. Select **Show URLs** in the Streaming locator list. The Streaming URLs screen will appear.

+On this screen, you'll see that the streaming endpoint that was created when you created your account is in the Streaming endpoint dropdown list along with other data about the streaming locator.

+In the streaming and download section, you'll see the URLs to use for your streaming application. For the following steps, you'll use the URL that ends with `(format=m3u8-cmaf)`. Keep this browser tab open as you'll be coming back to it in a later step.

+## Create a web page with a video player client

+Assuming that you created a Static Web App, you'll now change the HTML in the https://docsupdatetracker.net/index.html file. If you didn't create a web app with Azure, you can still use this code where you plan to host your web app.

+1. If you aren't already logged in, sign in to GitHub and navigate to the repository you created for the Static Web App.

+1. Navigate to the *https://docsupdatetracker.net/index.html* file. It should be in a directory called `src`.

+1. Select the edit pencil icon to edit the file.

+1. Replace the code that is in the html file with the following code:

+ ```html

+ <html lang="en-US">

+ <head>

+ <meta charset="utf-8">

+ <meta http-equiv="X-UA-Compatible" content="IE=edge">

+ <title>Basic Video on Demand Static Web App</title>

+ <meta name="description" content="">

+ <meta name="viewport" content="width=device-width, initial-scale=1">

+ <!--*****START OF Azure Media Player Scripts*****-->

+ <!--Note: DO NOT USE the "latest" folder in production. Replace "latest" with a version number like "1.0.0"-->

+ <!--EX:<script src="//amp.azure.net/libs/amp/1.0.0/azuremediaplayer.min.js"></script>-->

+ <!--Azure Media Player versions can be queried from //aka.ms/ampchangelog-->

+ <link href="//amp.azure.net/libs/amp/latest/skins/amp-default/azuremediaplayer.min.css" rel="stylesheet">

+ <script src="//amp.azure.net/libs/amp/latest/azuremediaplayer.min.js"></script>

+ <!--*****END OF Azure Media Player Scripts*****-->

+ </head>

+ <body>

+ <h1>Clear Streaming Only</h1>

+ <video id="azuremediaplayer" class="azuremediaplayer amp-default-skin amp-big-play-centered" controls autoplay width="640" height="400" poster="" data-setup='{}' tabindex="0">

+ <source src="put streaming url here" type="application/vnd.ms-sstr+xml" />

+ <p class="amp-no-js">To view this video please enable JavaScript, and consider upgrading to a web browser that supports HTML5 video</p>

+ </video>

+ </body>

+ </html>

+ ```

+1. Return to the Azure portal, Streaming locator browser tab where the streaming URLs are located.

+1. Copy the URL that ends with `(format=m3u8-cmaf)` under HLS.

+1. Return to the index file on GitHub browser tab.

+1. Paste the URL into the `src` value in the source object in the HTML.

+1. Select **Commit changes** to commit the change. It may take a minute for the changes to be live.

+1. Back in the Azure portal, Static web app tab, select the link next to **URL** to open the index page in another tab of your browser. The player should appear on the page.

+1. Select the **video play** button. The video should begin playing. If it isn't playing, check that your streaming endpoint is running.

+## Clean up resources

+If you don't intend to further develop this basic web app, make sure you delete all the resources you created or you'll be billed.

+Unsupported IPv6 | Only applicable to Azure VMware Solution assessments. Azure VMware Solution doesn't support IPv6 internet addresses. Contact the Azure VMware Solution team for remediation guidance if your server is detected with IPv6.

+Unsupported OS | Support for certain Operating System versions has been deprecated by VMware and the assessment recommends you to upgrade the operating system before migrating to Azure VMware Solution. [Learn more](https://www.vmware.com/resources/compatibility/search.php?deviceCategory=software)

+This gap can be addressed by enabling [application discovery](./how-to-discover-applications.md) on the VMware VMs. An Azure VM assessment uses the operating system detected from the VM by using the guest credentials provided. This Operating System data identifies the right OS information in the case of both Windows and Linux VMs.

+We have an on-premises VM with 4 cores and 8 GB of memory, with 50% CPU utilization and 50% memory utilization, and a specified comfort factor of 1.3.

+- If the assessment is **As on-premises**, an Azure VM SKU with 4 cores and 8 GB of memory is recommended.

+- If the assessment is **Performance-based**, based on effective CPU and memory utilization (50% of 4 cores * 1.3 = 2.6 cores and 50% of 8-GB memory * 1.3 = 5.3-GB memory), the cheapest VM SKU of 4 cores (nearest supported core count) and 8 GB of memory (nearest supported memory size) is recommended.

+## Why is my assessment showing a warning that it was created with an invalid offer?

+Your assessment was created with an offer that is no longer valid and hence, the **Edit** and **Recalculate** buttons are disabled. You can create a new assessment with any of the valid offers - *Pay as you go*, *Pay as you go Dev/Test*, and *Enterprise Agreement*. You can also use the **Discount(%)** field to specify any custom discount on top of the Azure offer. [Learn more](how-to-create-assessment.md).

+## Where is the Operating System data in my assessment discovered from?

+- For VMware VMs, by default, it's the Operating System data provided by the vCenter Server.

+- For Hyper-V VMs, the Operating System data is gathered from the Hyper-V host.

+>[!Note]

+>GTID is supported on versions 5.7 and 8.0 and only on servers that support storage up to 16 TB (General purpose storage v2).

+Global transaction identifier (GTID) is a unique identifier created with each committed transaction on a source server and is OFF by default in Azure Database for MySQL. GTID is supported on versions 5.7 and 8.0 and only on servers that support storage up to 16 TB(General purpose storage v2). To learn more about GTID and how it's used in replication, refer to MySQL's [replication with GTID](https://dev.mysql.com/doc/refman/5.7/en/replication-gtids.html) documentation.

+ms.devlang: java

+ms.devlang: java

+6. When primary region is down, one cannot create geo-redundant servers in the respective geo-paired region as storage cannot be provisioned in the primary region. One must wait for the primary region to be up to provision geo-redundant servers in the geo-paired region. With the primary region down one can still geo-restore the source server to the geo-paired region by disabling the geo-redundancy option in the Compute + Storage Configure Server settings in the restore portal experience and restore as a locally redundant server to ensure business continuity.

+ :::image type="content" source="./media/how-to-restore-server-portal/georestore-region-down-1.png" alt-text="Compute + Storage window":::

+ :::image type="content" source="./media/how-to-restore-server-portal/georestore-region-down-2.png" alt-text="Disabling Geo-Redundancy":::

+ :::image type="content" source="./media/how-to-restore-server-portal/georestore-region-down-3.png" alt-text="Restoring as Locally redundant server":::

+7. Select **Review + Create** to review your selections.

+8. A notification will be shown that the restore operation has been initiated. This operation may take a few minutes.

+ms.devlang: php

+ - When you're viewing automated backups for a HA enabled server in Backup and Restore blade, if at some point in time a forced or automatic failover is performed, you may lose viewing rights to the server's backups on the Backup and Restore blade. Despite the invisibility of information regarding backups on the portal, the flexible server is successfully taking daily automated backups for the server in the backend and the server can be restored to any point in time within the retention period.

+ > GTID is supported on versions 5.7 and 8.0 and only on servers that support storage up to 16 TB (General purpose storage v2).

+>[!Important]

+>This procedure can be only used to skip one transaction, and can't be used to skip gtid set or set gtid_purged.

+ms.devlang: java

+description: Learn about the concepts of backup and restore with Azure Database for PostgreSQL - Flexible Server.

+Backups form an essential part of any business continuity strategy. They help protect data from accidental corruption or deletion.

+Azure Database for PostgreSQL - Flexible Server automatically performs regular backups of your server. You can then do a point-in-time recovery (PITR) within a retention period that you specify. The overall time to restore and recovery typically depends on the size of data and the amount of recovery to be performed.

+Flexible Server takes snapshot backups of data files and stores them securely in zone-redundant storage or locally redundant storage, depending on the [region](overview.md#azure-regions). The server also backs up transaction logs when the write-ahead log (WAL) file is ready to be archived. You can use these backups to restore a server to any point in time within your configured backup retention period.

+The default backup retention period is 7 days, but you can extend the period to a maximum of 35 days. All backups are encrypted through AES 256-bit encryption for data stored at rest.

+These backup files can't be exported or used to create servers outside Azure Database for PostgreSQL - Flexible Server. For that purpose, you can use the PostgreSQL tools pg_dump and pg_restore/psql.

+Backups on flexible servers are snapshot based. The first snapshot backup is scheduled immediately after a server is created. Snapshot backups are currently taken once daily.

+Transaction log backups happen at varied frequencies, depending on the workload and when the WAL file is filled and ready to be archived. In general, the delay (recovery point objective, or RPO) can be up to 15 minutes.

+Flexible Server stores multiple copies of your backups to help protect your data from planned and unplanned events. These events can include transient hardware failures, network or power outages, and natural disasters. Backup redundancy helps ensure that your database meets its availability and durability targets, even if failures happen.

+Flexible Server offers three options:

+- **Zone-redundant backup storage**: This option is automatically chosen for regions that support availability zones. When the backups are stored in zone-redundant backup storage, multiple copies are not only stored within the availability zone in which your server is hosted, but also replicated to another availability zone in the same region.

+ This option provides backup data availability across availability zones and restricts replication of data to within a country/region to meet data residency requirements. This option provides at least 99.9999999999 percent (12 nines) durability of backup objects over a year.

+- **Locally redundant backup storage**: This option is automatically chosen for regions that don't support availability zones yet. When the backups are stored in locally redundant backup storage, multiple copies of backups are stored in the same datacenter.

+ This option helps protect your data against server rack and drive failures. It provides at least 99.999999999 percent (11 nines) durability of backup objects over a year.

+

+ By default, backup storage for servers with same-zone high availability (HA) or no high-availability configuration is set to locally redundant.

+- **Geo-redundant backup storage (preview)**: You can choose this option at the time of server creation. When the backups are stored in geo-redundant backup storage, in addition to three copies of data stored within the region where your server is hosted, the data is replicated to a geo-paired region.

+ This option provides the ability to restore your server in a different region in the event of a disaster. It also provides at least 99.99999999999999 percent (16 nines) durability of backup objects over a year.

+

+ Geo-redundancy is supported for servers hosted in any of the [Azure paired regions](../../availability-zones/cross-region-replication-azure.md).

+You can configure geo-redundant storage for backup only during server creation. After a server is provisioned, you can't change the backup storage redundancy option.

+Backups are retained based on the retention period that you set for the server. You can select a retention period between 7 (default) and 35 days. You can set the retention period during server creation or change it at a later time. Backups are retained even for stopped servers.

+The backup retention period governs how far back in time a PITR can be retrieved, because it's based on available backups. You can also treat the backup retention period as a recovery window from a restore perspective.

+All backups required to perform a PITR within the backup retention period are retained in the backup storage. For example, if the backup retention period is set to 7 days, the recovery window is the last 7 days. In this scenario, all the data and logs that are required to restore and recover the server in the last 7 days are retained.

+### Backup storage cost

+Flexible Server provides up to 100 percent of your provisioned server storage as backup storage at no additional cost. Any additional backup storage that you use is charged in gigabytes per month.

+For example, if you have provisioned a server with 250 gibibytes (GiB) of storage, then you have 250 GiB of backup storage capacity at no additional charge. If the daily backup usage is 25 GiB, then you can have up to 10 days of free backup storage. Backup storage consumption that exceeds 250 GiB is charged as defined in the [pricing model](https://azure.microsoft.com/pricing/details/postgresql/flexible-server/).

+If you configured your server with geo-redundant backup, the backup data is also copied to the Azure paired region. So, your backup size will be two times the local backup copy. Billing is computed as *( (2 x local backup size) - provisioned storage size ) x price @ gigabytes per month*.

+You can use the [Backup Storage Used](../concepts-monitoring.md) metric in the Azure portal to monitor the backup storage that a server consumes. The Backup Storage Used metric represents the sum of storage consumed by all the retained database backups and log backups, based on the backup retention period set for the server.

+>[!Note]

+> Irrespective of the database size, heavy transactional activity on the server generates more WAL files. The increase in files in turn increases the backup storage.

+## Point-in-time recovery

+In Flexible Server, performing a PITR creates a new server in the same region as your source server, but you can choose the availability zone. It's created with the source server's configuration for the pricing tier, compute generation, number of virtual cores, storage size, backup retention period, and backup redundancy option. Also, tags and settings such as virtual networks and firewall settings are inherited from the source server.

+The physical database files are first restored from the snapshot backups to the server's data location. The appropriate backup that was taken earlier than the desired point in time is automatically chosen and restored. A recovery process then starts by using WAL files to bring the database to a consistent state.

+For example, assume that the backups are performed at 11:00 PM every night. If the restore point is for August 15 at 10:00 AM, the daily backup of August 14 is restored. The database will be recovered until 10:00 AM of August 15 by using the transaction log backup from August 14, 11:00 PM, to August 15, 10:00 AM.

+To restore your database server, see [these steps](./how-to-restore-server-portal.md).

+> A restore operation in Flexible Server always creates a new database server with the name that you provide. It doesn't overwrite the existing database server.

+PITR is useful in scenarios like these:

+- A user accidentally deletes data, a table, or a database.

+- An application accidentally overwrites good data with bad data because of an application defect.

+With continuous backup of transaction logs, you'll be able to restore to the last transaction. You can choose between two restore options:

+- **Latest restore point (now)**: This is the default option. It allows you to restore the server to the latest point in time.

+- **Custom restore point**: This option allows you to choose any point in time within the retention period defined for this flexible server. By default, the latest time in UTC is automatically selected. Automatic selection is useful if you want to restore to the last committed transaction for test purposes. You can optionally choose other days and times.

+The estimated time to recover depends on several factors, including the volume of transaction logs to process after the previous backup time, and the total number of databases recovering in the same region at the same time. The overall recovery time usually takes from few minutes up to a few hours.

+If you've configured your server within a virtual network, you can restore to the same virtual network or to a different virtual network. However, you can't restore to public access. Similarly, if you configured your server with public access, you can't restore to private virtual network access.

+> A user can't restore deleted servers. If you delete a server, all databases that belong to the server are also deleted and can't be recovered. To help protect server resources from accidental deletion or unexpected changes after deployment, administrators can use [management locks](../../azure-resource-manager/management/lock-resources.md).

+>

+>If you accidentally deleted your server, please reach out to support. In some cases, your server might be restored with or without data loss.

+## Geo-redundant backup and restore (preview)

+To enable geo-redundant backup from the **Compute + storage** pane in the Azure portal, see the [quickstart guide](./quickstart-create-server-portal.md).

+> Geo-redundant backup can be configured only at the time of server creation.

+After you've configured your server with geo-redundant backup, you can restore it to a [geo-paired region](../../availability-zones/cross-region-replication-azure.md). For more information, see the [supported regions](overview.md#azure-regions) for geo-redundant backup.

+When the server is configured with geo-redundant backup, the backup data and transaction logs are copied to the paired region asynchronously through storage replication. After you create a server, wait at least one hour before initiating a geo-restore. That will allow the first set of backup data to be replicated to the paired region.

+Subsequently, the transaction logs and the daily backups are asynchronously copied to the paired region. There might be up to one hour of delay in data transmission. So, you can expect up to one hour of RPO when you restore. You can restore only to the last available backup data that's available at the paired region. Currently, PITR of geo-redundant backups is not available.

+The estimated time to recover the server (recovery time objective, or RTO) depends on factors like the size of the database, the last database backup time, and the amount of WAL to process until the last received backup data. The overall recovery time usually takes from a few minutes up to a few hours.

+During the geo-restore, the server configurations that can be changed include virtual network settings and the ability to remove geo-redundant backup from the restored server. Changing other server configurations--such as compute, storage, or pricing tier (Burstable, General Purpose, or Memory Optimized)--during geo-restore is not supported.

+For more information about performing a geo-restore, see the [how-to guide](how-to-restore-server-portal.md#performing-geo-restore-preview).

+> When the primary region is down, you can't create geo-redundant servers in the respective geo-paired region, because storage can't be provisioned in the primary region. Before you can provision geo-redundant servers in the geo-paired region, you must wait for the primary region to be up.

+>

+> With the primary region down, you can still geo-restore the source server to the geo-paired region. Disable the geo-redundancy option in the **Compute + Storage** > **Configure Server** settings in the portal, and restore as a locally redundant server to help ensure business continuity.

+### Point-in-time recovery

+If your source server is configured with a *public access* network, you can only restore to public access.

+If your source server is configured with a *private access* virtual network, you can restore either to the same virtual network or to a different virtual network. You can't perform PITR across public and private access.

+If your source server is configured with a *public access* network, you can only restore to public access. Also, you have to apply firewall rules after the restore operation is complete.

+If your source server is configured with a *private access* virtual network, you can only restore to a different virtual network, because virtual networks can't span regions. You can't perform geo-restore across public and private access.

+## Post-restore tasks

+After you restore the database, you can perform the following tasks to get your users and applications back up and running:

+- If the new server is meant to replace the original server, redirect clients and client applications to the new server. Change the server name of your connection string to point to the new server.

+- Ensure that appropriate server-level firewall and virtual network rules are in place for user connections. These rules are not copied over from the original server.

+- Scale up or scale down the restored server's compute as needed.

+- Ensure that appropriate logins and database-level permissions are in place.

+- Configure alerts as appropriate.

+- If you restored the database configured with high availability, and if you want to configure the restored server with high availability, you can then follow [the steps](./how-to-manage-high-availability-portal.md).

+### Backup-related questions

+* **How does Azure handle backup of my server?**

+ By default, Azure Database for PostgreSQL enables automated backups of your entire server (encompassing all databases created) with a default retention period of 7 days. The automated backups include a daily incremental snapshot of the database. The log (WAL) files are archived to Azure Blob Storage continuously.

+* **Can I configure automated backups to retain data for the long term?**

+ No. Currently, Flexible Server supports a maximum of 35 days of retention. You can use manual backups for a long-term retention requirement.

+* **How do I manually back up my Postgres servers?**

+ You can manually take a backup by using the PostgreSQL tool [pg_dump](https://www.postgresql.org/docs/current/app-pgdump.html). For examples, see [Migrate your PostgreSQL database by using dump and restore](../howto-migrate-using-dump-and-restore.md).

+

+ If you want to back up Azure Database for PostgreSQL to Blob Storage, see [Back up Azure Database for PostgreSQL to Blob Storage](https://techcommunity.microsoft.com/t5/azure-database-for-postgresql/backup-azure-database-for-postgresql-to-a-blob-storage/ba-p/803343) on our tech community blog.

+* **What are the backup windows for my server? Can I customize them?**

+ Azure manages backup windows, and you can't customize them. The first full snapshot backup is scheduled immediately after a server is created. Subsequent snapshot backups are incremental and occur once a day.

+ Yes. All Azure Database for PostgreSQL data, backups, and temporary files that are created during query execution are encrypted through AES 256-bit encryption. Storage encryption is always on and can't be disabled.

+* **Can I restore a single database or a few databases in a server?**

+ Restoring a single database or a few databases or tables is not directly supported. However, you can restore the entire server to a new server, and then extract tables or databases and import them to the new server.

+* **Is my server available while a backup is in progress?**

+ Yes. Backups are online operations that use snapshots. The snapshot operation takes only a few seconds and doesn't interfere with production workloads, to help ensure high availability of the server.

+* **When I'm setting up the maintenance window for the server, do I need to account for the backup window?**

+ No. Backups are triggered internally as part of the managed service and have no bearing on the maintenance window.

+* **Where are my automated backups stored, and how do I manage their retention?**

+

+ Azure Database for PostgreSQL automatically creates server backups and stores them in:

+

+ - Zone-redundant storage, in regions where multiple zones are supported.

+ - Locally redundant storage, in regions that don't support multiple zones yet.

+ - The paired region, if you've configured geo-redundant backup.

+

+ These backup files can't be exported.

+

+ You can use backups to restore your server to a point in time only. The default backup retention period is 7 days. You can optionally configure the backup retention up to 35 days.

+* **With geo-redundant backup, how often is the backup copied to the paired region?**

+ When the server is configured with geo-redundant backup, the backup data is stored in a geo-redundant storage account. The storage account copies data files to the paired region when the daily backup occurs at the primary server. WAL files are backed up when they're ready to be archived.

+

+ Backup data is asynchronously copied in a continuous manner to the paired region. You can expect up to one hour of delay in receiving backup data.

+* **How are backups performed in a HA-enabled servers?**

+ Data volumes in Flexible Server are backed up through managed disk incremental snapshots from the primary server. The WAL backup is performed from either the primary server or the standby server.

+* **How can I validate that backups are performed on my server?**

+ The best way to check backups is to perform periodic PITR and ensure that backups are valid and restorable. Backup operations or files are not exposed to end users.

+ In the Azure portal, under **Monitoring**, select **Metrics**. In **Backup usage metric**, you can monitor the total backup usage.

+ If you delete a server, all backups that belong to the server are also deleted and can't be recovered. To help protect server resources from accidental deletion or unexpected changes after deployment, administrators can use management locks.

+ No new backups are performed for stopped servers. All older backups (within the retention window) at the time of stopping the server are retained until the server is restarted. After that, backup retention for the active server is governed by its retention window.

+ Flexible Server provides up to 100 percent of your provisioned server storage as backup storage at no additional cost. Any additional backup storage that you use is charged in gigabytes per month, as defined in the pricing model.

+

+ The backup retention period and backup redundancy option that you select, along with transactional activity on the server, directly affect the total backup storage and billing.

+ While your server instance is stopped, no new backups are performed. You're charged for provisioned storage and backup storage (backups stored within your specified retention window).

+

+ Free backup storage is limited to the size of your provisioned database. Any excess backup data will be charged according to the backup price.

+* **I configured my server with zone-redundant high availability. Do you take two backups, and will I be charged twice?**

+ No. Irrespective of HA or non-HA servers, only one set of backup copies is maintained. You'll be charged only once.

+### Restore-related questions

+ Azure supports PITR for all servers. Users can restore to the latest restore point or a custom restore point by using the Azure portal, the Azure CLI, and the API.

+ To restore your server from manual backups by using tools like pg_dump, you can first create a flexible server and then restore your databases to the server by using [pg_restore](https://www.postgresql.org/docs/current/app-pgrestore.html).

+ Yes. If the region supports multiple availability zones, the backup is stored on a zone-redundant storage account so that you can restore to another zone.

+* **How long does a PITR take? Why is my restore taking so much time?**

+ The data restore operation from a snapshot doesn't depend on the size of data. But the recovery process timing that applies the logs (transaction activities to replay) might vary, depending on the previous backup of the requested date/time and the number of logs to process. This applies to both restoring within the same zone or and restoring data to a different zone.

+* **If I restore my HA-enabled server, is the restore server automatically configured with high availability?**

+ No. The server is restored as a single-instance flexible server. After the restore is complete, you can optionally configure the server with high availability.

+* **I configured my server within a virtual network. Can I restore to another virtual network?**

+ Yes. At the time of restore, choose a different virtual network to restore to.

+* **Can I restore my public access server to a virtual network or vice versa?**

+ No. Flexible Server currently doesn't support restoring servers across public and private access.

+ Currently, there's no way to track the restore operation. You can monitor the activity log to see if the operation is in progress or complete.

+- Learn about [business continuity](./concepts-business-continuity.md).

+- Learn about [zone-redundant high availability](./concepts-high-availability.md).

+- Learn [how to restore](./how-to-restore-server-portal.md).

+ms.devlang: java

+4. Run a test query. Copy the following command and paste it into the psql

+ prompt, then press enter to run:

+ ```sql

+ SHOW server_version;

+ ```

+ You should see a result matching the PostgreSQL version you selected

+ during server group creation. For instance:

+ ```

+ server_version

+ -

+ 13.5

+ (1 row)

+ ```

+5. Select **Configure server group**.

+ For this quickstart, you can accept the default value of **Basic** for

+6. Select **Save**.

+7. Select **Next : Networking >** at the bottom of the screen.

+8. In the **Networking** tab, select **Allow public access from Azure services

+9. Select **Review + create** and then **Create** to create the server.

+10. The page will redirect to monitor deployment. When the live status changes

+SELECT table_name, count(*) AS shards

+ table_name | shards

+ github_users | 32

+ github_events | 32

+Run the following commands to download example CSV files and load them into the

+database tables. (The `curl` command downloads the files, and comes

+pre-installed in the Azure Cloud Shell.)

+-- download users and store in table

+-- download events and store in table

+SELECT table_name,

+ pg_size_pretty(sum(shard_size)) AS shard_size_sum

+ table_name | shard_size_sum

+shards in parallel, and combines the results.

+Let's continue looking at a few more query examples:

+Hyperscale (Citus) also automatically applies data definition changes across

+Here are good resources to deepen your knowledge.

+* Scale your server group by [adding

+ nodes](howto-scale-grow.md#add-worker-nodes) and [rebalancing

+ shards](howto-scale-rebalance.md).

+Before creating any credentials, consider your data source types and networking requirements to decide which authentication method you need for your scenario. Review the following decision tree to find which credential is most suitable:

+If you're using the Azure Purview system-assigned managed identity (SAMI) to set up scans, you won't need to create a credential and link your key vault to Azure Purview to store them. For detailed instructions on adding the Azure Purview SAMI to have access to scan your data sources, refer to the data source-specific authentication sections below:

+To give Azure Purview access to your Azure Key Vault, there are two things you'll need to confirm:

+- [Firewall access to the Azure Key Vault](#firewall-access-to-azure-key-vault)

+- [Azure Purview permissions on the Azure Key Vault](#azure-purview-permissions-on-the-azure-key-vault)

+### Firewall access to Azure Key Vault

+If your Azure Key Vault has disabled public network access, you have two options to allow access for Azure Purview.

+- [Trusted Microsoft services](#trusted-microsoft-services)

+- [Private endpoint connections](#private-endpoint-connections)

+#### Trusted Microsoft services

+Azure Purview is listed as one of [Azure Key Vault's trusted services](../key-vault/general/overview-vnet-service-endpoints.md#trusted-services), so if public network access is disabled on your Azure Key Vault you can enable access only to trusted Microsoft services, and Azure Purview will be included.

+You can enable this setting in your Azure Key Vault under the **Networking** tab.

+At the bottom of the page, under Exception, enable the **Allow trusted Microsoft services to bypass this firewall** feature.

+#### Private endpoint connections

+To connect to Azure Key Vault with private endpoints, follow [Azure Key Vault's private endpoint documentation](../key-vault/general/private-link-service.md).

+### Azure Purview permissions on the Azure Key Vault

+- [Option 1 - Access Policies](#option-1assign-access-using-key-vault-access-policy)

+- [Option 2 - Role-based Access Control](#option-2assign-access-using-key-vault-azure-role-based-access-control)

+#### Option 1 - Assign access using Key Vault Access Policy

+5. For **Select principal**, choose the Azure Purview system managed identity. You can search for the Azure Purview SAMI using either the Azure Purview instance name **or** the managed identity application ID. We don't currently support compound identities (managed identity name + application ID).

+#### Option 2 - Assign access using Key Vault Azure role-based access control

+1. In the [Azure portal](https://portal.azure.com/) navigate to your Azure Purview account.

+1. After finishing the setup, go back to your Azure Purview account in the Azure portal. If the managed identity is successfully deployed, you'll see the Azure Purview account's status as **Succeeded**.

+ :::image type="content" source="media/manage-credentials/status-successful.png" alt-text="Screenshot the Azure Purview account in the Azure portal with Status highlighted under the overview tab and essentials menu.":::

+1. Select the Managed identity authentication method, and select your user assigned managed identity from the drop-down menu.

+There are specific instructions for each [source type](azure-purview-connector-overview.md).

+> [!IMPORTANT]

+> Verify that you have followed all prerequisite and authentication steps for the source you are connecting to.

+> You can find all available sources listed in the [Azure Purview supported sources article](azure-purview-connector-overview.md).

+To register a single data source in Azure Purview, such as an Azure Blog Storage or an Azure SQL Database, you must be granted at least **Reader** role on the resource or inherited from higher scope such as resource group or subscription. Some Azure RBAC roles, such as Security Admin, don't have read access to view Azure resources in control plane.

+1. From the [Azure portal](https://portal.azure.com), navigate to the resource that you're trying to register in Azure Purview. If you can view the resource, it's likely, that you already have at least reader role on the resource.

+4. Verify if any role assignments, such as Reader, exist in the list or add a new role assignment if needed.

+2. Select **Access Control (IAM)** from the left menu.

+3. Select **+Add**.

+## Scanning data sources using Private Link

+If public endpoint is restricted on your data sources, to scan Azure data sources using Private Link, you need to set up a Self-hosted integration runtime and create a credential.

+1. Select the version that you intend to use and verify that the password or account key is correct by selecting **Show Secret Value**.

+1. Verify that your Azure Purview managed identity shows under the _Current access policies_ section with at least **Get** and **List** permissions on Secrets

+If you don't see your Azure Purview managed identity listed, then follow the steps in [Create and manage credentials for scans](manage-credentials.md) to add it.

+If you list this role assignment using Azure PowerShell, you might see an empty `DisplayName` and `SignInName`, or a value for `ObjectType` of `Unknown`. For example, [Get-AzRoleAssignment](/powershell/module/az.resources/get-azroleassignment) returns a role assignment that is similar to the following output:

+ Title: 'Multi-region designs with Azure Route Server'

+description: Learn about how Azure Route Server enables multi-region designs.

+# Multi-region networking with Azure Route Server

+Applications that have demanding requirements around high availability or disaster recovery often need to be deployed in more than one Azure region, where spoke VNets in multiple regions need to communicate between each other. A possibility to achieve this communication pattern is peering to each other all spokes that need to communicate, but those flows would bypass any central NVAs in the hubs, such as firewalls. Another possibility is using User Defined Routes (UDRs) in the subnets where the hub NVAs are deployed, but that can be difficult to maintain. Azure Route Server offers an alternative which is very dynamic and adapts to topology changes without manual intervention.

+## Topology

+The following diagram shows a dual-region architecture, where a hub and spoke topology exists in each region, and the hub VNets are peered to each other via VNet global peering:

+Each NVA learns the prefixes from the local hub and spokes from its Azure Route Server, and will communicate it to the NVA in the other region via BGP. This communication between the NVAs should be established over an encapsulation technology such as IPsec or Virtual eXtensible LAN (VXLAN), since otherwise routing loops can occur in the network.

+The spokes need to be peered with the hub VNet with the setting "Use Remote Gateways", so that Azure Route Server advertises their prefixes to the local NVAs, and it injects learnt routes back into the spokes.

+The NVAs will advertise to their local Route Server the routes that they learn from the remote region, and Route Server will configure these routes in the local spokes, hence attracting traffic. If there are multiple NVAs in the same region (Route Server supports up to 8 BGP adjacencies), AS path prepending can be used to make one of the NVAs preferred to the others, hence defining an active/standby NVA topology.

+## ExpressRoute

+This design can be combined with ExpressRoute or VPN gateways. The following diagram shows a topology including an ExpressRoute gateway connected to an on-premises network in one of the Azure regions. In this case, an overlay network over the ExpressRoute circuit will help to simplify the network, so that on-premises prefixes will only appear in Azure as advertised by the NVA (and not from the ExpressRoute gateway).

+## Design without overlays

+The cross-region tunnels between the NVAs are required because otherwise a routing loop is formed. For example, looking at the NVA in region 1:

+- The NVA in region 1 learns the prefixes from region 2, and advertises them to the Route Server in region 1

+- The Route Server in region 1 will inject routes for those prefixes in all subnets in the local region, with the NVA in region 1 as the next hop

+- For traffic from region 1 to region 2, when the NVA in region 1 sends traffic to the other NVA, its own subnet inherits as well the routes programmed by the Route Server, which are pointing to itself (the NVA). So the packet is returned to the NVA, and a routing loop appears.

+If UDRs are an option, you could disable BGP route propagation in the NVAs' subnets, and configure static UDRs instead of an overlay, so that Azure can route traffic to the remote spokes.

+## Next steps

+* [Learn how Azure Route Server works with ExpressRoute](expressroute-vpn-support.md)

+* [Learn how Azure Route Server works with a network virtual appliance](resource-manager-template-samples.md)

+ Title: 'Injecting default route to Azure VMware Solution'

+description: Learn about how to advertise a default route to Azure VMware Solution with Azure Route Server.

+# Injecting a default route to Azure VMware Solution

+[Azure VMware Solution](../azure-vmware/introduction.md) is an Azure service where native VMware vSphere workloads run and communicate with other Azure services. This communication happens over ExpressRoute, and Azure Route Server can be used to modify the default behavior of Azure VMware Solution networking. For example, a default route can be injected from a Network Virtual Appliance (NVA) in Azure to attract traffic from AVS and inspect it before sending it out to the public Internet, or to analyze traffic between AVS and the on-premises network.

+## Topology

+The following diagram describes a basic hub and spoke topology connected to an AVS cloud and to an on-premises network through ExpressRoute. The diagram shows how the default route (`0.0.0.0/0`) is originated by the NVA in Azure, and propagated by Azure Route Server to Azure VMware Solution through ExpressRoute.

+> [!IMPORTANT]

+> The default route advertised by the NVA will be propagated to the on-premises network as well, so it needs to be filtered out in the customer routing environment.

+Communication between Azure VMware Solution and the on-premises network will typically happen over ExpressRoute Global Reach, as described in [Peer on-premises environments to Azure VMware Solution](../azure-vmware/tutorial-expressroute-global-reach-private-cloud.md).

+## Communication between Azure VMware Solution and the on-premises network via NVA

+If not only the Internet traffic should be inspected by the NVA, but also traffic between AVS and the on-premises network instead of being sent over ExpressRoute Global Reach, an additional transit VNet is required to avoid potential routing loops, which would be originated since a single ExpressRoute gateway wouldn't be able to route packets properly (more specifically, the User Defined Routes in the GatewaySubnet can either point to the NVA or to on-premises, but not to both).

+An additional NVA would be required in this transit VNet, and both NVAs would exchange the routes they learn from their respective Azure Route Servers via BGP and some sort of encapsulation protocol such as VXLAN or IPsec, as the following diagram shows.

+The reason why encapsulation is needed is because the NVA NICs would learn the routes from ExpressRoute or from the Route Server, so they would send packets that need to be routed to the other NVA in the wrong direction (potentially creating a routing loop returning the packets to the local NVA).

+## Next steps

+* [Learn how Azure Route Server works with ExpressRoute](expressroute-vpn-support.md)

+* [Learn how Azure Route Server works with a network virtual appliance](resource-manager-template-samples.md)

+> You can build complex skillsets with looping and branching using the [Conditional skill](cognitive-search-skill-conditional.md) to create the expressions. The syntax is based on the [JSON Pointer](https://tools.ietf.org/html/rfc6901) path notation, with a few modifications to identify nodes in the enrichment tree. A `"/"` traverses a level lower in the tree and `"*"` acts as a for-each operator in the context. Numerous examples in this article illustrate the [the syntax](cognitive-search-skill-annotation-language.md).

+ Title: Skill context and input annotation reference language

+description: Annotation syntax reference for annotation in the context, inputs and outputs of a skillset in an AI enrichment pipeline in Azure Cognitive Search.

+# Skill context and input annotation language

+This article is the reference documentation for skill context and input syntax. It's a full description of the expression language used to construct paths to nodes in an enriched document.

+Azure Cognitive Search skills can use and [enrich the data coming from the data source and from the output of other skills](cognitive-search-defining-skillset.md).

+The data working set that represents the current state of the indexer work for the current document starts from the raw data coming from the data source and is

+progressively enriched with each skill iteration's output data.

+That data is internally organized in a tree-like structure that can be queried to be used as skill inputs or to be added to the index.

+The nodes in the tree can be simple values such as strings and numbers, arrays, or complex objects and even binary files.

+Even simple values can be enriched with additional structured information.

+For example, a string can be annotated with additional information that is stored beneath it in the enrichment tree.

+The expressions used to query that internal structure use a rich syntax that is detailed in this article.

+The enriched data structure can be [inspected from debug sessions](cognitive-search-debug-session.md#ai-enrichments-tab--enriched-data-structure).

+Expressions querying the structure can also be [tested from debug sessions](cognitive-search-debug-session.md#expression-evaluator).

+Throughout the article, we'll use the following enriched data as an example.

+This data is typical of the kind of structure you would get when enriching a document using a skillset with [OCR](cognitive-search-skill-ocr.md), [key phrase extraction](cognitive-search-skill-keyphrases.md), [text translation](cognitive-search-skill-text-translation.md), [language detection](cognitive-search-skill-language-detection.md), [entity recognition](cognitive-search-skill-entity-recognition-v3.md) skills and a custom tokenizer skill.

+|Path|Value|

+|||

+|`document`||

+|&emsp;`merged_content`|"Study of BMN 110 in Pediatric Patients"...|

+|&emsp;&emsp;`keyphrases`||

+|&emsp;&emsp;&emsp;`[0]`|"Study of BMN"|

+|&emsp;&emsp;&emsp;`[1]`|"Syndrome"|

+|&emsp;&emsp;&emsp;`[2]`|"Pediatric Patients"|

+|&emsp;&emsp;&emsp;...||

+|&emsp;&emsp;`locations`||

+|&emsp;&emsp;&emsp;`[0]`|"IVA"|

+|&emsp;&emsp;`translated_text`|"Étude de BMN 110 chez les patients pédiatriques"...|

+|&emsp;&emsp;`entities`||

+|&emsp;&emsp;&emsp;`[0]`||

+|&emsp;&emsp;&emsp;&emsp;`category`|"Organization"|

+|&emsp;&emsp;&emsp;&emsp;`subcategory`|`null`|

+|&emsp;&emsp;&emsp;&emsp;`confidenceScore`|0.72|

+|&emsp;&emsp;&emsp;&emsp;`length`|3|

+|&emsp;&emsp;&emsp;&emsp;`offset`|9|

+|&emsp;&emsp;&emsp;&emsp;`text`|"BMN"|

+|&emsp;&emsp;&emsp;...||

+|&emsp;&emsp;`organizations`||

+|&emsp;&emsp;&emsp;`[0]`|"BMN"|

+|&emsp;&emsp;`language`|"en"|

+|&emsp;`normalized_images`||

+|&emsp;&emsp;`[0]`||

+|&emsp;&emsp;&emsp;`layoutText`|...|

+|&emsp;&emsp;&emsp;`text`||

+|&emsp;&emsp;&emsp;&emsp;`words`||

+|&emsp;&emsp;&emsp;&emsp;&emsp;`[0]`|"Study"|

+|&emsp;&emsp;&emsp;&emsp;&emsp;`[1]`|"of"|

+|&emsp;&emsp;&emsp;&emsp;&emsp;`[2]`|"BMN"|

+|&emsp;&emsp;&emsp;&emsp;&emsp;`[3]`|"110"|

+|&emsp;&emsp;&emsp;&emsp;&emsp;...||

+|&emsp;&emsp;`[1]`||

+|&emsp;&emsp;&emsp;`layoutText`|...|

+|&emsp;&emsp;&emsp;`text`||

+|&emsp;&emsp;&emsp;&emsp;`words`||

+|&emsp;&emsp;&emsp;&emsp;&emsp;`[0]`|"it"|

+|&emsp;&emsp;&emsp;&emsp;&emsp;`[1]`|"is"|

+|&emsp;&emsp;&emsp;&emsp;&emsp;`[2]`|"certainly"|

+|&emsp;&emsp;&emsp;&emsp;&emsp;...||

+|&emsp;&emsp;&emsp;&emsp;...

+|&emsp;&emsp;...||

+## Document root

+All the data is under one root element, for which the path is `"/document"`. The root element is the default context for skills.

+## Simple paths

+Simple paths through the internal enriched document can be expressed with simple tokens separated by slashes.

+This syntax is similar to [the JSON Pointer specification](https://datatracker.ietf.org/doc/html/rfc6901.htmlhttps://datatracker.ietf.org/doc/html/rfc6901.html).

+### Object properties

+The properties of nodes that represent objects add their values to the tree under the property's name.

+Those values can be obtained by appending the property name as a token separated by a slash:

+|Expression|Value|

+|||

+|`/document/merged_content/language`|`"en"`|

+Property name tokens are case-sensitive.

+### Array item index

+Specific elements of an array can be referenced by using their numeric index like a property name:

+|Expression|Value|

+|||

+|`/document/merged_content/keyphrases/1`|`"Syndrome"`|

+|`/document/merged_content/entities/0/text`|`"BMN"`|

+### Escape sequences

+There are two characters that have special meaning and need to be escaped if they appear in an expression and must be interpreted as is instead of as their special meaning: `'/'` and `'~'`.

+Those characters must be escaped respectively as `'~0'` and `'~1'`.

+## Array enumeration

+An array of values can be obtained using the `'*'` token:

+|Expression|Value|

+|||

+|`/document/normalized_images/0/text/words/*`|`["Study", "of", "BMN", "110" ...]`|

+The `'*'` token doesn't have to be at the end of the path. It's possible to enumerate all nodes matching a path with a star in the middle or with multiple stars:

+|Expression|Value|

+|||

+|`/document/normalized_images/*/text/words/*`|`["Study", "of", "BMN", "110" ... "it", "is", "certainly" ...]`|

+This example returns a flat list of all matching nodes.

+It's possible to maintain more structure and get a separate array for the words of each page by using a `'#'` token instead of the second `'*'` token:

+|Expression|Value|

+|||

+|`/document/normalized_images/*/text/words/#`|`[["Study", "of", "BMN", "110" ...], ["it", "is", "certainly" ...] ...]`|

+The `'#'` token expresses that the array should be treated as a single value instead of being enumerated.

+### Enumerating arrays in context

+It is often useful to process each element of an array in isolation and have a different set of skill inputs and outputs for each.

+This can be done by setting the context of the skill to an enumeration instead of the default `"/document"`.

+In the following example, we use one of the input expressions we used before, but with a different context that changes the resulting value.

+|Context|Expression|Values|

+||||

+|`/document/normalized_images/*`|`/document/normalized_images/*/text/words/*`|`["Study", "of", "BMN", "110" ...]`<br/>`["it", "is", "certainly" ...]`<br>...|

+For this combination of context and input, the skill will get executed once for each normalized image: once for `"/document/normalized_images/0"` and once for `"/document/normalized_images/1"`. The two input values corresponding to each skill execution are detailed in the values column.

+When enumerating an array in context, any outputs the skill produces will also be added to the document as enrichments of the context.

+In the above example, an output named `"out"` will have its values for each execution added to the document respectively under `"/document/normalized_images/0/out"` and `"/document/normalized_images/1/out"`.

+## Literal values

+Skill inputs can take literal values as their inputs instead of dynamic values queried from the existing document. This can be achieved by prefixing the value with an equal sign. Values can be numbers, strings or Boolean.

+String values can be enclosed in single `'` or double `"` quotes.

+|Expression|Value|

+|||

+|`=42`|`42`|

+|`=2.45E-4`|`0.000245`|

+|`="some string"`|`"some string"`|

+|`='some other string'`|`"some other string"`|

+|`="unicod\u0065"`|`"unicode"`|

+|`=false`|`false`|

+## Composite expressions

+It's possible to combine values together using unary, binary and ternary operators.

+Operators can combine literal values and values resulting from path evaluation.

+When used inside an expression, paths should be enclosed between `"$("` and `")"`.

+### Boolean not `'!'`

+|Expression|Value|

+|||

+|`=!false`|`true`|

+### Negative `'-'`

+|Expression|Value|

+|||

+|`=-42`|`-42`|

+|`=-$(/document/merged_content/entities/0/offset)`|`-9`|

+### Addition `'+'`

+|Expression|Value|

+|||

+|`=2+2`|`4`|

+|`=2+$(/document/merged_content/entities/0/offset)`|`11`|

+### Subtraction `'-'`

+|Expression|Value|

+|||

+|`=2-1`|`1`|

+|`=$(/document/merged_content/entities/0/offset)-2`|`7`|

+### Multiplication `'*'`

+|Expression|Value|

+|||

+|`=2*3`|`6`|

+|`=$(/document/merged_content/entities/0/offset)*2`|`18`|

+### Division `'/'`

+|Expression|Value|

+|||

+|`=3/2`|`1.5`|

+|`=$(/document/merged_content/entities/0/offset)/3`|`3`|

+### Modulo `'%'`

+|Expression|Value|

+|||

+|`=15%4`|`3`|

+|`=$(/document/merged_content/entities/0/offset)%2`|`1`|

+### Less than, less than or equal, greater than and greater than or equal `'<'` `'<='` `'>'` `'>='`

+|Expression|Value|

+|||

+|`=15<4`|`false`|

+|`=4<=4`|`true`|

+|`=15>4`|`true`|

+|`=1>=2`|`false`|

+### Equality and non-equality `'=='` `'!='`

+|Expression|Value|

+|||

+|`=15==4`|`false`|

+|`=4==4`|`true`|

+|`=15!=4`|`true`|

+|`=1!=1`|`false`|

+### Logical operations and, or and exclusive or `'&&'` `'||'` `'^'`

+|Expression|Value|

+|||

+|`=true&&true`|`true`|

+|`=true&&false`|`false`|

+|`=true||true`|`true`|

+|`=true||false`|`true`|

+|`=false||false`|`false`|

+|`=true^false`|`true`|

+|`=true^true`|`false`|

+### Ternary operator `'?:'`

+It is possible to give an input different values based on the evaluation of a Boolean expression using the ternary operator.

+|Expression|Value|

+|||

+|`=true?"true":"false"`|`"true"`|

+|`=$(/document/merged_content/entities/0/offset)==9?"nine":"not nine"`|`"nine"`|

+### Parentheses and operator priority

+Operators are evaluated with priorities that match usual conventions: unary operators, then multiplication, division and modulo, then addition and subtraction, then comparison, then equality, and then logical operators.

+Usual associativity rules also apply.

+Parentheses can be used to change or disambiguate evaluation order.

+|Expression|Value|

+|||

+|`=3*2+5`|`11`|

+|`=3*(2+5)`|`21`|

+## See also

+A search service is hosted on Azure and is typically accessed by client applications using public network connections. While that pattern is predominant, it's not the only traffic pattern that you need to care about. Understanding all points of entry and outbound traffic is necessary background for protecting your development and production environments.

+Inbound requests that target a search service endpoint consist of:

+For inbound access to data and operations on your search service, you can implement a progression of security measures, starting with [network security features](#service-access-and-authentication). You can create either inbound rules in an IP firewall, or private endpoints that fully shield your search service from the public internet.

+Independent of network security, all inbound requests must be authenticated. Key-based authentication is the default. Alternatively, you can use Azure Active Directory and role-based access control for data plane operations (currently in preview).

+Outbound requests from a search service to other applications are typically made by indexers for text-based indexing and some aspects of AI enrichment. Outbound requests include both read and write operations:

+Outbound connections can be made using a full access connection string that includes a shared access key or a database login, or a managed identity if you're using Azure Active Directory.

+If your Azure resources are behind a firewall, you'll need to create rules that admit indexer or service requests. For resources protected by Azure Private Link, you can create a shared private link that an indexer uses to make its connection.

+Internal requests are secured and managed by Microsoft. Internal traffic consists of service-to-service calls for tasks like authentication and authorization through Azure Active Directory, diagnostic logging in Azure Monitor, private endpoint connections, and requests made to Cognitive Services for built-in skills.

+[Network security](../security/fundamentals/network-overview.md) protects resources from unauthorized access or attack by applying controls to network traffic. Azure Cognitive Search supports networking features that can be your first line of defense against unauthorized access.

+A search service is provisioned with a public endpoint that allows access using a public IP address. To restrict which traffic comes through the public endpoint, create an inbound firewall rule that admits requests from a specific IP address or a range of IP addresses. All client connections must be made through an allowed IP address, or the connection is denied.

+You can use the portal to [configure firewall access](service-configure-firewall.md).

+For more stringent security, you can establish a [private endpoint](../private-link/private-endpoint-overview.md) for Azure Cognitive Search allows a client on a [virtual network](../virtual-network/virtual-networks-overview.md) to securely access data in a search index over a [Private Link](../private-link/private-link-overview.md).

+Once a request is admitted, it must still undergo authentication and authorization that determines whether the request is permitted.

+For inbound requests to the search service, authentication is on the request (not the calling app or user) through an [API key](search-security-api-keys.md), where the key is a string composed of randomly generated numbers and letters) that proves the request is from a trustworthy source. Keys are required on every request. Submission of a valid key is considered proof the request originates from a trusted entity.

+Alternatively, there's new support for Azure Active Directory authentication and role-based authorization, [currently in preview](search-security-rbac.md), that establishes the caller (and not the request) as the authenticated identity.

+In Azure Cognitive Search, encryption starts with connections and transmissions, and extends to content stored on disk. For search services on the public internet, Azure Cognitive Search listens on HTTPS port 443. All client-to-service connections use TLS 1.2 encryption. Earlier versions (1.0 or 1.1) aren't supported.

+Service-managed encryption is a Microsoft-internal operation, based on [Azure Storage Service Encryption](../storage/common/storage-service-encryption.md), using 256-bit [AES encryption](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard). It occurs automatically on all indexing, including on incremental updates to indexes that aren't fully encrypted (created before January 2018).

+In Azure Cognitive Search, double encryption is an extension of CMK. It's understood to be two-fold encryption (once by CMK, and again by service-managed keys), and comprehensive in scope, encompassing long-term storage that is written to a data disk, and short-term storage written to temporary disks. Double encryption is implemented in services created after specific dates. For more information, see [Double encryption](search-security-manage-encryption-keys.md#double-encryption).

+## Security administration

+### Manage API keys

+### Activity and diagnostic logs

+Cognitive Search does not log user identities so you can't refer to logs for information about a specific user. However, the service does log create-read-update-delete operations, which you might be able to correlate with other logs to understand the agency of specific actions.

+For Azure Cognitive Search, there's currently one built-in definition. It's for diagnostic logging. With this built-in, you can assign a policy that identifies any search service that is missing diagnostic logging, and then turns it on. For more information, see [Azure Policy Regulatory Compliance controls for Azure Cognitive Search](security-controls-policy.md).

+| **Azure Monitor VMConnection** collected as part of the Azure Monitor [VM Insights solution](/azure/azure-monitor/vm/vminsights-overview) |`_ASim_NetworkSession_VMConnection` (regular)<br> `_Im_NetworkSession_VMConnection` (filtering) | `ASimNetworkSessionVMConnection` (regular)<br> `vimNetworkSessionVMConnection` (filtering) |

+| <a name="eventproduct"></a>**EventProduct** | Mandatory | String | The product generating the event. The value should be one of the values listed in [Vendors and Products](#vendors-and-products).<br><br>Example: `Sysmon` |

+| <a name="eventvendor"></a>**EventVendor** | Mandatory | String | The vendor of the product generating the event. The value should be one of the values listed in [Vendors and Products](#vendors-and-products).<br><br>Example: `Microsoft` <br><br> |

+## Vendors and products

+To maintain consistency, the list of allowed vendors and products is set as part of ASIM, and may not directly correspond to the value sent by the source, when available.

+The currently supported list of vendors and products used in the [EventVendor](#eventvendor) and [EventProduct](#eventproduct) fields respectively is:

+| Vendor | Products |

+| | -- |

+| Apache | Squid Proxy |

+| AWS | - CloudTrail<br> - VPC |

+| Cisco | - ASA<br> - Umbrella |

+| Corelight | Zeek |

+| GCP | Cloud DNS |

+| Infoblox | NIOS |

+| Microsoft | - AAD<br> - Azure Defender for IoT<br> - Azure Firewall<br> - Azure File Storage<br> - DNS Server<br> - M365 Defender for Endpoint<br> - NSGFlow <br> - Security Events<br> - Sharepoint 365<br>- Sysmon<br> - Sysmon for Linux<br> - VMConnection<br> - Windows Firewall<br> - WireData <br>

+| Okta | Okta |

+| Palo Alto | - PanOS<br> - CDL<br> |

+| Zscaler | - ZIA DNS<br> - ZIA Firewall<br> - ZIA Proxy |

+|||

+If you are developing a parser for a vendor or a product which are not listed here, contact the [Microsoft Sentinel](mailto:azuresentinel@microsoft.com) team to allocate a new allowed vendor and product designators.

+The Advanced Security Information Model (ASIM) is a layer that is located between these diverse sources and the user. ASIM follows the [robustness principal](https://en.wikipedia.org/wiki/Robustness_principle): **"Be strict in what you send, be flexible in what you accept"**. Using the robustness principal as design pattern, ASIM transforms Microsoft Sentinel's inconsistent and hard to use source telemetry to user friendly data.

+This article provides an overview of the Advanced Security Information Model (ASIM), its use cases and major components. Refer to the [next steps](#next-steps) section for more details.

+> Also watch the [ASIM Webinar](https://www.youtube.com/watch?v=WoGD-JeC7ng) or review the [webinar slides](https://1drv.ms/b/s!AnEPjr8tHcNmjDY1cro08Fk3KUj-?e=murYHG).

+ - **SAP version 750 or later**: Install the SAP change request *NPLK900198*

+ - **SAP version 740**: Install the SAP change request *NPLK900200*

+- **SAP Basis versions 7.50 and higher**, install NPLK900198

+- **For lower versions**, install NPLK900200

+In the Azure portal, navigate to your Service Bus namespace, switch to **Topics** in the bottom pane, and select your topic to see the **Service Bus Topic** page for your topic. On this page, you should see 10 incoming and 10 outgoing messages in the **Messages** chart.

+If you run only the send app next time, on the **Service Bus Topic** page, you see 20 incoming messages (10 new) but 10 outgoing messages.

+On this page, if you select a subscription in the bottom pane, you get to the **Service Bus Subscription** page. You can see the active message count, dead-letter message count, and more on this page. In this example, there are 10 active messages that haven't been received by a receiver yet.

+ms.devlang: python

+ms.devlang: java

+# Introduction to Autoscaling on Service Fabric managed clusters

+* The Service Fabric managed cluster resource apiVersion should be **2022-01-01** or later.

+ "metricResourceUri": "[concat('/subscriptions/',subscription().subscriptionId,'/resourceGroups/SFC_', reference(resourceId('Microsoft.ServiceFabric/managedClusters', parameters('clusterName')), '2022-01-01').clusterId,'/providers/Microsoft.Compute/virtualMachineScaleSets/',parameters('nodeType2Name'))]",

+ "metricResourceUri": "[concat('/subscriptions/',subscription().subscriptionId,'/resourceGroups/SFC_', reference(resourceId('Microsoft.ServiceFabric/managedClusters', parameters('clusterName')), '2022-01-01').clusterId,'/providers/Microsoft.Compute/virtualMachineScaleSets/',parameters('nodeType2Name'))]",

+## Enable encryption at host

+> Any temp disk associated with VM Size will *not* be used for storing any Service Fabric or application related data by default. [Stateless node types](how-to-managed-cluster-stateless-node-type.md) do support temp disks if required.

+* Use apiVersion `2021-05-01` or later version of *Microsoft.ServiceFabric/managedclusters* and *Microsoft.ServiceFabric/managedclusters/nodetypes* resources

+ "apiVersion": "[variables('sfApiVersion')]",

+ "apiVersion": "[variables('sfApiVersion')]",

+## Configure multiple managed disks

+* The Service Fabric managed cluster resource apiVersion should be **2022-01-01** or later.

+## Configure the Service Fabric data disk drive letter

+* The Service Fabric managed cluster resource apiVersion should be **2022-01-01** or later.

+## Enable IPv6

+* The Service Fabric managed cluster resource apiVersion should be **2022-01-01** or later.

+ "resources": [

+ {

+ "apiVersion": "[variables('sfApiVersion')]",

+ ]

+## Bring your own virtual network

+* The Service Fabric managed cluster resource apiVersion should be **2022-01-01** or later.

+ "apiVersion": "[variables('sfApiVersion')]",

+ ]

+## Bring your own Azure Load Balancer

+ Obtain the required `Id` property info from the existing Azure Load Balancer.

+ * The Service Fabric managed cluster resource apiVersion should be **2022-01-01** or later.

+ "resources": [

+ }

+ ]

+## Enable Accelerated Networking

+Accelerated networking enables single root I/O virtualization (SR-IOV) to a virtual machine scale set VM that is the underlying resource for node types. This high-performance path bypasses the host from the data path, which reduces latency, jitter, and CPU utilization for the most demanding network workloads. Service Fabric managed cluster node types can be provisioned with Accelerated Networking on [supported VM SKUs](../virtual-machines/sizes.md). Reference this [limitations and constraints](../virtual-network/accelerated-networking-overview.md#limitations-and-constraints) for additional considerations.

+* The Service Fabric managed cluster resource apiVersion should be **2022-01-01** or later.

+## Configure Auxiliary Subnets

+* The Service Fabric managed cluster resource apiVersion should be **2022-01-01** or later.

+ "properties": {

+ ]

+ }

+ }

+ ]

+See [full list of parameters available](/azure/templates/microsoft.servicefabric/2022-01-01/managedclusters)

+* Primary node types cannot be configured to be stateless.

+* Stateless node types require an API version of **2021-05-01** or later.

+* This will automatically set the **multipleplacementgroup** property to **true** which you can [learn more here](how-to-managed-cluster-large-virtual-machine-scale-sets.md).

+* This enables support for up to 1000 nodes for the given node type.

+* Stateless node types can utilize a VM SKU temporary disk.

+## Temporary disk support

+Stateless node types can be configured to use temporary disk as the data disk instead of a Managed Disk. Using a temporary disk can reduce costs for stateless workloads. To configure a stateless node type to use the temporary disk set the **useTempDataDisk** property to **true**.

+* Temporary disk size must be 32GB or more. The size of the temporary disk depends on the VM size.

+* The temporary disk is not encrypted by server side encryption unless you enable encryption at host.

+* The Service Fabric managed cluster resource apiVersion should be **2022-01-01** or later.

+```json

+{

+ "apiVersion": "[variables('sfApiVersion')]",

+ "type": "Microsoft.ServiceFabric/managedclusters/nodetypes",

+ "name": "[concat(parameters('clusterName'), '/', parameters('nodeTypeName'))]",

+ "location": "[resourcegroup().location]",

+ "dependsOn": [

+ "[concat('Microsoft.ServiceFabric/managedclusters/', parameters('clusterName'))]"

+ ],

+ "properties": {

+ "isStateless": true,

+ "isPrimary": false,

+ "vmImagePublisher": "[parameters('vmImagePublisher')]",

+ "vmImageOffer": "[parameters('vmImageOffer')]",

+ "vmImageSku": "[parameters('vmImageSku')]",

+ "vmImageVersion": "[parameters('vmImageVersion')]",

+ "vmSize": "[parameters('nodeTypeSize')]",

+ "vmInstanceCount": "[parameters('nodeTypeVmInstanceCount')]",

+ "useTempDataDisk": true

+ }

+}

+```