+> Algeria (DZ), Austria (AT), Azerbaijan (AZ), Bahrain (BH), Belarus (BY), Belgium (BE), Bulgaria (BG), Croatia (HR), Cyprus (CY), Czech Republic (CZ), Denmark (DK), Egypt (EG), Estonia (EE), Finland (FT), France (FR), Germany (DE), Greece (GR), Hungary (HU), Iceland (IS), Ireland (IE), Israel (IL), Italy (IT), Jordan (JO), Kazakhstan (KZ), Kenya (KE), Kuwait (KW), Latvia (LV), Lebanon (LB), Liechtenstein (LI), Lithuania (LT), Luxembourg (LU), North Macedonia (ML), Malta (MT), Montenegro (ME), Morocco (MA), Netherlands (NL), Nigeria (NG), Norway (NO), Oman (OM), Pakistan (PK), Poland (PL), Portugal (PT), Qatar (QA), Romania (RO), Russia (RU), Saudi Arabia (SA), Serbia (RS), Slovakia (SK), Slovenia (ST), South Africa (ZA), Spain (ES), Sweden (SE), Switzerland (CH), Tunisia (TN), T├╝rkiye (TR), Ukraine (UA), United Arab Emirates (AE) and United Kingdom (GB)

+If you don't already have an iOS Swift application, set up a new project by doing the following steps:

+1. Use [CocoaPods](https://cocoapods.org/) to install the MSAL library. In the same folder as your project's *.xcodeproj* file, if the *podfile* file doesn't exist, create an empty file and name it *podfile*. Add the following code to the *podfile* file:

+Choose a `UIViewController` where users authenticate. In your `UIViewController`, merge the code with the [code that's provided in GitHub](https://github.com/Azure-Samples/active-directory-b2c-ios-swift-native-msal/blob/vNext/MSALiOS/ViewController.swift).

+The `acquireTokenSilent` method does the following actions:

+Add the SPA app `https://docsupdatetracker.net/index.html` file. This file implements a user interface that's built with a Bootstrap framework, and it imports script files for configuration, authentication, and web API calls.

+ <LocalizedString ElementType="UxElement" StringId="countryList">{"DEFAULT":"Country/Region","AF":"Afghanistan","AX":"Åland Islands","AL":"Albania","DZ":"Algeria","AS":"American Samoa","AD":"Andorra","AO":"Angola","AI":"Anguilla","AQ":"Antarctica","AG":"Antigua and Barbuda","AR":"Argentina","AM":"Armenia","AW":"Aruba","AU":"Australia","AT":"Austria","AZ":"Azerbaijan","BS":"Bahamas","BH":"Bahrain","BD":"Bangladesh","BB":"Barbados","BY":"Belarus","BE":"Belgium","BZ":"Belize","BJ":"Benin","BM":"Bermuda","BT":"Bhutan","BO":"Bolivia","BQ":"Bonaire","BA":"Bosnia and Herzegovina","BW":"Botswana","BV":"Bouvet Island","BR":"Brazil","IO":"British Indian Ocean Territory","VG":"British Virgin Islands","BN":"Brunei","BG":"Bulgaria","BF":"Burkina Faso","BI":"Burundi","CV":"Cabo Verde","KH":"Cambodia","CM":"Cameroon","CA":"Canada","KY":"Cayman Islands","CF":"Central African Republic","TD":"Chad","CL":"Chile","CN":"China","CX":"Christmas Island","CC":"Cocos (Keeling) Islands","CO":"Colombia","KM":"Comoros","CG":"Congo","CD":"Congo (DRC)","CK":"Cook Islands","CR":"Costa Rica","CI":"Côte d'Ivoire","HR":"Croatia","CU":"Cuba","CW":"Curaçao","CY":"Cyprus","CZ":"Czech Republic","DK":"Denmark","DJ":"Djibouti","DM":"Dominica","DO":"Dominican Republic","EC":"Ecuador","EG":"Egypt","SV":"El Salvador","GQ":"Equatorial Guinea","ER":"Eritrea","EE":"Estonia","ET":"Ethiopia","FK":"Falkland Islands","FO":"Faroe Islands","FJ":"Fiji","FI":"Finland","FR":"France","GF":"French Guiana","PF":"French Polynesia","TF":"French Southern Territories","GA":"Gabon","GM":"Gambia","GE":"Georgia","DE":"Germany","GH":"Ghana","GI":"Gibraltar","GR":"Greece","GL":"Greenland","GD":"Grenada","GP":"Guadeloupe","GU":"Guam","GT":"Guatemala","GG":"Guernsey","GN":"Guinea","GW":"Guinea-Bissau","GY":"Guyana","HT":"Haiti","HM":"Heard Island and McDonald Islands","HN":"Honduras","HK":"Hong Kong SAR","HU":"Hungary","IS":"Iceland","IN":"India","ID":"Indonesia","IR":"Iran","IQ":"Iraq","IE":"Ireland","IM":"Isle of Man","IL":"Israel","IT":"Italy","JM":"Jamaica","JP":"Japan","JE":"Jersey","JO":"Jordan","KZ":"Kazakhstan","KE":"Kenya","KI":"Kiribati","KR":"Korea","KW":"Kuwait","KG":"Kyrgyzstan","LA":"Laos","LV":"Latvia","LB":"Lebanon","LS":"Lesotho","LR":"Liberia","LY":"Libya","LI":"Liechtenstein","LT":"Lithuania","LU":"Luxembourg","MO":"Macao SAR","MK":"North Macedonia","MG":"Madagascar","MW":"Malawi","MY":"Malaysia","MV":"Maldives","ML":"Mali","MT":"Malta","MH":"Marshall Islands","MQ":"Martinique","MR":"Mauritania","MU":"Mauritius","YT":"Mayotte","MX":"Mexico","FM":"Micronesia","MD":"Moldova","MC":"Monaco","MN":"Mongolia","ME":"Montenegro","MS":"Montserrat","MA":"Morocco","MZ":"Mozambique","MM":"Myanmar","NA":"Namibia","NR":"Nauru","NP":"Nepal","NL":"Netherlands","NC":"New Caledonia","NZ":"New Zealand","NI":"Nicaragua","NE":"Niger","NG":"Nigeria","NU":"Niue","NF":"Norfolk Island","KP":"North Korea","MP":"Northern Mariana Islands","NO":"Norway","OM":"Oman","PK":"Pakistan","PW":"Palau","PS":"Palestinian Authority","PA":"Panama","PG":"Papua New Guinea","PY":"Paraguay","PE":"Peru","PH":"Philippines","PN":"Pitcairn Islands","PL":"Poland","PT":"Portugal","PR":"Puerto Rico","QA":"Qatar","RE":"Réunion","RO":"Romania","RU":"Russia","RW":"Rwanda","BL":"Saint Barthélemy","KN":"Saint Kitts and Nevis","LC":"Saint Lucia","MF":"Saint Martin","PM":"Saint Pierre and Miquelon","VC":"Saint Vincent and the Grenadines","WS":"Samoa","SM":"San Marino","ST":"São Tomé and Príncipe","SA":"Saudi Arabia","SN":"Senegal","RS":"Serbia","SC":"Seychelles","SL":"Sierra Leone","SG":"Singapore","SX":"Sint Maarten","SK":"Slovakia","SI":"Slovenia","SB":"Solomon Islands","SO":"Somalia","ZA":"South Africa","GS":"South Georgia and South Sandwich Islands","SS":"South Sudan","ES":"Spain","LK":"Sri Lanka","SH":"St Helena, Ascension, Tristan da Cunha","SD":"Sudan","SR":"Suriname","SJ":"Svalbard","SZ":"Swaziland","SE":"Sweden","CH":"Switzerland","SY":"Syria","TW":"Taiwan","TJ":"Tajikistan","TZ":"Tanzania","TH":"Thailand","TL":"Timor-Leste","TG":"Togo","TK":"Tokelau","TO":"Tonga","TT":"Trinidad and Tobago","TN":"Tunisia","TR":"Türkiye","TM":"Turkmenistan","TC":"Turks and Caicos Islands","TV":"Tuvalu","UM":"U.S. Outlying Islands","VI":"U.S. Virgin Islands","UG":"Uganda","UA":"Ukraine","AE":"United Arab Emirates","GB":"United Kingdom","US":"United States","UY":"Uruguay","UZ":"Uzbekistan","VU":"Vanuatu","VA":"Vatican City","VE":"Venezuela","VN":"Vietnam","WF":"Wallis and Futuna","YE":"Yemen","ZM":"Zambia","ZW":"Zimbabwe"}</LocalizedString>

+- **Expression** - the target attribute is populated based on the result of a script-like expression. For more information about expressions, see [Writing Expressions for Attribute-Mappings in Azure Active Directory](../app-provisioning/functions-for-customizing-application-data.md).

+In the previous section, you were introduced to the attribute-mapping type property.

+Along with this property, attribute-mappings also supports the attributes:

+- **Default value if null (optional)** - The value that is passed to the target system if the source attribute is null. This value is only provisioned when a user is created. The "default value when null" isn't provisioned when updating an existing user. For example, add a default value for job title, when creating a user, with the expression: `Switch(IsPresent([jobTitle]), "DefaultValue", "True", [jobTitle])`. For more information about expressions, see [Reference for writing expressions for attribute mappings in Azure Active Directory](../app-provisioning/functions-for-customizing-application-data.md).

+- **Matching precedence** ΓÇô Multiple matching attributes can be set. When there are multiple, they're evaluated in the order defined by this field. As soon as a match is found, no further matching attributes are evaluated. While you can set as many matching attributes as you would like, consider whether the attributes you're using as matching attributes are truly unique and need to be matching attributes. Generally customers have one or two matching attributes in their configuration.

+- **Multiple attributes can be used as matching attributes:** You can define multiple attributes to be evaluated when matching users and the order in which they're evaluated (defined as matching precedence in the UI). If for example, you define three attributes as matching attributes, and a user is uniquely matched after evaluating the first two attributes, the service won't evaluate the third attribute. The service evaluates matching attributes in the order specified and stops evaluating when a match is found.

+- Azure Active Directory ([Azure AD Graph API default attributes](/previous-versions/azure/ad/graph/api/entity-and-complex-type-reference#user-entity) and custom directory extensions are supported). For more information about creating extensions, see [Syncing extension attributes for Azure Active Directory Application Provisioning](./user-provisioning-sync-attributes-for-mapping.md) and [Known issues for provisioning in Azure Active Directory](./known-issues.md).

+- Azure Active Directory supports writeback to Workday or SuccessFactors for XPATH and JSONPath metadata. Azure Active Directory doesn't support new Workday or SuccessFactors attributes not included in the default schema.

+For SCIM applications, the attribute name must follow the pattern shown in the example. The "CustomExtensionName" and "CustomAttribute" can be customized per your application's requirements, for example: urn:ietf:params:scim:schemas:extension:CustomExtensionName:2.0:User:CustomAttribute

+Use the steps in the example to provision roles for a user to your application. Note that the description is specific to custom SCIM applications. For gallery applications such as Salesforce and ServiceNow, use the predefined role mappings. The bullets describe how to transform the AppRoleAssignments attribute to the format your application expects.

+ Then use the AppRoleAssignmentsComplex expression to map to the custom role attribute as shown in the image:

+Certain attributes such as phoneNumbers and emails are multi-value attributes where you may need to specify different types of phone numbers or emails. Use the expression for multi-value attributes. It allows you to specify the attribute type and map that to the corresponding Azure AD user attribute for the value.

+- The role attribute typically needs to be mapped using an expression, rather than a direct mapping. For more information about role mapping, see [Provisioning a role to a SCIM app](#Provisioning a role to a SCIM app).

+| HID | ![n] | ![y]| ![y]| ![n]| ![n] | https://www.hidglobal.com/products/crescendo-key |

+| Hypr | ![y] | ![y]| ![n]| ![y]| ![n] | https://www.hypr.com/true-passwordless-mfa |

+| Token Ring | ![y] | ![n]| ![y]| ![n]| ![n] | https://www.tokenring.com/ |

+| WiSECURE Technologies | ![n] | ![y]| ![n]| ![n]| ![n] | https://wisecure-tech.com/en-us/zero-trust/fido/authtron |

+| HID | ![n] | ![y]| ![y]| ![n]| ![n] | https://www.hidglobal.com/products/crescendo-key |

+| Hypr | ![y] | ![y]| ![n]| ![y]| ![n] | https://www.hypr.com/true-passwordless-mfa |

+| Identiv | ![n] | ![y]| ![y]| ![n]| ![n] | https://www.identiv.com/products/logical-access-control/utrust-fido2-security-keys/nfc |

+| Movenda | ![y] | ![n]| ![y]| ![y]| ![n] | https://www.movenda.com/en/authentication/fido2/overview |

+| Token Ring | ![y] | ![n]| ![y]| ![n]| ![n] | https://www.tokenring.com/ |

+| WiSECURE Technologies | ![n] | ![y]| ![n]| ![n]| ![n] | https://wisecure-tech.com/en-us/zero-trust/fido/authtron |

+## Guided walkthrough

+For a guided walkthrough of many of the recommendations in this article, see the [Microsoft 365 Configure multifactor authentication guided walkthrough](https://go.microsoft.com/fwlink/?linkid=2221401).

+### Guided walkthrough

+For a guided walkthrough of many of the recommendations in this article, see the [Plan your self-service password reset deployment](https://go.microsoft.com/fwlink/?linkid=2221600) guide.

+> If you want your location policies to be enforced in real time by continuous access evaluation, use only the [IP based Conditional Access location condition](../conditional-access/location-condition.md) and configure all IP addresses, **including both IPv4 and IPv6**, that can be seen by your identity provider and resources provider. Do not use country/region location conditions or the trusted ips feature that is available in Azure AD Multifactor Authentication's service settings page.

+With this preview, we're giving you the ability to create a Conditional Access policy to require token protection for sign-in tokens (refresh tokens) for specific services. We support token protection for sign-in tokens in Conditional Access for desktop applications accessing Exchange Online and SharePoint Online on Windows devices.

+> [!NOTE]

+> We may interchange sign in tokens and refresh tokens in this content. This preview doesn't currently support access tokens or web cookies.

+Locations exist in the Azure portal under **Azure Active Directory** > **Security** > **Conditional Access** > **Named locations**. These named network locations may include locations like an organization's headquarters network ranges, VPN network ranges, or ranges that you wish to block. Named locations are defined by IPv4 and IPv6 address ranges or by countries/regions.

+To define a named location by country/region, you need to provide:

+- Add one or more countries/regions.

+If you select **Determine location by IP address**, the system collects the IP address of the device the user is signing into. When a user signs in, Azure AD resolves the user's IPv4 or [IPv6](/troubleshoot/azure/active-directory/azure-ad-ipv6-support) address (starting April 3, 2023) to a country or region, and the mapping updates periodically. Organizations can use named locations defined by countries/regions to block traffic from countries/regions where they don't do business.

+1. In the **Storage Accounts** window that appears, select **Create**.

+1. For **Performance**, select the **Standard** option.

+1. For **Redundancy**, select the **Locally-redundant storage (LRS)** option from the dropdown.

+1. Select **Review** to review your storage account settings and create the account.

+1. In the left menu for the storage account, scroll to the **Data storage** section, and then select **Containers**.

+1. Select **Create** to create the container.

+1. In the **Assignment type** tab, select **Job function type** and then **Next**.

+1. In the **Role** tab, select **Storage Blob Data Contributor** role from the dropdown and then select **Next**.

+1. In the **Members** tab, select **Assign access to** -> **Managed identity** and then select **Members** -> **Select members**. In the **Select managed identities** window, find and select the managed identity created for your App Service in the **Managed identity** dropdown. Select the **Select** button.

+1. Select **Review and assign** and then select **Review and assign** once more.

+

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

+> [!IMPORTANT]

+If users need to use multi-factor authentication (MFA) to log in to the application, they will be blocked instead.

+The value of the `NameID` element must exactly match the `NameID` of the user that is being signed out.

+> [!NOTE]

+> During SAML logout request, the `NameID` value is not considered by Azure Active Directory.

+> If a single user session is active, Azure Active Directory will automatically select that session and the SAML logout will proceed.

+> If multiple user sessions are active, Azure Active Directory will enumerate the active sessions for user selection. After user selection, the SAML logout will proceed.

+| Property | `AzureADMyOrg` | `AzureADMultipleOrgs` | `AzureADandPersonalMicrosoftAccount` and `PersonalMicrosoftAccount` |

+| -- | | | -- |

+| Application ID URI (`identifierURIs`) | Must be unique in the tenant <br><br> `urn://` schemes are supported <br><br> Wildcards aren't supported <br><br> Query strings and fragments are supported <br><br> Maximum length of 255 characters <br><br> No limit\* on number of identifierURIs | Must be globally unique <br><br> `urn://` schemes are supported <br><br> Wildcards aren't supported <br><br> Query strings and fragments are supported <br><br> Maximum length of 255 characters <br><br> No limit\* on number of identifierURIs | Must be globally unique <br><br> urn:// schemes aren't supported <br><br> Wildcards, fragments, and query strings aren't supported <br><br> Maximum length of 120 characters <br><br> Maximum of 50 identifierURIs |

+| National clouds | Supported | Supported | Not supported |

+| Certificates (`keyCredentials`) | Symmetric signing key | Symmetric signing key | Encryption and asymmetric signing key |

+| Client secrets (`passwordCredentials`) | No limit\* | No limit\* | If liveSDK is enabled: Maximum of two client secrets |

+| Redirect URIs (`replyURLs`) | See [Redirect URI/reply URL restrictions and limitations](reply-url.md) for more info. | | |

+| API permissions (`requiredResourceAccess`) | No more than 50 APIs (resource apps) from the same tenant as the application, no more than 10 APIs from other tenants, and no more than 400 permissions total across all APIs. | No more than 50 APIs (resource apps) from the same tenant as the application, no more than 10 APIs from other tenants, and no more than 400 permissions total across all APIs. | Maximum of 50 resources per application and 30 permissions per resource (for example, Microsoft Graph). Total limit of 200 per application (resources x permissions). |

+| Scopes defined by this API (`oauth2Permissions`) | Maximum scope name length of 120 characters <br><br> No limit\* on the number of scopes defined | Maximum scope name length of 120 characters <br><br> No limit\* on the number of scopes defined | Maximum scope name length of 40 characters <br><br> Maximum of 100 scopes defined |

+| Authorized client applications (`preAuthorizedApplications`) | No limit\* | No limit\* | Total maximum of 500 <br><br> Maximum of 100 client apps defined <br><br> Maximum of 30 scopes defined per client |

+| appRoles | Supported <br> No limit\* | Supported <br> No limit\* | Not supported |

+| Front-channel logout URL | `https://localhost` is allowed <br><br> `http` scheme isn't allowed <br><br> Maximum length of 255 characters | `https://localhost` is allowed <br><br> `http` scheme isn't allowed <br><br> Maximum length of 255 characters | `https://localhost` is allowed, `http://localhost` fails <br><br> `http` scheme isn't allowed <br><br> Maximum length of 255 characters <br><br> Wildcards aren't supported |

+| Display name | Maximum length of 120 characters | Maximum length of 120 characters | Maximum length of 90 characters |

+| Tags | Individual tag size must be between 1 and 256 characters (inclusive) <br><br> No whitespaces or duplicate tags allowed <br><br> No limit\* on number of tags | Individual tag size must be between 1 and 256 characters (inclusive) <br><br> No whitespaces or duplicate tags allowed <br><br> No limit\* on number of tags | Individual tag size must be between 1 and 256 characters (inclusive) <br><br> No whitespaces or duplicate tags allowed <br><br> No limit\* on number of tags |

+>This information last updated on March 23rd, 2023.<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).

+| Privacy Management ΓÇô risk| PRIVACY_MANAGEMENT_RISK | e42bc969-759a-4820-9283-6b73085b68e6 | MIP_S_Exchange (cd31b152-6326-4d1b-ae1b-997b625182e6)<br/>PRIVACY_MANGEMENT_RISK (f281fb1f-99a7-46ab-9edb-ffd74e260ed3)<br/>PRIVACY_MANGEMENT_RISK_EXCHANGE (ebb17a6e-6002-4f65-acb0-d386480cebc1) | Data Classification in Microsoft 365 (cd31b152-6326-4d1b-ae1b-997b625182e6)<br/>Priva - Risk (f281fb1f-99a7-46ab-9edb-ffd74e260ed3)<br/>Priva - Risk (Exchange) (ebb17a6e-6002-4f65-acb0-d386480cebc1) |

+| Privacy Management - risk for EDU | PRIVACY_MANAGEMENT_RISK_EDU | dcdbaae7-d8c9-40cb-8bb1-62737b9e5a86 | MIP_S_Exchange (cd31b152-6326-4d1b-ae1b-997b625182e6)<br/>PRIVACY_MANGEMENT_RISK (f281fb1f-99a7-46ab-9edb-ffd74e260ed3)<br/>PRIVACY_MANGEMENT_RISK_EXCHANGE (ebb17a6e-6002-4f65-acb0-d386480cebc1) | Data Classification in Microsoft 365 (cd31b152-6326-4d1b-ae1b-997b625182e6)<br/>Priva - Risk (f281fb1f-99a7-46ab-9edb-ffd74e260ed3)<br/>Priva - Risk (Exchange) (ebb17a6e-6002-4f65-acb0-d386480cebc1) |

+| Privacy Management - risk GCC | PRIVACY_MANAGEMENT_RISK_GCC | 046f7d3b-9595-4685-a2e8-a2832d2b26aa | MIP_S_Exchange (cd31b152-6326-4d1b-ae1b-997b625182e6)<br/>PRIVACY_MANGEMENT_RISK (f281fb1f-99a7-46ab-9edb-ffd74e260ed3)<br/>PRIVACY_MANGEMENT_RISK_EXCHANGE (ebb17a6e-6002-4f65-acb0-d386480cebc1) | Data Classification in Microsoft 365 (cd31b152-6326-4d1b-ae1b-997b625182e6)<br/>Priva - Risk (f281fb1f-99a7-46ab-9edb-ffd74e260ed3)<br/>Priva - Risk (Exchange) (ebb17a6e-6002-4f65-acb0-d386480cebc1) |

+| Privacy Management - risk_USGOV_DOD | PRIVACY_MANAGEMENT_RISK_USGOV_DOD | 83b30692-0d09-435c-a455-2ab220d504b9 | MIP_S_Exchange (cd31b152-6326-4d1b-ae1b-997b625182e6)<br/>PRIVACY_MANGEMENT_RISK (f281fb1f-99a7-46ab-9edb-ffd74e260ed3)<br/>PRIVACY_MANGEMENT_RISK_EXCHANGE (ebb17a6e-6002-4f65-acb0-d386480cebc1) | Data Classification in Microsoft 365 (cd31b152-6326-4d1b-ae1b-997b625182e6)<br/>Priva - Risk (f281fb1f-99a7-46ab-9edb-ffd74e260ed3)<br/>Priva - Risk (Exchange) (ebb17a6e-6002-4f65-acb0-d386480cebc1) |

+| Privacy Management - risk_USGOV_GCCHIGH | PRIVACY_MANAGEMENT_RISK_USGOV_GCCHIGH | 787d7e75-29ca-4b90-a3a9-0b780b35367c | MIP_S_Exchange (cd31b152-6326-4d1b-ae1b-997b625182e6)<br/>PRIVACY_MANGEMENT_RISK (f281fb1f-99a7-46ab-9edb-ffd74e260ed3)<br/>PRIVACY_MANGEMENT_RISK_EXCHANGE (ebb17a6e-6002-4f65-acb0-d386480cebc1) | Data Classification in Microsoft 365 (cd31b152-6326-4d1b-ae1b-997b625182e6)<br/>Priva - Risk (f281fb1f-99a7-46ab-9edb-ffd74e260ed3)<br/>Priva - Risk (Exchange) (ebb17a6e-6002-4f65-acb0-d386480cebc1) |

+| Privacy Management - subject rights request (1) | PRIVACY_MANAGEMENT_SUB_RIGHTS_REQ_1_V2 | d9020d1c-94ef-495a-b6de-818cbbcaa3b8 | MIP_S_EXCHANGE_CO (5b96ffc4-3853-4cf4-af50-e38505080f6b)<br/>PRIVACY_MANGEMENT_DSR_EXCHANGE_1 (93d24177-c2c3-408a-821d-3d25dfa66e7a)<br/>PRIVACY_MANGEMENT_DSR_1 (07a4098c-3f2d-427f-bfe2-5889ed75dd7b) | Data Classification in Microsoft 365 - Company Level (MIP_S_EXCHANGE_CO)<br/>Privacy Management - Subject Rights Request (1 - Exchange) (PRIVACY_MANGEMENT_DSR_EXCHANGE_1)<br/>Privacy Management - Subject Rights Request (1) (PRIVACY_MANGEMENT_DSR_1) |

+| Privacy Management - subject rights request (1) for EDU | PRIVACY_MANAGEMENT_SUB_RIGHTS_REQ_1_EDU_V2 | 475e3e81-3c75-4e07-95b6-2fed374536c8 | MIP_S_EXCHANGE_CO (5b96ffc4-3853-4cf4-af50-e38505080f6b)<br/>PRIVACY_MANGEMENT_DSR_EXCHANGE_1 (93d24177-c2c3-408a-821d-3d25dfa66e7a)<br/>PRIVACY_MANGEMENT_DSR_1 (07a4098c-3f2d-427f-bfe2-5889ed75dd7b) | Data Classification in Microsoft 365 - Company Level (5b96ffc4-3853-4cf4-af50-e38505080f6b)<br/>Privacy Management - Subject Rights Request (1 - Exchange) (93d24177-c2c3-408a-821d-3d25dfa66e7a)<br/>Privacy Management - Subject Rights Request (1) (07a4098c-3f2d-427f-bfe2-5889ed75dd7b) |

+| Privacy Management - subject rights request (1) GCC | PRIVACY_MANAGEMENT_SUB_RIGHTS_REQ_1_V2_GCC | 017fb6f8-00dd-4025-be2b-4eff067cae72 | MIP_S_EXCHANGE_CO (5b96ffc4-3853-4cf4-af50-e38505080f6b)<br/>PRIVACY_MANGEMENT_DSR_EXCHANGE_1 (93d24177-c2c3-408a-821d-3d25dfa66e7a)<br/>PRIVACY_MANGEMENT_DSR_1 (07a4098c-3f2d-427f-bfe2-5889ed75dd7b) | Data Classification in Microsoft 365 - Company Level (5b96ffc4-3853-4cf4-af50-e38505080f6b)<br/>Privacy Management - Subject Rights Request (1 - Exchange) (93d24177-c2c3-408a-821d-3d25dfa66e7a)<br/Privacy Management - Subject Rights Request (1) (07a4098c-3f2d-427f-bfe2-5889ed75dd7b) |

+| Privacy Management - subject rights request (1) USGOV_DOD | PRIVACY_MANAGEMENT_SUB_RIGHTS_REQ_1_V2_USGOV_DOD | d3c841f3-ea93-4da2-8040-6f2348d20954 | MIP_S_EXCHANGE_CO (5b96ffc4-3853-4cf4-af50-e38505080f6b)<br/>PRIVACY_MANGEMENT_DSR_EXCHANGE_1 (93d24177-c2c3-408a-821d-3d25dfa66e7a)<br/>PRIVACY_MANGEMENT_DSR_1 (07a4098c-3f2d-427f-bfe2-5889ed75dd7b) | Data Classification in Microsoft 365 - Company Level (5b96ffc4-3853-4cf4-af50-e38505080f6b)<br/>Privacy Management - Subject Rights Request (1 - Exchange) (93d24177-c2c3-408a-821d-3d25dfa66e7a)<br/>Privacy Management - Subject Rights Request (1) (07a4098c-3f2d-427f-bfe2-5889ed75dd7b) |

+| Privacy Management - subject rights request (1) USGOV_GCCHIGH | PRIVACY_MANAGEMENT_SUB_RIGHTS_REQ_1_V2_USGOV_GCCHIGH | 706d2425-6170-4818-ba08-2ad8f1d2d078 | MIP_S_EXCHANGE_CO (5b96ffc4-3853-4cf4-af50-e38505080f6b)<br/>PRIVACY_MANGEMENT_DSR_EXCHANGE_1 (93d24177-c2c3-408a-821d-3d25dfa66e7a)<br/>PRIVACY_MANGEMENT_DSR_1 (07a4098c-3f2d-427f-bfe2-5889ed75dd7b) | Data Classification in Microsoft 365 - Company Level (5b96ffc4-3853-4cf4-af50-e38505080f6b)<br/>Privacy Management - Subject Rights Request (1 - Exchange) (93d24177-c2c3-408a-821d-3d25dfa66e7a)<br/>Privacy Management - Subject Rights Request (1) (07a4098c-3f2d-427f-bfe2-5889ed75dd7b) |

+| Privacy Management - subject rights request (10) | PRIVACY_MANAGEMENT_SUB_RIGHTS_REQ_10_V2 | 78ea43ac-9e5d-474f-8537-4abb82dafe27 | MIP_S_EXCHANGE_CO (5b96ffc4-3853-4cf4-af50-e38505080f6b)<br/>PRIVACY_MANGEMENT_DSR_EXCHANGE_10 (f0241705-7b44-4401-a6b6-7055062b5b03)<br/>PRIVACY_MANGEMENT_DSR_10 (74853901-d7a9-428e-895d-f4c8687a9f0b) | Data Classification in Microsoft 365 - Company Level (5b96ffc4-3853-4cf4-af50-e38505080f6b)<br/>Privacy Management - Subject Rights Request (10 - Exchange) (f0241705-7b44-4401-a6b6-7055062b5b03)<br/>Privacy Management - Subject Rights Request (10) (74853901-d7a9-428e-895d-f4c8687a9f0b) |

+| Privacy Management - subject rights request (10) for EDU | PRIVACY_MANAGEMENT_SUB_RIGHTS_REQ_10_EDU_V2 | e001d9f1-5047-4ebf-8927-148530491f83 | MIP_S_EXCHANGE_CO (5b96ffc4-3853-4cf4-af50-e38505080f6b)<br/>PRIVACY_MANGEMENT_DSR_EXCHANGE_10 (f0241705-7b44-4401-a6b6-7055062b5b03)<br/>PRIVACY_MANGEMENT_DSR_10 (74853901-d7a9-428e-895d-f4c8687a9f0b) | Data Classification in Microsoft 365 - Company Level (5b96ffc4-3853-4cf4-af50-e38505080f6b)<br/>Privacy Management - Subject Rights Request (10 - Exchange) (f0241705-7b44-4401-a6b6-7055062b5b03)<br/>Privacy Management - Subject Rights Request (10) (74853901-d7a9-428e-895d-f4c8687a9f0b) |

+| Privacy Management - subject rights request (10) GCC | PRIVACY_MANAGEMENT_SUB_RIGHTS_REQ_10_V2_GCC | a056b037-1fa0-4133-a583-d05cff47d551 | MIP_S_EXCHANGE_CO (5b96ffc4-3853-4cf4-af50-e38505080f6b)<br/>PRIVACY_MANGEMENT_DSR_EXCHANGE_10 (f0241705-7b44-4401-a6b6-7055062b5b03)<br/>PRIVACY_MANGEMENT_DSR_10 (74853901-d7a9-428e-895d-f4c8687a9f0b) | Data Classification in Microsoft 365 - Company Level (5b96ffc4-3853-4cf4-af50-e38505080f6b)<br/>Privacy Management - Subject Rights Request (10 - Exchange) (f0241705-7b44-4401-a6b6-7055062b5b03)<br/>Privacy Management - Subject Rights Request (10) (74853901-d7a9-428e-895d-f4c8687a9f0b) |

+| Privacy Management - subject rights request (10) USGOV_DOD | PRIVACY_MANAGEMENT_SUB_RIGHTS_REQ_10_V2_USGOV_DOD | ab28dfa1-853a-4f54-9315-f5146975ac9a | MIP_S_EXCHANGE_CO (5b96ffc4-3853-4cf4-af50-e38505080f6b)<br/>PRIVACY_MANGEMENT_DSR_EXCHANGE_10 (f0241705-7b44-4401-a6b6-7055062b5b03)<br/>PRIVACY_MANGEMENT_DSR_10 (74853901-d7a9-428e-895d-f4c8687a9f0b) | Data Classification in Microsoft 365 - Company Level (5b96ffc4-3853-4cf4-af50-e38505080f6b)<br/>Privacy Management - Subject Rights Request (10 - Exchange) (f0241705-7b44-4401-a6b6-7055062b5b03)<br/>Privacy Management - Subject Rights Request (10) (74853901-d7a9-428e-895d-f4c8687a9f0b) |

+| Privacy Management - subject rights request (10) USGOV_GCCHIGH | PRIVACY_MANAGEMENT_SUB_RIGHTS_REQ_10_V2_USGOV_GCCHIGH | f6aa3b3d-62f4-4c1d-a44f-0550f40f729c | MIP_S_EXCHANGE_CO (5b96ffc4-3853-4cf4-af50-e38505080f6b)<br/>PRIVACY_MANGEMENT_DSR_EXCHANGE_10 (f0241705-7b44-4401-a6b6-7055062b5b03)<br/>PRIVACY_MANGEMENT_DSR_10 (74853901-d7a9-428e-895d-f4c8687a9f0b) | Data Classification in Microsoft 365 - Company Level (5b96ffc4-3853-4cf4-af50-e38505080f6b)<br/>Privacy Management - Subject Rights Request (10 - Exchange) (f0241705-7b44-4401-a6b6-7055062b5b03)<br/>Privacy Management - Subject Rights Request (10) (74853901-d7a9-428e-895d-f4c8687a9f0b) |

+| Privacy Management - subject rights request (50) | PRIVACY_MANAGEMENT_SUB_RIGHTS_REQ_50 | c416b349-a83c-48cb-9529-c420841dedd6 | MIP_S_EXCHANGE_CO (5b96ffc4-3853-4cf4-af50-e38505080f6b)<br/>PRIVACY_MANGEMENT_DSR (8bbd1fea-6dc6-4aef-8abc-79af22d746e4)<br/>PRIVACY_MANGEMENT_DSR_EXCHANGE (7ca7f875-98db-4458-ab1b-47503826dd73) | Data Classification in Microsoft 365 - Company Level (5b96ffc4-3853-4cf4-af50-e38505080f6b)<br/>Privacy Management - Subject Rights Request (8bbd1fea-6dc6-4aef-8abc-79af22d746e4)<br/>Privacy Management - Subject Rights Request (Exchange) (7ca7f875-98db-4458-ab1b-47503826dd73) |

+| Privacy Management - subject rights request (50) | PRIVACY_MANAGEMENT_SUB_RIGHTS_REQ_50_V2 | f6c82f13-9554-4da1-bed3-c024cc906e02 | MIP_S_EXCHANGE_CO (5b96ffc4-3853-4cf4-af50-e38505080f6b)<br/>PRIVACY_MANGEMENT_DSR (8bbd1fea-6dc6-4aef-8abc-79af22d746e4)<br/>PRIVACY_MANGEMENT_DSR_EXCHANGE (7ca7f875-98db-4458-ab1b-47503826dd73) | Data Classification in Microsoft 365 - Company Level (5b96ffc4-3853-4cf4-af50-e38505080f6b)<br/>Privacy Management - Subject Rights Request (8bbd1fea-6dc6-4aef-8abc-79af22d746e4)<br/>Privacy Management - Subject Rights Request (Exchange) (7ca7f875-98db-4458-ab1b-47503826dd73) |

+| Privacy Management - subject rights request (50) for EDU | PRIVACY_MANAGEMENT_SUB_RIGHTS_REQ_50_EDU_V2 | ed45d397-7d61-4110-acc0-95674917bb14 | MIP_S_EXCHANGE_CO (5b96ffc4-3853-4cf4-af50-e38505080f6b)<br/>PRIVACY_MANGEMENT_DSR (8bbd1fea-6dc6-4aef-8abc-79af22d746e4)<br/>PRIVACY_MANGEMENT_DSR_EXCHANGE (7ca7f875-98db-4458-ab1b-47503826dd73) | Data Classification in Microsoft 365 - Company Level (5b96ffc4-3853-4cf4-af50-e38505080f6b)<br/>Privacy Management - Subject Rights Request (8bbd1fea-6dc6-4aef-8abc-79af22d746e4)<br/>Privacy Management - Subject Rights Request (Exchange) (7ca7f875-98db-4458-ab1b-47503826dd73) |

+| Privacy Management - subject rights request (100) | PRIVACY_MANAGEMENT_SUB_RIGHTS_REQ_100_V2 | cf4c6c3b-f863-4940-97e8-1d25e912f4c4 | MIP_S_EXCHANGE_CO (5b96ffc4-3853-4cf4-af50-e38505080f6b)<br/>PRIVACY_MANGEMENT_DSR_EXCHANGE_100 (5c221cec-2c39-435b-a1e2-7cdd7fac5913)<br/>PRIVACY_MANGEMENT_DSR_100 (500f440d-167e-4030-a3a7-8cd35421fbd8) | Data Classification in Microsoft 365 - Company Level (5b96ffc4-3853-4cf4-af50-e38505080f6b)<br/>Privacy Management - Subject Rights Request (100 - Exchange) (5c221cec-2c39-435b-a1e2-7cdd7fac5913)<br/>Privacy Management - Subject Rights Request (100) (500f440d-167e-4030-a3a7-8cd35421fbd8) |

+| Privacy Management - subject rights request (100) for EDU | PRIVACY_MANAGEMENT_SUB_RIGHTS_REQ_100_EDU_V2 | 9b85b4f0-92d9-4c3d-b230-041520cb1046 | MIP_S_EXCHANGE_CO (5b96ffc4-3853-4cf4-af50-e38505080f6b)<br/>PRIVACY_MANGEMENT_DSR_EXCHANGE_100 (5c221cec-2c39-435b-a1e2-7cdd7fac5913)<br/>PRIVACY_MANGEMENT_DSR_100 (500f440d-167e-4030-a3a7-8cd35421fbd8) | Data Classification in Microsoft 365 - Company Level (5b96ffc4-3853-4cf4-af50-e38505080f6b)<br/>Privacy Management - Subject Rights Request (100 - Exchange) (5c221cec-2c39-435b-a1e2-7cdd7fac5913)<br/>Privacy Management - Subject Rights Request (100) (500f440d-167e-4030-a3a7-8cd35421fbd8) |

+| Privacy Management - subject rights request (100) GCC | PRIVACY_MANAGEMENT_SUB_RIGHTS_REQ_100_V2_GCC | 91bbc479-4c2c-4210-9c88-e5b468c35b83 | MIP_S_EXCHANGE_CO (5b96ffc4-3853-4cf4-af50-e38505080f6b)<br/>PRIVACY_MANGEMENT_DSR_EXCHANGE_100 (5c221cec-2c39-435b-a1e2-7cdd7fac5913)<br/>PRIVACY_MANGEMENT_DSR_100 (500f440d-167e-4030-a3a7-8cd35421fbd8) | Data Classification in Microsoft 365 - Company Level (5b96ffc4-3853-4cf4-af50-e38505080f6b)<br/>Privacy Management - Subject Rights Request (100 - Exchange) (5c221cec-2c39-435b-a1e2-7cdd7fac5913)<br/>Privacy Management - Subject Rights Request (100) (500f440d-167e-4030-a3a7-8cd35421fbd8) |

+| Privacy Management - subject rights request (100) USGOV_DOD | PRIVACY_MANAGEMENT_SUB_RIGHTS_REQ_100_V2_USGOV_DOD | ba6e69d5-ba2e-47a7-b081-66c1b8e7e7d4 | MIP_S_EXCHANGE_CO (5b96ffc4-3853-4cf4-af50-e38505080f6b)<br/>PRIVACY_MANGEMENT_DSR_EXCHANGE_100 (5c221cec-2c39-435b-a1e2-7cdd7fac5913)<br/>PRIVACY_MANGEMENT_DSR_100 (500f440d-167e-4030-a3a7-8cd35421fbd8) | Data Classification in Microsoft 365 - Company Level (5b96ffc4-3853-4cf4-af50-e38505080f6b)<br/>Privacy Management - Subject Rights Request (100 - Exchange) (5c221cec-2c39-435b-a1e2-7cdd7fac5913)<br/>Privacy Management - Subject Rights Request (100) (500f440d-167e-4030-a3a7-8cd35421fbd8) |

+| Privacy Management - subject rights request (100) USGOV_GCCHIGH | PRIVACY_MANAGEMENT_SUB_RIGHTS_REQ_100_V2_USGOV_GCCHIGH | cee36ce4-cc31-481f-8cab-02765d3e441f | MIP_S_EXCHANGE_CO (5b96ffc4-3853-4cf4-af50-e38505080f6b)<br/>PRIVACY_MANGEMENT_DSR_EXCHANGE_100 (5c221cec-2c39-435b-a1e2-7cdd7fac5913)<br/>PRIVACY_MANGEMENT_DSR_100 (500f440d-167e-4030-a3a7-8cd35421fbd8) | Data Classification in Microsoft 365 - Company Level (5b96ffc4-3853-4cf4-af50-e38505080f6b)<br/>Privacy Management - Subject Rights Request (100 - Exchange) (5c221cec-2c39-435b-a1e2-7cdd7fac5913)<br/>Privacy Management - Subject Rights Request (100) (500f440d-167e-4030-a3a7-8cd35421fbd8) |

+Azure Active Directory is available as an identity provider option for B2B collaboration by default. If an external guest user has an Azure AD account through work or school, they can redeem your B2B collaboration invitations or complete your sign-up user flows using their Azure AD account.

+Azure Active Directory is available in the list of External Identities identity providers by default. No further configuration is needed to allow guest users to sign in with their Azure AD account using either the invitation flow or a self-service sign-up user flow.

+### Guided walkthrough

+For a guided walkthrough of many of the recommendations in this article, see the [Set up Azure AD](https://go.microsoft.com/fwlink/?linkid=2221308) guide.

+The default sign-in experience is the global look and feel that applies across all sign-ins to your tenant. Before you customize any settings, the default Microsoft branding appears in your sign-in pages. You can customize this default experience with a custom background image and/or color, favicon, layout, header, and footer. You can also upload a custom CSS.

+## License requirements

+The branding elements are called out in the following example. Text descriptions are provided following the image.

+1. **Favicon**: Small icon that appears on the left side of the browser tab.

+1. **Header logo**: Space across the top of the web page, below the web browser navigation area.

+1. **Background image** and **page background color**: The entire space behind the sign-in box.

+1. **Banner logo**: The logo that appears in the upper-left corner of the sign-in box.

+1. **Username hint and text**: The text that appears before a user enters their information.

+1. **Sign-in page text**: Additional text you can add below the username field.

+1. **Self-service password reset**: A link you can add below the sign-in page text for password resets.

+1. **Template**: The layout of the page and sign-in boxes.

+1. **Footer**: Text in the lower-right corner of the page where you can add Terms of use or privacy information.

+### User experience

+When customizing the sign-in pages that users see when accessing your organization's tenant-specific applications, there are some user experience scenarios you may need to consider.

+For Microsoft, Software as a Service (SaaS), and multi-tenant applications such as <https://myapps.microsoft.com>, or <https://outlook.com>, the customized sign-in page appears only after the user types their **Email** or **Phone number** and selects the **Next** button.

+Some Microsoft applications support [Home Realm Discovery](../manage-apps/home-realm-discovery-policy.md) for authentication. In these scenarios, when a customer signs in to an Azure AD common sign-in page, Azure AD can use the customer's user name to determine where they should sign in.

+For customers who access applications from a custom URL, the `whr` query string parameter, or a domain variable, can be used to apply company branding at the initial sign-in screen, not just after adding the email or phone number. For example, `whr=contoso.com` would appear in the custom URL for the app. With the Home Realm Discover and domain parameter included, the company branding appears immediately in the first sign-in step. Other domain hints can be included.

+In the following examples replace the contoso.com with your own tenant name, or verified domain name:

+- For Microsoft Outlook `https://outlook.com/contoso.com`

+- For SharePoint online `https://contoso.sharepoint.com`

+- For my app portal `https://myapps.microsoft.com/?whr=contoso.com`

+- Self-service password reset `https://passwordreset.microsoftonline.com/?whr=contoso.com`

+> [!NOTE]

+> The settings to manage the 'Stay signed in?' prompt can now be found in the User settings area of Azure AD. Go to **Azure AD** > **Users** > **User settings**.

+<br><br>

+For more information on the 'Stay signed in?' prompt, see [How to manage user profile information](how-to-manage-user-profile-info.md#learn-about-the-stay-signed-in-prompt).

+ 

+

+ 

+- **Custom CSS**: Upload custom CSS to replace the Microsoft default style of the page.

+ - [Download the CSS template](https://download.microsoft.com/download/7/2/7/727f287a-125d-4368-a673-a785907ac5ab/custom-styles-template-013023.css).

+ - View the [CSS template reference guide](reference-company-branding-css-template.md).

+

+- **Show 'Terms of Use'**: This option is also selected by default and displays the [Microsoft 'Terms of Use'](https://www.microsoft.com/servicesagreement/) link.

+Azure AD supports right-to-left functionality for languages such as Arabic and Hebrew that are read right-to-left. The layout adjusts automatically, based on the user's browser settings.

+

+- [View the CSS template reference guide](reference-company-branding-css-template.md).

+- [Manage the 'stay signed in' prompt](how-to-manage-user-profile-info.md#learn-about-the-stay-signed-in-prompt)

+ Title: How to manage user profile information

+description: Instructions about how to manage a user's profile and settings in Azure Active Directory.

+# Add or update a user's profile information and settings

+A user's profile information and settings can be managed on an individual basis and for all users in your directory. When you look at these settings together, you can see how permissions, restrictions, and other connections work together.

+This article covers how to add user profile information, such as a profile picture and job-specific information. You can also choose to allow users to connect their LinkedIn accounts or restrict access to the Azure AD administration portal. Some settings may be managed in more than one area of Azure AD. For more information about adding new users, see [How to add or delete users in Azure Active Directory](add-users-azure-active-directory.md).

+## Add or change profile information

+When new users are created, only some details are added to their user profile. If your organization needs more details, they can be added after the user is created.

+1. Sign in to the [Azure portal](https://portal.azure.com/) in the User Administrator role for the organization.

+1. Go to **Azure Active Directory** > **Users** and select a user.

+

+1. There are two ways to edit user profile details. Either select **Edit properties** from the top of the page or select **Properties**.

+ 

+1. After making any changes, select the **Save** button.

+If you selected the **Edit properties option**:

+ - The full list of properties appears in edit mode on the **All** category.

+ - To edit properties based on the category, select a category from the top of the page.

+ - Select the **Save** button at the bottom of the page to save any changes.

+

+ 

+

+If you selected the **Properties tab option**:

+ - The full list of properties appears for you to review.

+ - To edit a property, select the pencil icon next to the category heading.

+ - Select the **Save** button at the bottom of the page to save any changes.

+

+ 

+### Profile categories

+There are six categories of profile details you may be able to edit.

+- **Identity:** Add or update other identity values for the user, such as a married last name. You can set this name independently from the values of First name and Last name. For example, you could use it to include initials, a company name, or to change the sequence of names shown. If you have two users with the same name, such as ΓÇÿChris Green,ΓÇÖ you could use the Identity string to set their names to 'Chris B. Green' and 'Chris R. Green.'

+- **Job information:** Add any job-related information, such as the user's job title, department, or manager.

+- **Contact info:** Add any relevant contact information for the user.

+- **Parental controls:** For organizations like K-12 school districts, the user's age group may need to be provided. *Minors* are 12 and under, *Not adult* are 13-18 years old, and *Adults* are 18 and over. The combination of age group and consent provided by parent options determine the Legal age group classification. The Legal age group classification may limit the user's access and authority.

+- **Settings:** Decide whether the user can sign in to the Azure Active Directory tenant. You can also specify the user's global location.

+- **On-premises:** Accounts synced from Windows Server Active Directory include other values not applicable to Azure AD accounts.

+ >[!Note]

+ >You must use Windows Server Active Directory to update the identity, contact info, or job info for users whose source of authority is Windows Server Active Directory. After you complete your update, you must wait for the next synchronization cycle to complete before you'll see the changes.

+### Add or edit the profile picture

+On the user's overview page, select the camera icon in the lower-right corner of the user's thumbnail. If no image has been added, the user's initials appear here. This picture appears in Azure Active Directory and on the user's personal pages, such as the myapps.microsoft.com page.

+All your changes are saved for the user.

+>[!Note]

+> If you're having issues updating a user's profile picture, please ensure that your Office 365 Exchange Online Enterprise App is Enabled for users to sign in.

+## Manage settings for all users

+In the **User settings** area of Azure AD, you can adjust several settings that affect all users, such as restricting access to the Azure AD administration portal, how external collaboration is managed, and providing users the option to connect their LinkedIn account. Some settings are managed in a separate area of Azure AD and linked from this page.

+Go to **Azure AD** > **User settings**.

+### Learn about the 'Stay signed in?' prompt

+The **Stay signed in?** prompt appears after a user successfully signs in. This process is known as **Keep me signed in** (KMSI). If a user answers **Yes** to this prompt, a persistent authentication cookie is issued. The cookie must be stored in session for KMSI to work. KMSI won't work with locally stored cookies. If KMSI isn't enabled, a non-persistent cookie is issued and lasts for 24 hours or until the browser is closed.

+The following diagram shows the user sign-in flow for a managed tenant and federated tenant using the KMSI in prompt. This flow contains smart logic so that the **Stay signed in?** option won't be displayed if the machine learning system detects a high-risk sign-in or a sign-in from a shared device. For federated tenants, the prompt will show after the user successfully authenticates with the federated identity service.

+The KMSI setting is available in **User settings**. Some features of SharePoint Online and Office 2010 depend on users being able to choose to remain signed in. If you uncheck the **Show option to remain signed in** option, your users may see other unexpected prompts during the sign-in process.

+

+Configuring the 'keep me signed in' (KMSI) option requires one of the following licenses:

+- Azure AD Premium 1

+- Azure AD Premium 2

+- Office 365 (for Office apps)

+- Microsoft 365

+#### Troubleshoot 'Stay signed in?' issues

+If a user doesn't act on the **Stay signed in?** prompt but abandons the sign-in attempt, a sign-in log entry appears in the Azure AD **Sign-ins** page. The prompt the user sees is called an "interrupt."

+

+Details about the sign-in error are found in the **Sign-in logs** in Azure AD. Select the impacted user from the list and locate the following error code details in the **Basic info** section.

+* **Sign in error code**: 50140

+* **Failure reason**: This error occurred due to "Keep me signed in" interrupt when the user was signing in.

+You can stop users from seeing the interrupt by setting the **Show option to remain signed in** setting to **No** in the user settings. This setting disables the KMSI prompt for all users in your Azure AD directory.

+You also can use the [persistent browser session controls in Conditional Access](../conditional-access/howto-conditional-access-session-lifetime.md) to prevent users from seeing the KMSI prompt. This option allows you to disable the KMSI prompt for a select group of users (such as the global administrators) without affecting sign-in behavior for everyone else in the directory.

+To ensure that the KMSI prompt is shown only when it can benefit the user, the KMSI prompt is intentionally not shown in the following scenarios:

+* User is signed in via seamless SSO and integrated Windows authentication (IWA)

+* User is signed in via Active Directory Federation Services and IWA

+* User is a guest in the tenant

+* User's risk score is high

+* Sign-in occurs during user or admin consent flow

+* Persistent browser session control is configured in a conditional access policy

+## Next steps

+- [Add or delete users](add-users-azure-active-directory.md)

+- [Assign roles to users](active-directory-users-assign-role-azure-portal.md)

+- [Create a basic group and add members](active-directory-groups-create-azure-portal.md)

+- [View Azure AD enterprise user management documentation](../enterprise-users/index.yml).

+ Title: CSS reference guide for customizing company branding - Azure AD

+description: Learn about the CSS template selectors for customizing company branding.

+# CSS template reference guide

+Configuring your company branding for the user sign-in process provides a seamless experience in your applications that use Azure Active Directory (Azure AD) as the identity and access management service. Use this CSS reference guide if you're using the [CSS template](https://download.microsoft.com/download/7/2/7/727f287a-125d-4368-a673-a785907ac5ab/custom-styles-template-013023.css) as part of the [customize company branding](reference-company-branding-css-template.md) process.

+## HTML selectors

+The following CSS styles become the default body and link styles for the whole page. Applying styles for other links or text override CSS selectors.

+- `body` - Styles for the whole page

+- Styles for links:

+ - `a, a:link` - All links

+ - `a:hover` - When the mouse is over the link

+ - `a:focus` - When the link has focus

+ - `a:focus:hover` - When the link has focus *and* the mouse is over the link

+ - `a:active` - When the link is being clicked

+## Azure AD CSS selectors

+Use the following CSS selectors to configure the details of the sign-in experience.

+- `.ext-background-image` - Container that includes the background image in the default lightbox template

+- `.ext-header` - Header at the top of the container

+- `.ext-header-logo` - Header logo at the top of the container

+ 

+- `.ext-middle` - Style for the full-screen background that aligns the sign-in box vertically to the middle and horizontally to the center

+- `.ext-vertical-split-main-section` - Style for the container of the partial-screen background in the vertical split template that contains both a sign-in box and a background (This style is also known as the Active Directory Federation Services (ADFS) template.)

+- `.ext-vertical-split-background-image-container` - Sign-in box background in the vertical split/ADFS template

+- `.ext-sign-in-box` - Sign-in box container

+ 

+- `.ext-title` - Title text

+ 

+- `.ext-subtitle` - Subtitle text

+- Styles for primary buttons:

+ - `.ext-button.ext-primary` - Primary button default style

+ - `.ext-button.ext-primary:hover` - When the mouse is over the button

+ - `.ext-button.ext-primary:focus` - When the button has focus

+ - `.ext-button.ext-primary:focus:hover` - When the button has focus *and* the mouse is over the button

+ - `.ext-button.ext-primary:active` - When the button is being clicked

+ 

+- Styles for secondary buttons:

+ - `.ext-button.ext-secondary` - Secondary buttons

+ - `.ext-button.ext-secondary:hover` - When the mouse is over the button

+ - `.ext-button.ext-secondary:focus` When the button has focus

+ - `.ext-button.ext-secondary:focus:hover` - When the button has focus *and* the mouse is over the button

+ - `.ext-button.ext-secondary:active` - When the button is being clicked

+ 

+- `.ext-error` - Error text

+ 

+- Styles for text boxes:

+ - `.ext-input.ext-text-box` - Text boxes

+ - `.ext-input.ext-text-box.ext-has-error` - When there's a validation error associated with the text box

+ - `.ext-input.ext-text-box:hover` - When the mouse is over the text box

+ - `.ext-input.ext-text-box:focus` - When the text box has focus

+ - `.ext-input.ext-text-box:focus:hover` - When the text box has focus *and* the mouse is over the text box

+ 

+- `.ext-boilerplate-text` - Custom message text at the bottom of the sign-in box

+ 

+- `.ext-promoted-fed-cred-box` - Sign-in options text box

+ 

+

+- Styles for the footer:

+ - `.ext-footer` - Footer area at the bottom of the page

+ - `.ext-footer-links` - Links area in the footer at the bottom of the page

+ - `.ext-footer-item` - Link items (such as "Terms of use" or "Privacy & cookies") in the footer at the bottom of the page

+ - `.ext-debug-item` - Debug details ellipsis in the footer at the bottom of the page

+Applications | <ul><li>Register (create) new applications<li>Enumerate the list of all applications<li>Read properties of registered and enterprise applications<li>Manage application properties, assignments, and credentials for owned applications<li>Create or delete application passwords for users<li>Delete owned applications<li>Restore owned applications<li>List permissions granted to applications</ul> | <ul><li>Read properties of registered and enterprise applications<li>List permissions granted to applications</ul> | <ul><li>Read properties of registered and enterprise applications</li><li>List permissions granted to applications</li></ul>

+## September 2022

+### General Availability - SSPR writeback is now available for disconnected forests using Azure AD Connect cloud sync

+**Type:** New feature

+**Service category:** Azure AD Connect Cloud Sync

+**Product capability:** Identity Lifecycle Management

+Azure AD Connect Cloud Sync Password writeback now provides customers the ability to synchronize Azure AD password changes made in the cloud to an on-premises directory in real time. This can be accomplished using the lightweight Azure AD cloud provisioning agent. For more information, see: [Tutorial: Enable cloud sync self-service password reset writeback to an on-premises environment](../authentication/tutorial-enable-cloud-sync-sspr-writeback.md).

+### General Availability - Device-based conditional access on Linux Desktops

+**Type:** New feature

+**Service category:** Conditional Access

+**Product capability:** SSO

+This feature empowers users on Linux clients to register their devices with Azure AD, enroll into Intune management, and satisfy device-based Conditional Access policies when accessing their corporate resources.

+- Users can register their Linux devices with Azure AD.

+- Users can enroll in Mobile Device Management (Intune), which can be used to provide compliance decisions based upon policy definitions to allow device based conditional access on Linux Desktops.

+- If compliant, users can use Microsoft Edge Browser to enable Single-Sign on to M365/Azure resources and satisfy device-based Conditional Access policies.

+For more information, see:

+- [Azure AD registered devices](../devices/concept-azure-ad-register.md)

+- [Plan your Azure Active Directory device deployment](../devices/plan-device-deployment.md)

+### General Availability - Azure AD SCIM Validator

+**Type:** New feature

+**Service category:** Provisioning

+**Product capability:** Outbound to SaaS Applications

+Independent Software Vendors(ISVs) and developers can self-test their SCIM endpoints for compatibility: We have made it easier for ISVs to validate that their endpoints are compatible with the SCIM-based Azure AD provisioning services. This is now in general availability (GA) status.

+For more information, see: [Tutorial: Validate a SCIM endpoint](../app-provisioning/scim-validator-tutorial.md)

+### General Availability - prevent accidental deletions

+**Type:** New feature

+**Service category:** Provisioning

+**Product capability:** Outbound to SaaS Applications

+Accidental deletion of users in any system could be disastrous. WeΓÇÖre excited to announce the general availability of the accidental deletions prevention capability as part of the Azure AD provisioning service. When the number of deletions to be processed in a single provisioning cycle spikes above a customer defined threshold the following will happen. The Azure AD provisioning service pauses, provide you with visibility into the potential deletions, and allow you to accept or reject the deletions. This functionality has historically been available for Azure AD Connect, and Azure AD Connect Cloud Sync. It's now available across the various provisioning flows, including both HR-driven provisioning and application provisioning.

+For more information, see: [Enable accidental deletions prevention in the Azure AD provisioning service](../app-provisioning/accidental-deletions.md)

+### General Availability - Identity Protection Anonymous and Malicious IP for ADFS on-premises logins

+**Type:** New feature

+**Service category:** Identity Protection

+**Product capability:** Identity Security & Protection

+Identity protection expands its Anonymous and Malicious IP detections to protect ADFS sign-ins. This automatically applies to all customers who have AD Connect Health deployed and enabled, and show up as the existing "Anonymous IP" or "Malicious IP" detections with a token issuer type of "AD Federation Services".

+For more information, see: [What is risk?](../identity-protection/concept-identity-protection-risks.md)

+### New Federated Apps available in Azure AD Application gallery - September 2022

+**Type:** New feature

+**Service category:** Enterprise Apps

+**Product capability:** 3rd Party Integration

+In September 2022 we've added the following 15 new applications in our App gallery with Federation support:

+[RocketReach SSO](../saas-apps/rocketreach-sso-tutorial.md), [Arena EU](../saas-apps/arena-eu-tutorial.md), [Zola](../saas-apps/zola-tutorial.md), [FourKites SAML2.0 SSO for Tracking](../saas-apps/fourkites-tutorial.md), [Syniverse Customer Portal](../saas-apps/syniverse-customer-portal-tutorial.md), [Rimo](https://rimo.app/), [Q Ware CMMS](https://qware.app/), [Mapiq (OIDC)](https://app.mapiq.com/), [NICE Cxone](../saas-apps/nice-cxone-tutorial.md), [dominKnow|ONE](../saas-apps/dominknowone-tutorial.md), [Waynbo for Azure AD](https://webportal-eu.waynbo.com/Login), [innDex](https://web.inndex.co.uk/azure/authorize), [Profiler Software](https://www.profiler.net.au/), [Trotto go links](https://trot.to/_/auth/login), [AsignetSSOIntegration](../saas-apps/asignet-sso-tutorial.md).

+You can also find the documentation of all the applications from here https://aka.ms/AppsTutorial,

+For listing your application in the Azure AD app gallery, read the details here: https://aka.ms/AzureADAppRequest

+[Moula](https://moula.com.au/pay/merchants), [Surveypal](https://www.surveypal.com/app), [Kbot365](https://www.konverso.ai/), [Powell Teams](https://powell-software.com/en/powell-teams-en/), [Talentsoft Assistant](https://msteams.talent-soft.com/), [ASC Recording Insights](https://teams.asc-recording.app/product), [GO1](https://www.go1.com/), [B-Engaged](https://b-engaged.se/), [Competella Contact Center Workgroup](http://www.competella.com/), [Asite](http://www.asite.com/), [ImageSoft Identity](https://identity.imagesoftinc.com/), [My IBISWorld](https://identity.imagesoftinc.com/), [insuite](../saas-apps/insuite-tutorial.md), [Change Process Management](../saas-apps/change-process-management-tutorial.md), [Cyara CX Assurance Platform](../saas-apps/cyara-cx-assurance-platform-tutorial.md), [Smart Global Governance](../saas-apps/smart-global-governance-tutorial.md), [Prezi](../saas-apps/prezi-tutorial.md), [Mapbox](../saas-apps/mapbox-tutorial.md), [Datava Enterprise Service Platform](../saas-apps/datava-enterprise-service-platform-tutorial.md), [Whimsical](../saas-apps/whimsical-tutorial.md), [Trelica](../saas-apps/trelica-tutorial.md), [EasySSO for Confluence](../saas-apps/easysso-for-confluence-tutorial.md), [EasySSO for BitBucket](../saas-apps/easysso-for-bitbucket-tutorial.md), [EasySSO for Bamboo](../saas-apps/easysso-for-bamboo-tutorial.md), [Torii](../saas-apps/torii-tutorial.md), [Axiad Cloud](../saas-apps/axiad-cloud-tutorial.md), [Humanage](../saas-apps/humanage-tutorial.md), [ColorTokens ZTNA](../saas-apps/colortokens-ztna-tutorial.md), [CCH Tagetik](../saas-apps/cch-tagetik-tutorial.md), [ShareVault](../saas-apps/sharevault-tutorial.md), [Vyond](../saas-apps/vyond-tutorial.md), [TextExpander](../saas-apps/textexpander-tutorial.md), [Anyone Home CRM](../saas-apps/anyone-home-crm-tutorial.md), [askSpoke](../saas-apps/askspoke-tutorial.md), [ice Contact Center](../saas-apps/ice-contact-center-tutorial.md)

+[CoreStack](https://cloud.corestack.io/site/login), [HubSpot](../saas-apps/hubspot-tutorial.md), [GetThere](../saas-apps/getthere-tutorial.md), [Gra-Pe](../saas-apps/grape-tutorial.md), [eHour](https://getehour.com/try-now), [Consent2Go](../saas-apps/consent2go-tutorial.md), [Appinux](../saas-apps/appinux-tutorial.md), [DriveDollar](https://azuremarketplace.microsoft.com/marketplace/apps/savitas.drivedollar-azuread?tab=Overview), [Useall](../saas-apps/useall-tutorial.md), [Infinite Campus](../saas-apps/infinitecampus-tutorial.md), [Alaya](https://alayagood.com), [HeyBuddy](../saas-apps/heybuddy-tutorial.md), [Wrike SAML](../saas-apps/wrike-tutorial.md), [Drift](../saas-apps/drift-tutorial.md), [Zenegy for Business Central 365](https://accounting.zenegy.com/), [Everbridge Member Portal](../saas-apps/everbridge-tutorial.md), [Ivanti Service Manager (ISM)](../saas-apps/ivanti-service-manager-tutorial.md), [Peakon](../saas-apps/peakon-tutorial.md), [Allbound SSO](../saas-apps/allbound-sso-tutorial.md), [Plex Apps - Classic Test](https://test.plexonline.com/signon), [Plex Apps ΓÇô Classic](https://www.plexonline.com/signon), [Plex Apps - UX Test](https://test.cloud.plex.com/sso), [Plex Apps ΓÇô UX](https://cloud.plex.com/sso), [Plex Apps ΓÇô IAM](https://accounts.plex.com/)

+> Example: `(Get-AzureADDirectorySetting | ? { $_.DisplayName -eq "Group.Unified"} | Select-Object -ExpandProperty Values`

+- Azure AD Connect must be installed on a domain-joined Windows Server 2016 or later. You can deploy Azure AD Connect on Windows Server 2016 but since Windows Server 2016 is in extended support, you may require [a paid support program](/lifecycle/policies/fixed#extended-support) if you require support for this configuration. We recommend the usage of domain joined Windows Server 2022.

+## 27 March 2023

+**Agent Update**

+Azure AD Connect Health ADDS and ADFS Health Agents (version 3.2.2256.26)

+- We created a fix for so that the agents would be FIPS compliant

+ - the change was to have the agents use ΓÇÿCloudStorageAccount.UseV1MD5 = falseΓÇÖ so the agent only uses only FIPS compliant cryptography, otherwise azure blob client causes FIPs exceptions to be thrown.

+- Update of Newtonsoft.json library from 12.0.1 to 13.0.1 to resolve a component governance alert.

+- In ADFS health agent, the TestADFSDuplicateSPN test was disabled as the test was unreliable, it would generate misleading alerts when server experienced transient connectivity issues.

+| thumbnailphoto |X |X | |Synced to M365 profile photo periodically. Admins can set the frequency of the sync by changing the Azure AD Connect value. Please note that if users change their photo both on-premises and in cloud in a time span that is less than the Azure AD Connect value, we do not guarantee that the latest photo will be served.|

+| thumbnailphoto |X |X | |Synced to M365 profile photo periodically. Admins can set the frequency of the sync by changing the Azure AD Connect value. Please note that if users change their photo both on-premises and in cloud in a time span that is less than the Azure AD Connect value, we do not guarantee that the latest photo will be served.|

+| thumbnailphoto |X |X | |Synced to M365 profile photo periodically. Admins can set the frequency of the sync by changing the Azure AD Connect value. Please note that if users change their photo both on-premises and in cloud in a time span that is less than the Azure AD Connect value, we do not guarantee that the latest photo will be served.|

+- Signature algorithm not allowed. Only RSA-SHA256 is supported.

+> [!NOTE]

+> A `Signature` element in `AuthnRequest` elements is optional. If `Require Verification certificates` is not checked, Azure AD does not validate signed authentication requests if a signature is present. Requestor verification is provided for by only responding to registered Assertion Consumer Service URLs.

+> If `Require Verification certificates` is checked, SAML Request Signature Verification will work for SP-initiated(service provider/relying party initiated) authentication requests only. Only the application configured by the service provider will have the access to to the private and public keys for signing the incoming SAML Authentication Reqeusts from the applicaiton. The public key should be uploaded to allow the verification of the request, in which case AAD will have access to only the public key.

+> Enabling `Require Verification certificates` will not allow IDP-initiated authentication requests (like SSO testing feature, MyApps or M365 app launcher) to be validated as the IDP would not possess the same private keys as the registered applicaiton.

+## Guided walkthrough

+For a guided walkthrough of many of the recommendations in this article, see the [Microsoft 365 Secure your cloud apps with Single Sign On (SSO) guided walkthrough](https://go.microsoft.com/fwlink/?linkid=2221502).

+ Title: Sign-in logs (preview)

+description: Conceptual information about sign-in logs, including new features in preview.

+#### Considerations for MFA sign-ins

+When a user signs in with MFA, several separate MFA events are actually taking place. For example, if a user enters the wrong validation code or doesn't respond in time, additional MFA events are sent to reflect the latest status of the sign-in attempt. These sign-in events appear as one line item in the Azure AD sign-in logs. That same sign-in event in Azure Monitor, however, appears as multiple line items. These events all have the same `correlationId`.

+Like interactive user sign-ins, non-interactive sign-ins are done on behalf of a user. These sign-ins were performed by a client app or OS components on behalf of a user and don't require the user to provide an authentication factor. Instead, the device or client app uses a token or code to authenticate or access a resource on behalf of a user. In general, the user perceives these sign-ins as happening in the background.

+When Azure AD logs multiple sign-ins that are identical other than time and date, those sign-ins are from the same entity and are aggregated into a single row. A row with multiple identical sign-ins (except for date and time issued) have a value greater than 1 in the *# sign-ins* column. These aggregated sign-ins may also appear to have the same time stamps. The **Time aggregate** filter can set to 1 hour, 6 hours, or 24 hours. You can expand the row to see all the different sign-ins and their different time stamps.

+Unlike interactive and non-interactive user sign-ins, service principal sign-ins don't involve a user. Instead, they're sign-ins by any nonuser account, such as apps or service principals (except managed identity sign-in, which are in included only in the managed identity sign-in log). In these sign-ins, the app or service provides its own credential, such as a certificate or app secret to authenticate or access resources.

+There are several filter options to choose from:

+There are several filter options to choose from:

+- **IP addresses:** There's no definitive connection between an IP address and where the computer with that address is physically located. Mobile providers and VPNs issue IP addresses from central pools that are often far from where the client device is actually used. Currently, converting IP address to a physical location is a best effort based on traces, registry data, reverse lookups and other information.

+If a sign-in failed, you can get more information about the reason in the **Basic info** section of the related log item. The error code and associated failure reason appear in the details. Because of the complexity of some Azure AD environments, we can't document every possible error code and resolution. Some errors may require [submitting a support request](../fundamentals/how-to-get-support.md) to resolve the issue.

+#### Considerations for MFA sign-ins

+When a user signs in with MFA, several separate MFA events are actually taking place. For example, if a user enters the wrong validation code or doesn't respond in time, additional MFA events are sent to reflect the latest status of the sign-in attempt. These sign-in events appear as one line item in the Azure AD sign-in logs. That same sign-in event in Azure Monitor, however, appears as multiple line items. These events all have the same `correlationId`.

+[Azure AD recommendations](overview-recommendations.md) provides you with personalized insights and actionable guidance to align your tenant with recommended best practices.

+1. [Review the AD FS application activity report](../manage-apps/migrate-adfs-application-activity.md) to get insights about your AD FS applications.

+1. Read the solution guide for [migrating applications to Azure AD](../manage-apps/migrate-adfs-apps-to-azure.md).

+1. Migrate applications to Azure AD. For more information, see the article [Migrate from federation to cloud authentication](../hybrid/migrate-from-federation-to-cloud-authentication.md).

+### Guided walkthrough

+For a guided walkthrough of many of the recommendations in this article, see the migration guide [Migrate from AD FS to Microsoft Azure Active Directory for identity management](https://setup.microsoft.com/azure/migrate-ad-fs-to-microsoft-azure-ad).

+ Title: Azure Active Directory SSO integration with CITI Program

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

+# Azure Active Directory SSO integration with CITI Program

+In this article, you learn how to integrate CITI Program with Azure Active Directory (Azure AD). The CITI Program identifies education and training needs in the communities we serve and provides high quality, peer-reviewed, web-based educational materials to meet those needs. When you integrate CITI Program with Azure AD, you can:

+* Control in Azure AD who has access to CITI Program.

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

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

+You configure and test Azure AD single sign-on for CITI Program in a test environment. CITI Program supports **SP** initiated single sign-on and **Just In Time** user provisioning.

+> [!NOTE]

+> Identifier of this application is a fixed string value so only one instance can be configured in one tenant.

+## Prerequisites

+To integrate Azure Active Directory with CITI Program, you need:

+* An Azure AD user account. If you don't already have one, you can [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).

+* One of the following roles: Global Administrator, Cloud Application Administrator, Application Administrator, or owner of the service principal.

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

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

+## Add application and assign a test user

+Before you begin the process of configuring single sign-on, you need to add the CITI Program application from the Azure AD gallery. You need a test user account to assign to the application and test the single sign-on configuration.

+### Add CITI Program from the Azure AD gallery

+Add CITI Program from the Azure AD application gallery to configure single sign-on with CITI Program. For more information on how to add application from the gallery, see the [Quickstart: Add application from the gallery](../manage-apps/add-application-portal.md).

+### Create and assign Azure AD test user

+Follow the guidelines in the [create and assign a user account](../manage-apps/add-application-portal-assign-users.md) article to create a test user account in the Azure portal called B.Simon.

+Alternatively, you can also use the [Enterprise App Configuration Wizard](https://portal.office.com/AdminPortal/home?Q=Docs#/azureadappintegration). In this wizard, you can add an application to your tenant, add users/groups to the app, and assign roles. The wizard also provides a link to the single sign-on configuration pane in the Azure portal. [Learn more about Microsoft 365 wizards.](/microsoft-365/admin/misc/azure-ad-setup-guides).

+## Configure Azure AD SSO

+Complete the following steps to enable Azure AD single sign-on in the Azure portal.

+1. In the Azure portal, on the **CITI Program** 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, select the pencil icon for **Basic SAML Configuration** to edit the settings.

+ 

+1. On the **Basic SAML Configuration** section, perform the following steps:

+ a. In the **Identifier** textbox, type the URL:

+ `https://www.citiprogram.org/shibboleth`

+ b. In the **Reply URL** textbox, type the URL:

+ `https://www.citiprogram.org/Shibboleth.sso/SAML2/POST`

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

+ `https://www.citiprogram.org/Shibboleth.sso/Login?target=https://www.citiprogram.org/Secure/Welcome.cfm?inst=<InstitutionID>&entityID=<EntityID>`

+ > [!NOTE]

+ > This value is not real. Update this value with the actual Sign on URL. Contact [CITI Program support team](mailto:shibboleth@citiprogram.org) to get the value. You can also refer to the patterns shown in the **Basic SAML Configuration** section in the Azure portal.

+1. CITI Program application expects the SAML assertions in a specific format, which requires you to add custom attribute mappings to your SAML token attributes configuration. The following screenshot shows the list of default attributes.

+ 

+1. In addition to above, CITI Program application expects few more attributes to be passed back in SAML response, which are shown below. These attributes are also pre populated but you can review them as per your requirements.

+ | Name | Source Attribute|

+ | | |

+ | urn:oid:1.3.6.1.4.1.5923.1.1.1.6 | user.userprincipalname |

+ | urn:oid:0.9.2342.19200300.100.1.3 | user.userprincipalname |

+ | urn:oid:2.5.4.42 | user.givenname |

+ | urn:oid:2.5.4.4 | user.surname |

+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 CITI Program** section, copy the appropriate URL(s) based on your requirement.

+ 

+## Configure CITI Program SSO

+To configure single sign-on on **CITI Program** side, you need to send the downloaded **Federation Metadata XML** and appropriate copied URLs from Azure portal to [CITI Program support team](mailto:shibboleth@citiprogram.org). They set this setting to have the SAML SSO connection set properly on both sides.

+### Create CITI Program test user

+In this section, a user called B.Simon is created in CITI Program. CITI Program supports just-in-time user provisioning, which is enabled by default. There's no action item for you in this section. If a user doesn't already exist in CITI Program, a new one is commonly created after authentication.

+## 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 CITI Program Sign-on URL where you can initiate the login flow.

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

+* You can use Microsoft My Apps. When you click the CITI Program tile in the My Apps, this will redirect to CITI Program 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).

+## Additional resources

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

+* [Plan a single sign-on deployment](../manage-apps/plan-sso-deployment.md).

+## Next steps

+Once you configure CITI Program 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 Cloud App Security](/cloud-app-security/proxy-deployment-aad).

+ |Attribute|Type|Supported for filtering|Required by Infor CloudSuite|

+ |||||

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

+ |active|Boolean||

+ |displayName|String||

+ |externalId|String||

+ |name.familyName|String||

+ |name.givenName|String||

+ |displayName|String||

+ |title|String||

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

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

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

+ |urn:ietf:params:scim:schemas:extension:infor:2.0:User:actorId|String||

+ |urn:ietf:params:scim:schemas:extension:infor:2.0:User:federationId|String||

+ |urn:ietf:params:scim:schemas:extension:infor:2.0:User:ifsPersonId|String||

+ |urn:ietf:params:scim:schemas:extension:infor:2.0:User:inUser|String||

+ |urn:ietf:params:scim:schemas:extension:infor:2.0:User:userAlias|String||

+ |Attribute|Type|Supported for filtering|Required by Infor CloudSuite|

+ |||||

+ |displayName|String|&check;|&check;

+ |members|Reference||

+ |externalId|String||

+This operation starts the initial synchronization cycle of all users 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's to completion

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

+## Change log

+02/15/2023 - Added support for custom extension user attributes **urn:ietf:params:scim:schemas:extension:infor:2.0:User:actorId**, **urn:ietf:params:scim:schemas:extension:infor:2.0:User:federationId**, **urn:ietf:params:scim:schemas:extension:infor:2.0:User:ifsPersonId**, **urn:ietf:params:scim:schemas:extension:infor:2.0:User:inUser**, and **urn:ietf:params:scim:schemas:extension:infor:2.0:User:userAlias**.

+## More resources

+ Title: Azure Active Directory SSO integration with Intradiem

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

+# Azure Active Directory SSO integration with Intradiem

+In this article, you learn how to integrate Intradiem with Azure Active Directory (Azure AD). AI-Powered Productivity Solution that Integrates with Call Center and Workforce Management Software to Improve Savings, Productivity, and Engagement. When you integrate Intradiem with Azure AD, you can:

+* Control in Azure AD who has access to Intradiem.

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

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

+You configure and test Azure AD single sign-on for Intradiem in a test environment. Intradiem supports only **SP** initiated single sign-on.

+## Prerequisites

+To integrate Azure Active Directory with Intradiem, you need:

+* An Azure AD user account. If you don't already have one, you can [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).

+* One of the following roles: Global Administrator, Cloud Application Administrator, Application Administrator, or owner of the service principal.

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

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

+## Add application and assign a test user

+Before you begin the process of configuring single sign-on, you need to add the Intradiem application from the Azure AD gallery. You need a test user account to assign to the application and test the single sign-on configuration.

+### Add Intradiem from the Azure AD gallery

+Add Intradiem from the Azure AD application gallery to configure single sign-on with Intradiem. For more information on how to add application from the gallery, see the [Quickstart: Add application from the gallery](../manage-apps/add-application-portal.md).

+### Create and assign Azure AD test user

+Follow the guidelines in the [create and assign a user account](../manage-apps/add-application-portal-assign-users.md) article to create a test user account in the Azure portal called B.Simon.

+Alternatively, you can also use the [Enterprise App Configuration Wizard](https://portal.office.com/AdminPortal/home?Q=Docs#/azureadappintegration). In this wizard, you can add an application to your tenant, add users/groups to the app, and assign roles. The wizard also provides a link to the single sign-on configuration pane in the Azure portal. [Learn more about Microsoft 365 wizards.](/microsoft-365/admin/misc/azure-ad-setup-guides).

+## Configure Azure AD SSO

+Complete the following steps to enable Azure AD single sign-on in the Azure portal.

+1. In the Azure portal, on the **Intradiem** 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, select the pencil icon for **Basic SAML Configuration** to edit the settings.

+ 

+1. On the **Basic SAML Configuration** section, perform the following steps:

+ a. In the **Identifier** textbox, type a URL using one of the following patterns:

+ | **Identifier** |

+ ||

+ | `https://<CustomerName>.intradiem.com/auth/realms/<CustomerName>` |

+ | `https://<CustomerName>auth.intradiem.com/auth/realms/<CustomerName>` |

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

+ | **Reply URL** |

+ ||

+ | `https://<CustomerName>auth.intradiem.com/auth/realms/<CustomerName>/broker/<CustomerName>/endpoint` |

+ | `https://<CustomerName>.intradiem.com/auth/realms/<CustomerName>/broker/<CustomerName>/endpoint` |

+ c. In the **Sign on URL** textbox, type a URL using one of the following patterns:

+

+ | **Sign on URL** |

+ |-|

+ | `https://<CustomerName>auth.intradiem.com` |

+ | `https://<CustomerName>.intradiem.com` |

+ > [!Note]

+ > These values are not real. Update these values with the actual Identifier, Reply URL and Sign on URL. Contact [Intradiem support team](mailto:support@intradiem.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, click copy button to copy **App Federation Metadata Url** and save it on your computer.

+ 

+## Configure Intradiem SSO

+To configure single sign-on on **Intradiem** side, you need to send the **App Federation Metadata Url** to [Intradiem support team](mailto:support@intradiem.com). They set this setting to have the SAML SSO connection set properly on both sides

+### Create Intradiem test user

+In this section, you create a user called Britta Simon in Intradiem. Work with [Intradiem support team](mailto:support@intradiem.com) to add the users in the Intradiem 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 Intradiem Sign-on URL where you can initiate the login flow.

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

+* You can use Microsoft My Apps. When you click the Intradiem tile in the My Apps, this will redirect to Intradiem 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).

+## Additional resources

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

+* [Plan a single sign-on deployment](../manage-apps/plan-sso-deployment.md).

+## Next steps

+Once you configure Intradiem 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 Cloud App Security](/cloud-app-security/proxy-deployment-aad).

+ Title: Azure Active Directory SSO integration with LambdaTest Single Sign on

+description: Learn how to configure single sign-on between Azure Active Directory and LambdaTest Single Sign on.

+# Azure Active Directory SSO integration with LambdaTest Single Sign on

+In this article, you learn how to integrate LambdaTest Single Sign on with Azure Active Directory (Azure AD). LambdaTest's Single Sign-on application enables you to self-configure SSO with your Azure AD instance. When you integrate LambdaTest Single Sign on with Azure AD, you can:

+* Control in Azure AD who has access to LambdaTest Single Sign on.

+* Enable your users to be automatically signed-in to LambdaTest Single Sign on with their Azure AD accounts.

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

+You configure and test Azure AD single sign-on for LambdaTest Single Sign on in a test environment. LambdaTest Single Sign on supports both **SP** and **IDP** initiated single sign-on and **Just In Time** user provisioning.

+## Prerequisites

+To integrate Azure Active Directory with LambdaTest Single Sign on, you need:

+* An Azure AD user account. If you don't already have one, you can [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).

+* One of the following roles: Global Administrator, Cloud Application Administrator, Application Administrator, or owner of the service principal.

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

+* LambdaTest Single Sign on single sign-on (SSO) enabled subscription.

+## Add application and assign a test user

+Before you begin the process of configuring single sign-on, you need to add the LambdaTest Single Sign on application from the Azure AD gallery. You need a test user account to assign to the application and test the single sign-on configuration.

+### Add LambdaTest Single Sign on from the Azure AD gallery

+Add LambdaTest Single Sign on from the Azure AD application gallery to configure single sign-on with LambdaTest Single Sign on. For more information on how to add application from the gallery, see the [Quickstart: Add application from the gallery](../manage-apps/add-application-portal.md).

+### Create and assign Azure AD test user

+Follow the guidelines in the [create and assign a user account](../manage-apps/add-application-portal-assign-users.md) article to create a test user account in the Azure portal called B.Simon.

+Alternatively, you can also use the [Enterprise App Configuration Wizard](https://portal.office.com/AdminPortal/home?Q=Docs#/azureadappintegration). In this wizard, you can add an application to your tenant, add users/groups to the app, and assign roles. The wizard also provides a link to the single sign-on configuration pane in the Azure portal. [Learn more about Microsoft 365 wizards.](/microsoft-365/admin/misc/azure-ad-setup-guides).

+## Configure Azure AD SSO

+Complete the following steps to enable Azure AD single sign-on in the Azure portal.

+1. In the Azure portal, on the **LambdaTest Single Sign on** 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, select the pencil icon for **Basic SAML Configuration** to edit the settings.

+ 

+1. On the **Basic SAML Configuration** section, perform the following steps:

+ a. In the **Identifier** textbox, type a value using the following pattern:

+ `urn:auth0:lambdatest:<CustomerName>`

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

+ `https://lambdatest.auth0.com/login/callback?connection=<CustomerName>`

+1. If you wish to configure the application in **SP** initiated mode, then perform the following step:

+ In the **Sign on URL** textbox, type the URL:

+ `https://accounts.lambdatest.com/auth0/login`

+ > [!NOTE]

+ > These values are not real. Update these values with the actual Identifier and Reply URL. Contact [LambdaTest Single Sign on Client support team](mailto:support@lambdatest.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 **Certificate (Base64)** and select **Download** to download the certificate and save it on your computer.

+ 

+1. On the **Set up LambdaTest Single Sign on** section, copy the appropriate URL(s) based on your requirement.

+ 

+## Configure LambdaTest Single Sign on SSO

+To configure single sign-on on **LambdaTest Single Sign on** side, you need to send the downloaded **Certificate (Base64)** and appropriate copied URLs from Azure portal to [LambdaTest Single Sign on support team](mailto:support@lambdatest.com). They set this setting to have the SAML SSO connection set properly on both sides.

+### Create LambdaTest Single Sign on test user

+In this section, a user called B.Simon is created in LambdaTest Single Sign on. LambdaTest Single Sign on supports just-in-time user provisioning, which is enabled by default. There's no action item for you in this section. If a user doesn't already exist in LambdaTest Single Sign on, a new one is commonly created after authentication.

+## Test SSO

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

+#### SP initiated:

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

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

+#### IDP initiated:

+* Click on **Test this application** in Azure portal and you should be automatically signed in to the LambdaTest Single Sign on 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 LambdaTest Single Sign on 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 LambdaTest Single Sign on 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).

+## Additional resources

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

+* [Plan a single sign-on deployment](../manage-apps/plan-sso-deployment.md).

+## Next steps

+Once you configure LambdaTest Single Sign on 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 Cloud App Security](/cloud-app-security/proxy-deployment-aad).

+ Title: Azure Active Directory SSO integration with Sauce Labs

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

+# Azure Active Directory SSO integration with Sauce Labs

+In this article, you learn how to integrate Sauce Labs with Azure Active Directory (Azure AD). App integration for single sign-on and automatic account provisioning at Sauce Labs. When you integrate Sauce Labs with Azure AD, you can:

+* Control in Azure AD who has access to Sauce Labs.

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

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

+You configure and test Azure AD single sign-on for Sauce Labs in a test environment. Sauce Labs supports both **SP** and **IDP** initiated single sign-on and **Just In Time** user provisioning.

+> [!NOTE]

+> Identifier of this application is a fixed string value so only one instance can be configured in one tenant.

+## Prerequisites

+To integrate Azure Active Directory with Sauce Labs, you need:

+* An Azure AD user account. If you don't already have one, you can [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).

+* One of the following roles: Global Administrator, Cloud Application Administrator, Application Administrator, or owner of the service principal.

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

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

+## Add application and assign a test user

+Before you begin the process of configuring single sign-on, you need to add the Sauce Labs application from the Azure AD gallery. You need a test user account to assign to the application and test the single sign-on configuration.

+### Add Sauce Labs from the Azure AD gallery

+Add Sauce Labs from the Azure AD application gallery to configure single sign-on with Sauce Labs. For more information on how to add application from the gallery, see the [Quickstart: Add application from the gallery](../manage-apps/add-application-portal.md).

+### Create and assign Azure AD test user

+Follow the guidelines in the [create and assign a user account](../manage-apps/add-application-portal-assign-users.md) article to create a test user account in the Azure portal called B.Simon.

+Alternatively, you can also use the [Enterprise App Configuration Wizard](https://portal.office.com/AdminPortal/home?Q=Docs#/azureadappintegration). In this wizard, you can add an application to your tenant, add users/groups to the app, and assign roles. The wizard also provides a link to the single sign-on configuration pane in the Azure portal. [Learn more about Microsoft 365 wizards.](/microsoft-365/admin/misc/azure-ad-setup-guides).

+## Configure Azure AD SSO

+Complete the following steps to enable Azure AD single sign-on in the Azure portal.

+1. In the Azure portal, on the **Sauce Labs** 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, select the pencil icon for **Basic SAML Configuration** to edit the settings.

+ 

+1. On the **Basic SAML Configuration** section, the user doesn't have to perform any step as the app is already preintegrated with Azure.

+1. If you wish to configure the application in **SP** initiated mode, then perform the following step:

+ In the **Sign on URL** textbox, type the URL:

+ `https://accounts.saucelabs.com/`

+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 Sauce Labs** section, copy the appropriate URL(s) based on your requirement.

+ 

+## Configure Sauce Labs SSO

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

+### Create Sauce Labs test user

+In this section, a user called B.Simon is created in Sauce Labs. Sauce Labs supports just-in-time user provisioning, which is enabled by default. There's no action item for you in this section. If a user doesn't already exist in Sauce Labs, a new one is commonly created after authentication.

+## Test SSO

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

+#### SP initiated:

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

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

+#### IDP initiated:

+* Click on **Test this application** in Azure portal and you should be automatically signed in to the Sauce Labs 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 Sauce Labs 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 Sauce Labs 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).

+## Additional resources

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

+* [Plan a single sign-on deployment](../manage-apps/plan-sso-deployment.md).

+## Next steps

+Once you configure Sauce Labs 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 Cloud App Security](/cloud-app-security/proxy-deployment-aad).

+* Azure Load Balancer is available in two SKUs: *Basic* and *Standard*. The *Standard* SKU is used by default when you create an AKS cluster. The *Standard* SKU gives you access to added functionality, such as a larger backend pool, [multiple node pools](use-multiple-node-pools.md), [Availability Zones](availability-zones.md), and is [secure by default][azure-lb]. It's the recommended load balancer SKU for AKS. For more information on the *Basic* and *Standard* SKUs, see [Azure Load Balancer SKU comparison][azure-lb-comparison].

+* This article assumes you have an AKS cluster with the *Standard* SKU Azure Load Balancer. If you need an AKS cluster, you can create one [using Azure CLI][aks-quickstart-cli], [Azure PowerShell][aks-quickstart-powershell], or [the Azure portal][aks-quickstart-portal].

+* AKS manages the lifecycle and operations of agent nodes. Modifying the IaaS resources associated with the agent nodes isn't supported. An example of an unsupported operation is making manual changes to the load balancer resource group.

+* To use a custom DNS server, add the Azure public IP address 168.63.129.16 as the upstream DNS server in the custom DNS server, and make sure to add this public IP address as the *first* DNS server. For more information about the Azure IP address, see [What is IP address 168.63.129.16?][virtual-networks-168.63.129.16]

+* Create a VM in the same Azure Virtual Network (VNet) as the AKS cluster using the [`az vm create`][az-vm-create] command with the `--vnet-name` parameter.

+Creating a VM in the same VNet as the AKS cluster is the easiest option. Express Route and VPNs add costs and require additional networking complexity. Virtual network peering requires you to plan your network CIDR ranges to ensure there are no overlapping ranges.

+1. Select **Add**, add the virtual network of the VM, and then create the peering. For more information, see [Virtual network peering][virtual-network-peering].

+[az-vm-create]: /cli/azure/vm#az-vm-create

+ Title: Stop cluster upgrades on API breaking changes in Azure Kubernetes Service (AKS) (preview)

+description: Learn how to stop minor version change Azure Kubernetes Service (AKS) cluster upgrades on API breaking changes.

+# Stop cluster upgrades on API breaking changes in Azure Kubernetes Service (AKS)

+To stay within a supported Kubernetes version, you usually have to upgrade your version at least once per year and prepare for all possible disruptions. These disruptions include ones caused by API breaking changes and deprecations and dependencies such as Helm and CSI. It can be difficult to anticipate these disruptions and migrate critical workloads without experiencing any downtime.

+Azure Kubernetes Service (AKS) now supports fail fast on minor version change cluster upgrades. This feature alerts you with an error message if it detects usage on deprecated APIs in the goal version.

+## Fail fast on control plane minor version manual upgrades in AKS (preview)

+AKS will fail fast on minor version change cluster manual upgrades if it detects usage on deprecated APIs in the goal version. This will only happen if the following criteria are true:

+- It's a minor version change for the cluster control plane.

+- Your Kubernetes goal version is >= 1.26.0.

+- The PUT MC request uses a preview API version of >= 2023-01-02-preview.

+- The usage is performed within the last 1-12 hours. We record usage hourly, so usage within the last hour isn't guaranteed to appear in the detection.

+If the previous criteria are true and you attempt an upgrade, you'll receive an error message similar to the following example error message:

+```

+Bad Request({

+ "code": "ValidationError",

+ "message": "Control Plane upgrade is blocked due to recent usage of a Kubernetes API deprecated in the specified version. Please refer to https://kubernetes.io/docs/reference/using-api/deprecation-guide to migrate the usage. To bypass this error, set IgnoreKubernetesDeprecations in upgradeSettings.overrideSettings. Bypassing this error without migrating usage will result in the deprecated Kubernetes API calls failing. Usage details: 1 error occurred:\n\t* usage has been detected on API flowcontrol.apiserver.k8s.io.prioritylevelconfigurations.v1beta1, and was recently seen at: 2023-03-23 20:57:18 +0000 UTC, which will be removed in 1.26\n\n",

+ "subcode": "UpgradeBlockedOnDeprecatedAPIUsage"

+})

+```

+After receiving the error message, you have two options:

+- Remove usage on your end and wait 12 hours for the current record to expire.

+- Bypass the validation to ignore API changes.

+### Remove usage on API breaking changes

+Remove usage on API breaking changes using the following steps:

+1. Remove the deprecated API, which is listed in the error message.

+2. Wait 12 hours for the current record to expire.

+3. Retry your cluster upgrade.

+### Bypass validation to ignore API changes

+To bypass validation to ignore API breaking changes, update the `"properties":` block of `Microsoft.ContainerService/ManagedClusters` `PUT` operation with the following settings:

+> [!NOTE]

+> The date and time you specify for `"until"` has to be in the future. `Z` stands for timezone. The following example is in GMT. For more information, see [Combined date and time representations](https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations).

+```

+{

+ "properties": {

+ "upgradeSettings": {

+ "overrideSettings": {

+ "controlPlaneOverrides": [

+ "IgnoreKubernetesDeprecations"

+ ],

+ "until": "2023-04-01T13:00:00Z"

+ }

+ }

+ }

+}

+```

+## Next steps

+In this article, you learned how AKS detects deprecated APIs before an update is triggered and fails the upgrade operation upfront. To learn more about AKS cluster upgrades, see:

+- [Upgrade an AKS cluster][upgrade-cluster]

+- [Use Planned Maintenance to schedule and control upgrades for your AKS clusters (preview)][planned-maintenance-aks]

+<!-- INTERNAL LINKS -->

+[upgrade-cluster]: upgrade-cluster.md

+[planned-maintenance-aks]: planned-maintenance.md

+ apiVersion: v1

+ kind: ConfigMap

+ metadata:

+ name: metrics-server-config

+ namespace: kube-system

+ labels:

+ kubernetes.io/cluster-service: "true"

+ addonmanager.kubernetes.io/mode: EnsureExists

+ data:

+ NannyConfiguration: |-

+ apiVersion: nannyconfig/v1alpha1

+ kind: NannyConfiguration

+ baseCPU: 100m

+ cpuPerNode: 1m

+ baseMemory: 100Mi

+ memoryPerNode: 8Mi

+ apiVersion: v1

+ kind: ConfigMap

+ metadata:

+ name: metrics-server-config

+ namespace: kube-system

+ labels:

+ kubernetes.io/cluster-service: "true"

+ addonmanager.kubernetes.io/mode: EnsureExists

+ data:

+ NannyConfiguration: |-

+ apiVersion: nannyconfig/v1alpha1

+ kind: NannyConfiguration

+ baseCPU: 100m

+ cpuPerNode: 0m

+ baseMemory: 100Mi

+ memoryPerNode: 0Mi

+4. To verify the updated resources took effect, run the following command to review the Metrics Server VPA log.

+ apiVersion: v1

+ kind: ConfigMap

+ metadata:

+ name: metrics-server-config

+ namespace: kube-system

+ labels:

+ kubernetes.io/cluster-service: "true"

+ addonmanager.kubernetes.io/mode: EnsureExists

+ data:

+ NannyConfiguration: |-

+ apiVersion: nannyconfig/v1alpha1

+ kind: NannyConfiguration

+ baseCPU: 100

+ cpuPerNode: 1m

+ baseMemory: 100Mi

+ memoryPerNode: 8Mi

+[horizontal-pod-autoscaler]: concepts-scale.md#horizontal-pod-autoscaler

+|`azure.workload.identity/use` | This label is required in the pod template spec. Only pods with this label will be mutated by the azure-workload-identity mutating admission webhook to inject the Azure specific environment variables and the projected service account token volume. |true |Yes |

+| Private endpoint support for inbound connections | No | Yes | Yes | Yes | Yes |

+| [Workspaces](workspaces-overview.md) | No | Yes | No | Yes | Yes |

+| [Policies](api-management-howto-policies.md)⁴ | Yes | Yes | Yes | Yes | Yes |

+⁴ See [Gateway overview](api-management-gateways-overview.md#policies) for differences in policy support in the dedicated, consumption, and self-hosted gateways. <br/>

+ Title: Set up inbound private endpoint for Azure API Management

+description: Learn how to restrict inbound access to an Azure API Management instance by using an Azure private endpoint and Azure Private Link.

+# Connect privately to API Management using an inbound private endpoint

+You can configure an inbound [private endpoint](../private-link/private-endpoint-overview.md) for your API Management instance to allow clients in your private network to securely access the instance over [Azure Private Link](../private-link/private-link-overview.md).

+* The private endpoint uses an IP address from an Azure VNet in which it's hosted.

+* Only the API Management instance's Gateway endpoint supports inbound Private Link connections.

+* Each API Management instance supports at most 100 Private Link connections.

+* Connections aren't supported on the [self-hosted gateway](self-hosted-gateway-overview.md).

+1. Select **Inbound private endpoint connections** > **+ Add endpoint**.

+ | Name | Enter a name for the endpoint such as *myPrivateEndpoint*. |

+ | Network Interface Name | Enter a name for the network interface, such as *myInterface* |

+1. Select the **Virtual Network** tab or the **Next: Virtual Network** button at the bottom of the screen.

+1. In **Networking**, enter or select this information:

+ | Private IP configuration | In most cases, select **Dynamically allocate IP address.** |

+ | Application security group | Optionally select an [application security group](../virtual-network/application-security-groups.md). |

+1. Select the **DNS** tab or the **Next: DNS** button at the bottom of the screen.

+1. In **Private DNS integration**, enter or select this information:

+ | Setting | Value |

+ | - | -- |

+ | Private DNS zones | The default value is displayed: **(new) privatelink.azure-api.net**.

+1. Select the **Tags** tab or the **Next: Tabs** button at the bottom of the screen. If you desire, enter tags to organize your Azure resources.

+1. Select **Review + create**.

+After the private endpoint is created, it appears in the list on the API Management instance's **Inbound private endpoint connections** page in the portal.

+1. Navigate to your API Management service in the [Azure portal](https://portal.azure.com/).

+1. In the left-hand menu, select **Network** > **Inbound private endpoint connections**, and select the private endpoint you created.

+* Learn more about [private endpoints](../private-link/private-endpoint-overview.md) and [Private Link](../private-link/private-link-overview.md), including [Private Link pricing](https://azure.microsoft.com/pricing/details/private-link/).

+* **Enabling secure and private inbound connectivity** to the API Management gateway using a *private endpoint*.

+|**[Inbound private endpoint](#inbound-private-endpoint)** | Developer, Basic, Standard, Premium | Gateway only (managed gateway supported, self-hosted gateway not supported). | Only inbound traffic can be allowed from internet, peered virtual networks, Express Route, and S2S VPN connections. | Secure client connection to API Management gateway |

+* Due to platform limitations, connectivity between a resource in a globally peered VNet in another region and an API Management service in internal mode doesn't work. For more information, see the [virtual network documentation](../virtual-network/virtual-network-manage-peering.md#requirements-and-constraints).

+## Inbound private endpoint

+API Management supports [private endpoints](../private-link/private-endpoint-overview.md) for secure inbound client connections to your API Management instance. Each secure connection uses a private IP address from your virtual network and Azure Private Link.

+For more information, see [Connect privately to API Management using an inbound private endpoint](private-endpoint.md).

+Workspace APIs can't be published to self-hosted gateways.

+* *dnsSuffix*: This parameter defines the default root domain that's assigned to the ASE. In the public variation of Azure App Service, the default root domain for all web apps is *azurewebsites.net*. Because an ILB ASE is internal to a customer's virtual network, it doesn't make sense to use the public service's default root domain. Instead, an ILB ASE should have a default root domain that makes sense for use within a company's internal virtual network. For example, Contoso Corporation might use a default root domain of *internal-contoso.com* for apps that are intended to be resolvable and accessible only within Contoso's virtual network. To specify custom root domain you need to use api version `2018-11-01` or earlier versions.

+ILB ASEs that were made before May 2019 required you to set the domain suffix during ASE creation. They also required you to upload a default certificate that was based on that domain suffix. Also, with an older ILB ASE you can't perform single sign-on to the Kudu console with apps in that ILB ASE. When configuring DNS for an older ILB ASE, you need to set the wildcard A record in a zone that matches to your domain suffix. Creating or changing ILB ASE with custom domain suffix requires you to use Azure Resource Manager templates and an api version prior to 2019. Last support api version is `2018-11-01`.

+The DNS settings for the default domain suffix of your App Service Environment don't restrict your apps to only being accessible by those names. You can set a custom domain name without any validation on your apps in an App Service Environment. If you then want to create a zone named `contoso.net`, you can do so and point it to the inbound IP address. The custom domain name works for app requests, and if the custom domain suffix certificate includes a wildcard SAN for scm, custom domain name also work for `scm` site and you can create a `*.scm` record and point it to the inbound IP address.

+- **Manual**: Get [15 days window](./how-to-upgrade-preference.md) to deploy the upgrade manually.

+| SSL connection is required. Please specify SSL options and retry when trying to connect. | SSL connectivity to Azure Database for MySQL and Azure Database for PostgreSQL isn't supported for database backups. Use the native backup feature in the respective database instead. |

+ > [!NOTE]

+ > If you experience issues creating a custom location on your cluster, you may need to [enable the custom location feature on your cluster](../azure-arc/kubernetes/custom-locations.md#enable-custom-locations-on-your-cluster). This is required if logged into the CLI using a Service Principal or if you are logged in with an Azure Active Directory user with restricted permissions on the cluster resource.

+ >

+|`WEBSITE_HEALTHCHECK_MAXUNHEALTHYWORKERPERCENT` | 1 - 100 | By default, no more than half of the instances will be excluded from the load balancer at one time to avoid overwhelming the remaining healthy instances. For example, if an App Service Plan is scaled to four instances and three are unhealthy, two will be excluded. The other two instances (one healthy and one unhealthy) will continue to receive requests. In the worst-case scenario where all instances are unhealthy, none will be excluded. <br /> To override this behavior, set app setting to a value between `1` and `100`. A higher value means more unhealthy instances will be removed (default value is `50`). |

+You can control the IP address of outbound traffic from your app by using regional VNet integration together with a virtual network NAT gateway to direct traffic through a static public IP address. [Regional VNet integration](./overview-vnet-integration.md) is available on **Basic**, **Standard**, **Premium**, **PremiumV2** and **PremiumV3** App Service plans. To learn more about this setup, see [NAT gateway integration](./networking/nat-gateway-integration.md).

+> [Static IP restrictions](app-service-ip-restrictions.md)

+az resource update --resource-group <group-name> --name <app-name> --resource-type "Microsoft.Web/sites" --set properties.dnsConfiguration.dnsServers="['168.63.129.16','xxx.xxx.xxx.xxx']"

+When stored in the App Service file system, logs are subject to the available storage for your pricing tier (see [App Service limits](../azure-resource-manager/management/azure-subscription-service-limits.md#app-service-limits)).

+ Title: 'Tutorial - Web app accesses SQL Database as the user'

+description: Secure database connectivity with Azure Active Directory authentication from .NET web app, using the signed-in user. Learn how to apply it to other Azure services.

+ms.devlang: csharp

+# Tutorial: Connect an App Service app to SQL Database on behalf of the signed-in user

+This tutorial shows you how to enable [built-in authentication](overview-authentication-authorization.md) in an [App Service](overview.md) app using the Azure Active Directory authentication provider, then extend it by connecting it to a back-end Azure SQL Database by impersonating the signed-in user (also known as the [on-behalf-of flow](../active-directory/develop/v2-oauth2-on-behalf-of-flow.md)). This is a more advanced connectivity approach to [Tutorial: Access data with managed identity](tutorial-connect-msi-sql-database.md) and has the following advantages in enterprise scenarios:

+- Eliminates connection secrets to back-end services, just like the managed identity approach.

+- Gives the back-end database (or any other Azure service) more control over who or how much to grant access to its data and functionality.

+- Lets the app tailor its data presentation to the signed-in user.

+In this tutorial, you add Azure Active Directory authentication to the sample web app you deployed in one of the following tutorials:

+- [Tutorial: Build an ASP.NET app in Azure with Azure SQL Database](app-service-web-tutorial-dotnet-sqldatabase.md)

+- [Tutorial: Build an ASP.NET Core and Azure SQL Database app in Azure App Service](tutorial-dotnetcore-sqldb-app.md)

+When you're finished, your sample app will authenticate users connect to SQL Database securely on behalf of the signed-in user.

+> [!NOTE]

+> The steps covered in this tutorial support the following versions:

+>

+> - .NET Framework 4.8 and higher

+> - .NET 6.0 and higher

+>

+What you will learn:

+> [!div class="checklist"]

+> * Enable built-in authentication for Azure SQL Database

+> * Disable other authentication options in Azure SQL Database

+> * Enable App Service authentication

+> * Use Azure Active Directory as the identity provider

+> * Access Azure SQL Database on behalf of the signed-in Azure AD user

+> [!NOTE]

+>Azure AD authentication is _different_ from [Integrated Windows authentication](/previous-versions/windows/it-pro/windows-server-2003/cc758557(v=ws.10)) in on-premises Active Directory (AD DS). AD DS and Azure AD use completely different authentication protocols. For more information, see [Azure AD Domain Services documentation](../active-directory-domain-services/index.yml).

+## Prerequisites

+This article continues where you left off in either one of the following tutorials:

+- [Tutorial: Build an ASP.NET app in Azure with SQL Database](app-service-web-tutorial-dotnet-sqldatabase.md)

+- [Tutorial: Build an ASP.NET Core and SQL Database app in Azure App Service](tutorial-dotnetcore-sqldb-app.md).

+If you haven't already, follow one of the two tutorials first. Alternatively, you can adapt the steps for your own .NET app with SQL Database.

+Prepare your environment for the Azure CLI.

+## 1. Configure database server with Azure AD authentication

+First, enable Azure Active Directory authentication to SQL Database by assigning an Azure AD user as the admin of the server. This user is different from the Microsoft account you used to sign up for your Azure subscription. It must be a user that you created, imported, synced, or invited into Azure AD. For more information on allowed Azure AD users, see [Azure AD features and limitations in SQL Database](/azure/azure-sql/database/authentication-aad-overview#azure-ad-features-and-limitations).

+1. If your Azure AD tenant doesn't have a user yet, create one by following the steps at [Add or delete users using Azure Active Directory](../active-directory/fundamentals/add-users-azure-active-directory.md).

+1. Find the object ID of the Azure AD user using the [`az ad user list`](/cli/azure/ad/user#az_ad_user_list) and replace *\<user-principal-name>*. The result is saved to a variable.

+ ```azurecli-interactive

+ azureaduser=$(az ad user list --filter "userPrincipalName eq '<user-principal-name>'" --query [].id --output tsv)

+ ```

+ > [!TIP]

+ > To see the list of all user principal names in Azure AD, run `az ad user list --query [].userPrincipalName`.

+ >

+1. Add this Azure AD user as an Active Directory admin using [`az sql server ad-admin create`](/cli/azure/sql/server/ad-admin#az_sql_server_ad_admin_create) command in the Cloud Shell. In the following command, replace *\<server-name>* with the server name (without the `.database.windows.net` suffix).

+ ```azurecli-interactive

+ az sql server ad-admin create --resource-group <group-name> --server-name <server-name> --display-name ADMIN --object-id $azureaduser

+ ```

+1. Restrict the database server authentication to Active Directory authentication. This step effectively disables SQL authentication.

+ ```azurecli-interactive

+ az sql server ad-only-auth enable --resource-group <group-name> --server-name <server-name>

+ ```

+For more information on adding an Active Directory admin, see [Provision Azure AD admin (SQL Database)](/azure/azure-sql/database/authentication-aad-configure#provision-azure-ad-admin-sql-database).

+## 2. Enable user authentication for your app

+You enable authentication with Azure Active Directory as the identity provider. For more information, see [Configure Azure Active Directory authentication for your App Services application](configure-authentication-provider-aad.md).

+1. In the [Azure portal](https://portal.azure.com) menu, select **Resource groups** or search for and select *Resource groups* from any page.

+1. In **Resource groups**, find and select your resource group, then select your app.

+1. In your app's left menu, select **Authentication**, and then select **Add identity provider**.

+1. In the **Add an identity provider** page, select **Microsoft** as the **Identity provider** to sign in Microsoft and Azure AD identities.

+1. Accept the default settings and select **Add**.

+ :::image type="content" source="./media/tutorial-connect-app-access-sql-database-as-user-dotnet/add-azure-ad-provider.png" alt-text="Screenshot showing the add identity provider page." lightbox="./media/tutorial-connect-app-access-sql-database-as-user-dotnet/add-azure-ad-provider.png":::

+> [!TIP]

+> If you run into errors and reconfigure your app's authentication settings, the tokens in the token store may not be regenerated from the new settings. To make sure your tokens are regenerated, you need to sign out and sign back in to your app. An easy way to do it is to use your browser in private mode, and close and reopen the browser in private mode after changing the settings in your apps.

+## 3. Configure user impersonation to SQL Database

+Currently, your Azure app connects to SQL Database uses SQL authentication (username and password) managed as app settings. In this step, you give the app permissions to access SQL Database on behalf of the signed-in Azure AD user.

+1. In the **Authentication** page for the app, select your app name under **Identity provider**. This app registration was automatically generated for you. Select **API permissions** in the left menu.

+1. Select **Add a permission**, then select **APIs my organization uses**.

+1. Type *Azure SQL Database* in the search box and select the result.

+1. In the **Request API permissions** page for Azure SQL Database, select **Delegated permissions** and **user_impersonation**, then select **Add permissions**.

+ :::image type="content" source="./media/tutorial-connect-app-access-sql-database-as-user-dotnet/select-permission.png" alt-text="Screenshot of the Request API permissions page showing Delegated permissions, user_impersonation, and the Add permission button selected." lightbox="./media/tutorial-connect-app-access-sql-database-as-user-dotnet/select-permission.png":::

+## 4. Configure App Service to return a usable access token

+The app registration in Azure Active Directory now has the required permissions to connect to SQL Database by impersonating the signed-in user. Next, you configure your App Service app to give you a usable access token.

+In the Cloud Shell, run the following commands on the app to add the `scope` parameter to the authentication setting `identityProviders.azureActiveDirectory.login.loginParameters`.

+```azurecli-interactive

+authSettings=$(az webapp auth show --resource-group <group-name> --name <app-name>)

+authSettings=$(echo "$authSettings" | jq '.properties' | jq '.identityProviders.azureActiveDirectory.login += {"loginParameters":["scope=openid profile email offline_access https://database.windows.net/user_impersonation"]}')

+az webapp auth set --resource-group <group-name> --name <app-name> --body "$authSettings"

+```

+The commands effectively add a `loginParameters` property with extra custom scopes. Here's an explanation of the requested scopes:

+- `openid`, `profile`, and `email` are requested by App Service by default already. For information, see [OpenID Connect Scopes](../active-directory/develop/v2-permissions-and-consent.md#openid-connect-scopes).

+- `https://database.windows.net/user_impersonation` refers to Azure SQL Database. It's the scope that gives you a JWT token that includes SQL Database as a [token audience](https://wikipedia.org/wiki/JSON_Web_Token).

+- [offline_access](../active-directory/develop/v2-permissions-and-consent.md#offline_access) is included here for convenience (in case you want to [refresh tokens](#what-happens-when-access-tokens-expire)).

+> [!TIP]

+> To configure the required scopes using a web interface instead, see the Microsoft steps at [Refresh auth tokens](configure-authentication-oauth-tokens.md#refresh-auth-tokens).

+Your apps are now configured. The app can now generate a token that SQL Database accepts.

+## 5. Use the access token in your application code

+The steps you follow for your project depends on whether you're using [Entity Framework](/ef/ef6/) (default for ASP.NET) or [Entity Framework Core](/ef/core/) (default for ASP.NET Core).

+# [Entity Framework](#tab/ef)

+1. In Visual Studio, open the Package Manager Console and update Entity Framework:

+ ```powershell

+ Update-Package EntityFramework

+ ```

+1. In your DbContext object (in *Models/MyDbContext.cs*), add the following code to the default constructor.

+ ```csharp

+ var conn = (System.Data.SqlClient.SqlConnection)Database.Connection;

+ conn.AccessToken = System.Web.HttpContext.Current.Request.Headers["X-MS-TOKEN-AAD-ACCESS-TOKEN"];

+ ```

+# [Entity Framework Core](#tab/efcore)

+In your `DbContext` object (in *Models/MyDbContext.cs*), change the default constructor to the following.

+```csharp

+public MyDatabaseContext (DbContextOptions<MyDatabaseContext> options, IHttpContextAccessor accessor)

+ : base(options)

+{

+ var conn = Database.GetDbConnection() as SqlConnection;

+ conn.AccessToken = accessor.HttpContext.Request.Headers["X-MS-TOKEN-AAD-ACCESS-TOKEN"];

+}

+```

+--

+> [!NOTE]

+> The code adds the access token supplied by App Service authentication to the connection object.

+>

+> This code change doesn't work locally. For more information, see [How do I debug locally when using App Service authentication?](#how-do-i-debug-locally-when-using-app-service-authentication).

+## 6. Publish your changes

+# [ASP.NET](#tab/dotnet)

+1. **If you came from [Tutorial: Build an ASP.NET app in Azure with SQL Database](app-service-web-tutorial-dotnet-sqldatabase.md)**, you set a connection string in App Service using SQL authentication, with a username and password. Use the following command to remove the connection secrets, but replace *\<group-name>*, *\<app-name>*, *\<db-server-name>*, and *\<db-name>* with yours.

+ ```azurecli-interactive

+ az webapp config connection-string set --resource-group <group-name> --name <app-name> --type SQLAzure --settings MyDbConnection="server=tcp:<db-server-name>.database.windows.net;database=<db-name>;"

+ ```

+1. Publish your changes in Visual Studio. In the **Solution Explorer**, right-click your **DotNetAppSqlDb** project and select **Publish**.

+ :::image type="content" source="./media/app-service-web-tutorial-dotnet-sqldatabase/solution-explorer-publish.png" alt-text="Screenshot showing how to publish from the Solution Explorer in Visual Studio." lightbox="./media/app-service-web-tutorial-dotnet-sqldatabase/solution-explorer-publish.png":::

+1. In the publish page, select **Publish**.

+# [ASP.NET Core](#tab/dotnetcore)

+1. **If you came from [Tutorial: Build an ASP.NET Core and SQL Database app in Azure App Service](tutorial-dotnetcore-sqldb-app.md)**, you have a connection string called `defaultConnection` in App Service using SQL authentication, with a username and password. Use the following command to remove the connection secrets, but replace *\<group-name>*, *\<app-name>*, *\<db-server-name>*, and *\<db-name>* with yours.

+ ```azurecli-interactive

+ az webapp config connection-string set --resource-group <group-name> --name <app-name> --type SQLAzure --settings defaultConnection="server=tcp:<db-server-name>.database.windows.net;database=<db-name>;"

+ ```

+1. You would have made your code changes in your GitHub fork, with Visual Studio Code in the browser. From the left menu, select **Source Control**.

+1. Type in a commit message like `OBO connect` and select **Commit**.

+ The commit triggers a GitHub Actions deployment to App Service. Wait a few minutes for the deployment to finish.

+--

+When the new webpage shows your to-do list, your app is connecting to the database on behalf of the signed-in Azure AD user.

+

+You should now be able to edit the to-do list as before.

+## 7. Clean up resources

+In the preceding steps, you created Azure resources in a resource group. If you don't expect to need these resources in the future, delete the resource group by running the following command in the Cloud Shell:

+```azurecli-interactive

+az group delete --name <group-name>

+```

+This command may take a minute to run.

+## Frequently asked questions

+- [Why do I get a `Login failed for user '<token-identified principal>'.` error?](#why-do-i-get-a-login-failed-for-user-token-identified-principal-error)

+- [How do I add other Azure AD users or groups in Azure SQL Database?](#how-do-i-add-other-azure-ad-users-or-groups-in-azure-sql-database)

+- [How do I debug locally when using App Service authentication?](#how-do-i-debug-locally-when-using-app-service-authentication)

+- [What happens when access tokens expire?](#what-happens-when-access-tokens-expire)

+#### Why do I get a `Login failed for user '<token-identified principal>'.` error?

+The most common causes of this error are:

+- You're running the code locally, and there's no valid token in the `X-MS-TOKEN-AAD-ACCESS-TOKEN` request header. See [How do I debug locally when using App Service authentication?](#how-do-i-debug-locally-when-using-app-service-authentication).

+- Azure AD authentication isn't configured on your SQL Database.

+- The signed-in user isn't permitted to connect to the database. See [How do I add other Azure AD users or groups in Azure SQL Database?](#how-do-i-add-other-azure-ad-users-or-groups-in-azure-sql-database).

+#### How do I add other Azure AD users or groups in Azure SQL Database?

+1. Connect to your database server, such as with [sqlcmd](/azure/azure-sql/database/authentication-aad-configure#sqlcmd) or [SSMS](/azure/azure-sql/database/authentication-aad-configure#connect-to-the-database-using-ssms-or-ssdt).

+1. [Create contained users mapped to Azure AD identities](/azure/azure-sql/database/authentication-aad-configure#create-contained-users-mapped-to-azure-ad-identities) in SQL Database documentation.

+ The following Transact-SQL example adds an Azure AD identity to SQL Server and gives it some database roles:

+ ```sql

+ CREATE USER [<user-or-group-name>] FROM EXTERNAL PROVIDER;

+ ALTER ROLE db_datareader ADD MEMBER [<user-or-group-name>];

+ ALTER ROLE db_datawriter ADD MEMBER [<user-or-group-name>];

+ ALTER ROLE db_ddladmin ADD MEMBER [<user-or-group-name>];

+ GO

+ ```

+#### How do I debug locally when using App Service authentication?

+Because App Service authentication is a feature in Azure, it's not possible for the same code to work in your local environment. Unlike the app running in Azure, your local code doesn't benefit from the authentication middleware from App Service. You have a few alternatives:

+- Connect to SQL Database from your local environment with [`Active Directory Interactive`](/sql/connect/ado-net/sql/azure-active-directory-authentication#using-active-directory-interactive-authentication). The authentication flow doesn't sign in the user to the app itself, but it does connect to the back-end database with the signed-in user, and allows you to test database authorization locally.

+- Manually copy the access token from `https://<app-name>.azurewebsites.net/.auth/me` into your code, in place of the `X-MS-TOKEN-AAD-ACCESS-TOKEN` request header.

+- If you deploy from Visual Studio, use remote debugging of your App Service app.

+#### What happens when access tokens expire?

+Your access token expires after some time. For information on how to refresh your access tokens without requiring users to reauthenticate with your app, see [Refresh identity provider tokens](configure-authentication-oauth-tokens.md#refresh-auth-tokens).

+## Next steps

+What you learned:

+> [!div class="checklist"]

+> * Enable built-in authentication for Azure SQL Database

+> * Disable other authentication options in Azure SQL Database

+> * Enable App Service authentication

+> * Use Azure Active Directory as the identity provider

+> * Access Azure SQL Database on behalf of the signed-in Azure AD user

+> [!div class="nextstepaction"]

+> [Map an existing custom DNS name to Azure App Service](app-service-web-tutorial-custom-domain.md)

+> [!div class="nextstepaction"]

+> [Tutorial: Access Microsoft Graph from a secured .NET app as the app](scenario-secure-app-access-microsoft-graph-as-app.md)

+> [!div class="nextstepaction"]

+> [Tutorial: Isolate back-end communication with Virtual Network integration](tutorial-networking-isolate-vnet.md)

+[App Service](overview.md) provides a highly scalable, self-patching web hosting service in Azure. It also provides a [managed identity](overview-managed-identity.md) for your app, which is a turn-key solution for securing access to [Azure SQL Database](/azure/sql-database/) and other Azure services. Managed identities in App Service make your app more secure by eliminating secrets from your app, such as credentials in the connection strings. In this tutorial, you add managed identity to the sample web app you built in one of the following tutorials:

+ This code uses [Azure.Identity.DefaultAzureCredential](/dotnet/api/azure.identity.defaultazurecredential) to get a useable token for SQL Database from Azure Active Directory and then adds it to the database connection. While you can customize `DefaultAzureCredential`, by default it's already versatile. When it runs in App Service, it uses app's system-assigned managed identity. When it runs locally, it can get a token using the logged-in identity of Visual Studio, Visual Studio Code, Azure CLI, and Azure PowerShell.

+ That's every thing you need to connect to SQL Database. When you debug in Visual Studio, your code uses the Azure AD user you configured in [2. Set up your dev environment](#2-set-up-your-dev-environment). You'll set up SQL Database later to allow connection from the managed identity of your App Service app.

+ That's everything you need to connect to SQL Database. When you debug in Visual Studio, your code uses the Azure AD user you configured in [2. Set up your dev environment](#2-set-up-your-dev-environment). You'll set up SQL Database later to allow connection from the managed identity of your App Service app. The `DefaultAzureCredential` class caches the token in memory and retrieves it from Azure AD just before expiration. You don't need any custom code to refresh the token.

+> [!div class="nextstepaction"]

+> [Tutorial: Connect an App Service app to SQL Database on behalf of the signed-in user](tutorial-connect-app-access-sql-database-as-user-dotnet.md)

+* [Metrics](application-gateway-metrics.md): Application Gateway has several metrics that help you verify your system is performing as expected.

+|clientResponseTime| Time difference (in **seconds**) between first byte received from the backend to first byte sent to the client. |

+|host| The hostname with which the request has been sent to the backend server. If backend hostname is being overridden, this name reflects that.|

+The cookie-based session affinity feature is useful when you want to keep a user session on the same server. Using gateway-managed cookies, the Application Gateway can direct subsequent traffic from a user session to the same server for processing. This is important in cases where session state is saved locally on the server for a user session.

+Connection draining helps you achieve graceful removal of backend pool members during planned service updates or problems with backend health. This setting is enabled via the [Backend Setting](configuration-http-settings.md) and is applied to all backend pool members during rule creation. Once enabled, the application gateway ensures all deregistering instances of a backend pool don't receive any new requests while allowing existing requests to complete within a configured time limit. It applies to cases where backend instances are:

+- explicitly removed from the backend pool after a configuration change by a user

+- removed during a scale-in operation

+The only exception is when requests continue to be proxied to the deregistering instances because of gateway-managed session affinity.

+The connection draining is honored for WebSocket connections as well. Connection draining is invoked for every single update to the gateway. To prevent connection loss to existing members of the backend pool, make sure to enable connection draining.

+For information on time limits, see [Backend Settings configuration](configuration-http-settings.md#connection-draining).

+Application Gateway and WAF v2 SKU supports the capability to add, remove, or update HTTP request and response headers, while the request and response packets move between the client and backend pools. You can also rewrite URLs, query string parameters and host name. With URL rewrite and URL path-based routing, you can choose to either route requests to one of the backend pools based on the original path or the rewritten path, using the reevaluate path map option.

+> [!IMPORTANT]

+>

+> Custom classification model is currently in public preview. Features, approaches, and processes may change, prior to General Availability (GA), based on user feedback.

+>

+| &bullet; English (en) | United States (us), Australia (-au), Canada (-ca), United Kingdom (-uk), India (-in)|

+# Build and train a custom classification model (preview)

+> [!IMPORTANT]

+>

+> Custom classification model is currently in public preview. Features, approaches, and processes may change, prior to General Availability (GA), based on user feedback.

+>

+1. **Training a custom classifier requires the output from the Layout model for each document in your dataset**. Run layout on all documents prior to the model training process.

+## Troubleshoot

+The [classification model](../concept-custom-classifier.md) requires results from the [layout model](../concept-layout.md) for each training document. If you haven't provided the layout results, the Studio attempts to run the layout model for each document prior to training the classifier. This process is throttled and can result in a 429 response.

+In the Studiio, prior to training with the classification model, run the [layout model](https://formrecognizer.appliedai.azure.com/studio/layout) on each document and upload it to the same location as the original document. Once the layout results are added, you can train the classifier model with your documents.

+|**Arkas Logistics** | [**Arkas Logistics**](http://www.arkaslojistik.com.tr/) is operates under the umbrella of Arkas Holding, T├╝rkiye's leading holding institution and operating in 23 countries. During the COVID-19 crisis, the company has been able to provide outstanding, complete logistical services thanks to its focus on contactless operation and digitalization steps. Form Recognizer powers a solution that maintains the continuity of the supply chain and allows for uninterrupted service. | [Customer story](https://customers.microsoft.com/story/842149-arkas-logistics-transportation-azure-en-turkey ) |

+ * English - United States (en-US), Australia (en-AU), Canada (en-CA), United Kingdom (en-UK), India (en-IN)

+ * English - Australia (en-AU), Canada (en-CA), United Kingdom (en-UK), India (en-IN)

+| Turkish (T├╝rkiye) | tr-TR |

+| Turkish (T├╝rkiye) | tr-TR |

+| Turkish (T├╝rkiye) | tr-TR |

+| Turkish (T├╝rkiye) | tr-TR |

+Runbooks in Azure Automation that manage Azure resources require authentication to Azure. [Managed Identities](enable-managed-identity-for-automation.md) is the default mechanism that an Automation runbook uses to access Azure Resource Manager resources in your subscription. You can add this functionality to a graphical runbook by importing the following runbook into the automation account, which leverages the system-assigned Managed Identity of the automation account to authenticate and access Azure resources.

+```powershell-interactive

+wget https://raw.githubusercontent.com/azureautomation/runbooks/master/Utility/AzMI/AzureAutomationTutorialWithIdentityGraphical.graphrunbook -outfile AzureAutomationTutorialWithIdentityGraphical.graphrunbook

+```

+|**User** |Supports user-defined runbooks intended to run directly on the Windows and Linux machines. |

+> [!IMPORTANT]

+> Azure Automation Run As Account will retire on September 30, 2023 and will be replaced with Managed Identities. Before that date, you'll need to start migrating your runbooks to use [managed identities](automation-security-overview.md#managed-identities). For more information, see [migrating from an existing Run As accounts to managed identity](https://learn.microsoft.com/azure/automation/migrate-run-as-accounts-managed-identity?tabs=run-as-account#sample-scripts) to start migrating the runbooks from Run As account to managed identities before 30 September 2023.

+> [!IMPORTANT]

+> Azure Automation Run As Account will retire on September 30, 2023 and will be replaced with Managed Identities. Before that date, you'll need to start migrating your runbooks to use [managed identities](automation-security-overview.md#managed-identities). For more information, see [migrating from an existing Run As accounts to managed identity](https://learn.microsoft.com/azure/automation/migrate-run-as-accounts-managed-identity?tabs=run-as-account#sample-scripts) to start migrating the runbooks from Run As account to managed identities before 30 September 2023.

+> Start/Stop VM during off-hours version 1 is unavailable in the marketplace now as it will retire by 30 September 2023. We recommend you start using [version 2](../azure-functions/start-stop-vms/overview.md) which is now generally available. The new version offers all existing capabilities and provides new features, such as multi-subscription support from a single Start/Stop instance. If you have the version 1 solution already deployed, you can still use the feature, and we will provide support until 30 September 2023. The details of the announcement will be shared soon.

+| Windows | Linux |

+| &#9679; Windows Server 2022 (including Server Core) <br> &#9679; Windows Server 2019 (including Server Core) <br> &#9679; Windows Server 2016, version 1709 and 1803 (excluding Server Core) <br> &#9679; Windows Server 2012, 2012 R2 <br> &#9679; Windows 10 Enterprise (including multi-session) and Pro| &#9679; Debian GNU/Linux 8,9,10, and 11 <br> &#9679; Ubuntu 18.04 LTS, 20.04 LTS, and 22.04 LTS <br> &#9679; SUSE Linux Enterprise Server 15.2, and 15.3 <br> &#9679; Red Hat Enterprise Linux Server 7, and 8 </br> *Hybrid Worker extension would follow support timelines of the OS vendor.ΓÇ»|

+| Windows | Linux |

+cert = automationassets.get_automation_certificate("MyCertificate")

+cert = automationassets.get_automation_certificate("MyCertificate")

+You can scale your cache instances in the Azure portal. Also, you can programmatically scale your cache using PowerShell cmdlets, Azure CLI, and by using the Microsoft Azure Management Libraries (MAML).

+For more information on scaling and memory, depending on your tier see either:

+- [How to scale - Basic, Standard, and Premium tiers](cache-how-to-scale.md#how-to-scalebasic-standard-and-premium-tiers), or

+- [How to scale up and out - Enterprise and Enterprise Flash tiers](cache-how-to-scale.md#how-to-scale-up-and-outenterprise-and-enterprise-flash-tiers).

+ Title: Configure active encryption for Enterprise Azure Cache for Redis instances

+description: Learn about encryption for your Azure Cache for Redis Enterprise instances across Azure regions.

+# Configure disk encryption for Azure Cache for Redis instances using customer managed keys (preview)

+In this article, you learn how to configure disk encryption using Customer Managed Keys (CMK). The Enterprise and Enterprise Flash tiers of Azure Cache for Redis offer the ability to encrypt the OS and data persistence disks with customer-managed key encryption. Platform-managed keys (PMKs), also know as Microsoft-managed keys (MMKs), are used to encrypt the data. However, customer managed keys (CMK) can also be used to wrap the MMKs to control access to these keys. This makes the CMK a _key encryption key_ or KEK. For more information, see [key management in Azure](/azure/security/fundamentals/key-management).

+Data in a Redis server is stored in memory by default. This data isn't encrypted. You can implement your own encryption on the data before writing it to the cache. In some cases, data can reside on-disk, either due to the operations of the operating system, or because of deliberate actions to persist data using [export](cache-how-to-import-export-data.md) or [data persistence](cache-how-to-premium-persistence.md).

+> [!NOTE]

+> Operating system disk encryption is more important on the Premium tier because open-source Redis can page cache data to disk. The Enterprise tiers does not do page cache data to disk, which is an advantage of the Enterprise and Enterprise Flash tiers.

+>

+## Scope of availability for CMK disk encryption

+|: Tier :| Basic, Standard, Premium | Enterprise, Enterprise Flash |

+|--|||

+|Microsoft managed keys (MMK) | Yes | Yes |

+|Customer managed keys (CMK) | No | Yes (preview) |

+> [!NOTE]

+> By default, all Azure Cache for Redis tiers use Microsoft managed keys to encrypt disks mounted to cache instances. However, in the Basic and Standard tiers, the C0 and C1 SKUs do not support any disk encryption.

+>

+> [!IMPORTANT]

+> On the Premium tier, data persistence streams data directly to Azure Storage, so disk encryption is less important. Azure Storage offers a [variety of encryption methods](../storage/common/storage-service-encryption.md) to be used instead.

+>

+## Encryption coverage

+### Enterprise tiers

+In the **Enterprise** tier, disk encryption is used to encrypt the persistence disk, temporary files, and the OS disk:

+- persistence disk: holds persisted RDB or AOF files as part of [data persistence](cache-how-to-premium-persistence.md)

+- temporary files used in _export_: temporary data used exported is encrypted. When you [export](cache-how-to-import-export-data.md) data, the encryption of the final exported data is controlled by settings in the storage account.

+- the OS disk

+MMK is used to encrypt these disks by default, but CMK can also be used.

+In the **Enterprise Flash** tier, keys and values are also partially stored on-disk using nonvolatile memory express (NVMe) flash storage. However, this disk isn't the same as the one used for persisted data. Instead, it's ephemeral, and data isn't persisted after the cache is stopped, deallocated, or rebooted. only MMK is only supported on this disk because this data is transient and ephemeral.

+| Data stored |Disk |Encryption Options |

+|-||-|

+|Persistence files | Persistence disk | MMK or CMK |

+|RDB files waiting to be exported | OS disk and Persistence disk | MMK or CMK |

+|Keys & values (Enterprise Flash tier only) | Transient NVMe disk | MMK |

+### Other tiers

+In the **Basic, Standard, and Premium** tiers, the OS disk is encrypted using MMK. There's no persistence disk mounted and Azure Storage is used instead.

+## Prerequisites and limitations

+### General prerequisites and limitations

+- Disk encryption isn't available in the Basic and Standard tiers for the C0 or C1 SKUs

+- Only user assigned managed identity is supported to connect to Azure Key Vault

+- Changing between MMK and CMK on an existing cache instance triggers a long-running maintenance operation. We don't recommend this for production use because a service disruption occurs.

+### Azure Key Vault prerequisites and limitations

+- The Azure Key Vault resource containing the customer managed key must be in the same region as the cache resource.

+- [Purge protection and soft-delete](../key-vault/general/soft-delete-overview.md) must be enabled in the Azure Key Vault instance. Purge protection isn't enabled by default.

+- When you use firewall rules in the Azure Key Vault, the Key Vault instance must be configured to [allow trusted services](/azure/key-vault/general/network-security).

+- Only RSA keys are supported

+- The user assigned managed identity must be given the permissions _Get_, _Unwrap Key_, and _Wrap Key_ in the Key Vault access policies, or the equivalent permissions within Azure Role Based Access Control. A recommended built-in role definition with the least privileges needed for this scenario is called [KeyVault Crypto Service Encryption User](../role-based-access-control/built-in-roles.md#key-vault-crypto-service-encryption-user).

+## How to configure CMK encryption on Enterprise caches

+### Use the portal to create a new cache with CMK enabled

+1. Sign in to the [Azure portal](https://portal.azure.com) and start the [Create a Redis Enterprise cache](quickstart-create-redis-enterprise.md) quickstart guide.

+1. On the **Advanced** page, go to the section titled **Customer-managed key encryption at rest** and enable the **Use a customer-managed key** option.

+ :::image type="content" source="media/cache-how-to-encryption/cache-use-key-encryption.png" alt-text="Screenshot of the advanced settings with customer-managed key encryption checked and in a red box.":::

+1. Select **Add** to assign a [user assigned managed identity](../active-directory/managed-identities-azure-resources/how-manage-user-assigned-managed-identities.md) to the resource. This managed identity is used to connect to the [Azure Key Vault](../key-vault/general/overview.md) instance that holds the customer managed key.

+ :::image type="content" source="media/cache-how-to-encryption/cache-managed-identity-user-assigned.png" alt-text="Screenshot showing user managed identity in the working pane.":::

+1. Select your chosen user assigned managed identity, and then choose the key input method to use.

+1. If using the **Select Azure key vault and key** input method, choose the Key Vault instance that holds your customer managed key. This instance must be in the same region as your cache.

+ > [!NOTE]

+ > For instructions on how to set up an Azure Key Vault instance, see the [Azure Key Vault quickstart guide](../key-vault/secrets/quick-create-portal.md). You can also select the _Create a key vault_ link beneath the Key Vault selection to create a new Key Vault instance.

+1. Choose the specific key and version using the **Customer-managed key (RSA)** and **Version** drop-downs.

+ :::image type="content" source="media/cache-how-to-encryption/cache-managed-identity-version.png" alt-text="Screenshot showing the select identity and key fields completed.":::

+1. If using the **URI** input method, enter the Key Identifier URI for your chosen key from Azure Key Vault.

+1. When you've entered all the information for your cache, select **Review + create**.

+### Add CMK encryption to an existing Enterprise cache

+1. Go to the **Encryption** in the Resource menu of your cache instance. If CMK is already set up, you see the key information.

+1. If you haven't set up or if you want to change CMK settings, select **Change encryption settings**

+ :::image type="content" source="media/cache-how-to-encryption/cache-encryption-existing-use.png" alt-text="Screenshot encryption selected in the Resource menu for an Enterprise tier cache.":::

+1. Select **Use a customer-managed key** to see your configuration options.

+1. Select **Add** to assign a [user assigned managed identity](../active-directory/managed-identities-azure-resources/how-manage-user-assigned-managed-identities.md) to the resource. This managed identity is used to connect to the [Azure Key Vault](../key-vault/general/overview.md) instance that holds the customer managed key.

+1. Select your chosen user assigned managed identity, and then choose which key input method to use.

+1. If using the **Select Azure key vault and key** input method, choose the Key Vault instance that holds your customer managed key. This instance must be in the same region as your cache.

+ > [!NOTE]

+ > For instructions on how to set up an Azure Key Vault instance, see the [Azure Key Vault quickstart guide](../key-vault/secrets/quick-create-portal.md). You can also select the _Create a key vault_ link beneath the Key Vault selection to create a new Key Vault instance.

+1. Choose the specific key using the **Customer-managed key (RSA)** drop-down. If there are multiple versions of the key to choose from, use the **Version** drop-down.

+ :::image type="content" source="media/cache-how-to-encryption/cache-encryption-existing-key.png" alt-text="Screenshot showing the select identity and key fields completed for Encryption.":::

+

+1. If using the **URI** input method, enter the Key Identifier URI for your chosen key from Azure Key Vault.

+1. Select **Save**

+## Next steps

+Learn more about Azure Cache for Redis features:

+- [Data persistence](cache-how-to-premium-persistence.md)

+- [Import/Export](cache-how-to-import-export-data.md)

+Use the import and export functionality in Azure Cache for Redis as a data management operation. You import data into your cache instance or export data from a cache instance using an Azure Cache for Redis Database (RDB) snapshot. The snapshots are imported or exported using a blob in an Azure Storage Account.

+Import/Export is supported in the Premium, Enterprise, and Enterprise Flash tiers:

+- _Export_ - you can export your Azure Cache for Redis RDB snapshots to a Page Blob (Premium tier) or Block Blob (Enterprise tiers).

+- _Import_ - you can import your Azure Cache for Redis RDB snapshots from either a Page Blob or a Block Blob.

+You can use Import/Export to migrate between different Azure Cache for Redis instances or populate the cache with data before use.

+## Scope of availability

+|Tier | Basic, Standard | Premium |Enterprise, Enterprise Flash |

+|||||

+|Available | No | Yes | Yes |

+## Compatibility

+- Data is exported as an RDB page blob in the _Premium_ tier. In the _Enterprise_ and _Enterprise Flash_ tiers, data is exported as a .gz block blob.

+- Caches running Redis 4.0 support RDB version 8 and below. Caches running Redis 6.0 support RDB version 9 and below.

+- Exported backups from newer versions of Redis (for example, Redis 6.0) can't be imported into older versions of Redis (for example, Redis 4.0)

+- RDB files from _Premium_ tier caches can be imported into _Enterprise_ and _Enterprise Flash_ tier caches.

+

+ > [!IMPORTANT]

+ > Audit log support is not yet available in the Enterprise tiers.

+ >

+- [Which tiers support Import/Export?](#which-tiers-support-importexport)

+### Which tiers support Import/Export?

+The _import_ and _export_ features are available only in the _Premium_, _Enterprise_, and _Enterprise Flash_ tiers.

+Yes, you can import data that was exported from Azure Cache for Redis instances. You can import RDB files from any Redis server running in any cloud or environment. The environments include Linux, Windows, or cloud providers such as Amazon Web Services. To do import this data, upload the RDB file from the Redis server you want into a page or block blob in an Azure Storage Account. Then, import it into your premium Azure Cache for Redis instance.

+For example, you might want to:

+1. Export the data from your production cache.

+1. Then, import it into a cache that is used as part of a staging environment for testing or migration.

+For more information on supported RDB versions used with import, see the [compatibility section](#compatibility).

+The Azure Cache for Redis _persistence_ feature is primarily a data durability feature. Conversely, the _import/export_ functionality is designed as a method to make periodic data backups for point-in-time recovery.

+<!-- Kyle I rewrote this based on another convo. Also I want the primary answer to be in the first paragraph. -->

+When _persistence_ is configured, your cache persists a snapshot of the data to disk, based on a configurable backup frequency. The data is written with a Redis-proprietary binary format. If a catastrophic event occurs that disables both the primary and the replica caches, the cache data is restored automatically using the most recent snapshot.

+Data persistence is designed for disaster recovery. It isn't intended as a point-in-time recovery mechanism.

+- On the Premium tier, the data persistence file is stored in Azure Storage, but the file can't be imported into a different cache.

+- On the Enterprise tiers, the data persistence file is stored in a mounted disk that isn't user-accessible.

+If you want to make periodic data backups for point-in-time recovery, we recommend using the _import/export_ functionality. For more information, see [How to configure data persistence for Azure Cache for Redis](cache-how-to-premium-persistence.md).

+Yes, see the following instructions for the _Premium_ tier:

+- PowerShell instructions [to import Redis data](cache-how-to-manage-redis-cache-powershell.md#to-import-an-azure-cache-for-redis) and [to export Redis data](cache-how-to-manage-redis-cache-powershell.md#to-export-an-azure-cache-for-redis).

+- Azure CLI instructions to [import Redis data](/cli/azure/redis#az-redis-import) and [export Redis data](/cli/azure/redis#az-redis-export)

+For the _Enterprise_ and _Enterprise Flash_ tiers:

+- PowerShell instructions [to import Redis data](/powershell/module/az.redisenterprisecache/import-azredisenterprisecache) and [to export Redis data](/powershell/module/az.redisenterprisecache/export-azredisenterprisecache).

+- Azure CLI instructions to [import Redis data](/cli/azure/redisenterprise/database#az-redisenterprise-database-import) and [export Redis data](/cli/azure/redisenterprise/database#az-redisenterprise-database-export)

+

+> [!CAUTION]

+> The Server Load metric can present incorrect data for Enterprise and Enterprise Flash tier caches. Sometimes Server Load is represented as being over 100. We are investigating this issue. We recommend using the CPU metric instead in the meantime.

+# Configure data persistence for an Azure Cache for Redis instance

+[Redis persistence](https://redis.io/topics/persistence) allows you to persist data stored in cache instance. If there's a hardware failure, the cache instance is rehydrated with data from the persistence file when it comes back online. The ability to persist data is an important way to boost the durability of a cache instance because all cache data is stored in memory. Data loss is possible if a failure occurs when cache nodes are down. Persistence should be a key part of your [high availability and disaster recovery](cache-high-availability.md) strategy with Azure Cache for Redis.

+> [!WARNING]

+> If you are using persistence on the Premium tier, check to see if your storage account has soft delete enabled before using the data persistence feature. Using data persistence with soft delete causes very high storage costs. For more information, see [should I enable soft delete?](#how-frequently-does-rdb-and-aof-persistence-write-to-my-blobs-and-should-i-enable-soft-delete).

+## Scope of availability

+|Tier | Basic, Standard | Premium |Enterprise, Enterprise Flash |

+|||||

+|Available | No | Yes | Yes (preview) |

+## Types of data persistence in Redis

+You have two options for persistence with Azure Cache for Redis: the _Redis database_ (RDB) format and _Append only File_ (AOF) format:

+- _RDB persistence_ - When you use RDB persistence, Azure Cache for Redis persists a snapshot of your cache in a binary format. The snapshot is saved in an Azure Storage account. The configurable backup frequency determines how often to persist the snapshot. If a catastrophic event occurs that disables both the primary and replica cache, the cache is reconstructed using the most recent snapshot. Learn more about the [advantages](https://redis.io/topics/persistence#rdb-advantages) and [disadvantages](https://redis.io/topics/persistence#rdb-disadvantages) of RDB persistence.

+- _AOF persistence_ - When you use AOF persistence, Azure Cache for Redis saves every write operation to a log. The log is saved at least once per second in an Azure Storage account. If a catastrophic event occurs that disables both the primary and replica caches, the cache is reconstructed using the stored write operations. Learn more about the [advantages](https://redis.io/topics/persistence#aof-advantages) and [disadvantages](https://redis.io/topics/persistence#aof-disadvantages) of AOF persistence.

+Azure Cache for Redis persistence features are intended to be used to restore data to the same cache after data loss. The RDB/AOF persisted data files can't be imported to a new cache. To move data across caches, use the _Import and Export_ feature. For more information, see [Import and Export data in Azure Cache for Redis](cache-how-to-import-export-data.md).

+To generate any backups of data that can be added to a new cache, you can write automated scripts using PowerShell or CLI that export data periodically.

+## Prerequisites and limitations

+Persistence features are intended to be used to restore data to the same cache after data loss.

+- RDB/AOF persisted data files can't be imported to a new cache. Use the [Import/Export](cache-how-to-import-export-data.md) feature instead.

+- Persistence isn't supported with caches using [passive geo-replication](cache-how-to-geo-replication.md) or [active geo-replication](cache-how-to-active-geo-replication.md).

+- On the _Premium_ tier, AOF persistence isn't supported with [multiple replicas](cache-how-to-multi-replicas.md).

+- On the _Premium_ tier, data must be persisted to a storage account in the same region as the cache instance.

+## Differences between persistence in the Premium and Enterprise tiers

+On the **Premium** tier, data is persisted directly to an [Azure Storage](../storage/common/storage-introduction.md) account that you own and manage. Azure Storage automatically encrypts data when it's persisted, but you can also use your own keys for the encryption. For more information, see [Customer-managed keys for Azure Storage encryption](../storage/common/customer-managed-keys-overview.md).

+> [!WARNING]

+>

+> If you are using persistence on the Premium tier, check to see if your storage account has soft delete enabled before using the data persistence feature. Using data persistence with soft delete causes very high storage costs. For more information, see [should I enable soft delete?](#how-frequently-does-rdb-and-aof-persistence-write-to-my-blobs-and-should-i-enable-soft-delete).

+On the **Enterprise** and **Enterprise Flash** tiers, data is persisted to a managed disk attached directly to the cache instance. The location isn't configurable nor accessible to the user. Using a managed disk increases the performance of persistence. The disk is encrypted using Microsoft managed keys (MMK) by default, but customer managed keys (CMK) can also be used. For more information, see [managing data encryption](#managing-data-encryption).

+## How to set up data persistence using the Azure portal

+### [Using the portal (Premium tier)](#tab/premium)

+1. To create a Premium cache, sign in to the [Azure portal](https://portal.azure.com) and select **Create a resource**. You can create caches in the Azure portal. You can also create them using Resource Manager templates, PowerShell, or Azure CLI. For more information about creating an Azure Cache for Redis, see [Create a cache](cache-dotnet-how-to-use-azure-redis-cache.md#create-a-cache).

+ | **DNS name** | Enter a globally unique name. | The cache name must be a string between 1 and 63 characters that contain only numbers, letters, or hyphens. The name must start and end with a number or letter, and can't contain consecutive hyphens. The *host name* for your cache instance's is `\<DNS name>.redis.cache.windows.net`. |

+ | **Location** | Drop-down and select a location. | Select a [region](https://azure.microsoft.com/regions/) near other services that use your cache. |

+ | **Storage Account** | Drop-down and select your storage account. | Choose a storage account in the same region and subscription as the cache. A **Premium Storage** account is recommended because it has higher throughput. Also, we _strongly_ recommend that you disable the soft delete feature on the storage account as it leads to increased storage costs. For more information, see [Pricing and billing](../storage/blobs/soft-delete-blob-overview.md). |

+ | **First Storage Account** | Drop-down and select your storage account. | Choose a storage account in the same region and subscription as the cache. A **Premium Storage** account is recommended because it has higher throughput. Also, we _strongly_ recommend that you disable the soft delete feature on the storage account as it leads to increased storage costs. For more information, see [Pricing and billing](/azure/storage/blobs/soft-delete-blob-overview). |

+### [Using the portal (Enterprise tiers)](#tab/enterprise)

+1. Sign in to the [Azure portal](https://portal.azure.com) and start following the instructions in the [Enterprise tier quickstart guide](quickstart-create-redis-enterprise.md).

+1. When you reach the **Advanced** tab, select either _RDB_ or _AOF_ options in the **(PREVIEW) Data Persistence** section.

+ :::image type="content" source="media/cache-how-to-premium-persistence/cache-advanced-persistence.png" alt-text="Screenshot that shows the Enterprise tier Advanced tab and Data persistence is highlighted with a red box.":::

+1. To enable RDB persistence, select **RDB** and configure the settings.

+ | Setting | Suggested value | Description |

+ | | - | -- |

+ | **Backup Frequency** | Use the drop-down and select a backup interval. Choices include **60 Minutes**, **6 hours**, and **12 hours**. | This interval starts counting down after the previous backup operation successfully completes. When it elapses, a new backup starts. |

+1. To enable AOF persistence, select **AOF** and configure the settings.

+ | Setting | Suggested value | Description |

+ | | - | -- |

+ | **Backup Frequency** | Drop down and select a backup interval. Choices include **Write every second** and **Always write**. | The _Always write_ option will append new entries to the AOF file after every write to the cache. This choice offers the best durability but does lower cache performance. |

+

+1. Finish creating the cache by following the rest of the instructions in the [Enterprise tier quickstart guide](quickstart-create-redis-enterprise.md).

+> [!NOTE]

+> You can add persistence to a previously created Enterprise tier cache at any time by navigating to the **Advanced settings** in the Resource menu.

+>

+## How to set up data persistence using PowerShell and Azure CLI

+### [Using PowerShell (Premium tier)](#tab/premium)

+The [New-AzRedisCache](/powershell/module/az.rediscache/new-azrediscache) command can be used to create a new Premium-tier cache using data persistence. See examples for [RDB persistence](/powershell/module/az.rediscache/new-azrediscache#example-5-configure-data-persistence-for-a-premium-azure-cache-for-redis) and [AOF persistence](/powershell/module/az.rediscache/new-azrediscache#example-6-configure-data-persistence-for-a-premium-azure-cache-for-redis-aof-backup-enabled)

+Existing caches can be updated using the [Set-AzRedisCache](/powershell/module/az.rediscache/set-azrediscache) command. See examples of [adding persistence to an existing cache](/powershell/module/az.rediscache/set-azrediscache#example-3-modify-azure-cache-for-redis-if-you-want-to-add-data-persistence-after-azure-redis-cache-created).

+### [Using PowerShell (Enterprise tier)](#tab/enterprise)

+The [New-AzRedisEnterpriseCache](/powershell/module/az.redisenterprisecache/new-azredisenterprisecache) command can be used to create a new Enterprise-tier cache using data persistence. Use the `RdbPersistenceEnabled`, `RdbPersistenceFrequency`, `AofPersistenceEnabled`, and `AofPersistenceFrequency` parameters to configure the persistence setup. This example creates a new E10 Enterprise tier cache using RDB persistence with one hour frequency:

+```powershell-interactive

+New-AzRedisEnterpriseCache -Name "MyCache" -ResourceGroupName "MyGroup" -Location "West US" -Sku "Enterprise_E10" -RdbPersistenceEnabled -RdbPersistenceFrequency "1h"

+```

+Existing caches can be updated using the [Update-AzRedisEnterpriseCacheDatabase](/powershell/module/az.redisenterprisecache/update-azredisenterprisecachedatabase) command. This example adds RDB persistence with 12 hour frequency to an existing cache instance:

+```powershell-interactive

+Update-AzRedisEnterpriseCacheDatabase -Name "MyCache" -ResourceGroupName "MyGroup" -RdbPersistenceEnabled -RdbPersistenceFrequency "12h"

+```

+### [Using Azure CLI (Premium tier)](#tab/premium)

+The [az redis create](/cli/azure/redis#az-redis-create) command can be used to create a new Premium-tier cache using data persistence. For instance:

+```azurecli

+az redis create --location westus2 --name MyRedisCache --resource-group MyResourceGroup --sku Premium --vm-size p1 --redis-configuration @"config_rdb.json"

+```

+Existing caches can be updated using the [az redis update](/cli/azure/redis#az-redis-update) command. For instance:

+```azurecli

+az redis update --name MyRedisCache --resource-group MyResourceGroup --set "redisConfiguration.rdb-storage-connection-string"="BlobEndpoint=https//..." "redisConfiguration.rdb-backup-enabled"="true" "redisConfiguration.rdb-backup-frequency"="15" "redisConfiguration.rdb-backup-max-snapshot-count"="1"

+```

+### [Using Azure CLI (Enterprise tier)](#tab/enterprise)

+The [az redisenterprise create](/cli/azure/redisenterprise#az-redisenterprise-create) command can be used to create a new Enterprise-tier cache using data persistence. Use the `rdb-enabled`, `rdb-frequency`, `aof-enabled`, and `aof-frequency` parameters to configure the persistence setup. This example creates a new E10 Enterprise tier cache using RDB persistence with one hour frequency:

+```azurecli

+az redisenterprise create --cluster-name "cache1" --resource-group "rg1" --location "East US" --sku "Enterprise_E10" --persistence rdb-enabled=true rdb-frequency="1h"

+```

+Existing caches can be updated using the [az redisenterprise update](/cli/azure/redisenterprise#az-redisenterprise-update) command. This example adds RDB persistence with 12 hour frequency to an existing cache instance:

+```azurecli

+az redisenterprise database update --cluster-name "cache1" --resource-group "rg1" --persistence rdb-enabled=true rdb-frequency="12h"

+```

+## Managing data encryption

+Because Redis persistence creates data at rest, encrypting this data is an important concern for many users. Encryption options vary based on the tier of Azure Cache for Redis being used.

+With the **Premium** tier, data is streamed directly from the cache instance to Azure Storage when persistence is initiated. Various encryption methods can be used with Azure Storage, including Microsoft-managed keys, customer-managed keys, and customer-provided keys. For information on encryption methods, see [Azure Storage encryption for data at rest](../storage/common/storage-service-encryption.md).

+With the **Enterprise** and **Enterprise Flash** tiers, data is stored on a managed disk mounted to the cache instance. By default, the disk holding the persistence data, and the OS disk are encrypted using Microsoft-managed keys. A customer-managed key (CMK) can also be used to control data encryption. See [Encryption on Enterprise tier caches](cache-how-to-encryption.md) for instructions.

+- [Does AOF persistence affect throughput, latency, or performance of my cache?](#does-aof-persistence-affect-throughput-latency-or-performance-of-my-cache)

+Yes, persistence can be configured both at cache creation and on existing Premium, Enterprise, or Enterprise Flash caches.

+If you enable data persistence, geo-replication can't be enabled for your cache.

+For more information on performance when using AOF persistence, see [Does AOF persistence affect throughput, latency, or performance of my cache?](#does-aof-persistence-affect-throughput-latency-or-performance-of-my-cache)

+### Does AOF persistence affect throughput, latency, or performance of my cache?

+AOF persistence does affect throughput. AOF runs on both the primary and replica process, therefore you see higher CPU and Server Load for a cache with AOF persistence than an identical cache without AOF persistence. AOF offers the best consistency with the data in memory because each write and delete is persisted with only a few seconds of delay. The trade-off is that AOF is more compute intensive.

+As long as CPU and Server Load are both less than 90%, there is a penalty on throughput, but the cache operates normally, otherwise. Above 90% CPU and Server Load, the throughput penalty can get much higher, and the latency of all commands processed by the cache increases. This is because AOF persistence runs on both the primary and replica process, increasing the load on the node in use, and putting persistence on the critical path of data.

+- If you've scaled to a smaller size, and there isn't enough room in the smaller size to hold all of the data from the last backup, keys are evicted during the restore process. Typically, keys are evicted using the [allkeys-lru](https://redis.io/topics/lru-cache) eviction policy.

+### Will I be charged for the storage being used in data persistence?

+- For **Premium** caches, you're charged for the storage being used per the pricing model of the storage account being used.

+- For **Enterprise** and **Enterprise Flash** caches, you aren't charged for the managed disk storage. It's included in the price.

+We recommend that you avoid enabling soft delete on storage accounts when used with Azure Cache for Redis data persistence with the Premium tier. RDB and AOF persistence can write to your blobs as frequently as every hour, every few minutes, or every second. Also, enabling soft delete on a storage account means Azure Cache for Redis can't minimize storage costs by deleting the old backup data.

+Soft delete quickly becomes expensive with the typical data sizes of a cache that also performs write operations every second. For more information on soft delete costs, see [Pricing and billing](../storage/blobs/soft-delete-blob-overview.md).

+Yes, you can change the backup frequency for RDB persistence using the Azure portal, CLI, or PowerShell.

+All RDB persistence backups, except for the most recent one, are automatically deleted. This deletion might not happen immediately, but older backups aren't persisted indefinitely. If you're using the Premium tier for persistence, and soft delete is turned on for your storage account, the soft delete setting applies, and existing backups continue to reside in the soft delete state.

+Use a second storage account for AOF persistence when you think you've higher than expected set operations on the cache. Setting up the secondary storage account helps ensure your cache doesn't reach storage bandwidth limits. This option is only available for Premium tier caches.

+You can remove the AOF persistence secondary storage account by setting the second storage account to be the same as the first storage account. For existing caches, access **Data persistence** from the **Resource menu** for your cache. To disable AOF persistence, select **Disabled**.

+When the AOF file becomes large enough, a rewrite is automatically queued on the cache. The rewrite resizes the AOF file with the minimal set of operations needed to create the current data set. During rewrites, you can expect to reach performance limits sooner, especially when dealing with large datasets. Rewrites occur less often as the AOF file becomes larger, but take a significant amount of time when it happens.

+If the AOF file at the time of scaling is large, then expect the scale operation to take longer than expected because it reloads the file after scaling has finished.

+When you use the Premium tier, data stored in AOF files is divided into multiple page blobs per node to increase performance of saving the data to storage. The following table displays how many page blobs are used for each pricing tier:

+### Will having firewall exceptions on the storage account affect persistence?

+Using managed identity adds the cache instance to the [trusted services list](../storage/common/storage-network-security.md?tabs=azure-portal), making firewall exceptions easier to carry out. If you aren't using managed identity and instead authorizing to a storage account using a key, then having firewall exceptions on the storage account tends to break the persistence process. This only applies to persistence in the Premium tier.

+With the Premium tier, you can't use Append-only File (AOF) persistence with multiple replicas. In the Enterprise and Enterprise Flash tiers, replica architecture is more complicated, but AOF persistence is supported when Enterprise caches are used in zone redundant deployment.

+Azure Cache for Redis has different tier offerings that provide flexibility in the choice of cache size and features. Through scaling, you can change the size, tier, and number of nodes after creating a cache instance to match your application needs. This article shows you how to scale your cache using the Azure portal, plus tools such as Azure PowerShell and Azure CLI.

+## Types of scaling

+There are fundamentally two ways to scale an Azure Cache for Redis Instance:

+- _Scaling up_ increases the size of the Virtual Machine (VM) running the Redis server, adding more memory, Virtual CPUs (vCPUs), and network bandwidth. Scaling up is also called _vertical scaling_. The opposite of scaling up is _Scaling down_.

+- _Scaling out_ divides the cache instance into more nodes of the same size, increasing memory, vCPUs, and network bandwidth through parallelization. Scaling out is also referred to as _horizontal scaling_ or _sharding_. The opposite of scaling out is **Scaling in**. In the Redis community, scaling out is frequently called [_clustering_](https://redis.io/docs/management/scaling/).

+## Scope of availability

+|Tier | Basic and Standard | Premium | Enterprise and Enterprise Flash |

+||||-|

+|Scale Up | Yes | Yes | Yes (preview) |

+|Scale Down | Yes | Yes | No |

+|Scale Out | No | Yes | Yes (preview) |

+|Scale In | No | Yes | No |

+## When to scale

+You can use the [monitoring](cache-how-to-monitor.md) features of Azure Cache for Redis to monitor the health and performance of your cache. Use that information to determine when to scale the cache.

+You can monitor the following metrics to determine if you need to scale.

+- **Redis Server Load**

+ - High Redis server load means that the server is unable to keep pace with requests from all the clients. Because a Redis server is a single threaded process, it's typically more helpful to _scale out_ rather than _scale up_. Scaling out by enabling clustering helps distribute overhead functions across multiple Redis processes. Scaling out also helps distribute TLS encryption/decryption and connection/disconnection, speeding up cache instances using TLS.

+ - Scaling up can still be helpful in reducing server load because background tasks can take advantage of the more vCPUs and free up the thread for the main Redis server process.

+ - The Enterprise and Enterprise Flash tiers use Redis Enterprise rather than open source Redis. One of the advantages of these tiers is that the Redis server process can take advantage of multiple vCPUs. Because of that, both scaling up and scaling out in these tiers can be helpful in reducing server load. For more information, see [Best Practices for the Enterprise and Enterprise Flash tiers of Azure Cache for Redis](cache-best-practices-enterprise-tiers.md).

+ - For more information, see [Set up clustering](cache-how-to-premium-clustering.md#set-up-clustering).

+- **Memory Usage**

+ - High memory usage indicates that your data size is too large for the current cache size. Consider scaling to a cache size with larger memory. Either _scaling up_ or _scaling out_ is effective here.

+- **Client connections**

+ - Each cache size has a limit to the number of client connections it can support. If your client connections are close to the limit for the cache size, consider _scaling up_ to a larger tier. _Scaling out_ doesn't increase the number of supported client connections.

+ - For more information on connection limits by cache size, see [Azure Cache for Redis Pricing](https://azure.microsoft.com/pricing/details/cache/).

+- **Network Bandwidth**

+ - If the Redis server exceeds the available bandwidth, clients requests could time out because the server can't push data to the client fast enough. Check "Cache Read" and "Cache Write" metrics to see how much server-side bandwidth is being used. If your Redis server is exceeding available network bandwidth, you should consider scaling out or scaling up to a larger cache size with higher network bandwidth.

+ - For Enterprise tier caches using the _Enterprise cluster policy_, scaling out doesn't increase network bandwidth.

+ - For more information on network available bandwidth by cache size, see [Azure Cache for Redis planning FAQs](./cache-planning-faq.yml).

+For more information on determining the cache pricing tier to use, see [Choosing the right tier](cache-overview.md#choosing-the-right-tier) and [Azure Cache for Redis planning FAQs](./cache-planning-faq.yml).

+> For more information on how to optimize the scaling process, see the [best practices for scaling guide](cache-best-practices-scale.md)

+## Prerequisites/limitations of scaling Azure Cache for Redis

+You can scale up/down to a different pricing tier with the following restrictions:

+ - You can't scale from an **Enterprise** or **Enterprise Flash** cache down to any other tier.

+- You can't scale from a **Premium**, **Standard**, or **Basic** cache up to an **Enterprise** or **Enterprise Flash** cache.

+- You can't scale between **Enterprise** and **Enterprise Flash**.

+You can scale out/in with the following restrictions:

+- _Scale out_ is only supported on the **Premium**, **Enterprise**, and **Enterprise Flash** tiers.

+- _Scale in_ is only supported on the **Premium** tier.

+- On the **Premium** tier, clustering must be enabled first before scaling in or out.

+- Only the **Enterprise** and **Enterprise Flash** tiers can scale up and scale out simultaneously.

+## How to scale - Basic, Standard, and Premium tiers

+### [Scale up and down with Basic, Standard, and Premium](#tab/scale-up-and-down-with-basic-standard-and-premium)

+#### Scale up and down using the Azure portal

+1. To scale your cache, [browse to the cache](cache-configure.md#configure-azure-cache-for-redis-settings) in the [Azure portal](https://portal.azure.com) and select **Scale** from the Resource menu.

+ :::image type="content" source="media/cache-how-to-scale/scale-a-cache.png" alt-text="Screenshot showing Scale on the resource menu.":::

+1. Choose a pricing tier in the working pane and then choose **Select**.

+

+ :::image type="content" source="media/cache-how-to-scale/select-a-tier.png" alt-text="Screenshot showing the Azure Cache for Redis tiers.":::

+1. While the cache is scaling to the new tier, a **Scaling Redis Cache** notification is displayed.

+ :::image type="content" source="media/cache-how-to-scale/scaling-notification.png" alt-text="Screenshot showing the notification of scaling.":::

+1. When scaling is complete, the status changes from **Scaling** to **Running**.

+ > [!NOTE]

+ > When you scale a cache up or down using the portal, both `maxmemory-reserved` and `maxfragmentationmemory-reserved` settings automatically scale in proportion to the cache size.

+ > For example, if `maxmemory-reserved` is set to 3 GB on a 6-GB cache, and you scale to 12-GB cache, the settings automatically get updated to 6 GB during scaling.

+ > When you scale down, the reverse happens.

+ >

+#### Scale up and down using PowerShell

+You can scale your Azure Cache for Redis instances with PowerShell by using the [Set-AzRedisCache](/powershell/module/az.rediscache/set-azrediscache) cmdlet when the `Size`or `Sku` properties are modified. The following example shows how to scale a cache named `myCache` to a 6-GB cache in the same tier.

+ Set-AzRedisCache -ResourceGroupName myGroup -Name myCache -Size 6GB

+```

+For more information on scaling with PowerShell, see [To scale an Azure Cache for Redis using PowerShell](cache-how-to-manage-redis-cache-powershell.md#scale).

+#### Scale up and down using Azure CLI

+To scale your Azure Cache for Redis instances using Azure CLI, call the [az redis update](/cli/azure/redis#az-redis-update) command. Use the `sku.capcity` property to scale within a tier, for example from a Standard C0 to Standard C1 cache:

+```azurecli

+az redis update --cluster-name myCache --resource-group myGroup --set "sku.capacity"="2"

+```

+Use the 'sku.name' and 'sku.family' properties to scale up to a different tier, for instance from a Standard C1 cache to a Premium P1 cache:

+```azurecli

+az redis update --cluster-name myCache --resource-group myGroup --set "sku.name"="Premium" "sku.capacity"="1" "sku.family"="P"

+```

+For more information on scaling with Azure CLI, see [Change settings of an existing Azure Cache for Redis](cache-manage-cli.md#scale).

+> [!NOTE]

+> When you scale a cache up or down programatically (e.g. using PowerShell or Azure CLI), any `maxmemory-reserved` or `maxfragmentationmemory-reserved` are ignored as part of the update request. Only your scaling change is honored. You can update these memory settings after the scaling operation has completed.

+>

+### [Scale out and in - Premium only](#tab/scale-out-and-inpremium-only)

+#### Create a new cache that is scaled out using clustering

+Clustering is enabled during cache creation from the working pane, when you create a new Azure Cache for Redis.

+1. Use the [_Create an open-source Redis cache_ quickstart guide](quickstart-create-redis.md) to start creating a new cache using the Azure portal.

+1. In the **Advanced** tab for a **premium** cache instance, configure the settings for non-TLS port, clustering, and data persistence. To enable clustering, select **Enable**.

+ :::image type="content" source="media/cache-how-to-premium-clustering/redis-cache-clustering.png" alt-text="Clustering toggle.":::

+ You can have up to 10 shards in the cluster. After selecting **Enable**, slide the slider or type a number between 1 and 10 for **Shard count** and select **OK**.

+ Each shard is a primary/replica cache pair managed by Azure. The total size of the cache is calculated by multiplying the number of shards by the cache size selected in the pricing tier.

+ :::image type="content" source="media/cache-how-to-premium-clustering/redis-cache-clustering-selected.png" alt-text="Clustering toggle selected.":::

+ Once the cache is created, you connect to it and use it just like a nonclustered cache. Redis distributes the data throughout the Cache shards. If diagnostics is [enabled](cache-how-to-monitor.md#use-a-storage-account-to-export-cache-metrics), metrics are captured separately for each shard, and can be [viewed](cache-how-to-monitor.md) in Azure Cache for Redis using the Resource menu.

+1. Finish creating the cache using the [quickstart guide](quickstart-create-redis.md).

+It takes a while for the cache to create. You can monitor progress on the Azure Cache for Redis **Overview** page. When **Status** shows as **Running**, the cache is ready to use.

+> [!NOTE]

+>

+> There are some minor differences required in your client application when clustering is configured. For more information, see [Do I need to make any changes to my client application to use clustering?](#do-i-need-to-make-any-changes-to-my-client-application-to-use-clustering)

+>

+For sample code on working with clustering with the StackExchange.Redis client, see the [clustering.cs](https://github.com/rustd/RedisSamples/blob/master/HelloWorld/Clustering.cs) portion of the [Hello World](https://github.com/rustd/RedisSamples/tree/master/HelloWorld) sample.

+#### Scale a running Premium cache in or out

+To change the cluster size on a premium cache that you created earlier, and is already running with clustering enabled, select **Cluster size** from the Resource menu.

+To change the cluster size, use the slider or type a number between 1 and 10 in the **Shard count** text box. Then, select **OK** to save.

+Increasing the cluster size increases max throughput and cache size. Increasing the cluster size doesn't increase the max. connections available to clients.

+#### Scale out and in using PowerShell

+You can scale out your Azure Cache for Redis instances with PowerShell by using the [Set-AzRedisCache](/powershell/module/az.rediscache/set-azrediscache) cmdlet when the `ShardCount` property is modified. The following example shows how to scale out a cache named `myCache` out to use three shards (that is, scale out by a factor of three)

+```powershell

+ Set-AzRedisCache -ResourceGroupName myGroup -Name myCache -ShardCount 3

+#### Scale out and in using Azure CLI

+To scale your Azure Cache for Redis instances using Azure CLI, call the [az redis update](/cli/azure/redis#az-redis-update) command and use the `shard-count` property. The following example shows how to scale out a cache named `myCache` to use three shards (that is, scale out by a factor of three).

+```azurecli

+az redis update --cluster-name myCache --resource-group myGroup --set shard-count=3

+```

+> [!NOTE]

+> When you scale a cache up or down programmatically (e.g. using PowerShell or Azure CLI), any `maxmemory-reserved` or `maxfragmentationmemory-reserved` are ignored as part of the update request. Only your scaling change is honored. You can update these memory settings after the scaling operation has completed.

+>

+> [!NOTE]

+> Scaling a cluster runs the [MIGRATE](https://redis.io/commands/migrate) command, which is an expensive command. For minimal impact, consider running this operation during non-peak hours. During the migration process, you see a spike in server load. Scaling a cluster is a long running process and the amount of time taken depends on the number of keys and size of the values associated with those keys.

+>

+>

+## How to scale up and out - Enterprise and Enterprise Flash tiers

+The Enterprise and Enterprise Flash tiers are able to scale up and scale out in one operation. Other tiers require separate operations for each action.

+> [!CAUTION]

+> The Enterprise and Enterprise Flash tiers do not yet support _scale down_ or _scale in_ operations.

+>

+### Scale using the Azure portal

+1. To scale your cache, [browse to the cache](cache-configure.md#configure-azure-cache-for-redis-settings) in the [Azure portal](https://portal.azure.com) and select **Scale** from the Resource menu.

+

+ :::image type="content" source="media/cache-how-to-scale/cache-enterprise-scale.png" alt-text="Screenshot showing Scale selected in the Resource menu for an Enterprise cache.":::

+1. To scale up, choose a different **Cache type** and then choose **Save**.

+ > [!IMPORTANT]

+ > You can only scale up at this time. You cannot scale down.

+ :::image type="content" source="media/cache-how-to-scale/cache-enterprise-scale-up.png" alt-text="Screenshot showing the Enterprise tiers in the working pane.":::

+1. To scale out, increase the **Capacity** slider. Capacity increases in increments of two. This number reflects how many underlying Redis Enterprise nodes are being added. This number is always a multiple of two to reflect nodes being added for both primary and replica shards.

+ > [!IMPORTANT]

+ > You can only scale out, increasing capacity, at this time. You cannot scale in.

+ :::image type="content" source="media/cache-how-to-scale/cache-enterprise-capacity.png" alt-text="Screenshot showing Capacity in the working pane a red box around it.":::

+1. While the cache is scaling to the new tier, a **Scaling Redis Cache** notification is displayed.

+ :::image type="content" source="media/cache-how-to-scale/cache-enterprise-notifications.png" alt-text="Screenshot showing notification of scaling an Enterprise cache.":::

+

+1. When scaling is complete, the status changes from **Scaling** to **Running**.

+### Scale using PowerShell

+You can scale your Azure Cache for Redis instances with PowerShell by using the [Update-AzRedisEnterpriseCache](/powershell/module/az.redisenterprisecache/update-azredisenterprisecache) cmdlet. You can modify the `Sku` property to scale the instance up. You can modify the `Capacity` property to scale out the instance. The following example shows how to scale a cache named `myCache` to an Enterprise E20 (25 GB) instance with capacity of 4.

+```powershell

+ Update-AzRedisEnterpriseCache -ResourceGroupName myGroup -Name myCache -Sku Enterprise_E20 -Capacity 4

+### Scale using Azure CLI

+To scale your Azure Cache for Redis instances using Azure CLI, call the [az redisenterprise update](/cli/azure/redisenterprise#az-redisenterprise-update) command. You can modify the `sku` property to scale the instance up. You can modify the `capacity` property to scale out the instance. The following example shows how to scale a cache named `myCache` to an Enterprise E20 (25 GB) instance with capacity of 4.

+```azurecli

+az redisenterprise update --cluster-name "myCache" --resource-group "myGroup" --sku "Enterprise_E20" --capacity 4

+```

+- [Do I lose data from my cache during scaling?](#do-i-lose-data-from-my-cache-during-scaling)

+- [Is my cache be available during scaling?](#is-my-cache-be-available-during-scaling)

+- [Do I need to make any changes to my client application to use clustering?](#do-i-need-to-make-any-changes-to-my-client-application-to-use-clustering)

+- [How are keys distributed in a cluster?](#how-are-keys-distributed-in-a-cluster)

+- [What is the largest cache size I can create?](#what-is-the-largest-cache-size-i-can-create)

+- [Do all Redis clients support clustering?](#do-all-redis-clients-support-clustering)

+- [How do I connect to my cache when clustering is enabled?](#how-do-i-connect-to-my-cache-when-clustering-is-enabled)

+- [Can I directly connect to the individual shards of my cache?](#can-i-directly-connect-to-the-individual-shards-of-my-cache)

+- [Can I configure clustering for a previously created cache?](#can-i-configure-clustering-for-a-previously-created-cache)

+- [Can I configure clustering for a basic or standard cache?](#can-i-configure-clustering-for-a-basic-or-standard-cache)

+- [Can I use clustering with the Redis ASP.NET Session State and Output Caching providers?](#can-i-use-clustering-with-the-redis-aspnet-session-state-and-output-caching-providers)

+- [I'm getting MOVE exceptions when using StackExchange.Redis and clustering, what should I do?](#im-getting-move-exceptions-when-using-stackexchangeredis-and-clustering-what-should-i-do)

+- [What is the difference between OSS Clustering and Enterprise Clustering on Enterprise-tier caches?](#what-is-the-difference-between-oss-clustering-and-enterprise-clustering-on-enterprise-tier-caches)

+- [How many shards do Enterprise tier caches use?](#how-many-shards-do-enterprise-tier-caches-use)

+- You can't scale from a **Premium** cache to an **Enterprise** or **Enterprise Flash** cache.

+- When you scale a **Basic** cache to a different size, it's shut down, and a new cache is provisioned using the new size. During this time, the cache is unavailable and all data in the cache is lost.

+- When you scale a **Standard**, **Premium**, **Enterprise**, or **Enterprise Flash** cache to a different size, one of the replicas is shut down and reprovisioned to the new size and the data transferred over, and then the other replica does a failover before it's reprovisioned, similar to the process that occurs during a failure of one of the cache nodes.

+- In some cases, such as scaling or migrating your cache to a different cluster, the underlying IP address of the cache can change. The DNS record for the cache changes and is transparent to most applications. However, if you use an IP address to configure the connection to your cache, or to configure NSGs, or firewalls allowing traffic to the cache, your application might have trouble connecting sometime after the DNS record updates.

+### Do I lose data from my cache during scaling?

+- When you scale a **Standard**, **Premium**, **Enterprise**, or **Enterprise Flash** cache to a larger size, all data is typically preserved. When you scale a Standard or Premium cache to a smaller size, data can be lost if the data size exceeds the new smaller size when it's scaled down. If data is lost when scaling down, keys are evicted using the [allkeys-lru](https://redis.io/topics/lru-cache) eviction policy.

+While Standard, Premium, Enterprise, and Enterprise Flash caches have a SLA for availability, there's no SLA for data loss.

+### Is my cache be available during scaling?

+- **Standard**, **Premium**, **Enterprise**, and **Enterprise Flash** caches remain available during the scaling operation. However, connection blips can occur while scaling these caches, and also while scaling from **Basic** to **Standard** caches. These connection blips are expected to be small and redis clients can generally re-establish their connection instantly.

+- For Enterprise and Enterprise Flash caches using active geo-replication, scaling only a subset of linked caches can introduce issues over time in some cases. We recommend scaling all caches in the geo-replication group together were possible.

+With [passive geo-replication](cache-how-to-geo-replication.md) configured, you might notice that you canΓÇÖt scale a cache or change the shards in a cluster. A geo-replication link between two caches prevents you from scaling operation or changing the number of shards in a cluster. You must unlink the cache to issue these commands. For more information, see [Configure Geo-replication](cache-how-to-geo-replication.md).

+With [active geo-replication](cache-how-to-active-geo-replication.md) configured, you can't scale a cache. All caches in a geo replication group must be the same size and capacity.

+- You can't scale from a **Premium** cache to an **Enterprise** or **Enterprise Flash** cache.

+### Do I need to make any changes to my client application to use clustering?

+* When clustering is enabled, only database 0 is available. If your client application uses multiple databases and it tries to read or write to a database other than 0, the following exception is thrown: `Unhandled Exception: StackExchange.Redis.RedisConnectionException: ProtocolFailure on GET >` `StackExchange.Redis.RedisCommandException: Multiple databases are not supported on this server; cannot switch to database: 6`

+

+ For more information, see [Redis Cluster Specification - Implemented subset](https://redis.io/topics/cluster-spec#implemented-subset).

+* If you're using [StackExchange.Redis](https://www.nuget.org/packages/StackExchange.Redis/), you must use 1.0.481 or later. You connect to the cache using the same [endpoints, ports, and keys](cache-configure.md#properties) that you use when connecting to a cache where clustering is disabled. The only difference is that all reads and writes must be done to database 0.

+

+ Other clients may have different requirements. See [Do all Redis clients support clustering?](#do-all-redis-clients-support-clustering)

+* If your application uses multiple key operations batched into a single command, all keys must be located in the same shard. To locate keys in the same shard, see [How are keys distributed in a cluster?](#how-are-keys-distributed-in-a-cluster)

+* If you're using Redis ASP.NET Session State provider, you must use 2.0.1 or higher. See [Can I use clustering with the Redis ASP.NET Session State and Output Caching providers?](#can-i-use-clustering-with-the-redis-aspnet-session-state-and-output-caching-providers)

+> [!IMPORTANT]

+> When using the Enterprise or Enterprise FLash tiers, you are given the choice of _OSS Cluster Mode_ or _Enterprise Cluster Mode_. OSS Cluster Mode is the same as clustering on the Premium tier and follows the open source clustering specification. Enterprise Cluster Mode can be less performant, but uses Redis Enterprise clustering which doesn't require any client changes to use. For more information, see [Clustering on Enterprise](cache-best-practices-enterprise-tiers.md#clustering-on-enterprise).

+>

+>

+### How are keys distributed in a cluster?

+Per the Redis documentation on [Keys distribution model](https://redis.io/topics/cluster-spec#keys-distribution-model): The key space is split into 16,384 slots. Each key is hashed and assigned to one of these slots, which are distributed across the nodes of the cluster. You can configure which part of the key is hashed to ensure that multiple keys are located in the same shard using hash tags.

+* Keys with a hash tag - if any part of the key is enclosed in `{` and `}`, only that part of the key is hashed for the purposes of determining the hash slot of a key. For example, the following three keys would be located in the same shard: `{key}1`, `{key}2`, and `{key}3` since only the `key` part of the name is hashed. For a complete list of keys hash tag specifications, see [Keys hash tags](https://redis.io/topics/cluster-spec#keys-hash-tags).

+* Keys without a hash tag - the entire key name is used for hashing, resulting in a statistically even distribution across the shards of the cache.

+For best performance and throughput, we recommend distributing the keys evenly. If you're using keys with a hash tag, it's the application's responsibility to ensure the keys are distributed evenly.

+For more information, see [Keys distribution model](https://redis.io/topics/cluster-spec#keys-distribution-model), [Redis Cluster data sharding](https://redis.io/topics/cluster-tutorial#redis-cluster-data-sharding), and [Keys hash tags](https://redis.io/topics/cluster-spec#keys-hash-tags).

+For sample code about working with clustering and locating keys in the same shard with the StackExchange.Redis client, see the [clustering.cs](https://github.com/rustd/RedisSamples/blob/master/HelloWorld/Clustering.cs) portion of the [Hello World](https://github.com/rustd/RedisSamples/tree/master/HelloWorld) sample.

+### What is the largest cache size I can create?

+The largest cache size you can have is 4.5 TB. This result is a clustered F1500 cache with capacity 9. For more information, see [Azure Cache for Redis Pricing](https://azure.microsoft.com/pricing/details/cache/).

+### Do all Redis clients support clustering?

+Many clients libraries support Redis clustering but not all. Check the documentation for the library you're using to verify you're using a library and version that support clustering. StackExchange.Redis is one library that does support clustering, in its newer versions. For more information on other clients, see the [Playing with the cluster](https://redis.io/topics/cluster-tutorial#playing-with-the-cluster) section of the [Redis cluster tutorial](https://redis.io/topics/cluster-tutorial).

+The Redis clustering protocol requires each client to connect to each shard directly in clustering mode, and also defines new error responses such as 'MOVED' na 'CROSSSLOTS'. When you attempt to use a client library that doesn't support clustering, with a cluster mode cache, the result can be many [MOVED redirection exceptions](https://redis.io/topics/cluster-spec#moved-redirection), or just break your application, if you're doing cross-slot multi-key requests.

+> [!NOTE]

+> If you're using StackExchange.Redis as your client, verify that you are using the latest version of [StackExchange.Redis](https://www.nuget.org/packages/StackExchange.Redis/) 1.0.481 or later for clustering to work correctly. For more information on any issues with move exceptions, see [move exceptions](#im-getting-move-exceptions-when-using-stackexchangeredis-and-clustering-what-should-i-do).

+>

+### How do I connect to my cache when clustering is enabled?

+You can connect to your cache using the same [endpoints](cache-configure.md#properties), [ports](cache-configure.md#properties), and [keys](cache-configure.md#access-keys) that you use when connecting to a cache that doesn't have clustering enabled. Redis manages the clustering on the backend so you don't have to manage it from your client.

+### Can I directly connect to the individual shards of my cache?

+The clustering protocol requires the client to make the correct shard connections, so the client should make share connections for you. With that said, each shard consists of a primary/replica cache pair, collectively known as a cache instance. You can connect to these cache instances using the redis-cli utility in the [unstable](https://redis.io/download) branch of the Redis repository at GitHub. This version implements basic support when started with the `-c` switch. For more information, see [Playing with the cluster](https://redis.io/topics/cluster-tutorial#playing-with-the-cluster) on [https://redis.io](https://redis.io) in the [Redis cluster tutorial](https://redis.io/topics/cluster-tutorial).

+You need to use the `-p` switch to specify the correct port to connect to. Use the [CLUSTER NODES](https://redis.io/commands/cluster-nodes/) command to determine the exact ports used for the primary and replica nodes. The following port ranges are used:

+- For non-TLS Premium tier caches, ports are available in the `130XX` range

+- For TLS enabled Premium tier caches, ports are available in the `150XX` range

+- For Enterprise and Enterprise Flash caches using OSS clustering, the initial connection is through port 10000. Connecting to individual nodes can be done using ports in the 85XX range. The 85xx ports will change over time and shouldn't be hardcoded into your application.

+### Can I configure clustering for a previously created cache?

+Yes. First, ensure that your cache is premium by scaling it up. Next, you can see the cluster configuration options, including an option to enable cluster. Change the cluster size after the cache is created, or after you have enabled clustering for the first time.

+>[!IMPORTANT]

+>You can't undo enabling clustering. And a cache with clustering enabled and only one shard behaves *differently* than a cache of the same size with *no* clustering.

+All Enterprise and Enterprise Flash tier caches are always clustered.

+### Can I configure clustering for a basic or standard cache?

+Clustering is only available for Premium, Enterprise, and Enterprise Flash caches.

+### Can I use clustering with the Redis ASP.NET Session State and Output Caching providers?

+* **Redis Output Cache provider** - no changes required.

+* **Redis Session State provider** - to use clustering, you must use [RedisSessionStateProvider](https://www.nuget.org/packages/Microsoft.Web.RedisSessionStateProvider) 2.0.1 or higher or an exception is thrown, which is a breaking change. For more information, see [v2.0.0 Breaking Change Details](https://github.com/Azure/aspnet-redis-providers/wiki/v2.0.0-Breaking-Change-Details).

+### I'm getting MOVE exceptions when using StackExchange.Redis and clustering, what should I do?

+If you're using StackExchange.Redis and receive `MOVE` exceptions when using clustering, ensure that you're using [StackExchange.Redis 1.1.603](https://www.nuget.org/packages/StackExchange.Redis/) or later. For instructions on configuring your .NET applications to use StackExchange.Redis, see [Configure the cache clients](cache-dotnet-how-to-use-azure-redis-cache.md#configure-the-cache-client).

+### What is the difference between OSS Clustering and Enterprise Clustering on Enterprise tier caches?

+OSS Cluster Mode is the same as clustering on the Premium tier and follows the open source clustering specification. Enterprise Cluster Mode can be less performant, but uses Redis Enterprise clustering, which doesn't require any client changes to use. For more information, see [Clustering on Enterprise](cache-best-practices-enterprise-tiers.md#clustering-on-enterprise).

+### How many shards do Enterprise tier caches use?

+Unlike Basic, Standard, and Premium tier caches, Enterprise and Enterprise Flash caches can take advantage of multiple shards on a single node. For more information, see [Sharding and CPU utilization](cache-best-practices-enterprise-tiers.md#sharding-and-cpu-utilization).

+## Next steps

+- [Configure your maxmemory-reserved setting](cache-best-practices-memory-management.md#configure-your-maxmemory-reserved-setting)

+- [[Best practices for scaling](cache-best-practices-scale.md)]

+| [Session store](cache-aspnet-session-state-provider.md) | This pattern is commonly used with shopping carts and other user history data that a web application might associate with user cookies. Storing too much in a cookie can have a negative effect on performance as the cookie size grows and is passed and validated with every request. A typical solution uses the cookie as a key to query the data in a database. When you use an in-memory cache, like Azure Cache for Redis, to associate information with a user is faster than interacting with a full relational database. |

+| Basic | An OSS Redis cache running on a single VM. This tier has no service-level agreement (SLA) and is ideal for development/test and noncritical workloads. |

+| Enterprise Flash | Cost-effective large caches powered by Redis Inc.'s Redis Enterprise software. This tier extends Redis data storage to nonvolatile memory, which is cheaper than DRAM, on a VM. It reduces the overall per-GB memory cost. |

+- **Dedicated core for Redis server**: All caches except C0 run dedicated VM cores. Redis, by design, uses only one thread for command processing. Azure Cache for Redis uses other cores for I/O processing. Having more cores improves throughput performance even though it may not produce linear scaling. Furthermore, larger VM sizes typically come with higher bandwidth limits than smaller ones. That helps you avoid network saturation that cause timeouts in your application.

+You can scale your cache from the Basic tier up to Premium after it has been created. Scaling down to a lower tier isn't supported currently. For step-by-step scaling instructions, see [How to Scale Azure Cache for Redis](cache-how-to-scale.md) and [How to scale - Basic, Standard, and Premium tiers](cache-how-to-scale.md#how-to-scalebasic-standard-and-premium-tiers).

+>[!Important]

+> Private endpoint is supported on cache tiers Basic, Standard, Premium, and Enterprise. We recommend using private endpoint instead of VNets. Private endpoints are easy to set up or remove, are supported on all tiers, and can connect your cache to multiple different VNets at once.

+Note that completion will incur a small cost of a few USD cents or less in your Azure account.

+Note that completion will incur a small cost of a few USD cents or less in your Azure account.

+Note that completion will incur a small cost of a few USD cents or less in your Azure account.

+Note that completion will incur a small cost of a few USD cents or less in your Azure account.

+> The new programming models for authoring Functions in Python (V2) and Node.js (V4) are currently in preview. Compared to the current models, the new experiences are designed to be more flexible and intuitive for Python and JavaScript/TypeScript developers. Learn more about the differences between the models in the [Python developer guide](../functions-reference-python.md?pivots=python-mode-decorators) and [Node.js upgrade guide](../functions-node-upgrade-v4.md).

+* Make sure you have [Azure Functions Core Tools](../functions-run-local.md) version `v4.0.5095` or above.

+* Make sure you have [Azure Functions Core Tools](../functions-run-local.md) version `v4.0.5095` or above.

+[Update your extensions]: ./functions-bindings-register.md

+- [`@azure/functions`](https://www.npmjs.com/package/@azure/functions) npm package v4.0.0-alpha.9+

+- [Azure Functions Core Tools](./functions-run-local.md) v4.0.5095+ (if running locally)

+## Enable v4 programming model

+The following application setting is required to run the v4 programming model while it is in preview:

+- Name: `AzureWebJobsFeatureFlags`

+- Value: `EnableWorkerIndexing`

+If you're running locally using [Azure Functions Core Tools](functions-run-local.md), you should add this setting to your `local.settings.json` file. If you're running in Azure, follow these steps with the tool of your choice:

+# [Azure CLI](#tab/azure-cli-set-indexing-flag)

+Replace `<FUNCTION_APP_NAME>` and `<RESOURCE_GROUP_NAME>` with the name of your function app and resource group, respectively.

+```azurecli

+az functionapp config appsettings set --name <FUNCTION_APP_NAME> --resource-group <RESOURCE_GROUP_NAME> --settings AzureWebJobsFeatureFlags=EnableWorkerIndexing

+```

+# [Azure PowerShell](#tab/azure-powershell-set-indexing-flag)

+Replace `<FUNCTION_APP_NAME>` and `<RESOURCE_GROUP_NAME>` with the name of your function app and resource group, respectively.

+```azurepowershell

+Update-AzFunctionAppSetting -Name <FUNCTION_APP_NAME> -ResourceGroupName <RESOURCE_GROUP_NAME> -AppSetting @{"AzureWebJobsFeatureFlags" = "EnableWorkerIndexing"}

+```

+# [VS Code](#tab/vs-code-set-indexing-flag)

+1. Make sure you have the [Azure Functions extension for VS Code](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-azurefunctions) installed

+1. Press <kbd>F1</kbd> to open the command palette. In the command palette, search for and select `Azure Functions: Add New Setting...`.

+1. Choose your subscription and function app when prompted

+1. For the name, type `AzureWebJobsFeatureFlags` and press <kbd>Enter</kbd>.

+1. For the value, type `EnableWorkerIndexing` and press <kbd>Enter</kbd>.

+If you see the following error, make sure you [set the `EnableWorkerIndexing` flag](#enable-v4-programming-model) and you're using the minimum version of all [requirements](#requirements):

+| 4.x | Preview | 4.16+ | 18.x | Supports a flexible file structure and code-centric approach to triggers and bindings. |

+However, the [Search service] doesn't have the same level of information and accuracy for all countries/regions. Use this article to determine what kind of locations you can reliably search for in each region.

+| T├╝rkiye | Γ£ô | Γ£ô | Γ£ô | Γ£ô | Γ£ô |

+| T├╝rkiye | Γ£ô |

+| T├╝rkiye | Γ£ô | Γ£ô | Γ£ô |

+| T├╝rkiye | Γ£ô | Γ£ô |

+| T├╝rkiye | Γ£ô | Γ£ô | | Γ£ô |

+| [VM insights](../vm/vminsights-overview.md) | Public preview | Dependency Agent extension, if youΓÇÖre using the Map Services feature | [Enable VM Insights](../vm/vminsights-enable-overview.md) |

+| [Container insights](../containers/container-insights-overview.md) | Public preview | Containerized Azure Monitor agent | [Enable Container Insights](../containers/container-insights-onboard.md) |

+| Azure Stack HCI Insights | private preview | No additional extension installed | [Sign up here](https://aka.ms/amadcr-privatepreviews) |

+| Azure Virtual Desktop (AVD) Insights | private preview | No additional extension installed | [Sign up here](https://aka.ms/amadcr-privatepreviews) |

+Azure Monitor Agent is available in all public regions, Azure Government anmd China clouds, for generally available features. It's not yet supported in air-gapped clouds. For more information, see [Product availability by region](https://azure.microsoft.com/global-infrastructure/services/?products=monitor&rar=true&regions=all).

+There's no cost for the Azure Monitor Agent, but you might incur charges for the data ingested and stored. For information on Log Analytics data collection and retention and for customer metrics, see [Azure Monitor pricing](https://azure.microsoft.com/pricing/details/monitor/).

+1. From the top command bar, select **Alert rules**. The page shows all your alert rules on all subscriptions.

+1. Select an alert rule or use the checkboxes on the left to select multiple alert rules.

+1. If you select multiple alert rules, you can enable or disable the selected rules. Selecting multiple rules can be useful when you want to perform maintenance on specific resources.

+1. If you select a single alert rule, you can edit, disable, duplicate, or delete the rule in the alert rule pane.

+ :::image type="content" source="media/alerts-managing-alert-instances/alerts-rules-pane.png" alt-text="Screenshot of alerts rules pane.":::

+1. To edit an alert rule, select **Edit**, and then edit any of the fields in the following sections. You can't edit the **Alert Rule Name**, or the **Signal type** of an existing alert rule.

+ 1. (Optional) Set up the IP ranges. To list the ITSM IP addresses to allow ITSM connections from partner ITSM tools, list the whole public IP range of an Azure region where the Log Analytics workspace belongs. For more information, see the [Microsoft Download Center](https://www.microsoft.com/en-us/download/details.aspx?id=56519). For regions EUS/WEU/WUS2/US South Central, the customer can list the ActionGroup network tag only.

+To add Application Insights logging to ASP.NET Core applications:

+1. Install the [`Microsoft.Extensions.Logging.ApplicationInsights`][nuget-ai].

+# [.NET 6.0+](#tab/dotnet6)

+```csharp

+using Microsoft.Extensions.Logging.ApplicationInsights;

+var builder = WebApplication.CreateBuilder(args);

+// Add services to the container.

+builder.Services.AddControllers();

+// Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle

+builder.Services.AddEndpointsApiExplorer();

+builder.Services.AddSwaggerGen();

+builder.Logging.AddApplicationInsights(

+ configureTelemetryConfiguration: (config) =>

+ config.ConnectionString = builder.Configuration.GetConnectionString("APPLICATIONINSIGHTS_CONNECTION_STRING"),

+ configureApplicationInsightsLoggerOptions: (options) => { }

+ );

+builder.Logging.AddFilter<ApplicationInsightsLoggerProvider>("your-category", LogLevel.Trace);

+var app = builder.Build();

+// Configure the HTTP request pipeline.

+if (app.Environment.IsDevelopment())

+{

+ app.UseSwagger();

+ app.UseSwaggerUI();

+}

+app.UseHttpsRedirection();

+app.UseAuthorization();

+app.MapControllers();

+app.Run();

+```

+# [.NET 5.0](#tab/dotnet5)

+```csharp

+using Microsoft.AspNetCore.Hosting;

+using Microsoft.Extensions.DependencyInjection;

+using Microsoft.Extensions.Hosting;

+using Microsoft.Extensions.Logging;

+using Microsoft.Extensions.Logging.ApplicationInsights;

+namespace WebApplication

+{

+ public class Program

+ public static void Main(string[] args)

+ var host = CreateHostBuilder(args).Build();

+ var logger = host.Services.GetRequiredService<ILogger<Program>>();

+ logger.LogInformation("From Program, running the host now.");

+ host.Run();

+ public static IHostBuilder CreateHostBuilder(string[] args) =>

+ Host.CreateDefaultBuilder(args)

+ .ConfigureWebHostDefaults(webBuilder =>

+ {

+ webBuilder.UseStartup<Startup>();

+ })

+ .ConfigureLogging((context, builder) =>

+ {

+ builder.AddApplicationInsights(

+ configureTelemetryConfiguration: (config) => config.ConnectionString = context.Configuration["APPLICATIONINSIGHTS_CONNECTION_STRING"],

+ configureApplicationInsightsLoggerOptions: (options) => { }

+ );

+ // Capture all log-level entries from Startup

+ builder.AddFilter<ApplicationInsightsLoggerProvider>(

+ typeof(Startup).FullName, LogLevel.Trace);

+ });

+}

+```

+To add Application Insights logging to console applications, first install the following NuGet packages:

+* [`Microsoft.Extensions.Logging.ApplicationInsights`][nuget-ai]

+* [`Microsoft.Extensions.DependencyInjection`][nuget-ai]

+# [.NET 6.0+](#tab/dotnet6)

+```csharp

+using Microsoft.ApplicationInsights.Channel;

+using Microsoft.ApplicationInsights.Extensibility;

+using Microsoft.Extensions.DependencyInjection;

+using Microsoft.Extensions.Logging;

+using var channel = new InMemoryChannel();

+try

+{

+ IServiceCollection services = new ServiceCollection();

+ services.Configure<TelemetryConfiguration>(config => config.TelemetryChannel = channel);

+ services.AddLogging(builder =>

+ {

+ // Only Application Insights is registered as a logger provider

+ builder.AddApplicationInsights(

+ configureTelemetryConfiguration: (config) => config.ConnectionString = "<YourConnectionString>",

+ configureApplicationInsightsLoggerOptions: (options) => { }

+ );

+ });

+ IServiceProvider serviceProvider = services.BuildServiceProvider();

+ ILogger<Program> logger = serviceProvider.GetRequiredService<ILogger<Program>>();

+ logger.LogInformation("Logger is working...");

+}

+finally

+{

+ // Explicitly call Flush() followed by Delay, as required in console apps.

+ // This ensures that even if the application terminates, telemetry is sent to the back end.

+ channel.Flush();

+ await Task.Delay(TimeSpan.FromMilliseconds(1000));

+}

+# [.NET 5.0](#tab/dotnet5)

+If you need a more flexible alternative than `DisableIpMasking`, you can use a [telemetry initializer](./api-filtering-sampling.md#addmodify-properties-itelemetryinitializer) to copy all or part of the IP address to a custom field. The code for this class is the same across .NET versions.

+# [.NET 6.0+](#tab/framework)

+ using Microsoft.ApplicationInsights.Extensibility;

+ using CustomInitializer.Telemetry;

+builder.services.AddSingleton<ITelemetryInitializer, CloneIPAddress>();

+```

+# [.NET 5.0](#tab/dotnet5)

+```csharp

+ using Microsoft.ApplicationInsights.Extensibility;

+ using CustomInitializer.Telemetry;

+ public void ConfigureServices(IServiceCollection services)

+{

+ services.AddSingleton<ITelemetryInitializer, CloneIPAddress>();

+}

+```

+# [ASP.NET Framework](#tab/dotnet6)

+```csharp

+using Microsoft.ApplicationInsights.Extensibility;

+| level |[Severity level](#severity-level) of the event. |

+| level |[Severity level](#severity-level) of the event. |

+| level |[Severity level](#severity-level) of the event. |

+| level |[Severity level](#severity-level) of the event. |

+| level |[Severity level](#severity-level) of the event.|

+| level |[Severity level](#severity-level) of the event.|

+| level | [Severity level](#severity-level) of the event. Audit uses "Warning" and Deny uses "Error". An auditIfNotExists or deployIfNotExists error can generate "Warning" or "Error" depending on severity. All other Policy events use "Informational". |

+ "resourceId": "/subscriptions/s1/resourceGroups/MSSupportGroup/providers/microsoft.support/supporttickets/123456112305841",

+ "authorization": {

+ "scope": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg-001/providers/Microsoft.Storage/storageAccounts/ msftstorageaccount",

+ "action": "Microsoft.Storage/storageAccounts/listAccountSas/action",

+ "evidence": {

+ "role": "Azure Eventhubs Service Role",

+ "roleAssignmentScope": "/subscriptions/00000000-0000-0000-0000-000000000000",

+ "roleAssignmentId": "123abc2a6c314b0ab03a891259123abc",

+ "roleDefinitionId": "123456789de042a6a64b29b123456789",

+ "principalId": "abcdef038c6444c18f1c31311fabcdef",

+ "principalType": "ServicePrincipal"

+ }

+ },

+ "iss": "https://sts.windows.net/abcde123-86f1-41af-91ab-abcde1234567/",

+ "http://schemas.microsoft.com/identity/claims/objectidentifier": "123abc45-8211-44e3-95xq-85137af64708",

+ "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier": "9876543210DKk1YzIY8k0t1_EAPaXoeHyPRn6f413zM",

+ "groups": "12345678-cacfe77c-e058-4712-83qw-f9b08849fd60,12345678-4c41-4b23-99d2-d32ce7aa621c,12345678-0578-4ea0-9gdc-e66cc564d18c",

+ "appid": "12345678-3bq0-49c1-b47d-974e53cbdf3c",

+ "serviceRequestId": "12345678-8ca0-47ad-9b80-6cde2207f97c"

+Once you have set up a diagnostic setting, data should start flowing to your selected destination(s) within 90 minutes. If you get no information within 24 hours, then either

+1. Configure your data collection rule (DCR) following procedures at [Send data to Azure Monitor using Logs ingestion API (Resource Manager templates)](tutorial-logs-ingestion-api.md) or [Add transformation in workspace data collection rule to Azure Monitor using Resource Manager templates](tutorial-workspace-transformations-api.md).

+1. If using the Logs ingestion API, also [configure the data collection endpoint (DCE)](tutorial-logs-ingestion-api.md#create-data-collection-endpoint) and the agent or component that will be sending data to the API.

+Log Analytics Dedicated Clusters use a commitment tier pricing model of at least 500 GB/day. Any usage above the tier level incurs charges based on the per-GB rate of that commitment tier. See [Azure Monitor Logs pricing details](cost-logs.md#dedicated-clusters) for pricing details for dedicated clusters. The commitment tiers have a 31-day commitment period from the time a commitment tier is selected.

+When the data volume to linked workspaces changes over time, you can update the Commitment Tier level appropriately to optimize cost. The tier is specified in units of Gigabytes (GB) and can have values of 500, 1000, 2000 or 5000 GB per day. You don't have to provide the full REST request body, but you must include the sku.

+During the commitment period, you can change to a higher commitment tier, which restarts the 31-day commitment period. You can't move back to pay-as-you-go or to a lower commitment tier until after you finish the commitment period.

+You can unlink a workspace from a cluster at any time. The workspace pricing tier is changed to per-GB, data ingested to cluster before the unlink operation remains in the cluster, and new data to workspace get ingested to Log Analytics.

+> [!WARNING]

+> Unlinking a workspace does not move workspace data out of the cluster. Any data collected for workspace while linked to cluster, remains in cluster for the retention period defined in workspace, and accessible as long as cluster isn't deleted.

+Queries aren't affected when workspace is unlinked and service performs cross-cluster queries seamlessly. If cluster was configured with Customer-managed key (CMK), data ingested to workspace while was linked, remains encrypted with your key and accessible, while your key and permissions to Key Vault remain.

+> - There is a limit of two link operations for a specific workspace within a month to prevent data distribution across clusters. Contact support if you reach the limit.

+> - Unlinked workspaces are moved to Pay-As-You-Go pricing tier.

+Cluster deletion operation should be done with caution, since operation is non-recoverable. All ingested data to cluster from linked workspaces, gets permanently deleted.

+The cluster's billing stops when cluster is deleted, regardless of the 31-days commitment tier defined in cluster.

+If you delete a cluster that has linked workspaces, workspaces get automatically unlinked from the cluster, workspaces are moved to Pay-As-You-Go pricing tier, and new data to workspaces is ingested to Log Analytics clusters instead. You can query workspace for the time range before it was linked to the cluster, and after the unlink, and the service performs cross-cluster queries seamlessly.

+> - Cluster's name remain reserved two weeks after deletion, and can't be used for creating a new cluster.

+- Deleting a workspace is permitted while linked to cluster. If you decide to [recover](./delete-workspace.md#recover-a-workspace) the workspace during the [soft-delete](./delete-workspace.md#soft-delete-behavior) period, workspace returns to previous state and remains linked to cluster.

+- During the commitment period, you can change to a higher commitment tier, which restarts the 31-day commitment period. You can't move back to pay-as-you-go or to a lower commitment tier until after you finish the commitment period.

+description: Send data to a Log Analytics workspace using REST API or client libraries.

+The Logs Ingestion API in Azure Monitor lets you send data to a Log Analytics workspace using either a [REST API call](#rest-api-call) or [client libraries](#client-libraries). By using this API, you can send data to [supported Azure tables](#supported-tables) or to [custom tables that you create](../logs/create-custom-table.md#create-a-custom-table). You can even [extend the schema of Azure tables with custom columns](../logs/create-custom-table.md#add-or-delete-a-custom-column) to accept additional data.

+- Potentially filters and transforms the data for the target table.

+- Directs the data to a specific table in a specific workspace.

+You can modify the target table and workspace by modifying the DCR without any change to the API call or source data.

+## Components

+The Log ingestion API requires the following components to be created before you can send data. Each of these components must all be located in the same region.

+| Component | Description |

+|:|:|

+| Data collection endpoint (DCE) | The DCE provides an endpoint for the application to send to. A single DCE can support multiple DCRs. |

+| Data collection rule (DCR) | [Data collection rules](../essentials/data-collection-rule-overview.md) define data collected by Azure Monitor and specify how and where that data should be sent or stored. The API call must specify a DCR to use. The DCR must understand the structure of the input data and the structure of the target table. If the two don't match, it can include a [transformation](../essentials/data-collection-transformations.md) to convert the source data to match the target table. You can also use the transformation to filter source data and perform any other calculations or conversions.

+| Log Analytics workspace | The Log Analytics workspace contains the tables that will receive the data. The target tables are specific in the DCR. See [Support tables](#supported-tables) for the tables that the ingestion API can send to. |

+## Supported tables

+The following tables can receive data from the ingestion API.

+| Tables | Description |

+|:|:|

+| Custom tables | The Logs Ingestion API can send data to any custom table that you create in your Log Analytics workspace. The target table must exist before you can send data to it. Custom tables must have the `_CL` suffix. |

+| Azure tables | The Logs Ingestion API can send data to the following Azure tables. Other tables may be added to this list as support for them is implemented.<br><br>- [CommonSecurityLog](/azure/azure-monitor/reference/tables/commonsecuritylog)<br>- [SecurityEvents](/azure/azure-monitor/reference/tables/securityevent)<br>- [Syslog](/azure/azure-monitor/reference/tables/syslog)<br>- [WindowsEvents](/azure/azure-monitor/reference/tables/windowsevent)

+## Client libraries

+You can use the following client libraries to send data to the Logs ingestion API.

+- [.NET](/dotnet/api/overview/azure/Monitor.Ingestion-readme)

+- [Java](/java/api/overview/azure/monitor-ingestion-readme)

+- [JavaScript](/javascript/api/overview/azure/monitor-ingestion-readme)

+- [Python](/python/api/overview/azure/monitor-ingestion-readme)

+## REST API call

+To send data to Azure Monitor with a REST API call, make a POST call to the DCE over HTTP. Details of the call are described in the following sections.

+- [Walk through a tutorial configuring the i using the Azure portal](tutorial-logs-ingestion-portal.md)

+[Azure custom roles](../../role-based-access-control/custom-roles.md) let you grant specific users or groups access to specific tables in the workspace. Azure custom roles apply to workspaces with either workspace-context or resource-context [access control modes](#access-control-mode) regardless of the user's [access mode](#access-mode).

+### Examples

+### Custom tables

+Custom tables store data you collect from data sources such as [text logs](../agents/data-sources-custom-logs.md) and the [HTTP Data Collector API](data-collector-api.md). To identify the table type, [view table information in Log Analytics](./log-analytics-tutorial.md#view-table-information).

+You can't grant access to individual custom log tables at the table level, but you can grant access to all custom log tables. To create a role with access to all custom log tables, create a custom role by using the following actions:

+### Considerations

+ Title: 'Tutorial: Send data to Azure Monitor Logs with Logs ingestion API (Resource Manager templates)'

+description: Tutorial on how sending data to a Log Analytics workspace in Azure Monitor using the Logs ingestion API. Supporting components configured using Resource Manager templates.

+# Tutorial: Send data to Azure Monitor using Logs ingestion API (Resource Manager templates)

+The [Logs Ingestion API](logs-ingestion-api-overview.md) in Azure Monitor allows you to send custom data to a Log Analytics workspace. This tutorial uses Azure Resource Manager templates (ARM templates) to walk through configuration of the components required to support the API and then provides a sample application using both the REST API and client libraries for [.NET](/dotnet/api/overview/azure/Monitor.Ingestion-readme), [Java](/java/api/overview/azure/monitor-ingestion-readme), [JavaScript](/javascript/api/overview/azure/monitor-ingestion-readme), and [Python](/python/api/overview/azure/monitor-ingestion-readme).

+> This tutorial uses ARM templates to configure the components required to support the Logs ingestion API. See [Tutorial: Send data to Azure Monitor Logs with Logs ingestion API (Azure portal)](tutorial-logs-ingestion-api.md) for a similar tutorial that uses Azure Resource Manager templates to configure these components.

+The steps required to configure the Logs ingestion API are as follows:

+1. [Create an Azure AD application](#create-azure-ad-application) to authenticate against the API.

+3. [Create a data collection endpoint (DCE)](#create-data-collection-endpoint) to receive data.

+2. [Create a custom table in a Log Analytics workspace](#create-new-table-in-log-analytics-workspace). This is the table you'll be sending data to.

+4. [Create a data collection rule (DCR)](#create-data-collection-rule) to direct the data to the target table.

+5. [Give the AD application access to the DCR](#assign-permissions-to-a-dcr).

+6. See [Sample code to send data to Azure Monitor using Logs ingestion API](tutorial-logs-ingestion-code.md) for sample code to send data to using the Logs ingestion API.

+## Create Azure AD application

+## Create data collection endpoint

+A [DCE](../essentials/data-collection-endpoint-overview.md) is required to accept the data being sent to Azure Monitor. After you configure the DCE and link it to a DCR, you can send data over HTTP from your application. The DCE must be located in the same region as the DCR and the Log Analytics workspace where the data will be sent.

+ "description": "Specifies the location for the Data Collection Endpoint."

+1. Select **JSON View** to view other details for the DCE. Copy the **Resource ID** and the **logsIngestion endpoint** which you'll need in a later step.

+ :::image type="content" source="media/tutorial-logs-ingestion-api/data-collection-endpoint-json.png" lightbox="media/tutorial-logs-ingestion-api/data-collection-endpoint-json.png" alt-text="Screenshot that shows the DCE resource ID.":::

+## Create new table in Log Analytics workspace

+The custom table must be created before you can send data to it. The table for this tutorial will include five columns shown in the schema below. The `name`, `type`, and `description` properties are mandatory for each column. The properties `isHidden` and `isDefaultDisplay` both default to `false` if not explicitly specified. Possible data types are `string`, `int`, `long`, `real`, `boolean`, `dateTime`, `guid`, and `dynamic`.

+> [!NOTE]

+> This tutorial uses PowerShell from Azure Cloud Shell to make REST API calls by using the Azure Monitor **Tables** API. You can use any other valid method to make these calls.

+> [!IMPORTANT]

+> Custom tables must use a suffix of `_CL`.

+1. Select the **Cloud Shell** button in the Azure portal and ensure the environment is set to **PowerShell**.

+ :::image type="content" source="media/tutorial-workspace-transformations-api/open-cloud-shell.png" lightbox="media/tutorial-workspace-transformations-api/open-cloud-shell.png" alt-text="Screenshot that shows opening Cloud Shell.":::

+1. Copy the following PowerShell code and replace the variables in the **Path** parameter with the appropriate values for your workspace in the `Invoke-AzRestMethod` command. Paste it into the Cloud Shell prompt to run it.

+ ```PowerShell

+ $tableParams = @'

+ {

+ "properties": {

+ "schema": {

+ "name": "MyTable_CL",

+ "columns": [

+ {

+ "name": "TimeGenerated",

+ "type": "datetime",

+ "description": "The time at which the data was generated"

+ },

+ {

+ "name": "Computer",

+ "type": "string",

+ "description": "The computer that generated the data"

+ },

+ {

+ "name": "AdditionalContext",

+ "type": "dynamic",

+ "description": "Additional message properties"

+ },

+ {

+ "name": "CounterName",

+ "type": "string",

+ "description": "Name of the counter"

+ },

+ {

+ "name": "CounterValue",

+ "type": "real",

+ "description": "Value collected for the counter"

+ }

+ ]

+ }

+ }

+ }

+ '@

+ Invoke-AzRestMethod -Path "/subscriptions/{subscription}/resourcegroups/{resourcegroup}/providers/microsoft.operationalinsights/workspaces/{workspace}/tables/MyTable_CL?api-version=2021-12-01-preview" -Method PUT -payload $tableParams

+ ```

+## Create data collection rule

+The [DCR](../essentials/data-collection-rule-overview.md) defines how the data will be handled once it's received. This includes:

+- Schema of data that's being sent to the endpoint

+- [Transformation](../essentials/data-collection-transformations.md) that will be applied to the data before it's sent to the workspace

+- Destination workspace and table the transformed data will be sent to

+2. Select **Build your own template in the editor**.

+3. Paste the following ARM template into the editor and then select **Save**.

+ - `dataCollectionEndpointId`: Resource ID of the data collection endpoint.

+ - `streamDeclarations`: Column definitions of the incoming data.

+ - `destinations`: Destination workspace.

+ "name": "myworkspace"

+ "myworkspace"

+4. On the **Custom deployment** screen, specify a **Subscription** and **Resource group** to store the DCR. Then provide values defined in the template. The values include a **Name** for the DCR and the **Workspace Resource ID** that you collected in a previous step. The **Location** should be the same location as the workspace. The **Region** will already be populated and will be used for the location of the DCR.

+5. Select **Review + create** and then select **Create** after you review the details.

+6. When the deployment is complete, expand the **Deployment details** box and select your DCR to view its details. Select **JSON View**.

+## Sample code

+See [Sample code to send data to Azure Monitor using Logs ingestion API](tutorial-logs-ingestion-code.md) for sample code using the components created in this tutorial.

+ Title: 'Sample code to send data to Azure Monitor using Logs ingestion API'

+description: Sample code using REST API and client libraries for Logs ingestion API in Azure Monitor.

+# Sample code to send data to Azure Monitor using Logs ingestion API

+This article provides sample code using the [Logs ingestion API](logs-ingestion-api-overview.md). Each sample requires the following components to be created before the code is run. See [Tutorial: Send data to Azure Monitor using Logs ingestion API (Resource Manager templates)](tutorial-logs-ingestion-api.md) for a complete walkthrough of creating these components configured to support each of these samples.

+- Custom table in a Log Analytics workspace

+- Data collection endpoint (DCE) to receive data

+- Data collection rule (DCR) to direct the data to the target table

+- AD application with access to the DCR

+## Sample code

+## [PowerShell](#tab/powershell)

+The following PowerShell code sends data to the endpoint by using HTTP REST fundamentals.

+> [!NOTE]

+> This sample requires PowerShell v7.0 or later.

+1. Run the following sample PowerShell command, which adds a required assembly for the script.

+ ```powershell

+ Add-Type -AssemblyName System.Web

+ ```

+1. Replace the parameters in the **Step 0** section with values from your application, DCE, and DCR. You might also want to replace the sample data in the **Step 2** section with your own.

+ ```powershell

+ ### Step 0: Set variables required for the rest of the script.

+

+ # information needed to authenticate to AAD and obtain a bearer token

+ $tenantId = "00000000-0000-0000-00000000000000000" #Tenant ID the data collection endpoint resides in

+ $appId = " 000000000-0000-0000-00000000000000000" #Application ID created and granted permissions

+ $appSecret = "0000000000000000000000000000000000000000" #Secret created for the application

+

+ # information needed to send data to the DCR endpoint

+ $dceEndpoint = "https://logs-ingestion-rzmk.eastus2-1.ingest.monitor.azure.com" #the endpoint property of the Data Collection Endpoint object

+ $dcrImmutableId = "dcr-00000000000000000000000000000000" #the immutableId property of the DCR object

+ $streamName = "Custom-MyTableRawData" #name of the stream in the DCR that represents the destination table

+

+

+ ### Step 1: Obtain a bearer token used later to authenticate against the DCE.

+

+ $scope= [System.Web.HttpUtility]::UrlEncode("https://monitor.azure.com//.default")

+ $body = "client_id=$appId&scope=$scope&client_secret=$appSecret&grant_type=client_credentials";

+ $headers = @{"Content-Type"="application/x-www-form-urlencoded"};

+ $uri = "https://login.microsoftonline.com/$tenantId/oauth2/v2.0/token"

+

+ $bearerToken = (Invoke-RestMethod -Uri $uri -Method "Post" -Body $body -Headers $headers).access_token

+

+

+ ### Step 2: Create some sample data.

+

+ $currentTime = Get-Date ([datetime]::UtcNow) -Format O

+ $staticData = @"

+ [

+ {

+ "Time": "$currentTime",

+ "Computer": "Computer1",

+ "AdditionalContext": {

+ "InstanceName": "user1",

+ "TimeZone": "Pacific Time",

+ "Level": 4,

+ "CounterName": "AppMetric1",

+ "CounterValue": 15.3

+ }

+ },

+ {

+ "Time": "$currentTime",

+ "Computer": "Computer2",

+ "AdditionalContext": {

+ "InstanceName": "user2",

+ "TimeZone": "Central Time",

+ "Level": 3,

+ "CounterName": "AppMetric1",

+ "CounterValue": 23.5

+ }

+ }

+ ]

+ "@;

+

+

+ ### Step 3: Send the data to the Log Analytics workspace via the DCE.

+

+ $body = $staticData;

+ $headers = @{"Authorization"="Bearer $bearerToken";"Content-Type"="application/json"};

+ $uri = "$dceEndpoint/dataCollectionRules/$dcrImmutableId/streams/$($streamName)?api-version=2021-11-01-preview"

+

+ $uploadResponse = Invoke-RestMethod -Uri $uri -Method "Post" -Body $body -Headers $headers

+ ```

+ > [!NOTE]

+ > If you receive an `Unable to find type [System.Web.HttpUtility].` error, run the last line in section 1 of the script for a fix and execute it. Executing it uncommented as part of the script won't resolve the issue. The command must be executed separately.

+3. Execute the script, and you should see an `HTTP - 204` response. The data should arrive in your Log Analytics workspace within a few minutes.

+## [Python](#tab/python)

+The following sample code uses the [Azure Monitor Ingestion client library for Python](/python/api/overview/azure/monitor-ingestion-readme).

+1. Use [pip](https://pypi.org/project/pip/) to install the Azure Monitor Ingestion and Azure Identity client libraries for Python. The Azure Identity library is required for the authentication used in this sample.

+ ```bash

+ pip install azure-monitor-ingestion

+ pip install azure-identity

+ ```

+2. Create the following environment variables with values for your Azure AD application. These values are used by `DefaultAzureCredential` in the Azure Identity library.

+ - AZURE_TENANT_ID

+ - AZURE_CLIENT_ID

+ - AZURE_CLIENT_SECRET

+3. Replace the variables in the following sample code with values from your DCE and DCR. You might also want to replace the sample data in the **Step 2** section with your own.

+ ```python

+ # information needed to send data to the DCR endpoint

+ dce_endpoint = "https://logs-ingestion-rzmk.eastus2-1.ingest.monitor.azure.com" # ingestion endpoint of the Data Collection Endpoint object

+ dcr_immutableid = "dcr-00000000000000000000000000000000" # immutableId property of the Data Collection Rule

+ stream_name = "Custom-MyTableRawData" #name of the stream in the DCR that represents the destination table

+

+ # Import required modules

+ import os

+ from azure.identity import DefaultAzureCredential

+ from azure.monitor.ingestion import LogsIngestionClient

+ from azure.core.exceptions import HttpResponseError

+

+ credential = DefaultAzureCredential()

+ client = LogsIngestionClient(endpoint=dce_endpoint, credential=credential, logging_enable=True)

+

+ body = [

+ {

+ "Time": "2023-03-12T15:04:48.423211Z",

+ "Computer": "Computer1",

+ "AdditionalContext": {

+ "InstanceName": "user1",

+ "TimeZone": "Pacific Time",

+ "Level": 4,

+ "CounterName": "AppMetric2",

+ "CounterValue": 35.3

+ }

+ },

+ {

+ "Time": "2023-03-12T15:04:48.794972Z",

+ "Computer": "Computer2",

+ "AdditionalContext": {

+ "InstanceName": "user2",

+ "TimeZone": "Central Time",

+ "Level": 3,

+ "CounterName": "AppMetric2",

+ "CounterValue": 43.5

+ }

+ }

+ ]

+

+ try:

+ client.upload(rule_id=dcr_immutableid, stream_name=stream_name, logs=body)

+ except HttpResponseError as e:

+ print(f"Upload failed: {e}")

+ ```

+3. Execute the code, and the data should arrive in your Log Analytics workspace within a few minutes.

+## [JavaScript](#tab/javascript)

+The following sample code uses the [Azure Monitor Ingestion client library for JavaScript](/javascript/api/overview/azure/monitor-ingestion-readme).

+1. Use [npm](https://www.npmjs.com/) to install the Azure Monitor Ingestion and Azure Identity client libraries for JavaScript. The Azure Identity library is required for the authentication used in this sample.

+ ```bash

+ npm install --save @azure/monitor-ingestion

+ npm install --save @azure/identity

+ ```

+2. Create the following environment variables with values for your Azure AD application. These values are used by `DefaultAzureCredential` in the Azure Identity library.

+ - AZURE_TENANT_ID

+ - AZURE_CLIENT_ID

+ - AZURE_CLIENT_SECRET

+3. Replace the variables in the following sample code with values from your DCE and DCR. You might also want to replace the sample data with your own.

+ ```javascript

+ const { isAggregateLogsUploadError, DefaultAzureCredential } = require("@azure/identity");

+ const { LogsIngestionClient } = require("@azure/monitor-ingestion");

+

+ require("dotenv").config();

+

+ async function main() {

+ const logsIngestionEndpoint = "https://logs-ingestion-rzmk.eastus2-1.ingest.monitor.azure.com";

+ const ruleId = "dcr-00000000000000000000000000000000";

+ const streamName = "Custom-MyTableRawData";

+ const credential = new DefaultAzureCredential();

+ const client = new LogsIngestionClient(logsIngestionEndpoint, credential);

+ const logs = [

+ {

+ Time: "2021-12-08T23:51:14.1104269Z",

+ Computer: "Computer1",

+ AdditionalContext: {

+ "InstanceName": "user1",

+ "TimeZone": "Pacific Time",

+ "Level": 4,

+ "CounterName": "AppMetric2",

+ "CounterValue": 35.3

+ }

+ },

+ {

+ Time: "2021-12-08T23:51:14.1104269Z",

+ Computer: "Computer2",

+ AdditionalContext: {

+ "InstanceName": "user2",

+ "TimeZone": "Pacific Time",

+ "Level": 4,

+ "CounterName": "AppMetric2",

+ "CounterValue": 43.5

+ }

+ },

+ ];

+ try{

+ await client.upload(ruleId, streamName, logs);

+ }

+ catch(e){

+ let aggregateErrors = isAggregateLogsUploadError(e) ? e.errors : [];

+ if (aggregateErrors.length > 0) {

+ console.log("Some logs have failed to complete ingestion");

+ for (const error of aggregateErrors) {

+ console.log(`Error - ${JSON.stringify(error.cause)}`);

+ console.log(`Log - ${JSON.stringify(error.failedLogs)}`);

+ }

+ } else {

+ console.log(e);

+ }

+ }

+ }

+

+ main().catch((err) => {

+ console.error("The sample encountered an error:", err);

+ process.exit(1);

+ });

+ ```

+4. Execute the code, and the data should arrive in your Log Analytics workspace within a few minutes.

+## [Java](#tab/java)

+The following sample code uses the [Azure Monitor Ingestion client library for Java](/java/api/overview/azure/monitor-ingestion-readme).

+1. Include the Logs ingestion package and the `azure-identity` package from the [Azure Identity library](https://github.com/Azure/azure-sdk-for-java/tree/azure-monitor-ingestion_1.0.1/sdk/identity/azure-identity). The Azure Identity library is required for the authentication used in this sample.

+ > [!NOTE]

+ > See the Maven repositories for [Microsoft Azure Client Library For Identity](https://mvnrepository.com/artifact/com.azure/azure-identity) and [Microsoft Azure SDK For Azure Monitor Data Ingestion](https://mvnrepository.com/artifact/com.azure/azure-monitor-ingestion) for the latest versions.

+ ```xml

+ <dependency>

+ <groupId>com.azure</groupId>

+ <artifactId>azure-monitor-ingestion</artifactId>

+ <version>{get-latest-version}</version>

+ <dependency>

+ <groupId>com.azure</groupId>

+ <artifactId>azure-identity</artifactId>

+ <version>{get-latest-version}</version>

+ </dependency>

+ ```

+3. Create the following environment variables with values for your Azure AD application. These values are used by `DefaultAzureCredential` in the Azure Identity library.

+ - AZURE_TENANT_ID

+ - AZURE_CLIENT_ID

+ - AZURE_CLIENT_SECRET

+4. Replace the variables in the following sample code with values from your DCE and DCR. You may also want to replace the sample data with your own.

+ ```java

+ import com.azure.identity.DefaultAzureCredentialBuilder;

+ import com.azure.monitor.ingestion.models.LogsUploadException;

+ import java.time.OffsetDateTime;

+ import java.util.Arrays;

+ import java.util.List;

+ public class LogsUploadSample {

+ public static void main(String[] args) {

+

+ LogsIngestionClient client = new LogsIngestionClientBuilder()

+ .endpoint("https://logs-ingestion-rzmk.eastus2-1.ingest.monitor.azure.com")

+ .credential(new DefaultAzureCredentialBuilder().build())

+ .buildClient();

+

+ List<Object> dataList = Arrays.asList(

+ new Object() {

+ OffsetDateTime time = OffsetDateTime.now();

+ String computer = "Computer1";

+ Object additionalContext = new Object() {

+ String instanceName = "user4";

+ String timeZone = "Pacific Time";

+ int level = 4;

+ String counterName = "AppMetric1";

+ double counterValue = 15.3;

+ };

+ },

+ new Object() {

+ OffsetDateTime time = OffsetDateTime.now();

+ String computer = "Computer2";

+ Object additionalContext = new Object() {

+ String instanceName = "user2";

+ String timeZone = "Central Time";

+ int level = 3;

+ String counterName = "AppMetric2";

+ double counterValue = 43.5;

+ };

+ });

+

+ try {

+ client.upload("dcr-00000000000000000000000000000000", "Custom-MyTableRawData", dataList);

+ System.out.println("Logs uploaded successfully");

+ } catch (LogsUploadException exception) {

+ System.out.println("Failed to upload logs ");

+ exception.getLogsUploadErrors()

+ .forEach(httpError -> System.out.println(httpError.getMessage()));

+ }

+ }

+ }

+ ```

+5. Execute the code, and the data should arrive in your Log Analytics workspace within a few minutes.

+## [.NET](#tab/net)

+The following script uses the [Azure Monitor Ingestion client library for .NET](/dotnet/api/overview/azure/Monitor.Ingestion-readme).

+1. Install the Azure Monitor Ingestion client library and the Azure Identity library. The Azure Identity library is required for the authentication used in this sample.

+

+ ```dotnetcli

+ dotnet add package Azure.Identity

+ dotnet add package Azure.Monitor.Ingestion

+ ```

+3. Create the following environment variables with values for your Azure AD application. These values are used by `DefaultAzureCredential` in the Azure Identity library.

+ - AZURE_TENANT_ID

+ - AZURE_CLIENT_ID

+ - AZURE_CLIENT_SECRET

+2. Replace the variables in the following sample code with values from your DCE and DCR. You may also want to replace the sample data with your own.

+ ```csharp

+ using Azure;

+ using Azure.Core;

+ using Azure.Identity;

+ using Azure.Monitor.Ingestion;

+ // Initialize variables

+ var endpoint = new Uri("https://logs-ingestion-rzmk.eastus2-1.ingest.monitor.azure.com");

+ var ruleId = "dcr-00000000000000000000000000000000";

+ var streamName = "Custom-MyTableRawData";

+

+ // Create credential and client

+ var credential = new DefaultAzureCredential();

+ LogsIngestionClient client = new(endpoint, credential);

+

+ DateTimeOffset currentTime = DateTimeOffset.UtcNow;

+

+ // Use BinaryData to serialize instances of an anonymous type into JSON

+ BinaryData data = BinaryData.FromObjectAsJson(

+     new[] {

+         new

+         {

+             Time = currentTime,

+             Computer = "Computer1",

+             AdditionalContext = new

+             {

+                 InstanceName = "user1",

+                 TimeZone = "Pacific Time",

+                 Level = 4,

+                 CounterName = "AppMetric1",

+                 CounterValue = 15.3

+             }

+         },

+         new

+         {

+             Time = currentTime,

+             Computer = "Computer2",

+             AdditionalContext = new

+             {

+                 InstanceName = "user2",

+                 TimeZone = "Central Time",

+                 Level = 3,

+                 CounterName = "AppMetric1",

+                 CounterValue = 23.5

+             }

+         },

+     });

+

+ // Upload logs

+ try

+ {

+     Response response = client.Upload(ruleId, streamName, RequestContent.Create(data));

+ }

+ catch (Exception ex)

+ {

+     Console.WriteLine("Upload failed with Exception " + ex.Message);

+ }

+

+ // Logs can also be uploaded in a List

+ var entries = new List<Object>();

+ for (int i = 0; i < 10; i++)

+ {

+     entries.Add(

+         new {

+             Time = recordingNow,

+             Computer = "Computer" + i.ToString(),

+             AdditionalContext = i

+         }

+     );

+ }

+

+ // Make the request

+ LogsUploadOptions options = new LogsUploadOptions();

+ bool isTriggered = false;

+ options.UploadFailed += Options_UploadFailed;

+ await client.UploadAsync(TestEnvironment.DCRImmutableId, TestEnvironment.StreamName, entries, options).ConfigureAwait(false);

+

+ Task Options_UploadFailed(LogsUploadFailedEventArgs e)

+ {

+     isTriggered = true;

+     Console.WriteLine(e.Exception);

+     foreach (var log in e.FailedLogs)

+     {

+         Console.WriteLine(log);

+     }

+     return Task.CompletedTask;

+ }

+ ```

+3. Execute the code, and the data should arrive in your Log Analytics workspace within a few minutes.

+## Troubleshooting

+This section describes different error conditions you might receive and how to correct them.

+### Script returns error code 403

+Ensure that you have the correct permissions for your application to the DCR. You might also need to wait up to 30 minutes for permissions to propagate.

+### Script returns error code 413 or warning of TimeoutExpired with the message ReadyBody_ClientConnectionAbort in the response

+The message is too large. The maximum message size is currently 1 MB per call.

+### Script returns error code 429

+API limits have been exceeded. The limits are currently set to 500 MB of data per minute for both compressed and uncompressed data and 300,000 requests per minute. Retry after the duration listed in the `Retry-After` header in the response.

+### Script returns error code 503

+Ensure that you have the correct permissions for your application to the DCR. You might also need to wait up to 30 minutes for permissions to propagate.

+### You don't receive an error, but data doesn't appear in the workspace

+The data might take some time to be ingested, especially if this is the first time data is being sent to a particular table. It shouldn't take longer than 15 minutes.

+### IntelliSense in Log Analytics doesn't recognize the new table

+The cache that drives IntelliSense might take up to 24 hours to update.

+## Next steps

+- [Learn more about data collection rules](../essentials/data-collection-rule-overview.md)

+- [Learn more about writing transformation queries](../essentials//data-collection-transformations.md)

+ Title: 'Tutorial: Send data to Azure Monitor Logs with Logs ingestion API (Azure portal)'

+description: Tutorial on how sending data to a Log Analytics workspace in Azure Monitor using the Logs ingestion API. Supporting components configured using the Azure portal.

+# Tutorial: Send data to Azure Monitor Logs with Logs ingestion API (Azure portal)

+The [Logs Ingestion API](logs-ingestion-api-overview.md) in Azure Monitor allows you to send external data to a Log Analytics workspace with a REST API. This tutorial uses the Azure portal to walk through configuration of a new table and a sample application to send log data to Azure Monitor. The sample application collects entries from a text file and

+> This tutorial uses the Azure portal to configure the components to support the Logs ingestion API. See [Tutorial: Send data to Azure Monitor using Logs ingestion API (Resource Manager templates)](tutorial-logs-ingestion-api.md) for a similar tutorial that uses Azure Resource Manager templates to configure these components and that has sample code for client libraries for [.NET](/dotnet/api/overview/azure/Monitor.Ingestion-readme), [Java](/java/api/overview/azure/monitor-ingestion-readme), [JavaScript](/javascript/api/overview/azure/monitor-ingestion-readme), and [Python](/python/api/overview/azure/monitor-ingestion-readme).

+The steps required to configure the Logs ingestion API are as follows:

+1. [Create an Azure AD application](#create-azure-ad-application) to authenticate against the API.

+3. [Create a data collection endpoint (DCE)](#create-data-collection-endpoint) to receive data.

+2. [Create a custom table in a Log Analytics workspace](#create-new-table-in-log-analytics-workspace). This is the table you'll be sending data to. As part of this process, you will create a data collection rule (DCR) to direct the data to the target table.

+5. [Give the AD application access to the DCR](#assign-permissions-to-the-dcr).

+6. [Use sample code to send data to using the Logs ingestion API](#send-sample-data).

+## Create Azure AD application

+## Create data collection endpoint

+A [data collection endpoint](../essentials/data-collection-endpoint-overview.md) is required to accept the data from the script. After you configure the DCE and link it to a DCR, you can send data over HTTP from your application. The DCE does not need to be in the same region as the Log Analytics workspace where the data will be sent or the data collection rule being used.

+## Create new table in Log Analytics workspace

+## Generate sample data

+The following PowerShell script generates sample data to configure the custom table and sends sample data to the logs ingestion API to test the configuration.

+1. Run the following PowerShell command, which adds a required assembly for the script:

+ ```powershell

+ Add-Type -AssemblyName System.Web

+ ```

+1. Update the values of `$tenantId`, `$appId`, and `$appSecret` with the values you noted for **Directory (tenant) ID**, **Application (client) ID**, and secret **Value**. Then save it with the file name *LogGenerator.ps1*.

+ ``` PowerShell

+ param ([Parameter(Mandatory=$true)] $Log, $Type="file", $Output, $DcrImmutableId, $DceURI, $Table)

+ ################

+ ##### Usage

+ ################

+ # LogGenerator.ps1

+ # -Log <String> - Log file to be forwarded

+ # [-Type "file|API"] - Whether the script should generate sample JSON file or send data via

+ # API call. Data will be written to a file by default.

+ # [-Output <String>] - Path to resulting JSON sample

+ # [-DcrImmutableId <string>] - DCR immutable ID

+ # [-DceURI] - Data collection endpoint URI

+ # [-Table] - The name of the custom log table, including "_CL" suffix

+ ##### >>>> PUT YOUR VALUES HERE <<<<<

+ # Information needed to authenticate to Azure Active Directory and obtain a bearer token

+ $tenantId = "<put tenant ID here>"; #the tenant ID in which the Data Collection Endpoint resides

+ $appId = "<put application ID here>"; #the app ID created and granted permissions

+ $appSecret = "<put secret value here>"; #the secret created for the above app - never store your secrets in the source code

+ ##### >>>> END <<<<<

+ $file_data = Get-Content $Log

+ if ("file" -eq $Type) {

+ ############

+ ## Convert plain log to JSON format and output to .json file

+ ############

+ # If not provided, get output file name

+ if ($null -eq $Output) {

+ $Output = Read-Host "Enter output file name"

+ };

+ # Form file payload

+ $payload = @();

+ $records_to_generate = [math]::min($file_data.count, 500)

+ for ($i=0; $i -lt $records_to_generate; $i++) {

+ $log_entry = @{

+ # Define the structure of log entry, as it will be sent

+ Time = Get-Date ([datetime]::UtcNow) -Format O

+ Application = "LogGenerator"

+ RawData = $file_data[$i]

+ }

+ $payload += $log_entry

+ }

+ # Write resulting payload to file

+ New-Item -Path $Output -ItemType "file" -Value ($payload | ConvertTo-Json) -Force

+ } else {

+ ############

+ ## Send the content to the data collection endpoint

+ ############

+ if ($null -eq $DcrImmutableId) {

+ $DcrImmutableId = Read-Host "Enter DCR Immutable ID"

+ };

+ if ($null -eq $DceURI) {

+ $DceURI = Read-Host "Enter data collection endpoint URI"

+ }

+ if ($null -eq $Table) {

+ $Table = Read-Host "Enter the name of custom log table"

+ }

+ ## Obtain a bearer token used to authenticate against the data collection endpoint

+ $scope = [System.Web.HttpUtility]::UrlEncode("https://monitor.azure.com//.default")

+ $body = "client_id=$appId&scope=$scope&client_secret=$appSecret&grant_type=client_credentials";

+ $headers = @{"Content-Type" = "application/x-www-form-urlencoded" };

+ $uri = "https://login.microsoftonline.com/$tenantId/oauth2/v2.0/token"

+ $bearerToken = (Invoke-RestMethod -Uri $uri -Method "Post" -Body $body -Headers $headers).access_token

+ ## Generate and send some data

+ foreach ($line in $file_data) {

+ # We are going to send log entries one by one with a small delay

+ $log_entry = @{

+ # Define the structure of log entry, as it will be sent

+ Time = Get-Date ([datetime]::UtcNow) -Format O

+ Application = "LogGenerator"

+ RawData = $line

+ }

+ # Sending the data to Log Analytics via the DCR!

+ $body = $log_entry | ConvertTo-Json -AsArray;

+ $headers = @{"Authorization" = "Bearer $bearerToken"; "Content-Type" = "application/json" };

+ $uri = "$DceURI/dataCollectionRules/$DcrImmutableId/streams/Custom-$Table"+"?api-version=2021-11-01-preview";

+ $uploadResponse = Invoke-RestMethod -Uri $uri -Method "Post" -Body $body -Headers $headers;

+ # Let's see how the response looks

+ Write-Output $uploadResponse

+ Write-Output ""

+ # Pausing for 1 second before processing the next entry

+ Start-Sleep -Seconds 1

+ }

+ }

+ ```

+1. Copy the sample log data from [sample data](#sample-data) or copy your own Apache log data into a file called `sample_access.log`.

+1. To read the data in the file and create a JSON file called `data_sample.json` that you can send to the logs ingestion API, run:

+ ```PowerShell

+ .\LogGenerator.ps1 -Log "sample_access.log" -Type "file" -Output "data_sample.json"

+ ```

+See the [Troubleshooting](tutorial-logs-ingestion-code.md#troubleshooting) section of the sample code article if your code doesn't work as expected.

+|APPINSIGHTS_INSTRUMENTATIONKEY | Unique value from your App Insights resource. |

+* Currently, large volumes are not suited for database (HANA, Oracle, SQL Server, etc) data and log volumes. For database workloads requiring more than a single volumeΓÇÖs throughput limit, consider deploying multiple regular volumes.

+10.23.1.5:/HN1-data-mnt00001 /hana/data/HN1/mnt00001 nfs rw,vers=4,minorversion=1,hard,timeo=600,rsize=262144,wsize=262144,noatime,_netdev,sec=sys 0 0

+10.23.1.6:/HN1-data-mnt00002 /hana/data/HN1/mnt00002 nfs rw,vers=4,minorversion=1,hard,timeo=600,rsize=262144,wsize=262144,noatime,_netdev,sec=sys 0 0

+10.23.1.4:/HN1-log-mnt00001 /hana/log/HN1/mnt00001 nfs rw,vers=4,minorversion=1,hard,timeo=600,rsize=262144,wsize=262144,noatime,_netdev,sec=sys 0 0

+10.23.1.6:/HN1-log-mnt00002 /hana/log/HN1/mnt00002 nfs rw,vers=4,minorversion=1,hard,timeo=600,rsize=262144,wsize=262144,noatime,_netdev,sec=sys 0 0

+10.23.1.4:/HN1-shared/shared /hana/shared nfs rw,vers=4,minorversion=1,hard,timeo=600,rsize=262144,wsize=262144,noatime,_netdev,sec=sys 0 0

+ Title: Quickstart - Create a client using the Azure Web PubSub client SDK (preview)

+# Quickstart: Create a client using the Azure Web PubSub client SDK (preview)

+Get started with the Azure Web PubSub client SDK for .NET or JavaScript to create a Web PubSub client

+that:

+* connects to a Web PubSub service instance

+* subscribes a Web PubSub group.

+* publishes a message to the Web PubSub group.

+[API reference documentation](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/web-pubsub/web-pubsub-client) | [Library source code](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/web-pubsub/web-pubsub-client/src) | [Package (JavaScript npm)](https://www.npmjs.com/package/@azure/web-pubsub-client) | [Samples](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/web-pubsub/web-pubsub-client/samples-dev/helloworld.ts)

+[API reference documentation](https://github.com/Azure/azure-sdk-for-net#azure-sdk-for-net) | [Library source code](https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/webpubsub/Azure.Messaging.WebPubSub.Client/src) | [Package (NuGet)](https://www.nuget.org/packages/Azure.Messaging.WebPubSub.Client) | [Samples](https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/webpubsub/Azure.Messaging.WebPubSub.Client/samples)

+> The client SDK is still in preview version. The interface may change in later versions.

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

+## Setting up

+### Create an Azure Web PubSub service instance

+1. In the Azure portal **Home** page, select **Create a resource**.

+1. In the **Search the Marketplace** box, enter *Web PubSub*.

+1. Select **Web PubSub** from the results.

+1. Select **Create**.

+1. Create a new resource group

+ 1. Select **Create new**.

+ 1. Enter the name and select **OK**.

+1. Enter a **Resource Name** for the service instance.

+1. Select **Pricing tier**. You can choose **Free** for testing.

+1. Select **Create**, then **Create** again to confirm the new service instance.

+1. Once deployment is complete, select **Go to resource**.

+### Generate the client URL

+A client uses a Client Access URL to connect and authenticate with the service, which follows a pattern of `wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>`.

+To give the client permission to send messages to and join a specific group, you must generate a Client Access URL with the **Send To Groups** and **Join/Leave Groups** permissions.

+1. In the Azure portal, go to your Web PubSub service resource page.

+1. Select **Keys** from the menu.

+1. In the **Client URL Generator** section:

+ 1. Select **Send To Groups**

+ 1. Select **Allow Sending To Specific Groups**.

+ 1. Enter *group1* in the **Group Name** field and select **Add**.

+ 1. Select **Join/Leave Groups**.

+ 1. Select **Allow Joining/Leaving Specific Groups**.

+ 1. Enter *group1* in the **Group Name** field and select **Add**.

+ 1. Copy and save the **Client Access URL** for use later in this article.

+### Install programming language

+This quickstart uses the Azure Web PubSub client SDK for JavaScript or C#. Open a terminal window and install the dependencies for the language you're using.

+### Install the package

+Install the Azure Web PubSub client SDK for the language you're using.

+The SDK is available as an [npm module](https://www.npmjs.com/package/@azure/web-pubsub-client).

+Open a terminal window and install the Web PubSub client SDK using the following command.

+Note that the SDK is available as an [npm module](https://www.npmjs.com/package/@azure/web-pubsub-client).

+Open a terminal window to create your project and install the Web PubSub client SDK.

+# create project directory

+mkdir webpubsub-client

+# change to the project directory

+cd webpubsub-client

+Note that the SDK is available as a [NuGet packet](https://www.nuget.org/packages/Azure.Messaging.WebPubSub.Client).

+## Code examples

+### Create and connect to the Web PubSub service

+This code example creates a Web PubSub client that connects to the Web PubSub service instance. A client uses a Client Access URL to connect and authenticate with the service. It's best practice to not hard code the Client Access URL in your code. In the production world, we usually set up an app server to return this URL on demand.

+For this example, you can use the Client Access URL you generated in the portal.

+In the terminal window, create a new directory for your project and change to that directory.

+```bash

+mkdir webpubsub-client

+cd webpubsub-client

+```

+Create a file with name `index.js` and enter following code:

+// Instantiates the client object. env.process.env.WebPubSubClientURL

+// env.process.env.WebPubSubClientURL is the Client Access URL from Azure portal

+const client = new WebPubSubClient(env.process.env.WebPubSubClientURL);

+Edit the `Program.cs` file and add following code:

+// Client Access URL from Azure portal

+var clientURL = Environment.GetEnvironmentVariable("WebPubSubClientURL"));

+// Instantiates the client object.

+var client = new WebPubSubClient(new Uri(clientURL));

+### Subscribe to a group

+To receive message from a group, you need to subscribe to the group and add a callback to handle messages you receive from the group. The following code subscribes the client to a group called `group1`.

+Add this following code to the `index.js` file:

+Add the following code to the `Program.cs` file:

+### Publish a message to a group

+After your client has subscribed to the group, it can send messages to and receive the message from the group.

+Add the following code to the `index.js` file:

+Add the following code to the `Program.cs` file:

+## Run the code

+Run the client in your terminal. To verify the client is sending and receiving messages, you can open a second terminal and start the client from the same directory. You can see the message you sent from the second client in the first client's terminal window.

+# [JavaScript](#tab/javascript)

+To start the client go the terminal and run the following command. Replace the `<Client Access URL>` with the client access URL you copied from the portal.

+```bash

+export WebPubSubClientURL="<Client Access URL>"

+node index.js

+```

+# [C#](#tab/csharp)

+To start the client, run the following command in your terminal replacing the `<client-access-url>` with the client access URL you copied from the portal:

+```bash

+export WebPubSubClientURL="<Client Access URL>"

+dotnet run <client-access-url>

+```

+## Clean up resources

+To delete the resources you created in this quickstart, you can delete the resource group you created. Go to the Azure portal, select your resource group, and select **Delete resource group**.

+## Next steps

+To learn more the Web PubSub service client SDKs, see the following resources:

+- a Bash and PowerShell command shell. The Python, JavaScript and Java samples require a Bash command shell.

+To sign in to Azure from the CLI, run the following command and follow the prompts to complete the authentication process. If you're using Cloud Shell, it isn't necessary to sign in.

+You can choose between C#, JavaScript, Python and Java. The dependencies for each language are installed in the steps for that language. Python, JavaScript and Java require a bash shell to run the commands in this quickstart.

+1. Save the connection string from the client shell. Replace the `<your_connection_string>` placeholder with the connection string you displayed in an earlier step.

+ connection_string="<your_connection_string>"

+- [Learn more](manage-azure-managed-disks.md#stop-protection) about stopping backup for a disk.

+You won't incur backup storage charges or instance fees during the preview. However, you'll incur the source side cost, [associated with Object replication](../storage/blobs/object-replication-overview.md#billing), on the backed-up source account.

+### Stop Protection

+1. Select **Stop Backup**.

+| Asia | Hong Kong<br />Jakarta, Indonesia<br />Osaka, Japan<br />Tokyo, Japan<br />Singapore<br />Kaohsiung, Taiwan<br />Taipei, Taiwan <br />Manila, Philippines | Hong Kong<br />Indonesia<br />Israel<br />Japan<br />Macau<br />Malaysia<br />Philippines<br />Singapore<br />South Korea<br />Taiwan<br />Thailand<br />T├╝rkiye<br />Vietnam |

+* The geo-filtering feature uses [country/region codes](microsoft-pop-abbreviations.md) codes to define the countries/regions from which a request is allowed or blocked for a secured directory. **Azure CDN from Verizon** and **Azure CDN from Akamai** profiles use ISO 3166-1 alpha-2 country codes to define the countries/regions from which a request are allowed or blocked for a secured directory.

+| N/A |[3192321] |T├╝rkiye ends DST observance |5.3, 4.38, 3.45, 2.57 |Nov 8, 2016 |

+|T├╝rkiye|TR|

+|T├╝rkiye|Turkish|tr-TR|

+|T├╝rkiye|TR|

+|T├╝rkiye|Turkish|tr-TR|

+|T├╝rkiye|Turkish|tr-TR|

+|T├╝rkiye|TR|

+|T├╝rkiye|TR|

+|T├╝rkiye|Turkish|tr-TR|

+- [See batch transcription code samples at GitHub](https://github.com/Azure-Samples/cognitive-services-speech-sdk/tree/master/samples/batch/)

+- [Get batch transcription results](batch-transcription-get.md)

+- [See batch transcription code samples at GitHub](https://github.com/Azure-Samples/cognitive-services-speech-sdk/tree/master/samples/batch/)

+- [See batch transcription code samples at GitHub](https://github.com/Azure-Samples/cognitive-services-speech-sdk/tree/master/samples/batch/)

+- [See batch transcription code samples at GitHub](https://github.com/Azure-Samples/cognitive-services-speech-sdk/tree/master/samples/batch/)

+>

+> Access to [Custom Neural Voice (CNV) Lite](custom-neural-voice-lite.md) is available for anyone to demo and evaluate CNV before investing in professional recordings to create a higher-quality voice.

+| Turkish (T├╝rkiye) | `tr-TR` | Female | `tr-TR-SedaRUS`|

+In this article, you learn how to create user delegation, shared access signature (SAS) tokens, using the Azure portal or Azure Storage Explorer. User delegation SAS tokens are secured with Azure AD credentials. SAS tokens provide secure, delegated access to resources in your Azure storage account.

+>[!TIP]

+>

+> [Managed identities](create-use-managed-identities.md) provide an alternate method for you to grant access to your storage data without the need to include SAS tokens with your HTTP requests. *See*, [Managed identities for Document Translation](create-use-managed-identities.md).

+>

+> * You can use managed identities to grant access to any resource that supports Azure AD authentication, including your own applications.

+> * Using managed identities replaces the requirement for you to include shared access signature tokens (SAS) with your source and target URLs.

+> * There's no added cost to use managed identities in Azure.

+To get started, you need the following resources:

+* A **standard performance** [Azure Blob Storage account](https://portal.azure.com/#create/Microsoft.StorageAccount-ARM). You also need to create containers to store and organize your files within your storage account. If you don't know how to create an Azure storage account with a storage container, follow these quickstarts:

+ * Consider setting a longer duration period for the time you're using your storage account for Translator Service operations.

+1. The **Allowed IP addresses** field is optional and specifies an IP address or a range of IP addresses from which to accept requests. If the request IP address doesn't match the IP address or address range specified on the SAS token, authorization fails.

+1. The **Blob SAS token** query string and **Blob SAS URL** are displayed in the lower area of window.

+* You need the [**Azure Storage Explorer**](../../../../vs-azure-tools-storage-manage-with-storage-explorer.md) app installed in your Windows, macOS, or Linux development environment.

+1. A new window appears with the **Container** name, **URI**, and **Query string** for your container.

+1. A new window appears with the **Blob** name, **URI**, and **Query string** for your blob.

+The SAS URL includes a special set of [query parameters](/rest/api/storageservices/create-user-delegation-sas#assign-permissions-with-rbac). Those parameters indicate how the client accesses the resources.

+ Managed identities for Azure resources are service principals that create an Azure Active Directory (Azure AD) identity and specific permissions for Azure managed resources. Managed identities are a safer way to grant access to data without the need to include SAS tokens with your HTTP requests.

+In our quickstart, you learn how to rapidly get started using Document Translation. To begin, you need an active [Azure account](https://azure.microsoft.com/free/cognitive-services/). If you don't have one, you can [create a free account](https://azure.microsoft.com/free).

+Document Translation supports the following document file types:

+|Adobe PDF|`pdf`|Portable document file format. Document Translation uses optical character recognition (OCR) technology to extract and translate text in scanned PDF document while retaining the original layout.|

+|Comma-Separated Values |`csv`| A comma-delimited raw-data file used by spreadsheet programs.|

+|HTML|`html`, `htm`|Hyper Text Markup Language.|

+|Markdown| `markdown`, `mdown`, `mkdn`, `md`, `mkd`, `mdwn`, `mdtxt`, `mdtext`, `rmd`| A lightweight markup language for creating formatted text.|

+|M&#8203;HTML|`mthml`, `mht`| A web page archive format used to combine HTML code and its companion resources.|

+|Microsoft Excel|`xls`, `xlsx`|A spreadsheet file for data analysis and documentation.|

+|Microsoft Outlook|`msg`|An email message created or saved within Microsoft Outlook.|

+|Microsoft PowerPoint|`ppt`, `pptx`| A presentation file used to display content in a slideshow format.|

+|Microsoft Word|`doc`, `docx`| A text document file.|

+|OpenDocument Text|`odt`|An open-source text document file.|

+|OpenDocument Presentation|`odp`|An open-source presentation file.|

+|OpenDocument Spreadsheet|`ods`|An open-source spreadsheet file.|

+|Rich Text Format|`rtf`|A text document containing formatting.|

+|Tab Separated Values/TAB|`tsv`/`tab`| A tab-delimited raw-data file used by spreadsheet programs.|

+|Text|`txt`| An unformatted text document.|

+Source file types are preserved during the document translation with the following **exceptions**:

+Document Translation supports the following glossary file types:

+|Comma-Separated Values| `csv` |A comma-delimited raw-data file used by spreadsheet programs.|

+|Localization Interchange File Format| `xlf` , `xliff`| A parallel document format, export of Translation Memory systems The languages used are defined inside the file.|

+|Tab-Separated Values/TAB|`tsv`, `tab`| A tab-delimited raw-data file used by spreadsheet programs.|

+Gets the set of languages currently supported by other operations of the Translator.

+ <td>*Optional parameter*.<br/>A comma-separated list of names defining the group of languages to return. Allowed group names are: `translation`, `transliteration` and `dictionary`. If no scope is given, then all groups are returned, which is equivalent to passing `scope=translation,transliteration,dictionary`.</td>

+</table>

+*See* [response body](#response-body).

+ <td>*Optional request header*.<br/>The language to use for user interface strings. Some of the fields in the response are names of languages or names of regions. Use this parameter to define the language in which these names are returned. The language is specified by providing a well-formed BCP 47 language tag. For instance, use the value `fr` to request names in French or use the value `zh-Hant` to request names in Chinese Traditional.<br/>Names are provided in the English language when a target language isn't specified or when localization isn't available.

+</table>

+The structure of the response object doesn't change without a change in the version of the API. For the same version of the API, the list of available languages may change over time because Microsoft Translator continually extends the list of languages supported by its services.

+The list of supported languages doesn't change frequently. To save network bandwidth and improve responsiveness, a client application should consider caching language resources and the corresponding entity tag (`ETag`). Then, the client application can periodically (for example, once every 24 hours) query the service to fetch the latest set of supported languages. Passing the current `ETag` value in an `If-None-Match` header field allows the service to optimize the response. If the resource hasn't been modified, the service returns status code 304 and an empty response body.

+ <td>Value generated by the service to identify the request. It's used for troubleshooting purposes.</td>

+</table>

+The following are the possible HTTP status codes that a request returns.

+ <td>The resource hasn't been modified since the version specified by request headers `If-None-Match`.</td>

+</table>

+If an error occurs, the request also returns a JSON error response. The error code is a 6-digit number combining the 3-digit HTTP status code followed by a 3-digit number to further categorize the error. Common error codes can be found on the [v3 Translator reference page](./v3-0-reference.md#errors).

+|T├╝rkiye|TR|

+|T├╝rkiye|Turkish|tr-TR|

+ <option value="tr-TR">T├╝rkiye (Turkish)</option>

+This boundary defines data residency and processing rules for resources based on the data location selected when creating a new communication resource. When a data location for a resource is one of the European countries/regions in scope of EUDB, then all processing and storage of personal data remain within the European Union. The EU Data Boundary consists of the countries/regions in the European Union (EU) and the European Free Trade Association (EFTA). The EU countries/regions are Austria, Belgium, Bulgaria, Croatia, Cyprus, Czechia, Denmark, Estonia, Finland, France, Germany, Greece, Hungary, Ireland, Italy, Latvia, Lithuania, Luxembourg, Malta, Netherlands, Poland, Portugal, Romania, Slovakia, Slovenia, Spain, and Sweden; and the EFTA countries/regions are Liechtenstein, Iceland, Norway, and Switzerland.

+\* In some countries/regions, number purchases are only allowed for own use. Reselling or suballcoating to another parties is not allowed. Due to this, purchases for CSP and LSP customers is not allowed.

+|Geographic |Starting at USD 0.165/min |USD 0.0072/min |

+|Toll-free |Starting at USD 0.165/min | USD 0.2200/min |

+*To find all countries/regions where telephone numbers are available, please refer to [subscription eligibility and number capabilities page](../numbers/sub-eligibility-number-capability.md).

+ Title: Mute participants during a call

+description: Provides a how-to guide for muting participants during a call.

+zone_pivot_groups: acs-csharp-java

+# Mute participants during a call

+>[!IMPORTANT]

+>Functionality described on this document is currently in private preview. Private preview includes access to SDKs and documentation for testing purposes that are not yet available publicly.

+>Apply to become an early adopter by filling out the form for [preview access to Azure Communication Services](https://aka.ms/acs-tap-invite).

+With Azure Communication Services Call Automation SDK, developers can now mute participants through server based API requests. This feature can be useful when you want your application to mute participants after they've joined the meeting to avoid any interruptions or distractions to ongoing meetings.

+If youΓÇÖre interested in abilities to allow participants to mute/unmute themselves on the call when theyΓÇÖve joined with ACS Client Libraries, you can use our [mute/unmute function](../../../communication-services/how-tos/calling-sdk/manage-calls.md) provided through our Calling Library.

+## Common use cases

+### Contact center supervisor call monitoring

+In a typical contact center, there may be times when a supervisor needs to join an on-going call to monitor the call to provide guidance to agents after the call on how they could improve their assistance. The supervisor would join muted as to not disturb the on-going call with any extra side noise.

+*This guide helps you learn how to mute participants by using the mute action provided through Azure Communication Services Call Automation SDK.*

+## Clean up resources

+If you want to clean up and remove a Communication Services subscription, you can delete the resource or resource group. Deleting the resource group also deletes any other resources associated with it. Learn more about [cleaning up resources](../../quickstarts/create-communication-resource.md#clean-up-resources).

+## Next steps

+Learn more about [Call Automation](../../concepts/call-automation/call-automation.md).

+2. System Assigned Managed Identity is disabled by default. Enable it and click on *Save*

+1. Grant confidential VM Service Principal `Confidential VM Orchestrator` to tenant

+For this step you need to be a Global Admin or you need to have the User Access Administrator RBAC role.

+ ```azurecli

+ Connect-AzureAD -Tenant "your tenant ID"

+ New-AzureADServicePrincipal -AppId bf7b6499-ff71-4aa2-97a4-f372087be7f0 -DisplayName "Confidential VM Orchestrator"

+ ```

+2. Create an Azure Key Vault using the [az keyvault create](/cli/azure/keyvault) command. For the pricing tier, select Premium (includes support for HSM backed keys). Make sure that you have an owner role in this key vault.

+3. Give `Confidential VM Orchestrator` permissions to `get` and `release` the key vault.

+ ```azurecli

+ $cvmAgent = az ad sp show --id "bf7b6499-ff71-4aa2-97a4-f372087be7f0" | Out-String | ConvertFrom-Json

+ az keyvault set-policy --name $KeyVault --object-id $cvmAgent.objectId --key-permissions get release

+ ```

+4. Create a key in the key vault using [az keyvault key create](/cli/azure/keyvault). For the key type, use RSA-HSM.

+5. Create the disk encryption set using [az disk-encryption-set create](/cli/azure/disk-encryption-set). Set the encryption type to `ConfidentialVmEncryptedWithCustomerKey`.

+6. Grant the disk encryption set resource access to the key vault using [az key vault set-policy](/cli/azure/keyvault).

+7. Use the disk encryption set ID to create the VM.

+8. Create a VM with the [az vm create](/cli/azure/vm) command. Choose `DiskWithVMGuestState` for OS disk confidential encryption with a customer-managed key. Enabling secure boot is optional, but recommended. For more information, see [secure boot and vTPM](../virtual-machines/trusted-launch.md). For more information on disk encryption, see [confidential OS disk encryption](confidential-vm-overview.md).

+> [Create a confidential VM on AMD with an ARM template](quick-create-confidential-vm-arm-amd.md)

+ > [!NOTE]

+ > If you experience issues creating a custom location on your cluster, you may need to [enable the custom location feature on your cluster](../azure-arc/kubernetes/custom-locations.md#enable-custom-locations-on-your-cluster). This is required if logged into the CLI using a Service Principal or if you are logged in with an Azure Active Directory user with restricted permissions on the cluster resource.

+ >

+- Spring App console logs.

+While developing and troubleshooting your container app, it's essential to see the [logs](logging.md) for your container app in real time. Azure Container Apps lets you stream:

+- [system logs](logging.md#system-logs) from the Container Apps environment and your container app.

+- container [console logs](logging.md#container-console-logs) from your container app.

+Log streams are accessible through the Azure portal or the Azure CLI.

+## View log streams via the Azure portal

+You can view system logs and console logs in the Azure portal. System logs are generated by the container app's runtime. Console logs are generated by your container app.

+### Environment system log stream

+To troubleshoot issues in your container app environment, you can view the system log stream from your environment page. The log stream displays the system logs for the Container Apps service and the apps actively running in the environment:

+1. Go to your environment in the Azure portal.

+ :::image type="content" source="media/observability/system-log-streaming-env.png" alt-text="Screenshot of Container Apps environment system log stream page.":::

+### Container app log stream

+You can view a log stream of your container app's system or console logs from your container app page.

+1. Go to your container app in the Azure portal.

+1. Select **Log stream** under the *Monitoring* section on the sidebar menu.

+1. To view the console log stream, select **Console**.

+ 1. If you have multiple revisions, replicas, or containers, you can select from the drop-down menus to choose a container. If your app has only one container, you can skip this step.

+ :::image type="content" source="media/observability/screenshot-log-stream-console-app.png" alt-text="Screenshot of Container Apps console log stream from app page.":::

+1. To view the system log stream, select **System**. The system log stream displays the system logs for all running containers in your container app.

+ :::image type="content" source="media/observability/screenshot-log-stream-system-app.png" alt-text="Screenshot of Container Apps system log stream from app page.":::

+## View log streams via the Azure CLI

+You can view your container app's log streams from the Azure CLI with the `az containerapp logs show` command or your container app's environment system log stream with the `az containerapp env logs show` command.

+Control the log stream with the following arguments:

+- `--tail` (Default) View the last n log messages. Values are 0-300 messages. The default is 20.

+- `--follow` View a continuous live stream of the log messages.

+### Stream Container app logs

+You can stream the system or console logs for your container app. To stream the container app system logs, use the `--type` argument with the value `system`. To stream the container console logs, use the `--type` argument with the value `console`. The default is `console`.

+#### View container app system log stream

+This example uses the `--tail` argument to display the last 50 system log messages from the container app. Replace the \<placeholders\> with your container app's values.

+ --type system \

+ --type system `

+This example displays a continuous live stream of system log messages from the container app using the `--follow` argument. Replace the \<placeholders\> with your container app's values.

+# [Bash](#tab/bash)

+```azurecli

+az containerapp logs show \

+ --name <ContainerAppName> \

+ --resource-group <ResourceGroup> \

+ --type system \

+ --follow

+```

+# [PowerShell](#tab/powershell)

+```azurecli

+az containerapp logs show `

+ --name <ContainerAppName> `

+ --resource-group <ResourceGroup> `

+ --type system `

+ --follow

+```

+Use `Ctrl-C` or `Cmd-C` to stop the live stream.

+### View container console log stream

+To connect to a container's console log stream in a container app with multiple revisions, replicas, and containers, include the following parameters in the `az containerapp logs show` command.

+| `--revision` | The revision name. |

+| `--replica` | The replica name in the revision. |

+| `--container` | The container name to connect to. |

+You can get the revision names with the `az containerapp revision list` command. Replace the \<placeholders\> with your container app's values.

+Live stream the container console using the `az container app show` command with the `--follow` argument. Replace the \<placeholders\> with your container app's values.

+ --type console \

+ --type console `

+ --follow

+```

+Use `Ctrl-C` or `Cmd-C` to stop the live stream.

+View the last 50 console log messages using the `az containerapp logs show` command with the `--tail` argument. Replace the \<placeholders\> with your container app's values.

+# [Bash](#tab/bash)

+```azurecli

+az containerapp logs show \

+ --name <ContainerAppName> \

+ --resource-group <ResourceGroup> \

+ --revision <RevisionName> \

+ --replica <ReplicaName> \

+ --container <ContainerName> \

+ --type console \

+ --tail 50

+```

+# [PowerShell](#tab/powershell)

+```azurecli

+az containerapp logs show `

+ --name <ContainerAppName> `

+ --resource-group <ResourceGroup> `

+ --revision <RevisionName> `

+ --replica <ReplicaName> `

+ --container <ContainerName> `

+ --type console `

+ --tail 50

+```

+### View environment system log stream

+Use the following command with the `--follow` argument to view the live system log stream from the Container Apps environment. Replace the \<placeholders\> with your environment values.

+# [Bash](#tab/bash)

+```azurecli

+az containerapp env logs show \

+ --name <ContainerAppEnvironmentName> \

+ --resource-group <ResourceGroup> \

+ --follow

+```

+# [PowerShell](#tab/powershell)

+```azurecli

+az containerapp env logs show `

+ --name <ContainerAppEnvironmentName> `

+ --resource-group <ResourceGroup> `

+Use `Ctrl-C` or `Cmd-C` to stop the live stream.

+This example uses the `--tail` argument to display the last 50 environment system log messages. Replace the \<placeholders\> with your environment values.

+# [Bash](#tab/bash)

+```azurecli

+az containerapp env logs show \

+ --name <ContainerAppName> \

+ --resource-group <ResourceGroup> \

+ --tail 50

+```

+# [PowerShell](#tab/powershell)

+```azurecli

+az containerapp env logs show `

+ --name <ContainerAppName> `

+ --resource-group <ResourceGroup> `

+ --tail 50

+```

+> [Log storage and monitoring options in Azure Container Apps](log-monitoring.md)

+- [Container console logs](#container-console-logs): Log streams from your container console.

+- [System logs](#system-logs): Logs generated by the Azure Container Apps service.

+You can view the [log streams](log-streaming.md) in near real-time in the Azure portal or CLI. For more options to store and monitor your logs, see [Logging options](log-options.md).

+Container Apps captures the `stdout` and `stderr` output streams from your application containers and displays them as console logs. When you implement logging in your application, you can troubleshoot problems and monitor the health of your app.

+Container Apps generates system logs to inform you of the status of service level events. Log messages include the following information:

+- Auth enabled on app

+- Creating authentication config

+- Setting a traffic weight

+|[Log streaming](log-streaming.md) | View streaming system and console logs from a container in near real-time. |

+ Title: Change data capture in analytical store

+description: Change data capture (CDC) in Azure Cosmos DB analytical store allows you to efficiently consume a continuous and incremental feed of changed data.

+# Change Data Capture in Azure Cosmos DB analytical store

+Change data capture (CDC) in [Azure Cosmos DB analytical store](analytical-store-introduction.md) allows you to efficiently consume a continuous and incremental feed of changed (inserted, updated, and deleted) data from analytical store. The change data capture feature of the analytical store is seamlessly integrated with Azure Synapse and Azure Data Factory, providing you with a scalable no-code experience for high data volume. As the change data capture feature is based on analytical store, it [doesn't consume provisioned RUs, doesn't affect your transactional workloads](analytical-store-introduction.md#decoupled-performance-for-analytical-workloads), provides lower latency, and has lower TCO.

+In addition to providing incremental data feed from analytical store to diverse targets, change data capture supports the following capabilities:

+- Supports applying filters, projections and transformations on the Change feed via source query

+- Supports capturing deletes and intermediate updates

+- Ability to filter the change feed for a specific type of operation (**Insert** | **Update** | **Delete** | **TTL**)

+- Each change in Container appears exactly once in the change data capture feed, and the checkpoints are managed internally for you

+- Changes can be synchronized from ΓÇ£the BeginningΓÇ¥ or ΓÇ£from a given timestampΓÇ¥ or ΓÇ£from nowΓÇ¥

+- There's no limitation around the fixed data retention period for which changes are available

+- Multiple change feeds on the same container can be consumed simultaneously

+## Features

+Change data capture in Azure Cosmos DB analytical store supports the following key features.

+### Capturing deletes and intermediate updates

+The change data capture feature for the analytical store captures deleted records and the intermediate updates. The captured deletes and updates can be applied on Sinks that support delete and update operations. The {_rid} value uniquely identifies the records and so by specifying {_rid} as key column on the Sink side, the update and delete operations would be reflected on the Sink.

+### Filter the change feed for a specific type of operation

+You can filter the change data capture feed for a specific type of operation. For example, you can selectively capture the insert and update operations only, thereby ignoring the user-delete and TTL-delete operations.

+### Applying filters, projections, and transformations on the Change feed via source query

+You can optionally use a source query to specify filter(s), projection(s), and transformation(s), which would all be pushed down to the columnar analytical store. Here's a sample source-query that would only capture incremental records with the filter `Category = 'Urban'`. This sample query projects only five fields and applies a simple transformation:

+```sql

+SELECT ProductId, Product, Segment, concat(Manufacturer, '-', Category) as ManufacturerCategory

+FROM c

+WHERE Category = 'Urban'

+```

+> [!NOTE]

+> If you would like to enable source-query based change data capture on Azure Data Factory data flows during preview, please email [cosmosdbsynapselink@microsoft.com](mailto:cosmosdbsynapselink@microsoft.com) and share your **subscription Id** and **region**. This is not necessary to enable source-query based change data capture on an Azure Synapse data flow.

+### Throughput isolation, lower latency and lower TCO

+Operations on Cosmos DB analytical store don't consume the provisioned RUs and so don't affect your transactional workloads. change data capture with analytical store also has lower latency and lower TCO. The lower latency is attributed to analytical store enabling better parallelism for data processing and reduces the overall TCO enabling you to drive cost efficiencies in these rapidly shifting economic conditions.

+## Scenarios

+Here are common scenarios where you could use change data capture and the analytical store.

+### Consuming incremental data from Cosmos DB

+You can use analytical store change data capture, if you're currently using or planning to use:

+- Incremental data capture using Azure Data Factory Data Flows or Copy activity.

+- One time batch processing using Azure Data Factory.

+- Streaming Cosmos DB data

+ - The analytical store has up to 2-min latency to sync transactional store data. You can schedule Data Flows in Azure Data Factory every minute.

+ - If you need to stream without the above latency, we recommend using the change feed feature of the transactional store.

+- Capturing deletes, incremental changes, applying filters on Cosmos DB Data.

+ - If you're using Azure Functions triggers or any other option with change feed and would like to capture deletes, incremental changes, apply transformations etc.; we recommend change data capture over analytical store.

+### Incremental feed to analytical platform of your choice

+change data capture capability enables end-to-end analytical story providing you with the flexibility to use Azure Cosmos DB data on analytical platform of your choice seamlessly. It also enables you to bring Cosmos DB data into a centralized data lake and join with data from diverse data sources. For more information, see [supported sink types](../data-factory/data-flow-sink.md#supported-sinks). You can flatten the data, apply more transformations either in Azure Synapse Analytics or Azure Data Factory.

+## Change data capture on Azure Cosmos DB for MongoDB containers

+The linked service interface for the API for MongoDB isn't available within Azure Data Factory data flows yet. You can use your API for MongoDB's account endpoint with the **Azure Cosmos DB for NoSQL** linked service interface as a work around until the Mongo linked service is directly supported.

+In the interface for a new NoSQL linked service, select **Enter Manually** to provide the Azure Cosmos DB account information. Here, use the account's NoSQL document endpoint (ex: `https://<account-name>.documents.azure.com:443/`) instead of the Mongo DB endpoint (ex: `mongodb://<account-name>.mongo.cosmos.azure.com:10255/`)

+## Next steps

+> [!div class="nextstepaction"]

+> [Get started with change data capture in the analytical store](get-started-change-data-capture.md)

+ Title: Get started with change data capture in analytical store

+description: Enable change data capture in Azure Cosmos DB analytical store for an existing account to consume a continuous and incremental feed of changed data.

+# Get started with change data capture in the analytical store for Azure Cosmos DB

+Use Change data capture (CDC) in Azure Cosmos DB analytical store as a source to [Azure Data Factory](../data-factory/index.yml) or [Azure Synapse Analytics](../synapse-analytics/index.yml) to capture specific changes to your data.

+## Prerequisites

+- An existing Azure Cosmos DB account.

+ - If you have an Azure subscription, [create a new account](nosql/how-to-create-account.md?tabs=azure-portal).

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

+ - Alternatively, you can [try Azure Cosmos DB free](try-free.md) before you commit.

+## Enable analytical store

+First, enable Azure Synapse Link at the account level and then enable analytical store for the containers that's appropriate for your workload.

+1. Enable Azure Synapse Link: [Enable Azure Synapse Link for an Azure Cosmos DB account](configure-synapse-link.md#enable-synapse-link) |

+1. Enable analytical store for your container\[s\]:

+ | Option | Guide |

+ | | |

+ | **Enable for a specific new container** | [Enable Azure Synapse Link for your new containers](configure-synapse-link.md#new-container) |

+ | **Enable for a specific existing container** | [Enable Azure Synapse Link for your existing containers](configure-synapse-link.md#existing-container) |

+## Create a target Azure resource using data flows

+The change data capture feature of the analytical store is available through the data flow feature of [Azure Data Factory](../data-factory/concepts-data-flow-overview.md) or [Azure Synapse Analytics](../synapse-analytics/concepts-data-flow-overview.md). For this guide, use Azure Data Factory.

+> [!IMPORTANT]

+> You can alternatively use Azure Synapse Analytics. First, [create an Azure Synapse workspace](../synapse-analytics/quickstart-create-workspace.md), if you don't already have one. Within the newly created workspace, select the **Develop** tab, select **Add new resource**, and then select **Data flow**.

+1. [Create an Azure Data Factory](../data-factory/quickstart-create-data-factory.md), if you don't already have one.

+ > [!TIP]

+ > If possible, create the data factory in the same region where your Azure Cosmos DB account resides.

+1. Launch the newly created data factory.

+1. In the data factory, select the **Data flows** tab, and then select **New data flow**.

+1. Give the newly created data flow a unique name. In this example, the data flow is named `cosmoscdc`.

+ :::image type="content" source="media/get-started-change-data-capture/data-flow-name.png" lightbox="media/get-started-change-data-capture/data-flow-name.png" alt-text="Screnshot of a new data flow with the name cosmoscdc.":::

+## Configure source settings for the analytical store container

+Now create and configure a source to flow data from the Azure Cosmos DB account's analytical store.

+1. Select **Add Source**.

+ :::image type="content" source="media/get-started-change-data-capture/add-source.png" alt-text="Screenshot of the add source menu option.":::

+1. In the **Output stream name** field, enter **cosmos**.

+ :::image type="content" source="media/get-started-change-data-capture/source-name.png" alt-text="Screenshot of naming the newly created source cosmos.":::

+1. In the **Source type** section, select **Inline**.

+ :::image type="content" source="media/get-started-change-data-capture/inline-source-type.png" alt-text="Screenshot of selecting the inline source type.":::

+1. In the **Dataset** field, select **Azure - Azure Cosmos DB for NoSQL**.

+ :::image type="content" source="media/get-started-change-data-capture/dataset-type-cosmos.png" alt-text="Screenshot of selecting Azure Cosmos DB for NoSQL as the dataset type.":::

+1. Create a new linked service for your account named **cosmoslinkedservice**. Select your existing Azure Cosmos DB for NoSQL account in the **New linked service** popup dialog and then select **Ok**. In this example, we select a pre-existing Azure Cosmos DB for NoSQL account named `msdocs-cosmos-source` and a database named `cosmicworks`.

+ :::image type="content" source="media/get-started-change-data-capture/new-linked-service.png" alt-text="Screenshot of the New linked service dialog with an Azure Cosmos DB account selected.":::

+1. Select **Analytical** for the store type.

+ :::image type="content" source="media/get-started-change-data-capture/linked-service-analytical.png" alt-text="Screenshot of the analytical option selected for a linked service.":::

+1. Select the **Source options** tab.

+1. Within **Source options**, select your target container and enable **Data flow debug**. In this example, the container is named `products`.

+ :::image type="content" source="media/get-started-change-data-capture/container-name.png" alt-text="Screenshot of a source container selected named products.":::

+1. Select **Data flow debug**. In the **Turn on data flow debug** popup dialog, retain the default options and then select **Ok**.

+ :::image type="content" source="media/get-started-change-data-capture/enable-data-flow-debug.png" alt-text="Screenshot of the toggle option to enable data flow debug.":::

+1. The **Source options** tab also contains other options you may wish to enable. This table describes those options:

+| Option | Description |

+| | |

+| Capture intermediate updates | Enable this option if you would like to capture the history of changes to items including the intermediate changes between change data capture reads. |

+| Capture Deletes | Enable this option to capture user-deleted records and apply them on the Sink. Deletes can't be applied on Azure Data Explorer and Azure Cosmos DB Sinks. |

+| Capture Transactional store TTLs | Enable this option to capture Azure Cosmos DB transactional store (time-to-live) TTL deleted records and apply on the Sink. TTL-deletes can't be applied on Azure Data Explorer and Azure Cosmos DB sinks. |

+| Batchsize in bytes | Specify the size in bytes if you would like to batch the change data capture feeds |

+| Extra Configs | Extra Azure Cosmos DB analytical store configs and their values. (ex: `spark.cosmos.allowWhiteSpaceInFieldNames -> true`) |

+## Create and configure sink settings for update and delete operations

+First, create a straightforward [Azure Blob Storage](../storage/blobs/index.yml) sink and then configure the sink to filter data to only specific operations.

+1. [Create an Azure Blob Storage](../data-factory/quickstart-create-data-factory.md) account and container, if you don't already have one. For the next examples, we'll use an account named `msdocsblobstorage` and a container named `output`.

+ > [!TIP]

+ > If possible, create the storage account in the same region where your Azure Cosmos DB account resides.

+1. Back in Azure Data Factory, create a new sink for the change data captured from your `cosmos` source.

+ :::image type="content" source="media/get-started-change-data-capture/add-sink.png" alt-text="Screenshot of adding a new sink that's connected to the existing source.":::

+1. Give the sink a unique name. In this example, the sink is named `storage`.

+ :::image type="content" source="media/get-started-change-data-capture/sink-name.png" alt-text="Screenshot of naming the newly created sink storage.":::

+1. In the **Sink type** section, select **Inline**. In the **Dataset** field, select **Delta**.

+ :::image type="content" source="media/get-started-change-data-capture/sink-dataset-type.png" alt-text="Screenshot of selecting and Inline Delta dataset type for the sink.":::

+1. Create a new linked service for your account using **Azure Blob Storage** named **storagelinkedservice**. Select your existing Azure Blob Storage account in the **New linked service** popup dialog and then select **Ok**. In this example, we select a pre-existing Azure Blob Storage account named `msdocsblobstorage`.

+ :::image type="content" source="media/get-started-change-data-capture/new-linked-service-sink-type.png" alt-text="Screenshot of the service type options for a new Delta linked service.":::

+ :::image type="content" source="media/get-started-change-data-capture/new-linked-service-sink-config.png" alt-text="Screenshot of the New linked service dialog with an Azure Blob Storage account selected.":::

+1. Select the **Settings** tab.

+1. Within **Settings**, set the **Folder path** to the name of the blob container. In this example, the container's name is `output`.

+ :::image type="content" source="media/get-started-change-data-capture/sink-container-name.png" alt-text="Screenshot of the blob container named output set as the sink target.":::

+1. Locate the **Update method** section and change the selections to only allow **delete** and **update** operations. Also, specify the **Key columns** as a **List of columns** using the field `_{rid}` as the unique identifier.

+ :::image type="content" source="media/get-started-change-data-capture/sink-methods-columns.png" alt-text="Screenshot of update methods and key columns being specified for the sink.":::

+1. Select **Validate** to ensure you haven't made any errors or omissions. Then, select **Publish** to publish the data flow.

+ :::image type="content" source="media/get-started-change-data-capture/validate-publish-data-flow.png" alt-text="Screenshot of the option to validate and then publish the current data flow.":::

+## Schedule change data capture execution

+After a data flow has been published, you can add a new pipeline to move and transform your data.

+1. Create a new pipeline. Give the pipeline a unique name. In this example, the pipeline is named `cosmoscdcpipeline`.

+ :::image type="content" source="media/get-started-change-data-capture/new-pipeline.png" alt-text="Screenshot of the new pipeline option within the resources section.":::

+1. In the **Activities** section, expand the **Move &amp; transform** option and then select **Data flow**.

+ :::image type="content" source="media/get-started-change-data-capture/data-flow-activity.png" alt-text="Screenshot of the data flow activity option within the activities section.":::

+1. Give the data flow activity a unique name. In this example, the activity is named `cosmoscdcactivity`.

+1. In the **Settings** tab, select the data flow named `cosmoscdc` you created earlier in this guide. Then, select a compute size based on the data volume and required latency for your workload.

+ :::image type="content" source="media/get-started-change-data-capture/data-flow-settings.png" alt-text="Screenshot of the configuration settings for both the data flow and compute size for the activity.":::

+ > [!TIP]

+ > For incremental data sizes greater than 100 GB, we recommend the **Custom** size with a core count of 32 (+16 driver cores).

+1. Select **Add trigger**. Schedule this pipeline to execute at a cadence that makes sense for your workload. In this example, the pipeline is configured to execute every five minutes.

+ :::image type="content" source="media/get-started-change-data-capture/add-trigger.png" alt-text="Screenshot of the add trigger button for a new pipeline.":::

+ :::image type="content" source="media/get-started-change-data-capture/trigger-configuration.png" alt-text="Screenshot of a trigger configuration based on a schedule, starting in the year 2023, that runs every five minutes.":::

+ > [!NOTE]

+ > The minimum recurrence window for change data capture executions is one minute.

+1. Select **Validate** to ensure you haven't made any errors or omissions. Then, select **Publish** to publish the pipeline.

+1. Observe the data placed into the Azure Blob Storage container as an output of the data flow using Azure Cosmos DB analytical store change data capture.

+ :::image type="content" source="media/get-started-change-data-capture/output-files.png" alt-text="Screnshot of the output files from the pipeline in the Azure Blob Storage container.":::

+ > [!NOTE]

+ > The initial cluster startup time may take up to three minutes. To avoid cluster startup time in the subsequent change data capture executions, configure the Dataflow cluster **Time to live** value. For more information about the itegration runtime and TTL, see [integration runtime in Azure Data Factory](../data-factory/concepts-integration-runtime.md).

+## Next steps

+- Review the [overview of Azure Cosmos DB analytical store](analytical-store-introduction.md)

+| `$objectToArray` | :::image type="icon" source="media/compatibility/yes-icon.svg"::: Yes |

+ Title: Modify periodic backup interval and retention period

+description: Learn how to modify the interval and retention period for periodic backup in Azure Cosmos DB accounts.

+# Modify periodic backup interval and retention period in Azure Cosmos DB

+Azure Cosmos DB automatically takes a full backup of your data for every 4 hours and at any point of time, the latest two backups are stored. This configuration is the default option and itΓÇÖs offered without any extra cost. You can change the default backup interval and retention period during the Azure Cosmos DB account creation or after the account is created. The backup configuration is set at the Azure Cosmos DB account level and you need to configure it on each account. After you configure the backup options for an account, itΓÇÖs applied to all the containers within that account. You can modify these settings using the Azure portal, Azure PowerShell, or the Azure CLI.

+## Prerequisites

+- An existing Azure Cosmos DB account.

+ - If you have an Azure subscription, [create a new account](nosql/how-to-create-account.md?tabs=azure-portal).

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

+ - Alternatively, you can [try Azure Cosmos DB free](try-free.md) before you commit.

+## Before you start

+If you've accidentally deleted or corrupted your data, **before you create a support request to restore the data, make sure to increase the backup retention for your account to at least seven days. ItΓÇÖs best to increase your retention within 8 hours of this event.** This way, the Azure Cosmos DB team has enough time to restore your account.

+## Modify backup options for an existing account

+Use the following steps to change the default backup options for an existing Azure Cosmos DB account.

+### [Azure portal](#tab/azure-portal)

+1. Sign into the [Azure portal](https://portal.azure.com/).

+1. Navigate to your Azure Cosmos DB account and open the **Backup & Restore** pane. Update the backup interval and the backup retention period as required.

+ - **Backup Interval** - ItΓÇÖs the interval at which Azure Cosmos DB attempts to take a backup of your data. Backup takes a nonzero amount of time and in some case it could potentially fail due to downstream dependencies. Azure Cosmos DB tries its best to take a backup at the configured interval, however, it doesnΓÇÖt guarantee that the backup completes within that time interval. You can configure this value in hours or minutes. Backup Interval can't be less than 1 hour and greater than 24 hours. When you change this interval, the new interval takes into effect starting from the time when the last backup was taken.

+ - **Backup Retention** - It represents the period where each backup is retained. You can configure it in hours or days. The minimum retention period canΓÇÖt be less than two times the backup interval (in hours) and it canΓÇÖt be greater than 720 hours.

+ - **Copies of data retained** - By default, two backup copies of your data are offered at free of charge. There's an extra charge if you need more than two copies. See the Consumed Storage section in the [pricing page](https://azure.microsoft.com/pricing/details/cosmos-db/) to know the exact price for extra copies.

+ - **Backup storage redundancy** - Choose the required storage redundancy option. For more information, see [backup storage redundancy](periodic-backup-storage-redundancy.md). By default, your existing periodic backup mode accounts have geo-redundant storage if the region where the account is being provisioned supports it. Otherwise, the account fallback to the highest redundancy option available. You can choose other storage such as locally redundant to ensure the backup isn't replicated to another region. The changes made to an existing account are applied to only future backups. After the backup storage redundancy of an existing account is updated, it may take up to twice the backup interval time for the changes to take effect, and **you will lose access to restore the older backups immediately.**

+ > [!NOTE]

+ > You must have the Azure [Azure Cosmos DB Operator role](../role-based-access-control/built-in-roles.md#cosmos-db-operator) role assigned at the subscription level to configure backup storage redundancy.

+ :::image type="content" source="./media/periodic-backup-modify-interval-retention/configure-existing-account-portal.png" lightbox="./media/periodic-backup-modify-interval-retention/configure-existing-account-portal.png" alt-text="Screenshot of configuration options including backup interval, retention, and storage redundancy for an existing Azure Cosmos DB account.":::

+### [Azure CLI](#tab/azure-cli)

+Use the [`az cosmosdb update`](/cli/azure/cosmosdb#az-cosmosdb-update) command to update the periodic backup options for an existing account.

+```azurecli-interactive

+az cosmosdb update \

+ --resource-group <resource-group-name> \

+ --name <account-name> \

+ --backup-interval 480 \

+ --backup-retention 24

+```

+### [Azure PowerShell](#tab/azure-powershell)

+Use the [`Update-AzCosmosDBAccount`](/powershell/module/az.cosmosdb/update-azcosmosdbaccount) cmdlet to update the periodic backup options for an existing account.

+```azurepowershell-interactive

+$parameters = @{

+ ResourceGroupName = "<resource-group-name>"

+ Name = "<account-name>"

+ BackupIntervalInMinutes = 480

+ BackupRetentionIntervalInHours = 24

+}

+Update-AzCosmosDBAccount @parameters

+```

+### [Azure Resource Manager template](#tab/azure-resource-manager-template)

+Use the following Azure Resource Manager JSON template to update the periodic backup options for an existing account.

+```json

+{

+ "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",

+ "contentVersion": "1.0.0.0",

+ "parameters": {

+ "newAccountName": {

+ "type": "string",

+ "defaultValue": "[format('nosql-{0}', toLower(uniqueString(resourceGroup().id)))]",

+ "metadata": {

+ "description": "Name of the existing Azure Cosmos DB account."

+ }

+ },

+ "location": {

+ "type": "string",

+ "defaultValue": "[resourceGroup().location]",

+ "metadata": {

+ "description": "Location for the Azure Cosmos DB account."

+ }

+ }

+ },

+ "resources": [

+ {

+ "type": "Microsoft.DocumentDB/databaseAccounts",

+ "apiVersion": "2022-05-15",

+ "name": "[parameters('newAccountName')]",

+ "location": "[parameters('location')]",

+ "kind": "GlobalDocumentDB",

+ "properties": {

+ "databaseAccountOfferType": "Standard",

+ "locations": [

+ {

+ "locationName": "[parameters('location')]"

+ }

+ ],

+ "backupPolicy": {

+ "type": "Periodic",

+ "periodicModeProperties": {

+ "backupIntervalInMinutes": 480,

+ "backupRetentionIntervalInHours": 24,

+ "backupStorageRedundancy": "Local"

+ }

+ }

+ }

+ }

+ ]

+}

+```

+Alternatively, you can use the Bicep variant of the same template.

+```bicep

+@description('Name of the existing Azure Cosmos DB account.')

+param newAccountName string = 'nosql-${toLower(uniqueString(resourceGroup().id))}'

+@description('Location for the Azure Cosmos DB account.')

+param location string = resourceGroup().location

+resource account 'Microsoft.DocumentDB/databaseAccounts@2022-05-15' = {

+ name: newAccountName

+ location: location

+ kind: 'GlobalDocumentDB'

+ properties: {

+ databaseAccountOfferType: 'Standard'

+ locations: [

+ {

+ locationName: location

+ }

+ ]

+ backupPolicy:

+ type: 'Periodic'

+ periodicModeProperties:

+ backupIntervalInMinutes: 480,

+ backupRetentionIntervalInHours: 24,

+ backupStorageRedundancy: 'Local'

+ }

+}

+```

+## Configure backup options for a new account

+Use these steps to change the default backup options for a new Azure Cosmos DB account.

+> [!NOTE]

+> For illustrative purposes, these examples assume that you are creating an [Azure Cosmos DB for NoSQL](nosql/index.yml) account. The steps are very similar for accounts using other APIs.

+### [Azure portal](#tab/azure-portal)

+When provisioning a new account, from the **Backup Policy** tab, select **Periodic*** backup policy. The periodic policy allows you to configure the backup interval, backup retention, and backup storage redundancy. For example, you can choose **locally redundant backup storage** or **Zone redundant backup storage** options to prevent backup data replication outside your region.

+### [Azure CLI](#tab/azure-cli)

+Use the [`az cosmosdb create`](/cli/azure/cosmosdb#az-cosmosdb-create) command to create a new account with the specified periodic backup options.

+```azurecli-interactive

+az cosmosdb create \

+ --resource-group <resource-group-name> \

+ --name <account-name> \

+ --locations regionName=<azure-region> \

+ --backup-interval 360 \

+ --backup-retention 12

+```

+### [Azure PowerShell](#tab/azure-powershell)

+Use the [`New-AzCosmosDBAccount`](/powershell/module/az.cosmosdb/new-azcosmosdbaccount) cmdlet to create a new account with the specified periodic backup options.

+```azurepowershell-interactive

+$parameters = @{

+ ResourceGroupName = "<resource-group-name>"

+ Name = "<account-name>"

+ Location = "<azure-region>"

+ BackupPolicyType = "Periodic"

+ BackupIntervalInMinutes = 360

+ BackupRetentionIntervalInHours = 12

+}

+New-AzCosmosDBAccount @parameters

+```

+### [Azure Resource Manager template](#tab/azure-resource-manager-template)

+Use the following Azure Resource Manager JSON template to update the periodic backup options for an existing account.

+```json

+{

+ "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",

+ "contentVersion": "1.0.0.0",

+ "parameters": {

+ "newAccountName": {

+ "type": "string",

+ "defaultValue": "[format('nosql-{0}', toLower(uniqueString(resourceGroup().id)))]",

+ "metadata": {

+ "description": "New Azure Cosmos DB account name. Max length is 44 characters."

+ }

+ },

+ "location": {

+ "type": "string",

+ "defaultValue": "[resourceGroup().location]",

+ "metadata": {

+ "description": "Location for the new Azure Cosmos DB account."

+ }

+ }

+ },

+ "resources": [

+ {

+ "type": "Microsoft.DocumentDB/databaseAccounts",

+ "apiVersion": "2022-05-15",

+ "name": "[parameters('newAccountName')]",

+ "location": "[parameters('location')]",

+ "kind": "GlobalDocumentDB",

+ "properties": {

+ "databaseAccountOfferType": "Standard",

+ "locations": [

+ {

+ "locationName": "[parameters('location')]"

+ }

+ ],

+ "backupPolicy": {

+ "type": "Periodic",

+ "periodicModeProperties": {

+ "backupIntervalInMinutes": 360,

+ "backupRetentionIntervalInHours": 12,

+ "backupStorageRedundancy": "Zone"

+ }

+ }

+ }

+ }

+ ]

+}

+```

+Alternatively, you can use the Bicep variant of the same template.

+```bicep

+@description('New Azure Cosmos DB account name. Max length is 44 characters.')

+param newAccountName string = 'sql-${toLower(uniqueString(resourceGroup().id))}'

+@description('Location for the new Azure Cosmos DB account.')

+param location string = resourceGroup().location

+resource account 'Microsoft.DocumentDB/databaseAccounts@2022-05-15' = {

+ name: newAccountName

+ location: location

+ kind: 'GlobalDocumentDB'

+ properties: {

+ databaseAccountOfferType: 'Standard'

+ locations: [

+ {

+ locationName: location

+ }

+ ]

+ backupPolicy:

+ type: 'Periodic'

+ periodicModeProperties:

+ backupIntervalInMinutes: 360,

+ backupRetentionIntervalInHours: 12,

+ backupStorageRedundancy: 'Zone'

+ }

+}

+```

+## Next steps

+> [!div class="nextstepaction"]

+> [Request data restoration from a backup](periodic-backup-request-data-restore.md)

+ Title: Request data restoration from a backup

+description: Request the restoration of your Azure Cosmos DB data from a backup if you've lost or accidentally deleted a database or container.

+# Request data restoration from an Azure Cosmos DB backup

+If you accidentally delete your database or a container, you can [file a support ticket](https://portal.azure.com/?#blade/Microsoft_Azure_Support/HelpAndSupportBlade) or [call the Azure support](https://azure.microsoft.com/support/options/) to restore the data from automatic online backups. Azure support is available for selected plans only such as **Standard**, **Developer**, and plans higher than those tiers. Azure support isn't available with **Basic** plan. To learn about different support plans, see the [Azure support plans](https://azure.microsoft.com/support/plans/) page.

+To restore a specific snapshot of the backup, Azure Cosmos DB requires that the data is available during the backup cycle for that snapshot.

+You should have the following details before requesting a restore:

+- Have your subscription ID ready.

+- Based on how your data was accidentally deleted or modified, you should prepare to have additional information. It's advised that you have the information available ahead to minimize the back-and-forth that can be detrimental in some time sensitive cases.

+- If the entire Azure Cosmos DB account is deleted, you need to provide the name of the deleted account. If you create another account with the same name as the deleted account, share that with the support team because it helps to determine the right account to choose. It's recommended to file different support tickets for each deleted account because it minimizes the confusion for the state of restore.

+- If one or more databases are deleted, you should provide the Azure Cosmos DB account, and the Azure Cosmos DB database names and specify if a new database with the same name exists.

+- If one or more containers are deleted, you should provide the Azure Cosmos DB account name, database names, and the container names. And specify if a container with the same name exists.

+- If you've accidentally deleted or corrupted your data, you should contact [Azure support](https://azure.microsoft.com/support/options/) within 8 hours so that the Azure Cosmos DB team can help you restore the data from the backups. **Before you create a support request to restore the data, make sure to [increase the backup retention](periodic-backup-modify-interval-retention.md) for your account to at least seven days. ItΓÇÖs best to increase your retention within 8 hours of this event.** This way the Azure Cosmos DB support team has enough time to restore your account.

+In addition to Azure Cosmos DB account name, database names, container names, you should specify the point in time to use for data restoration. It's important to be as precise as possible to help us determine the best available backups at that time. **It is also important to specify the time in UTC.**

+The following screenshot illustrates how to create a support request for a container(collection/graph/table) to restore data by using Azure portal. Provide other details such as type of data, purpose of the restore, time when the data was deleted to help us prioritize the request.

+## Considerations for restoring the data from a backup

+You may accidentally delete or modify your data in one of the following scenarios:

+- Delete the entire Azure Cosmos DB account.

+- Delete one or more Azure Cosmos DB databases.

+- Delete one or more Azure Cosmos DB containers.

+- Delete or modify the Azure Cosmos DB items (for example, documents) within a container. This specific case is typically referred to as data corruption.

+- A shared offer database or containers within a shared offer database are deleted or corrupted.

+Azure Cosmos DB can restore data in all the above scenarios. A new Azure Cosmos DB account is created to hold the restored data when restoring from a backup. The name of the new account, if it's not specified, has the format `<Azure_Cosmos_account_original_name>-restored1`. The last digit is incremented when multiple restores are attempted. You can't restore data to a precreated Azure Cosmos DB account.

+When you accidentally delete an Azure Cosmos DB account, we can restore the data into a new account with the same name, if the account name isn't in use. So, we recommend that you don't re-create the account after deleting it. Because it not only prevents the restored data to use the same name, but also makes discovering the right account to restore from difficult.

+When you accidentally delete an Azure Cosmos DB database, we can restore the whole database or a subset of the containers within that database. It's also possible to select specific containers across databases and restore them to a new Azure Cosmos DB account.

+When you accidentally delete or modify one or more items within a container (the data corruption case), you need to specify the time to restore to. Time is important if there's data corruption. Because the container is live, the backup is still running, so if you wait beyond the retention period (the default is eight hours) the backups would be overwritten. In order to prevent the backup from being overwritten, increase the backup retention for your account to at least seven days. ItΓÇÖs best to increase your retention within 8 hours from the data corruption.

+If you've accidentally deleted or corrupted your data, you should contact [Azure support](https://azure.microsoft.com/support/options/) within 8 hours so that the Azure Cosmos DB team can help you restore the data from the backups. This way the Azure Cosmos DB support team has enough time to restore your account.

+> [!NOTE]

+> After you restore the data, not all the source capabilities or settings are carried over to the restored account. The following settings are not carried over to the new account:

+>

+> - VNET access control lists

+> - Stored procedures, triggers and user-defined functions

+> - Multi-region settings

+> - Managed identity settings

+>

+If you assign throughput at the database level, the backup and restore process in this case happen at the entire database level, and not at the individual containers level. In such cases, you can't select a subset of containers to restore.

+## Get the restore details from the restored account

+After the restore operation completes, you may want to know the source account details from which you restored or the restore time. You can get these details from the Azure portal, PowerShell, or CLI.

+### [Azure portal](#tab/azure-portal)

+Use the following steps to get the restore details from Azure portal:

+1. Sign into the [Azure portal](https://portal.azure.com/) and navigate to the restored account.

+1. Open the **Tags** page.

+1. The **Tags** page should have the tags **restoredAtTimestamp** and **restoredSourceDatabaseAccountName**. These tags describe the timestamp and the source account name that were used for the periodic restore.

+### [Azure CLI](#tab/azure-cli)

+Run the following command to get the restore details. The `restoreSourceAccountName` and `restoreTimestamp` fields are within the `tags` field:

+```azurecli-interactive

+az cosmosdb show \

+ --resource-group <resource-group-name> \

+ --name <account-name>

+```

+### [Azure PowerShell](#tab/azure-powershell)

+Import the Az.CosmosDB module and run the following command to get the restore details. The `restoreSourceAccountName` and `restoreTimestamp` are within the `tags` field:

+```powershell-interactive

+$parameters = @{

+ ResourceGroupName = "<resource-group-name>"

+ Name = "<account-name>"

+}

+Get-AzCosmosDBAccount @parameters

+```

+## Post-restore actions

+The primary goal of the data restore is to recover the data that you've accidentally deleted or modified. So, we recommend that you first inspect the content of the recovered data to ensure it contains what you are expecting. If everything looks good, you can migrate the data back to the primary account. Although it's possible to use the restored account as your new active account, it's not a recommended option if you have production workloads.

+After you restore the data, you get a notification about the name of the new account (itΓÇÖs typically in the format `<original-name>-restored1`) and the time when the account was restored to. The restored account has the same provisioned throughput, indexing policies and it is in same region as the original account. A user who is the subscription admin or a coadmin can see the restored account.

+### Migrate data to the original account

+The following are different ways to migrate data back to the original account:

+- Use the [Azure Data Factory](../data-factory/connector-azure-cosmos-db.md).

+- Use the [change feed](change-feed.md) in Azure Cosmos DB.

+- You can write your own custom code.

+It's advised that you delete the container or database immediately after migrating the data. If you don't delete the restored databases or containers, they incur cost for request units, storage, and egress.

+## Next steps

+- Learn more about [periodic backup and restore](periodic-backup-restore-introduction.md)

+- Learn more about [continuous backup](continuous-backup-restore-introduction.md)

+ Title: Periodic backup/restore introduction

+description: Learn about Azure Cosmos DB accounts with periodic backup retention and restoration capabilities at a specified interval.

+# Periodic backup and restore in Azure Cosmos DB

+Azure Cosmos DB automatically takes backups of your data at regular intervals. The automatic backups are taken without affecting the performance or availability of the database operations. All the backups are stored separately in a storage service, and those backups are globally replicated for resiliency against regional disasters. With Azure Cosmos DB, not only your data, but also the backups of your data are highly redundant and resilient to regional disasters.

+## How Azure Cosmos DB performs data backup

+The following steps show how Azure Cosmos DB performs data backup:

+ :::image type="content" source="./media/periodic-backup-restore-introduction/automatic-backup.png" alt-text="Diagram of periodic full backups taken of multiple Azure Cosmos DB entities in geo-redundant Azure Storage." lightbox="./media/periodic-backup-restore-introduction/automatic-backup.png" border="false":::

+## Azure Cosmos DB Backup with Azure Synapse Link

+For Azure Synapse Link enabled accounts, analytical store data isn't included in the backups and restores. When Azure Synapse Link is enabled, Azure Cosmos DB continues to automatically take backups of your data in the transactional store at a scheduled backup interval. Automatic backup and restore of your data in the analytical store isn't supported at this time.

+## Understanding the cost of backups

+Two backups are provided free and extra backups are charged according to the region-based pricing for backup storage described in [backup storage pricing](https://azure.microsoft.com/pricing/details/cosmos-db/).

+For example, consider a scenario where Backup Retention is configured to **240 hrs** (or **10 days**) and Backup Interval is configured to **24 hours**. This configuration implies that there are **10** copies of the backup data. If you have **1 TB** of data in an Azure region, the cost for backup storage in a given month would be: `0.12 * 1000 * 8`

+## Required permissions to manage retention or restoration

+## Manually managing periodic backups in Azure Cosmos DB

+### Azure Data Factory

+Use [Azure Data Factory](../data-factory/connector-azure-cosmos-db.md) to move data periodically to a storage solution of your choice.

+### Azure Cosmos DB change feed

+Use Azure Cosmos DB [change feed](change-feed.md) to read data periodically for full backups or for incremental changes, and store it in your own storage.

+> [!div class="nextstepaction"]

+> [Periodic backup storage redundancy](periodic-backup-storage-redundancy.md)

+ Title: Periodic backup storage redundancy

+description: Learn how to configure Azure Storage-based data redundancy for periodic backup in Azure Cosmos DB accounts.

+# Periodic backup storage redundancy in Azure Cosmos DB

+By default, Azure Cosmos DB stores periodic mode backup data in geo-redundant [Azure Blob Storage](../storage/common/storage-redundancy.md). The blob storage is then, by default, replicated to a [paired region](../availability-zones/cross-region-replication-azure.md). You can update this default value using Azure PowerShell or Azure CLI and define an Azure policy to enforce a specific storage redundancy option. For more information, see [update backup storage redundancy](periodic-backup-update-storage-redundancy.md).

+## Best practices

+Change the default geo-redundant backup storage to ensure that your backup data stays within the same region where your Azure Cosmos DB account is provisioned. You can configure the geo-redundant backup to use either locally redundant or zone-redundant storage. Storage redundancy mechanisms store multiple copies of your backups so that it's protected from planned and unplanned events. These events can include transient hardware failure, network or power outages, or massive natural disasters.

+## Redundancy options

+You can configure storage redundancy for periodic backup mode at the time of account creation or update it for an existing account. You can use the following three data redundancy options in periodic backup mode:

+- **Geo-redundant backup storage:** This option copies your data asynchronously across the paired region.

+- **Zone-redundant backup storage:** This option copies your data synchronously across three Azure availability zones in the primary region. For more information, see [Zone-redundant storage.](../storage/common/storage-redundancy.md#redundancy-in-the-primary-region)

+- **Locally-redundant backup storage:** This option copies your data synchronously three times within a single physical location in the primary region. For more information, see [locally redundant storage.](../storage/common/storage-redundancy.md#redundancy-in-the-primary-region)

+> [!NOTE]

+> Zone-redundant storage is currently available only in [specific regions](../availability-zones/az-region.md). Depending on the region you select for a new account or the region you have for an existing account; the zone-redundant option will not be available.

+>

+> Updating backup storage redundancy will not have any impact on backup storage pricing.

+## Next steps

+> [!div class="nextstepaction"]

+> [Update the redundancy of backup storage](periodic-backup-update-storage-redundancy.md)

+ Title: Update periodic backup storage redundancy

+description: Update the backup storage redundancy using Azure CLI or Azure PowerShell and enforce a minimum storage redundancy using Azure Policy.

+# Update periodic backup storage redundancy for Azure Cosmos DB

+## Prerequisites

+- An existing Azure Cosmos DB account.

+ - If you have an Azure subscription, [create a new account](nosql/how-to-create-account.md?tabs=azure-portal).

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

+ - Alternatively, you can [try Azure Cosmos DB free](try-free.md) before you commit.

+## Update storage redundancy

+Use the following steps to update backup storage redundancy.

+### [Azure portal](#tab/azure-portal)

+1. Open the **Backup & Restore** pane, update the backup storage redundancy and select **Submit**. It takes few minutes for the operation to complete.

+ :::image type="content" source="./media/periodic-backup-update-storage-redundancy/update-existing-account-portal.png" lightbox="./media/periodic-backup-update-storage-redundancy/update-existing-account-portal.png" alt-text="Screenshot of the update backup storage redundancy page from the Azure portal.":::