-A claims transformation technical profile accesses the `isForgotPassword` claim. The technical profile is referenced later. When it's invoked, it sets the value of the `isForgotPassword` claim to `true`. Find the **ClaimsProviders** element (if the element doesn't exist, create it), and then add the following claims provider:

-Find the **SubJourneys** element. If the element doesn't exist, add it after the **User Journeys** element. Then, add the following sub journey:

-1. In the starter pack, open the *TrustFrameworkBase.xml* file.

-1. Open *TrustFrameworkExtensions.xml* and find the **UserJourneys** element. If the element doesn't exist, add one.

-In your user journey, you can represent the Forgot Password sub journey as a **ClaimsProviderSelection**. Adding this element connects the **Forgot your password?** link to the Forgot Password sub journey.

-1. In the next orchestration step, add a **ClaimsExchange** element. Add the following line:

-Now that you've modified or created a user journey, in the **Relying Party** section, specify the journey that Azure AD B2C will execute for this custom policy. In the [RelyingParty](relyingparty.md) element, find the **DefaultUserJourney** element. Update the **DefaultUserJourney ReferenceId** to match the ID of the user journey in which you added the **ClaimsProviderSelections**.

- 1. The extension policy, for example, *TrustFrameworkExtensions.xml*.

- 1. The relying party policy, for example, *SignUpSignIn.xml*.

-For web applications (including .NET, PHP, Java, Ruby, Python, and Node.js) that are hosted on a server and accessed through a browser, Azure AD B2C supports [OpenID Connect](protocols-overview.md) for all user experiences. In the Azure AD B2C implementation of OpenID Connect, your web application initiates user experiences by issuing authentication requests to Azure AD. The result of the request is an `id_token`. This security token represents the user's identity. It also provides information about the user in the form of claims:

-In addition to facilitating simple sign in, a web server application might also need to access a back-end web service. In this case, the web application can perform a slightly different [OpenID Connect flow](openid-connect.md) and acquire tokens by using authorization codes and refresh tokens. This scenario is depicted in the following [Web APIs section](#web-apis).

- scopes: ["https://your-tenant-namee.onmicrosoft.com/tasks-api/tasks.read"],

- <img src="https://mucp.api.account.microsoft.com/m/v2/v?d=AIAACWEPFYXYIUTJIJVV4ST7XLBHVI5MLLYBKJAVXHBDTBHUM5VBSVVPTTVRWDFIXJ5JQTHYOH5TUYIPO4ZAFRFK52UAMIS3UNIPPI7ZJNDZPRXD5VEJBN4H6RO3SPTBS6AJEEAJOUYL4APQX5RJUJOWGPKUABY&amp;i=AIAACL23GD2PFRFEY5YVM2XQLM5YYWMHFDZOCDXUI2B4LM7ETZQO473CVF22PT6WPGR5IIE6TCS6VGEKO5OZIONJWCDMRKWQQVNP5VBYAINF3S7STKYOVDJ4JF2XEW4QQVNHMAPQNHFV3KMR3V3BA4I36B6BO7L4VQUHQOI64EOWPLMG5RB3SIMEDEHPILXTF73ZYD3JT6MYOLAZJG7PJJCAXCZCQOEFVH5VCW2KBQOKRYISWQLRWAT7IINZ3EFGQI2CY2EMK3FQOXM7UI3R7CZ6D73IKDI" width="1" height="1"></body>

- <img src="https://mucp.api.account.microsoft.com/m/v2/v?d=AIAACWEPFYXYIUTJIJVV4ST7XLBHVI5MLLYBKJAVXHBDTBHUM5VBSVVPTTVRWDFIXJ5JQTHYOH5TUYIPO4ZAFRFK52UAMIS3UNIPPI7ZJNDZPRXD5VEJBN4H6RO3SPTBS6AJEEAJOUYL4APQX5RJUJOWGPKUABY&amp;i=AIAACL23GD2PFRFEY5YVM2XQLM5YYWMHFDZOCDXUI2B4LM7ETZQO473CVF22PT6WPGR5IIE6TCS6VGEKO5OZIONJWCDMRKWQQVNP5VBYAINF3S7STKYOVDJ4JF2XEW4QQVNHMAPQNHFV3KMR3V3BA4I36B6BO7L4VQUHQOI64EOWPLMG5RB3SIMEDEHPILXTF73ZYD3JT6MYOLAZJG7PJJCAXCZCQOEFVH5VCW2KBQOKRYISWQLRWAT7IINZ3EFGQI2CY2EMK3FQOXM7UI3R7CZ6D73IKDI" width="1" height="1"></body>

-val extraQueryParameters: MutableList<Pair<String, String>> = ArrayList()

-extraQueryParameters.add(Pair("ui_locales", "en-us"))

-1. Make sure you're using the directory that contains your organizational Azure AD tenant (for example, Contoso). Select the **Directories + subscriptions** icon in the portal toolbar.

-1. On the **Portal settings | Directories + subscriptions** page, find your Azure AD directory in the **Directory name** list, and then select **Switch**.

-1. Under **Azure services**, select **App registrations** or search for and select **App registrations**.

-1. Select **New registration**.

-1. Sign in to the [Azure portal](https://portal.azure.com) using your organizational Azure AD tenant. Search for and select **Azure Active Directory**.

-1. From the **Manage** section, select **App registrations**.

-1. Select the application you want to configure optional claims for in the list.

-|displayName |String|The display name for the user. Max length 256.|Yes|Yes|Persisted, Output|

-When using a phone for multi-factor authentication (MFA), the mobile phone is used to verify the user identity. To [add](/graph/api/authentication-post-phonemethods) a new phone number programmatically, [update](/graph/api/b2cauthenticationmethodspolicy-update), [get](/graph/api/b2cauthenticationmethodspolicy-get), or [delete](/graph/api/phoneauthenticationmethod-delete) the phone number, use MS Graph API [phone authentication method](/graph/api/resources/phoneauthenticationmethod).

-|Endpoint|The endpoint is a URL or an [user portal](../manage-apps/end-user-experiences.md). Users can reach applications while outside of your network by accessing an external URL. Users within your network can access the application through a URL or an user portal. When users go to one of these endpoints, they authenticate in Azure AD and then are routed through the connector to the on-premises application.|

-# Azure Active Directory certificate-based authentication on Android

-For Azure Active Directory to revoke a client certificate, the ADFS token must have the following claims:

-Azure Active Directory adds these claims to the refresh token if they are available in the ADFS token (or any other SAML token). When the refresh token needs to be validated, this information is used to check the revocation.

-As a best practice, you should update your organization's ADFS error pages with the following information:

-Some Office apps (with modern authentication enabled) send '*prompt=login*' to Azure AD in their request. By default, Azure AD translates '*prompt=login*' in the request to ADFS as '*wauth=usernamepassworduri*' (asks ADFS to do U/P Auth) and '*wfresh=0*' (asks ADFS to ignore SSO state and do a fresh authentication). If you want to enable certificate-based authentication for these apps, you need to modify the default Azure AD behavior. Set the '*PromptLoginBehavior*' in your federated domain settings to '*Disabled*'.

-`Set-MSOLDomainFederationSettings -domainname <domain> -PromptLoginBehavior Disabled`

-# Azure Active Directory certificate-based authentication on iOS

-* An identity preference must be created in the macOS Keychain that include the authentication URL of the ADFS server. For more information, see [Create an identity preference in Keychain Access on Mac](https://support.apple.com/guide/keychain-access/create-an-identity-preference-kyca6343b6c9/mac).

-The following Active Directory Federation Services (ADFS) requirements and considerations apply:

-* The ADFS server must be enabled for certificate authentication and use federated authentication.

-## Configure ADFS

-For Azure AD to revoke a client certificate, the ADFS token must have the following claims. Azure AD adds these claims to the refresh token if they're available in the ADFS token (or any other SAML token). When the refresh token needs to be validated, this information is used to check the revocation:

-As a best practice, you also should update your organization's ADFS error pages with the following information:

-Some Office apps with modern authentication enabled send `prompt=login` to Azure AD in their request. By default, Azure AD translates `prompt=login` in the request to ADFS as `wauth=usernamepassworduri` (asks ADFS to do U/P Auth) and `wfresh=0` (asks ADFS to ignore SSO state and do a fresh authentication). If you want to enable certificate-based authentication for these apps, modify the default Azure AD behavior.

->[!NOTE]

->Azure AD certificate-based authentication is currently in public preview. Some features might not be supported or have limited capabilities. For more information about previews, see [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/).

-description: Learn about Azure Active Directory certificate-based authentication on mobile devices (Android and iOS)

-# Azure Active Directory certificate-based authentication on mobile devices (Android and iOS) (Preview)

-Android and iOS devices can use certificate-based authentication (CBA) to authenticate to Azure Active Directory using a client certificate on their device when connecting to:

-Azure AD certificate-based authentication (CBA) is supported for certificates on-device on native browsers as well as on Microsoft first-party applications on both iOS and Android devices.

-Azure AD CBA eliminates the need to enter a username and password combination into certain mail and Microsoft Office applications on your mobile device.

-## Prerequisites

-## Microsoft mobile applications support

-| Applications | Support |

-|:|::|

-|Azure Information Protection app| &#x2705; |

-|Company Portal | &#x2705; |

-|Microsoft Teams | &#x2705; |

-|Office (mobile) | &#x2705; |

-|OneNote | &#x2705; |

-|OneDrive | &#x2705; |

-|Outlook | &#x2705; |

-|Power BI | &#x2705; |

-|Skype for Business | &#x2705; |

-|Word / Excel / PowerPoint | &#x2705; |

-|Yammer | &#x2705; |

-## Support for Exchange ActiveSync clients

-On iOS 9 or later, the native iOS mail client is supported.

-Certain Exchange ActiveSync applications on Android 5.0 (Lollipop) or later are supported.

-To determine if your email application supports this feature, contact your application developer.

-## Known issue

-On iOS, users will see a double prompt, where they must click the option to use certificate-based authentication twice. We are working on making the user experience better.

-## Next steps

-description: Learn how to enable Windows SmartCard logon using Azure Active Directory certificate-based authentication

-# Windows SmartCard logon using Azure Active Directory certificate-based authentication (Preview)

-Azure AD users can authenticate using X.509 certificates on their SmartCards directly against Azure AD at Windows logon. There is no special configuration needed on the Windows client to accept the SmartCard authentication.

-Follow these steps to set up Windows SmartCard logon:

-1. Make sure the user is either on managed authentication or using staged rollout.

-1. Present the physical or virtual SmartCard to the test machine.

-1. Select SmartCard icon, enter the PIN and authenticate the user.

- :::image type="content" border="false" source="./media/concept-certificate-based-authentication/smartcard.png" alt-text="Screenshot of SmartCard sign in.":::

-Users will get a primary refresh token (PRT) from Azure Active Directory after the successful login and depending on the Certificate-based authentication configuration, the PRT will contain the multifactor claim.

-# Azure AD certificate-based authentication technical deep dive (Preview)

-This article explains how Azure Active Directory (Azure AD) certificate-based authentication (CBA) works, with background information and testing scenarios.

->[!NOTE]

->Azure AD certificate-based authentication is currently in public preview. Some features might not be supported or have limited capabilities. For more information about previews, see [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/).

-## How does Azure Active Directory certificate-based authentication work?

-This diagram shows what happens when a user tries to sign into an application secured by Azure AD CBA is enabled on the tenant:

-Let's cover each step:

-1. If the user is not already signed in, the user is redirected to the Azure AD **User Sign-in** page at [https://login.microsoftonline.com/](https://login.microsoftonline.com/).

-1. The user enters their username into the Azure AD sign-in page, and then clicks **Next**.

-1. Azure AD checks whether CBA is enabled for the tenant. If CBA is enabled for the tenant, the user sees a link to **Sign in with a certificate** on the password page. If you do not see the sign-in link, make sure CBA is enabled on the tenant. For more information, see [How do I enable Azure AD CBA?](certificate-based-authentication-faq.yml#how-do-i-enable-azure-ad-cba-).

- > If CBA is enabled on the tenant, all users will see the link to **Sign in with a certificate** on the password page. However, only the users in scope for CBA will be able to authenticate successfully against an application that uses Azure Active Directory as their Identity provider.

- :::image type="content" border="true" source="./media/concept-certificate-based-authentication-technical-deep-dive/sign-in-cert.png" alt-text="Screenshot of the Sign-in with a certificate.":::

- If you have enabled other authentication methods like **Phone sign-in** or **FIDO2**, users may see a different sign-in screen.

-1. After the user clicks the link, the client is redirected to the certauth endpoint, which is [https://certauth.login.microsoftonline.com](https://certauth.login.microsoftonline.com) for Azure Global. For [Azure Government](../../azure-government/compare-azure-government-global-azure.md#guidance-for-developers), the certauth endpoint is [https://certauth.login.microsoftonline.us](https://certauth.login.microsoftonline.us). For the correct endpoint for other environments, see the specific Microsoft cloud docs.

- The endpoint performs mutual authentication and requests the client certificate as part of the TLS handshake. You will see an entry for this request in the Sign-in logs. There is a [known issue](#known-issues) where User ID is displayed instead of Username.

- :::image type="content" border="true" source="./media/concept-certificate-based-authentication-technical-deep-dive/sign-in-log.png" alt-text="Screenshot of the Sign-in log in Azure AD." lightbox="./media/concept-certificate-based-authentication-technical-deep-dive/sign-in-log.png":::

- >The network administrator should allow access to certauth endpoint for the customerΓÇÖs cloud environment in addition to login.microsoftonline.com. Disable TLS inspection on the certauth endpoint to make sure the client certificate request succeeds as part of the TLS handshake.

- Click the log entry to bring up **Activity Details** and click **Authentication Details**. You will see an entry for X.509 certificate.

-1. Azure AD will request a client certificate and the user picks the client certificate and clicks **Ok**.

- >TrustedCA hints are not supported, so the list of certificates can't be further scoped.

-1. Azure AD verifies the certificate revocation list to make sure the certificate is not revoked and is valid. Azure AD identifies the user in the tenant by using the [username binding configured](how-to-certificate-based-authentication.md#step-4-configure-username-binding-policy) on the tenant by mapping the certificate field value to user attribute value.

-1. If a unique user is found and the user has a conditional access policy and needs multifactor authentication (MFA) and the [certificate authentication binding rule](how-to-certificate-based-authentication.md#step-3-configure-authentication-binding-policy) satisfies MFA, then Azure AD signs the user in immediately. If the certificate satisfies only a single factor, then it requests the user for a second factor to complete Azure AD Multi-Factor Authentication.

-The authentication binding policy helps determine the strength of authentication as either single-factor or multi-factor. An administrator can change the default value from single factor to multifactor or set up custom policy configurations either by issuer subject or policy OID fields in the certificate.

-Since multiple authentication binding policy rules can be created with different certificate fields, there are some rules that determine the authentication protection level. They are as follows:

-1. Exact match is used for strong authentication via policy OID. If you have a certificate A with policy OID **1.2.3.4.5** and a derived credential B based on that certificate has a policy OID **1.2.3.4.5.6** and the custom rule is defined as **Policy OID** with value **1.2.3.4.5** with MFA, only certificate A will satisfy MFA and credential B will satisfy only single-factor authentication. If the user used derived credential during sign-in and was configured to have MFA, the user will be asked for a second factor for successful authentication.

-1. Policy OID rules will take precedence over certificate issuer rules. If a certificate has both policy OID and Issuer, the policy OID is always checked first and if no policy rule is found then the issuer subject bindings are checked. Policy OID has a higher strong authentication binding priority than the issuer.

-1. If there is a conflict between multiple policy OIDs (such as when a certificate has two policy OIDs, where one binds to single-factor authentication and the other binds to MFA) then treat the certificate as a single-factor authentication.

-1. One certificate can only have one valid strong authentication binding (that is, a certificate cannot bind to both single-factor and MFA).

-The username binding policy helps locate the user in the tenant. By default, Subject Alternate Name (SAN) Principal Name in the certificate is mapped to onPremisesUserPrincipalName attribute of the user object to determine the user.

-An administrator can override the default and create a custom mapping. Currently, we support two certificate fields SAN Principal Name and SAN RFC822Name to map against the user object attribute userPrincipalName and onPremisesUserPrincipalName.

-**Rules applied for user bindings:**

-1. If the X.509 certificate field is on the presented certificate, try to look up the user by using the value in the specified field.

- 1. If a unique user is found, authenticate the user.

- 1. If a unique user is not found, authentication fails.

-1. If the X.509 certificate field is not on the presented certificate, move to the next priority binding.

-1. If the specified X.509 certificate field is found on the certificate, but Azure AD does not find a user object in the directory matching that value, the authentication fails. Azure AD does not attempt to use the next binding in the list in this case. Only if the X.509 certificate field is not on the certificate does it try the next binding, as mentioned in Step 2.

-The certificate revocation process allows the admin to revoke a previously issued certificate from being used for future authentication. The certificate revocation will not revoke already issued tokens of the user. Follow the steps to manually revoke tokens at [Configure revocation](active-directory-certificate-based-authentication-get-started.md#step-3-configure-revocation).

-An admin can configure the CRL distribution point during the setup process of the trusted issuers in the Azure AD tenant. Each trusted issuer should have a CRL that can be referenced via an internet-facing URL.

->The maximum size of a CRL for Azure Active Directory to successfully download and cache is 20MB in Azure Global and 45MB in Azure US Government clouds, and the time required to download the CRL must not exceed 10 seconds. If Azure Active Directory can't download a CRL, certificate-based authentications using certificates issued by the corresponding CA will fail. Best practices to ensure CRL files are within size constraints are to keep certificate lifetimes to within reasonable limits and to clean up expired certificates. For more information, see [Is there a limit for CRL size?](certificate-based-authentication-faq.yml#is-there-a-limit-for-crl-size-).

->If the admin skips the configuration of the CRL, Azure AD will not perform any CRL checks during the certificate-based authentication of the user. This can be helpful for initial troubleshooting but should not be considered for production use.

-**Typical flow of the CRL check:**

- - A CRL has been configured for the trusted issuer and Azure AD cannot download the CRL, due to availability, size, or latency constraints.

- :::image type="content" border="true" source="./media/concept-certificate-based-authentication-technical-deep-dive/user-cert.png" alt-text="Screenshot of the revoked user certificate in the CRL." :::

->Azure AD will only check the CRL of the issuing CA but not of the entire PKI trust chain up to the root CA. In case of a CA compromise, the administrator should remove the compromised trusted issuer from the Azure AD tenant configuration.

-There is no way for the administrator to manually force or re-trigger the download of the CRL.

-## Understanding Sign in logs

-**Test scenario configuration**

-1. Sign in to the Azure portal as the test user by using CBA. The authentication policy is set where Issuer subject rule satisfies single-factor authentication, but the user has MFA required by the conditional access policy, so a second authentication factor is requested.

- The first entry requests the X.509 certificate from the user. The status **Success** means that Azure AD validated that CBA is enabled in the tenant and a certificate is requested for authentication.

- The next entry provides more information about the authentication request and the certificate used. We can see that since the certificate satisfies only a single-factor and the user requires MFA, a second factor was requested.

- :::image type="content" border="true" source="./media/concept-certificate-based-authentication-technical-deep-dive/second-factor.png" alt-text="Screenshot of second-factor sign-in details in the sign-in logs." :::

- The **Authentication Details** also show the second factor request.

- :::image type="content" border="true" source="./media/concept-certificate-based-authentication-technical-deep-dive/sign-in-details-mfa.png" alt-text="Screenshot of multifactor sign-in details in the sign-in logs." :::

- These additional entries show that the authentication is complete and a primary refresh token is sent back to the browser and user is given access to the resource.

- Click **Additional Details** to MFA succeeded.

- :::image type="content" border="true" source="./media/concept-certificate-based-authentication-technical-deep-dive/refresh-token-details.png" alt-text="Screenshot of refresh token authentication details in the sign-in logs." :::

-1. Sign in to the Azure portal using CBA. since the policy was set to satisfy multifactor authentication, the user sign-in is successful without a second factor.

-1. Click **Azure Active Directory** > **Sign-in logs**, including and entry with **Interrupted** status.

- You will see several entries in the Sign-in logs.

-## Known issues

- :::image type="content" border="true" source="./media/concept-certificate-based-authentication-technical-deep-dive/known-issue.png" alt-text="Screenshot of username in the sign-in logs." :::

- When an iOS client sees a client TLS challenge and the user clicks **Sign in with certificate**, iOS client knows it cannot handle it and sends a completely new authorization request using the Safari browser. The user clicks **Sign in with certificate** again, at which point Safari which has access to certificates for authentication in device storage. This requires users to click **Sign in with certificate** twice, once in appΓÇÖs WKWebView and once in SafariΓÇÖs System WebView.

- We are aware of the UX experience issue and are working to fix this on iOS and to have a seamless UX experience.

-# Overview of Azure AD certificate-based authentication (Preview)

-Azure AD certificate-based authentication (CBA) enables customers to allow or require users to authenticate with X.509 certificates against their Azure Active Directory (Azure AD) for applications and browser sign-in.

-This feature enables customers to adopt a phishing resistant authentication and authenticate with an X.509 certificate against their Enterprise Public Key Infrastructure (PKI).

->[!NOTE]

->Azure AD certificate-based authentication is currently in public preview. Some features might not be supported or have limited capabilities. For more information about previews, see [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/).

-Before this feature brought cloud-managed support for CBA to Azure AD, customers had to implement federated certificate-based authentication. Federated CBA requires deploying Active Directory Federation Services (AD FS) to be able to authenticate using X.509 certificates against Azure AD. With Azure AD certificate-based authentication, customers can authenticate directly against Azure AD. Azure AD CBA eliminates the need for federated AD FS, which helps simplify customer environments and reduce costs.

-| Easy to deploy and administer |- No need for complex on-premises deployments or network configuration.<br>- Directly authenticate against Azure AD. <br>- No management overhead or cost. |

-| Secure |- On-premises passwords need not be stored in the cloud in any form.<br>- Protects your user accounts by working seamlessly with Azure AD Conditional Access policies, including multifactor authentication (MFA) and blocking legacy authentication.<br>- Strong authentication support where users can define authentication policies through the certificate fields like issuer or policy OID (object identifiers) to determine which certificates qualify as single-factor versus multifactor. |

-## Feature highlights

-# How to configure Azure AD certificate-based authentication (Preview)

-Azure Active Directory (Azure AD) certificate-based authentication (CBA) enables customers to configure their Azure AD tenants to allow or require users to authenticate with X.509 certificates verified against their Enterprise Public Key Infrastructure (PKI) for app and browser sign-in. This feature enables customers to adopt phishing resistant authentication by using an x.509 certificate.

-During sign-in, users will see an option to authenticate with a certificate instead of entering a password.

-If multiple matching certificates are present on the device, the user can pick which one to use. The certificate is validated, the binding to the user account is checked, and if successful, they are signed in.

-This topic covers how to configure and use certificate-based authentication for tenants in Office 365 Enterprise and US Government plans. You should already have a [public key infrastructure (PKI)](https://aka.ms/securingpki) configured.

-Follow these instructions to configure and use Azure AD CBA.

->[!NOTE]

->Azure AD certificate-based authentication is currently in public preview. Some features might not be supported or have limited capabilities. For more information about previews, see [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/).

-Make sure that the following prerequisites are in place.

->Each CA should have a certificate revocation list (CRL) that can be referenced from internet-facing URLs. If the trusted CA does not have a CRL configured, Azure AD will not perform any CRL checking, revocation of user certificates will not work, and authentication will not be blocked.

->[!IMPORTANT]

->Make sure the PKI is secure and cannot be easily compromised. In the event of a compromise, the attacker can create and sign client certificates and compromise any user in the tenant, both synced and cloud-only users. However, a strong key protection strategy, along with other physical and logical controls such as HSM activation cards or tokens for the secure storage of artifacts, can provide defense-in-depth to prevent external attackers or insider threats from compromising the integrity of the PKI. For more information, see [Securing PKI](/previous-versions/windows/it-pro/windows-server-2012-r2-and-2012/dn786443(v=ws.11)).

-There are some configuration steps to complete before enabling Azure AD CBA. First, an admin must configure the trusted CAs that issue user certificates. As seen in the following diagram, we use role-based access control to make sure only least-privileged administrators make changes. Configuring the certification authority is done only by the [Privileged Authentication Administrator](../roles/permissions-reference.md#privileged-authentication-administrator) role.

-Optionally, you can also configure authentication bindings to map certificates to single-factor or multifactor and configure username bindings to map certificate field to a user object attribute. Configuring user-related settings can be done by [Authentication Policy Administrators](../roles/permissions-reference.md#authentication-policy-administrator). Once all the configurations are complete, enable Azure AD CBA on the tenant.

-1. Select Azure Active Directory, then choose Security from the menu on the left-hand side.

- 1. Set the http internet-facing URL for the certification authority's base CRL that contains all revoked certificates. This should be set or authentication with revoked certificates will not fail.

-Only one CRL Distribution Point (CDP) for a trusted CA is supported. The CDP can only be HTTP URLs. Online Certificate Status Protocol (OCSP) or Lightweight Directory Access Protocol (LDAP) URLs are not supported.

-You can validate the crlDistributionPoint value you provide in the above PowerShell example are valid for the certification authority being added by downloading the CRL and comparing the CA certificate and the CRL Information.

-The below table and graphic indicate how to map information from the CA Certificate to the attributes of the downloaded CRL.

->The value for crlDistributionPoint in the above is the http location for the CAΓÇÖs Certificate Revocation List (CRL). This can be found in a few places.

->- In the CRL Distribution Point (CDP) attribute of a certificate issued from the CA

->If Issuing CA is Windows Server

- of the CA in the certification authority Microsoft Management Console (MMC)

->- On the CA running [certutil](/windows-server/administration/windows-commands/certutil#-cainfo) -cainfo cdp

-For additional details see: [Understanding the certificate revocation process](./concept-certificate-based-authentication-technical-deep-dive.md#understanding-the-certificate-revocation-process).

-To enable the certificate-based authentication in the Azure Portal, complete the following steps:

-To enable the certificate-based authentication and configure user bindings in the Azure portal, complete the following steps:

-The username binding policy helps determine the user in the tenant. By default, we map Principal Name in the certificate to onPremisesUserPrincipalName in the user object to determine the user.

-An admin can override the default and create a custom mapping. Currently, we support two certificate fields, SAN (Subject Alternate Name) Principal Name and SAN RFC822Name, to map against the user object attribute userPrincipalName and onPremisesUserPrincipalName.

->If a username binding policy uses synced attributes, such as onPremisesUserPrincipalName attribute of the user object, be aware that any user with administrative access to the Azure AD Connect server can change the sync attribute mapping, and in turn change the value of the synced attribute to their needs. The user does not need to be a cloud admin.

-1. Create the username binding by selecting one of the X.509 certificate fields to bind with one of the user attributes. The username binding order represents the priority level of the binding. The first one has the highest priority and so on.

- If the specified X.509 certificate field is found on the certificate, but Azure AD doesnΓÇÖt find a user object using that value, the authentication fails. Azure AD doesnΓÇÖt try the next binding in the list.

- The next priority is attempted only if the X.509 certificate field is not in the certificate.

-Currently supported set of username bindings:

->[!NOTE]

->If the RFC822Name binding is evaluated and if no RFC822Name is specified in the certificate Subject Alternative Name, we will fall back on legacy Subject Name "E=user@contoso.com" if no RFC822Name is specified in the certificate we will fall back on legacy Subject Name E=user@contoso.com.

- :::image type="content" border="true" source="./media/how-to-certificate-based-authentication/certificate.png" alt-text="Screenshot of sign in with certificate.":::

- If you have enabled other authentication methods like Phone sign-in or FIDO2, users may see a different sign-in screen.

- :::image type="content" border="true" source="./media/how-to-certificate-based-authentication/alternative.png" alt-text="Screenshot of the alternative sign in.":::

-Let's walk through a scenario where we will validate strong authentication by creating two authentication policy rules, one via issuer subject satisfying single factor and one via policy OID satisfying multi factor.

-1. Create an issuer Subject rule with protection level as single factor authentication and value set to your CAs Subject value. For example:

- `CN=ContosoCA,DC=Contoso,DC=org`

-1. Create a policy OID rule, with protection level as multi-factor authentication and value set to one of the policy OIDΓÇÖs in your certificate. For example, 1.2.3.4.

-1. Create a conditional access policy for the user to require multi-factor authentication by following steps at [Conditional Access - Require MFA](../conditional-access/howto-conditional-access-policy-all-users-mfa.md#create-a-conditional-access-policy).

- :::image type="content" border="true" source="./media/how-to-certificate-based-authentication/certificate.png" alt-text="Screenshot of sign in with certificate.":::

- If you have enabled other authentication methods like Phone sign-in or FIDO2, users may see a different sign-in screen.

- :::image type="content" border="true" source="./media/how-to-certificate-based-authentication/alternative.png" alt-text="Screenshot of the alternative sign in.":::

-1. The policy OID in the certificate matches the configured value of **1.2.3.4** and it will satisfy multifactor authentication. Similarly, the issuer in the certificate matches the configured value of **CN=ContosoCA,DC=Contoso,DC=org** and it will satisfy single-factor authentication.

-1. The conditional access policy for the user requires MFA and the certificate satisfies multifactor, so the user will be authenticated into the application.

-To enable the certificate-based authentication and configure username bindings using Graph API, complete the following steps.

- GET https://graph.microsoft.com/beta/policies/authenticationmethodspolicy

- GET https://graph.microsoft.com/beta/policies/authenticationmethodspolicy/authenticationMethodConfigurations/X509Certificate

- PATCH https: //graph.microsoft.com/beta/policies/authenticationMethodsPolicy/authenticationMethodConfigurations/x509Certificate

- "identifier": "CN=ContosoCA,DC=Contoso,DC=org ",

-1. You will get a `204 No content` response code. Re-run the GET request to make sure the policies are updated correctly.

-You can enable and disable application name and geographic location separately. Under featureSettings, you can use the following name mapping for each features:

-https://graph.microsoft.com/v1.0/authenticationMethodsPolicy/authenticationMethodConfigurations/MicrosoftAuthenticator

- "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#authenticationMethodConfigurations/$entity",

- "includeTargets@odata.context": "https://graph.microsoft.com/v1.0/$metadata#authenticationMethodsPolicy/authenticationMethodConfigurations('MicrosoftAuthenticator')/microsoft.graph.microsoftAuthenticatorAuthenticationMethodConfiguration/includeTargets",

- "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#authenticationMethodConfigurations/$entity",

- "includeTargets@odata.context": "https://graph.microsoft.com/v1.0/$metadata#authenticationMethodsPolicy/authenticationMethodConfigurations('MicrosoftAuthenticator')/microsoft.graph.microsoftAuthenticatorAuthenticationMethodConfiguration/includeTargets",

-GET https://graph.microsoft.com/v1.0/authenticationMethodsPolicy/authenticationMethodConfigurations/MicrosoftAuthenticator

- "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#authenticationMethodConfigurations/$entity",

- "includeTargets@odata.context": "https://graph.microsoft.com/v1.0/$metadata#authenticationMethodsPolicy/authenticationMethodConfigurations('MicrosoftAuthenticator')/microsoft.graph.microsoftAuthenticatorAuthenticationMethodConfiguration/includeTargets",

-In addition, for each of the features, you'll change the id of the excludeTarget to the ObjectID of the group from the Azure AD portal. This will exclude that group from seeing application name or geographic location.

- "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#authenticationMethodConfigurations/$entity",

- "includeTargets@odata.context": "https://graph.microsoft.com/v1.0/$metadata#authenticationMethodsPolicy/authenticationMethodConfigurations('MicrosoftAuthenticator')/microsoft.graph.microsoftAuthenticatorAuthenticationMethodConfiguration/includeTargets",

- "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#authenticationMethodConfigurations/$entity",

- "includeTargets@odata.context": "https://graph.microsoft.com/v1.0/$metadata#authenticationMethodsPolicy/authenticationMethodConfigurations('MicrosoftAuthenticator')/microsoft.graph.microsoftAuthenticatorAuthenticationMethodConfiguration/includeTargets",

- "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#authenticationMethodConfigurations/$entity",

- "includeTargets@odata.context": "https://graph.microsoft.com/v1.0/$metadata#authenticationMethodsPolicy/authenticationMethodConfigurations('MicrosoftAuthenticator')/microsoft.graph.microsoftAuthenticatorAuthenticationMethodConfiguration/includeTargets",

-Number matching isn't supported for Apple Watch notifications. Apple Watch users need to use their phone to approve notifications when number matching is enabled.

-https://graph.microsoft.com/v1.0/authenticationMethodsPolicy/authenticationMethodConfigurations/MicrosoftAuthenticator

-| excludeTarget | featureTarget | A single entity that is excluded from this feature. <br> Please note: You'll be able to only exclude one group for number matching. |

-| includeTarget | featureTarget | A single entity that is included in this feature. <br> Please note: You'll be able to only set one group for number matching.|

-Note that the value of Authentication Mode can be either **any** or **push**, depending on whether or not you also want to enable passwordless phone sign-in. In these examples, we will use **any**, but if you don't want to allow passwordless, use **push**.

- "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#authenticationMethodConfigurations/$entity",

- "includeTargets@odata.context": "https://graph.microsoft.com/v1.0/$metadata#authenticationMethodsPolicy/authenticationMethodConfigurations('MicrosoftAuthenticator')/microsoft.graph.microsoftAuthenticatorAuthenticationMethodConfiguration/includeTargets",

-To confirm this has applied, please run the GET request by using the following endpoint:

-GET https://graph.microsoft.com/v1.0/authenticationMethodsPolicy/authenticationMethodConfigurations/MicrosoftAuthenticator

- "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#authenticationMethodConfigurations/$entity",

- "includeTargets@odata.context": "https://graph.microsoft.com/v1.0/$metadata#authenticationMethodsPolicy/authenticationMethodConfigurations('MicrosoftAuthenticator')/microsoft.graph.microsoftAuthenticatorAuthenticationMethodConfiguration/includeTargets",

-GET https://graph.microsoft.com/v1.0/authenticationMethodsPolicy/authenticationMethodConfigurations/MicrosoftAuthenticator

- "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#authenticationMethodConfigurations/$entity",

- "includeTargets@odata.context": "https://graph.microsoft.com/v1.0/$metadata#authenticationMethodsPolicy/authenticationMethodConfigurations('MicrosoftAuthenticator')/microsoft.graph.microsoftAuthenticatorAuthenticationMethodConfiguration/includeTargets",

- "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#authenticationMethodConfigurations/$entity",

- "includeTargets@odata.context": "https://graph.microsoft.com/v1.0/$metadata#authenticationMethodsPolicy/authenticationMethodConfigurations('MicrosoftAuthenticator')/microsoft.graph.microsoftAuthenticatorAuthenticationMethodConfiguration/includeTargets",

-# Customer intent: As an identity administrator, I want to encourage users to use the Microsoft Authenticator app in Azure AD to improve and secure user sign-in events.

-**Will a user who has a the Authenticator app setup only for TOTP codes see the nudge?** 

-[Enable passwordless sign-in with Microsoft Authenticator](howto-authentication-passwordless-phone.md)

-description: Learn how to troubleshoot Azure AD certificate-based authentication in Azure Active Directory

-# Troubleshoot Azure AD certificate-based authentication (Preview)

-This topic covers how to troubleshoot Azure AD certificate-based authentication (CBA).

->[!NOTE]

->Azure AD certificate-based authentication is currently in public preview. Some features might not be supported or have limited capabilities. For more information about previews, see [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/).

-## Why don't I see an option to sign in using certificates against Azure Active Directory after I enter my username?

-An administrator needs to enable CBA for the tenant to make the sign-in with certificate option available for users. For more information, see [Step 3: Configure authentication binding policy](how-to-certificate-based-authentication.md#step-3-configure-authentication-binding-policy).

-## User-facing sign-in error messages

-If the user is unable to sign in using Certificate-based Authentication, they may see one of the following user-facing errors on the Azure AD sign-in screen.

-### ADSTS1001000 - Unable to acquire certificate policy from tenant

-This is a server-side error that occurs when the server could not fetch an authentication policy for the user using the SAN Principal Name/SAN RFC822Name field of the user certificate. Make sure that the authentication policy rules are correct, a valid certificate is used, and retry.

-### AADSTS1001003 ΓÇô User sign-in fails with "Unable To Acquire Value Specified In Binding From Certificate"

-This error is returned if the user selects the wrong user certificate from the list while signing in.

-Make sure the certificate is valid and works for the user binding and authentication policy configuration.

-### AADSTS50034 - User sign-in fails with "Your account or password is incorrect. If you don't remember your password, reset it now."

-Make sure the user is trying to sign in with the correct username. This error happens when a unique user can't be found using the [username binding](how-to-certificate-based-authentication.md#step-4-configure-username-binding-policy) on the certificate fields.

-For more information, see [Step 4: Configure username binding policy](how-to-certificate-based-authentication.md#step-4-configure-username-binding-policy).

-If the user is a federated user moving to Azure AD and if the user binding configuration is Principal Name > onPremisesUserPrincipalName:

->[!NOTE]

->There is a known issue that this scenario is not logged into the sign-in logs.

-### AADSTS130501 - User sign-in fails with "Sign in was blocked due to User Credential Policy"

-There is also a known issue when a user who is not in scope for CBA ties to sign in with a certificate to an [Office app](https://office.com) or any portal app, and the sign-in fails with an error:

-In both cases, the error can be resolved by making sure the user is in scope for Azure AD CBA. For more information, see [Step 2: Enable CBA on the tenant](how-to-certificate-based-authentication.md#step-2-enable-cba-on-the-tenant).

-### AADSTS90100: flowtoken parameter is empty or not valid

-After sign-in fails and I retry sign-in with the correct certificate, I get an error:

-This is a client behavior where the browser keeps using the original certificate selected. When the sign-in fails, close the existing browser session and retry sign-in from a new browser session.

-## User sign-in failed but not much diagnostic information

-There is a known issue when the authentication sometimes fails, the failure screen may not have an error message or troubleshooting information.

-For example, if a user certificate is revoked and is part of a Certificate Revocation List, then authentication fails correctly. However, instead of the error message, you might see the following screen:

-To get more diagnostic information, look in **Sign-in logs**. If a user authentication fails due to CRL validation for example, sign-in logs show the error information correctly.

-## Why didn't my changes to authentication policy changes take effect?

-The authentication policy is cached. After a policy update, it may take up to an hour for the changes to be effective. Try after an hour to make sure the policy caching is not the cause.

-## I get an error ΓÇÿCannot read properties of undefineΓÇÖ while trying to add a custom authentication rule

-This is a known issue, and we are working on graceful error handling. This error happens when there is no Certification Authority (CA) on the tenant. To resolve the error, see [Configure the certificate authorities](how-to-certificate-based-authentication.md#step-1-configure-the-certification-authorities).

-## I see a valid Certificate Revocation List (CRL) endpoint set, but why don't I see any CRL revocation?

-## Next steps

-**Learn about migrating to the the latest version of the Microsoft identity platform**

-During initial setup, the a few things are done that makes cloud sync happen. These are:

-This list is not all encompassing, if your app is not in this list please check with the application vendor to confirm support.

-Custom controls is a preview capability of Azure AD. When you use custom controls, your users are redirected to a compatible service to satisfy authentication requirements that are separate from Azure AD. For more information, check out the [Custom controls](controls.md) article.

- - All guest and external users

- - This selection includes any [B2B guests and external users](../external-identities/external-identities-overview.md) including any user with the `user type` attribute set to `guest`. This selection also applies to any external user signed-in from a different organization like a Cloud Solution Provider (CSP).

- - This selection includes any B2B guests and external users including any user with the `user type` attribute set to `guest`. This selection also applies to any external user signed-in from a different organization like a Cloud Solution Provider (CSP).

-Conditional Access policies that target external users may interfere with service provider access, for example granular delegated admin privileges [Introduction to granular delegated admin privileges (GDAP)](/partner-center/gdap-introduction).

-| `x5t` | Base64-encoded SHA-1 thumbprint of the X.509 certificate. For example, given an X.509 certificate hash of `84E05C1D98BCE3A5421D225B140B36E86A3D5534` (Hex), the `x5t` claim would be `hOBcHZi846VCHSJbFAs26Go9VTQ=` (Base64). |

-> The private key must be in PKCS#12 format since Azure AD does not support other format types. Using the wrong format can result in the the error "Invalid certificate: Key value is invalid certificate" when using Microsoft Graph to PATCH the service principal with a `keyCredentials` containing the certificate info.

-App roles and groups both store information about user assignments in the Azure AD directory. Another option for managing user role information that is available to developers is to maintain the information outside of the directory in a custom data store. For example, in a SQL Database, Azure Table storage or Azure Cosmos DB Table API.

-New-AzRoleAssignment -RoleDefinitionName Reader -ServicePrincipalName $sp.ApplicationId

-$ApplicationId = (Get-AzADApplication -DisplayNameStartWith exampleapp).ApplicationId

- New-AzRoleAssignment -RoleDefinitionName Reader -ServicePrincipalName $ServicePrincipal.ApplicationId | Write-Verbose -ErrorAction SilentlyContinue

-(Get-AzADApplication -DisplayNameStartWith {display-name}).ApplicationId

-This article shows you how to use the portal to create the service principal in the Azure portal. It focuses on a single-tenant application where the application is intended to run within only one organization. You typically use single-tenant applications for line-of-business applications that run within your organization. You can also [use Azure PowerShell to create a service principal](howto-authenticate-service-principal-powershell.md).

-* Learn how to [use Azure PowerShell to create a service principal](howto-authenticate-service-principal-powershell.md).

-In addition to identifying browsers that offer custom tabs support, our testing indicates that a few browsers that don't support custom tabs also work for authentication. These browsers include Opera, Opera Mini, InBrowser, and Maxthon.

-| Device | Browser | Result |

-If the user has no browser enabled on the device, MSAL.NET will throw an `AndroidActivityNotFound` exception.

-If authentication fails (for example, if authentication launches with DuckDuckGo), MSAL.NET will return `AuthenticationCanceled MsalClientException`.

- - **Root problem**: A browser that supports custom tabs wasn't enabled on the device. Authentication launched with a browser that couldn't complete authentication.

-For more information and code examples, see [Choosing between an embedded web browser and a system browser on Xamarin Android](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/wiki/MSAL.NET-uses-web-browser#choosing-between-embedded-web-browser-or-system-browser-on-xamarinandroid) and [Embedded versus system web UI](msal-net-web-browsers.md#embedded-vs-system-web-ui).

-Sample | Platform | Description

-## System browser experience on .NET

- .WithRedirectUri("http://localhost")

-var options = new SystemWebViewOptions()

-var options = new SystemWebViewOptions()

-You can also enable embedded webviews in Xamarin.iOS and Xamarin.Android apps. Starting with MSAL.NET 2.0.0-preview, MSAL.NET also supports using the **embedded** webview option.

-## Update the Android manifest for System WebView support

-To use the system browser and brokered authentication in Android 11, you must first declare these packages, so they are visible to the app. Apps that target Android 10 (API 29) and earlier can query the OS for a list of packages that are available on the device at any given time. To support privacy and security, Android 11 reduces package visibility to a default list of OS packages and the packages that are specified in the app's *AndroidManifest.xml* file.

-```

-Replace `{Package Name}` with the application package name.

- <uses-sdk android:minSdkVersion="21" android:targetSdkVersion="30" />

- <uses-permission android:name="android.permission.INTERNET" />

- <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

- <application android:theme="@android:style/Theme.NoTitleBar">

- <activity android:name="microsoft.identity.client.BrowserTabActivity" android:configChanges="orientation|screenSize">

- <intent-filter>

- <action android:name="android.intent.action.VIEW" />

- <category android:name="android.intent.category.DEFAULT" />

- <category android:name="android.intent.category.BROWSABLE" />

- <data android:scheme="msal4a1aa1d5-c567-49d0-ad0b-cd957a47f842" android:host="auth" />

- </intent-filter>

- <intent-filter>

- <action android:name="android.intent.action.VIEW" />

- <category android:name="android.intent.category.DEFAULT" />

- <category android:name="android.intent.category.BROWSABLE" />

- <data android:scheme="msauth" android:host="com.companyname.XamarinDev" android:path="/Fc4l/5I4mMvLnF+l+XopDuQ2gEM=" />

- </intent-filter>

- </activity>

- </application>

- <!-- Required for API Level 30 to make sure we can detect browsers and other apps we want to

- <!--https://developer.android.com/training/basics/intents/package-visibility-use-cases-->

- <queries>

- <package android:name="com.azure.authenticator" />

- <package android:name="com.companyname.xamarindev" />

- <package android:name="com.microsoft.windowsintune.companyportal" />

- <!-- Required for API Level 30 to make sure we can detect browsers

- <intent>

- <action android:name="android.intent.action.VIEW" />

- <category android:name="android.intent.category.BROWSABLE" />

- <data android:scheme="https" />

- </intent>

- <!-- Required for API Level 30 to make sure we can detect browsers that support custom tabs -->

- <!-- https://developers.google.com/web/updates/2020/07/custom-tabs-android-11#detecting_browsers_that_support_custom_tabs -->

- <intent>

- <action android:name="android.support.customtabs.action.CustomTabsService" />

- </intent>

- </queries>

-If you get an error message similar to "The application cannot access the iOS keychain for the application publisher (the TeamId is null)", this means MSAL is not able to access the KeyChain. This is a configuration issue. To troubleshoot, try to access the KeyChain on your own, for example:

-This code is extracted from the [MSAL Java dev samples](https://github.com/AzureAD/microsoft-authentication-library-for-java/blob/dev/src/samples/confidential-client/).

-This extract is from the [MSAL Java dev samples](https://github.com/AzureAD/microsoft-authentication-library-for-java/blob/dev/src/samples/public-client/).

-private static IAuthenticationResult acquireTokenDeviceCode() throws Exception {

- // Load token cache from file and initialize token cache aspect. The token cache will have

- // dummy data, so the acquireTokenSilently call will fail.

- TokenCacheAspect tokenCacheAspect = new TokenCacheAspect("sample_cache.json");

- PublicClientApplication pca = PublicClientApplication.builder(CLIENT_ID)

- .authority(AUTHORITY)

- .setTokenCacheAccessAspect(tokenCacheAspect)

- .build();

- Set<IAccount> accountsInCache = pca.getAccounts().join();

- // Take first account in the cache. In a production application, you would filter

- // accountsInCache to get the right account for the user authenticating.

- IAccount account = accountsInCache.iterator().next();

- IAuthenticationResult result;

- try {

- SilentParameters silentParameters =

- SilentParameters

- .builder(SCOPE, account)

- .build();

- // try to acquire token silently. This call will fail since the token cache

- // does not have any data for the user you are trying to acquire a token for

- result = pca.acquireTokenSilently(silentParameters).join();

- } catch (Exception ex) {

- if (ex.getCause() instanceof MsalException) {

- Consumer<DeviceCode> deviceCodeConsumer = (DeviceCode deviceCode) ->

- System.out.println(deviceCode.message());

- DeviceCodeFlowParameters parameters =

- DeviceCodeFlowParameters

- .builder(SCOPE, deviceCodeConsumer)

- // Try to acquire a token via device code flow. If successful, you should see

- // the token and account information printed out to console, and the sample_cache.json

- // file should have been updated with the latest tokens.

- result = pca.acquireToken(parameters).join();

- } else {

- // Handle other exceptions accordingly

- throw ex;

- return result;

-}

-This extract is from the [MSAL Java dev samples](https://github.com/AzureAD/microsoft-authentication-library-for-java/blob/dev/src/samples/public-client/).

-private static IAuthenticationResult acquireTokenIwa() throws Exception {

- // Load token cache from file and initialize token cache aspect. The token cache will have

- // dummy data, so the acquireTokenSilently call will fail.

- TokenCacheAspect tokenCacheAspect = new TokenCacheAspect("sample_cache.json");

- PublicClientApplication pca = PublicClientApplication.builder(CLIENT_ID)

- .authority(AUTHORITY)

- .setTokenCacheAccessAspect(tokenCacheAspect)

- .build();

- Set<IAccount> accountsInCache = pca.getAccounts().join();

- // Take first account in the cache. In a production application, you would filter

- // accountsInCache to get the right account for the user authenticating.

- IAccount account = accountsInCache.iterator().next();

- IAuthenticationResult result;

- try {

- SilentParameters silentParameters =

- SilentParameters

- .builder(SCOPE, account)

- .build();

- // try to acquire token silently. This call will fail since the token cache

- // does not have any data for the user you are trying to acquire a token for

- result = pca.acquireTokenSilently(silentParameters).join();

- } catch (Exception ex) {

- if (ex.getCause() instanceof MsalException) {

- IntegratedWindowsAuthenticationParameters parameters =

- IntegratedWindowsAuthenticationParameters

- .builder(SCOPE, USER_NAME)

- .build();

- // Try to acquire a IWA. You will need to generate a Kerberos ticket.

- // If successful, you should see the token and account information printed out to

- // console

- result = pca.acquireToken(parameters).join();

- } else {

- // Handle other exceptions accordingly

- throw ex;

- return result;

-}

-The following extract is from the [MSAL Java dev samples](https://github.com/AzureAD/microsoft-authentication-library-for-java/blob/dev/src/samples/public-client/).

-private static IAuthenticationResult acquireTokenUsernamePassword() throws Exception {

- // Load token cache from file and initialize token cache aspect. The token cache will have

- // dummy data, so the acquireTokenSilently call will fail.

- TokenCacheAspect tokenCacheAspect = new TokenCacheAspect("sample_cache.json");

- PublicClientApplication pca = PublicClientApplication.builder(CLIENT_ID)

- .authority(AUTHORITY)

- .setTokenCacheAccessAspect(tokenCacheAspect)

- .build();

- Set<IAccount> accountsInCache = pca.getAccounts().join();

- // Take first account in the cache. In a production application, you would filter

- // accountsInCache to get the right account for the user authenticating.

- IAccount account = accountsInCache.iterator().next();

- IAuthenticationResult result;

- try {

- SilentParameters silentParameters =

- SilentParameters

- .builder(SCOPE, account)

- .build();

- // try to acquire token silently. This call will fail since the token cache

- // does not have any data for the user you are trying to acquire a token for

- result = pca.acquireTokenSilently(silentParameters).join();

- } catch (Exception ex) {

- if (ex.getCause() instanceof MsalException) {

- UserNamePasswordParameters parameters =

- UserNamePasswordParameters

- .builder(SCOPE, USER_NAME, USER_PASSWORD.toCharArray())

- // Try to acquire a token via username/password. If successful, you should see

- // the token and account information printed out to console

- result = pca.acquireToken(parameters).join();

- } else {

- // Handle other exceptions accordingly

- throw ex;

- return result;

-}

-Here's the class used in MSAL Java development samples to configure the samples: [TestData](https://github.com/AzureAD/microsoft-authentication-library-for-java/blob/dev/src/samples/public-client/).

-[Quickstart: ASP.NET Core web app that signs in users](quickstart-v2-aspnet-core-webapp.md)

-[Quickstart: ASP.NET web app that signs in users](quickstart-v2-aspnet-webapp.md)

-[Quickstart: Add sign-in with Microsoft to a Java web app](quickstart-v2-java-webapp.md)

-[Quickstart: Add sign-in with Microsoft to a Node.js web app](quickstart-v2-nodejs-webapp-msal.md)

-[Quickstart: Add sign-in with Microsoft to a Python web app](quickstart-v2-python-webapp.md)

-> [!NOTE]

-> Adding sign-in to a web app is about protecting the web app and validating a user token, which is what **middleware** libraries do. In the case of .NET, this scenario does not yet require the Microsoft Authentication Library (MSAL), which is about acquiring a token to call protected APIs. Authentication libraries for .NET will be introduced in the follow-up scenario, when the web app needs to call web APIs.

-> [!IMPORTANT]

-> This capability is now generally available. The previous version that made use of device code flow was [deprecated on August 15, 2021](/azure-docs-archive-pr/virtual-machines/linux/login-using-aad). To migrate from the old version to this version, see the section [Migrate from the previous (preview) version](#migrate-from-the-previous-preview-version).

-You can also assign the scope at a resource group or subscription level. Normal Azure RBAC inheritance permissions apply. For more information, see [Log in to a Linux virtual machine in Azure by using Azure Active Directory authentication](/azure-docs-archive-pr/virtual-machines/linux/login-using-aad).

-description: Explains how to prepare an Azure AD tenant for deletion, including self-service tenants

-When an organization (tenant) is deleted in Azure Active Directory (Azure AD), part of Microsoft Entra, all resources that are contained in the organization are also deleted. Prepare your organization by minimizing its associated resources before you delete. Only a global administrator in Azure AD can delete an Azure AD organization from the portal.

-You can't delete an organization in Azure AD until it passes several checks. These checks reduce risk that deleting an Azure AD organization negatively impacts user access, such as the ability to sign in to Microsoft 365 or access resources in Azure. For example, if the organization associated with a subscription is unintentionally deleted, then users can't access the Azure resources for that subscription. The following conditions should be checked:

-* You must have paid all outstanding invoices and amounts due or overdue.

-* There can be no users in the Azure AD tenant except one global administrator who is to delete the organization. Any other users must be deleted before the organization can be deleted. If users are synchronized from on-premises, then sync must first be turned off, and the users must be deleted in the cloud organization using the Azure portal or Azure PowerShell cmdlets.

-* There can be no applications in the organization. Any applications must be removed before the organization can be deleted.

-* There can be no multifactor authentication providers linked to the organization.

-* There can be no subscriptions for any Microsoft Online Services such as Microsoft Azure, Microsoft 365, or Azure AD Premium associated with the organization. For example, if a default Azure AD tenant was created for you in Azure, you can't delete this organization if your Azure subscription still relies on it for authentication. You also can't delete a tenant if another user has associated an Azure subscription with it.

-> Microsoft is aware that customers with certain tenant configurations may be unable to successfully delete their Azure AD organization. We are working to address this problem. In the meantime, if needed, you can contact Microsoft support for details about the issue.

-1. Sign in to the [Azure AD admin center](https://aad.portal.azure.com) with an account that is the Global Administrator for your organization.

-1. On a tenant Overview page, select **Manage tenants**.

- 

-1. Select the check box for the tenant you want to delete, and select **Delete**.

- 

-1. If your organization doesn't pass one or more checks, you're provided with a link to more information on how to pass. After you pass all checks, select **Delete** to complete the process.

-## If you can't delete the organization

-When you configured your Azure AD organization, you may have also activated license-based subscriptions for your organization like Azure AD Premium P2, Microsoft 365 Business Standard, or Enterprise Mobility + Security E5. To avoid accidental data loss, you can't delete an organization until the subscriptions are fully deleted. The subscriptions must be in a **Deprovisioned** state to allow organization deletion. An **Expired** or **Canceled** subscription moves to the **Disabled** state, and the final stage is the **Deprovisioned** state.

-Active (30 days for trial) | Data accessible to all | Users have normal access to Microsoft 365 files, or apps<br>Admins have normal access to Microsoft 365 admin center and resources

-Expired (30 days) | Data accessible to all| Users have normal access to Microsoft 365 files, or apps<br>Admins have normal access to Microsoft 365 admin center and resources

-Disabled (30 days) | Data accessible to admin only | Users canΓÇÖt access Microsoft 365 files, or apps<br>Admins can access the Microsoft 365 admin center but canΓÇÖt assign licenses to or update users

-Deprovisioned (30 days after Disabled) | Data deleted (automatically deleted if no other services are in use) | Users canΓÇÖt access Microsoft 365 files, or apps<br>Admins can access the Microsoft 365 admin center to purchase and manage other subscriptions

-## Delete a Office/Microsoft 365 subscription

-You can put a subscription into the **Deprovisioned** state to be deleted in three days using the Microsoft 365 admin center.

-1. Sign in to the [Microsoft 365 admin center](https://admin.microsoft.com) with an account that is a global administrator in your organization. If you are trying to delete the ΓÇ£ContosoΓÇ¥ organization that has the initial default domain contoso.onmicrosoft.com, sign in with a UPN such as admin@contoso.onmicrosoft.com.

-1. Preview the new Microsoft 365 admin center by making sure the **Try the new admin center** toggle is enabled.

- 

-1. Once the new admin center is enabled, you need to cancel a subscription before you can delete it. Select **Billing** and select **Your products**, then select **Cancel subscription** for the subscription you want to cancel. You'll be brought to a feedback page.

- 

-1. Complete the feedback form and select **Cancel subscription** to cancel the subscription.

- 

-1. You can now delete the subscription. Select **Delete** for the subscription you want to delete. If you can't find the subscription in the **Products & services** page, make sure you have **Subscription status** set to **All**.

- 

-1. Select **Delete subscription** to delete the subscription and accept the terms and conditions. All data is permanently deleted within three days. You can [reactivate the subscription](/office365/admin/subscriptions-and-billing/reactivate-your-subscription) during the three-day period if you change your mind.

- 

-1. Now the subscription state has changed, and the subscription is marked for deletion. The subscription enters the **Deprovisioned** state 72 hours later.

-1. Once you've deleted a subscription in your organization and 72 hours have elapsed, you can sign back into the Azure AD admin center again and there should be no required action and no subscriptions blocking your organization deletion. You should be able to successfully delete your Azure AD organization.

- 

-If you have an Active or canceled Azure subscription associated to your Azure AD Tenant then you wouldn't be able to delete Azure AD Tenant. After you cancel, billing is stopped immediately. However, Microsoft waits 30 - 90 days before permanently deleting your data in case you need to access it or you change your mind. We don't charge you for keeping the data.

-Once you have all the Azure and Office/Microsoft 365 Subscriptions canceled and deleted, you can proceed with cleaning up rest of the things within Azure AD Tenant before actually delete it.

-## Enterprise apps with no way to delete

-Currently, there are few enterprise applications that can't be deleted in the Azure portal. If you find that you are unable to successfully delete an Azure AD tenant from the portal, you can use the following PowerShell commands to remove any blocking enterprise applications.

-Follow below instructions to remove blocking enterprise apps/service principals before you attempt to delete the tenant:

-1. Install MSOnline module for PowerShell by running the following command:

- 'Install-Module -Name MSOnline'

-2. Install Az PowerShell module by running the following command:

- 'Install-Module -Name Az'

-3. Create or use a managed admin account from the tenant you would like to delete, for example, newAdmin@tenanttodelete.onmicrosoft.com

-4. Open PowerShell and connect to MSODS using the admin credentials, with command

- 'connect-msolservice'

- > You must run PowerShell using admin credentials for the tenant that you are trying to delete. Only homed-in admins have access to manage the directory via Powershell.You can't use guest user admins, live-ids or multi-directories. Before you proceed, to verify you are connected to the tenant you intend to delete with MSOnline module. It is recommended you run the command `Get-MsolDomain` to confirm that you are connected to the correct tenantID and onmicrosoft.com domain.

-5. Run below command to set the tenant context

- 'Connect-AzAccount -Tenant \<object id of the tenant you are attempting to delete\>'

- > Before proceeding, to verify you are connected to the tenant you intend to delete with Az module, it is recommended you run the command Get-AzContext to check the connected tenant ID and onmicrosoft.com domain.

-6. Run below command to remove any enterprise apps with no way to delete:

- 'Get-AzADServicePrincipal | ForEach-Object { Remove-AzADServicePrincipal -ObjectId $_.Id }'

-7. Run below command to remove application/service principals

- 'Get-MsolServicePrincipal | Remove-MsolServicePrincipal'

-8. Lastly, run the command to disable any blocking service principals:

- 'Get-MsolServicePrincipal | Set-MsolServicePrincipal -AccountEnabled $false'

-9. Sign back into the Azure portal and remove any new admin account created in step 3.

-10. Retry tenant deletion from the Azure portal again.

-## Trial subscription that blocks deletion

-There are [self-service sign-up products](/office365/admin/misc/self-service-sign-up) like Microsoft Power BI, Rights Management Services, Microsoft Power Apps, or Dynamics 365, individual users can sign up via Microsoft 365, which also creates a guest user for authentication in your Azure AD organization. These self-service products block directory deletions until the products are fully deleted from the organization, to avoid data loss. They can be deleted only by the Azure AD admin whether the user signed up individually or was assigned the product.

-There are two types of self-service sign-up products in how they are assigned:

-* Org-level assignment: An Azure AD admin assigns the product to the entire organization and a user can be actively using the service with this org-level assignment even if they aren't licensed individually.

-* User level assignment: An individual user during self-service sign-up essentially assigns the product to themselves without an admin. Once the organization becomes managed by an admin (see [Administrator takeover of an unmanaged organization](domains-admin-takeover.md), then the admin can directly assign the product to users without self-service sign-up.

-When you begin the deletion of the self-service sign-up product, the action permanently deletes the data and removes all user access to the service. Any user that was assigned the offer individually or on the organization level is then blocked from signing in or accessing any existing data. If you want to prevent data loss with the self-service sign-up product like [Microsoft Power BI dashboards](/power-bi/service-export-to-pbix) or [Rights Management Services policy configuration](/azure/information-protection/configure-policy#how-to-configure-the-azure-information-protection-policy), ensure that the data is backed up and saved elsewhere.

-For what to expect when a trial Microsoft 365 subscription expires (not including paid Partner/CSP, Enterprise Agreement, or Volume Licensing), see the following table. For more information on Microsoft 365 data retention and subscription lifecycle, see [What happens to my data and access when my Microsoft 365 for business subscription ends?](/office365/admin/subscriptions-and-billing/what-if-my-subscription-expires).

-Active (30 days for trial) | Data accessible to all | Users have normal access to self-service sign up product, files, or apps<br>Admins have normal access to Microsoft 365 admin center and resources

-Deleted | Data deleted | Users canΓÇÖt access self-service sign-up product, files, or apps<br>Admins can access the Microsoft 365 admin center to purchase and manage other subscriptions

-You can put a self-service sign-up product like Microsoft Power BI or Azure Rights Management Services into a **Delete** state to be immediately deleted in the Azure AD portal.

-1. Sign in to the [Azure AD admin center](https://aad.portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/Overview) with an account that is a Global administrator in the organization. If you are trying to delete the ΓÇ£ContosoΓÇ¥ organization that has the initial default domain contoso.onmicrosoft.com, sign on with a UPN such as admin@contoso.onmicrosoft.com.

-1. Select **Licenses**, and then select **Self-service sign-up products**. You can see all the self-service sign-up products separately from the seat-based subscriptions. Choose the product you want to permanently delete. Here's an example in Microsoft Power BI:

- 

-1. Select **Delete** to delete the product and accept the terms that data is deleted immediately and irrevocably. This delete action will remove all users and remove organization access to the product. Select Yes to move forward with the deletion.

- 

-1. When you select **Yes**, the deletion of the self-service product will be initiated. There is a notification that will tell you of the deletion in progress.

- 

-1. Now the self-service sign-up product state has changed to **Deleted**. When you refresh the page, the product should be removed from the **Self-service sign-up products** page.

- 

-1. Once you have deleted all the products, you can sign back into the Azure AD admin center again, and there should be no required action and no products blocking your organization deletion. You should be able to successfully delete your Azure AD organization.

- 

-* Assign licenses to groups instead of to individual users.

-* Delegate permissions to distribute the work of Azure AD management to less-privileged roles.

-You can use groups in Azure AD to assign licenses to large numbers of users, or to assign user access to deployed enterprise apps. You can use groups to assign all administrator roles except for Global Administrator in Azure AD, or you can grant access to resources that are external, such as SaaS applications or SharePoint sites.

-For additional flexibility and to reduce group membership management work, you can use [dynamic groups](groups-create-rule.md) in Azure AD to expand and contract group membership automatically. You'll need an Azure AD Premium P1 license for each unique user that is a member of one or more dynamic groups.

-Assigning or removing licenses from users individually can demand time and attention. If you [assign licenses to groups](../fundamentals/license-users-groups.md?context=azure%2factive-directory%2fusers-groups-roles%2fcontext%2fugr-context) instead, you can make your large-scale license management easier.

-If there aren't enough licenses available, or an issue occurs like service plans that can't be assigned at the same time, you can see status of any licensing issue for the group in the Azure portal.

-You can use Azure AD to assign group access to the [enterprise apps that are deployed in your Azure AD organization](../manage-apps/assign-user-or-group-access-portal.md?context=azure%2factive-directory%2fusers-groups-roles%2fcontext%2fugr-context). If you combine dynamic groups with group assignment to apps, you can automate your user app access assignments as your organization grows. You'll need an Azure Active Directory Premium P1 or Premium P2 license to assign access to enterprise apps.

-| onPremisesDistinguishedName (preview)| Any string value or *null* | user.onPremisesDistinguishedName -eq "value" |

-3. At the top of the users list, select **+**.

-

- 

-Organizations can enforce Conditional Access policies for external B2B collaboration and B2B direct connect users in the same way that theyΓÇÖre enabled for full-time employees and members of the organization. With the introduction of cross-tenant access settings, you can also trust MFA and device claims from external Azure AD organizations. This section describes important considerations for applying Conditional Access to users outside of your organization.

-# Azure Active Directory (Azure AD) identity provider for External Identities

-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.

- >If you intend to trust inbound MFA for external users, make sure you don't have an [Identity Protection policy](../identity-protection/howto-identity-protection-configure-mfa-policy.md) in place that requires external users to register for MFA. When both of these policies are present, external users wonΓÇÖt be able to satisfy the requirements for access. If you want to enforce the Identity Protection MFA registration policy, be sure to exclude external users.

-# Microsoft account (MSA) identity provider for External Identities

-Microsoft accounts are set up by a user to get access to consumer-oriented Microsoft products and cloud services, such as Outlook, OneDrive, Xbox LIVE, or Microsoft 365. The account is created and stored in the Microsoft consumer identity account system that's run by Microsoft.

-Microsoft account 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 Microsoft account using either the invitation flow or a self-service sign-up user flow.

-

-

-Microsoft account is an identity provider option for your self-service sign-up user flows. Users can sign up for your applications using their own Microsoft accounts. First, you'll need to [enable self-service sign-up](self-service-sign-up-user-flow.md) for your tenant. Then you can set up a user flow for the application and select Microsoft account as one of the sign-in options.

-

-As of November 2020, new application registrations show up as unverified in the user consent prompt unless [the application's publisher domain is verified](../develop/howto-configure-publisher-domain.md) ***and*** the companyΓÇÖs identity has been verified with the Microsoft Partner Network and associated with the application. ([Learn more](../develop/publisher-verification-overview.md) about this change.) Note that for Azure AD user flows, the publisherΓÇÖs domain appears only when using a Microsoft account or other [Azure AD tenant](azure-ad-account.md) as the identity provider. To meet these new requirements, do the following:

-5. On the **Create** page, enter a **Name** for the user flow. Note that the name is automatically prefixed with **B2X_1_**.

-6. In the **Identity providers** list, select one or more identity providers that your external users can use to log into your application. **Azure Active Directory Sign up** is selected by default. (See [Before you begin](#before-you-begin) earlier in this article to learn how to add identity providers.)

-7. Under **User attributes**, choose the attributes you want to collect from the user. For additional attributes, select **Show more**. For example, select **Show more**, and then choose attributes and claims for **Country/Region**, **Display Name**, and **Postal Code**. Select **OK**.

-Now you can associate applications with the user flow.

-| Who can be added by default?| Internal users (tenant members)| Tenant members and guests from any organization |

-Not all Microsoft services are available in all locations. Before a license can be assigned to a group, you must specify the **Usage location** for all members. You can set this value in the **Azure Active Directory &gt; Users &gt; Profile &gt; Settings** area in Azure AD. Any user whose usage location isn't specified inherits the location of the Azure AD organization.

- > Not all Microsoft services are available in all locations. Before a license can be assigned to a user, you must specify the **Usage location**. You can set this value in the **Azure Active Directory &gt; Users &gt; Profile &gt; Settings** area in Azure AD. Any user whose usage location is not specified inherits the location of the Azure AD organization.

-* **Individual resources** - You can assign roles to specific resources so that they don't impact any other resources. In the example above, the Benefits engineering team can assign a data analyst the Cosmos DB Account Reader role just for the test instance of the Cosmos DB, without interfering with the test web app, or any production resource.

-Azure has a control plane and a data plane. In the control plane, you create resources, and in the data plane you access them. For example, you create a Cosmos database in the control plane, but query it in the data plane.

-`https://graph.microsoft.com/v1.0/servicePrincipals?$filter=(servicePrincipalType eq 'ManagedIdentity') `

- ` Get-AzureADServicePrincipal | % { Get-AzureADServiceAppRoleAssignment -ObjectId $_ }`

-* Ensure the managed identity is not part of any privileged groups, such as an administrators group.

-ΓÇÄYou can do this by enumerating the members of your highly privileged groups with PowerShell.

-

-

-| **Restrict access to Azure AD administration portal** | **What does this switch do?** <br>**No** lets non-administrators browse the Azure AD administration portal. <br>**Yes** Restricts non-administrators from browsing the Azure AD administration portal. Non-administrators who are owners of groups or applications are unable to use the Azure portal to manage their owned resources. </p><p></p><p>**What does it not do?** <br> It does not restrict access to Azure AD data using PowerShell, Microsoft GraphAPI, or other clients such as Visual Studio. <br>It does not restrict access as long as a user is assigned a custom role (or any role). <br>It does not restrict access to Entra Portal. </p><p></p><p>**When should I use this switch?** <br>Use this to prevent users from misconfiguring the resources that they own. </p><p></p><p>**When should I not use this switch?** <br>Do not use this switch as a security measure. Instead, create a Conditional Access policy that targets Microsoft Azure Management will block non-administrators access to [Microsoft Azure Management](../conditional-access/concept-conditional-access-cloud-apps.md#microsoft-azure-management). </p><p></p><p> **How do I grant only a specific non-administrator users the ability to use the Azure AD administration portal?** <br> Set this option to **Yes**, then assign them a role like global reader. </p><p></p><p>**Restrict access to the Entra administration portal** <br>A Conditional Access policy that targets Microsoft Azure Management will target access to all Azure management. |

-Specialized clouds, such as Azure Germany, and Azure China 21Vianet, aren't currently available for use.

- - Source attribute: msDS-cloudExtensionAttribute1

- 1. Open a PowerShell window as administrator and run `Set-ADSyncScheduler -SyncCycleEnabled $false`.

-|Days from event | 0 | ✔️ |

- "mail": "mpricne@<your tenant name here>",

- "employeeHireDate": "2022-04-15T22:10:00Z"

- "employeeHireDate": "2021-01-15T22:10:00Z"

-Although this release has undergone extensive testing, you might still encounter issues. One of the goals of this public preview release is to find and fix any issues before the feature moves to general availability.

-Microsoft provides support for this public preview release, but it might not be able to immediately fix issues that you encounter. For this reason, we recommend that you use your best judgment before deploying this release in your production environment.ΓÇ»

-Azure AD Connect Health for AD FS supports AD FS 2.0 on Windows Server 2008 R2, Windows Server 2012, Windows Server 2012 R2 and Windows Server 2016. It also supports monitoring the AD FS proxy or web application proxy servers that provide authentication support for extranet access. With an easy and quick installation of the Health Agent, Azure AD Connect Health for AD FS provides you a set of key capabilities.

-# [The Azure portal](#tab/azure-portal)

-# [PowerShell](#tab/azure-powershell)

-#### Connect to Microsoft Graph PowerShell

-#### Disable user consent

-#### Allow user consent subject to an app consent policy

-> * Create a Cosmos DB account

-> * Create a collection in the Cosmos DB account

-> * Get access keys from Azure Resource Manager to make Cosmos DB calls

-## Create a Cosmos DB account

-If you don't already have one, create a Cosmos DB account. You can skip this step and use an existing Cosmos DB account.

-3. Enter an **ID** for the Cosmos DB account, which you use later.

-5. Ensure the **Subscription** and **Resource Group** match the ones you specified when you created your VM in the previous step. Select a **Location** where Cosmos DB is available.

-### Create a collection in the Cosmos DB account

-Next, add a data collection in the Cosmos DB account that you can query in later steps.

-1. Navigate to your newly created Cosmos DB account.

-To gain access to the Cosmos DB account access keys from the Resource Manager in the following section, you need to retrieve the `principalID` of the Linux VM's system-assigned managed identity. Be sure to replace the `<SUBSCRIPTION ID>`, `<RESOURCE GROUP>` (resource group in which your VM resides), and `<VM NAME>` parameter values with your own values.

-### Grant your Linux VM's system-assigned identity access to the Cosmos DB account access keys

-Cosmos DB does not natively support Azure AD authentication. However, you can use a managed identity to retrieve a Cosmos DB access key from the Resource Manager, then use the key to access Cosmos DB. In this step, you grant your system-assigned managed identity access to the keys to the Cosmos DB account.

-To grant the system-assigned managed identity access to the Cosmos DB account in Azure Resource Manager using the Azure CLI, update the values for `<SUBSCRIPTION ID>`, `<RESOURCE GROUP>`, and `<COSMOS DB ACCOUNT NAME>` for your environment. Replace `<MI PRINCIPALID>` with the `principalId` property returned by the `az resource show` command in Retrieve the principalID of the Linux VM's MI. Cosmos DB supports two levels of granularity when using access keys: read/write access to the account, and read-only access to the account. Assign the `DocumentDB Account Contributor` role if you want to get read/write keys for the account, or assign the `Cosmos DB Account Reader Role` role if you want to get read-only keys for the account:

-### Get access keys from Azure Resource Manager to make Cosmos DB calls

-Now use CURL to call Resource Manager using the access token retrieved in the previous section to retrieve the Cosmos DB account access key. Once we have the access key, we can query Cosmos DB. Be sure to replace the `<SUBSCRIPTION ID>`, `<RESOURCE GROUP>`, and `<COSMOS DB ACCOUNT NAME>` parameter values with your own values. Replace the `<ACCESS TOKEN>` value with the access token you retrieved earlier. If you want to retrieve read/write keys, use key operation type `listKeys`. If you want to retrieve read-only keys, use the key operation type `readonlykeys`:

-Now that you have the access key for the Cosmos DB account you can pass it to a Cosmos DB SDK and make calls to access the account.

-In this tutorial, you learned how to use a system-assigned managed identity on a Linux virtual machine to access Cosmos DB. To learn more about Cosmos DB see:

-#Customer intent: As an administrator, I want to know how to access Cosmos DB from a virtual machine using a managed identity

-# How to use managed identities to connect to Cosmos DB from an Azure virtual machine

-In this article, we set up a virtual machine to use managed identities to connect to Cosmos. [Azure Cosmos DB](../../cosmos-db/introduction.md) is a fully managed NoSQL database for modern app development. [Managed identities for Azure resources](overview.md) allow your applications to authenticate when accessing services that support Azure AD authentication using an identity managed by Azure.

-## Create a Cosmos DB account

-Now that we have a VM with either a user-assigned managed identity or a system-assigned managed identity we need a Cosmos DB account available where you have administrative rights. If you need to create a Cosmos DB account for this tutorial, the [Cosmos DB quickstart](../..//cosmos-db/sql/create-cosmosdb-resources-portal.md) provides detailed steps on how to do that.

-> Managed identities may be used to access any Azure resource that supports Azure Active Directory authentication. This tutorial assumes that your Cosmos DB account will be configured as shown below.

- |Subscription|Subscription name|Select the Azure subscription that you want to use for this Azure Cosmos account. |

- |Account Name|A unique name|Enter a name to identify your Azure Cosmos account. Because *documents.azure.com* is appended to the name that you provide to create your URI, use a unique name.<br><br>The name can only contain lowercase letters, numbers, and the hyphen (-) character. It must be between 3-44 characters in length.|

- |API|The type of account to create|Select **Core (SQL)** to create a document database and query by using SQL syntax. <br><br>[Learn more about the SQL API](../../cosmos-db/introduction.md).|

- > If you are testing you may want to apply Azure Cosmos DB free tier discount. With Azure Cosmos DB free tier, you will get the first 1000 RU/s and 25 GB of storage for free in an account. Learn more about [free tier](https://azure.microsoft.com/pricing/details/cosmos-db/). Keep in mind that for the purpose of this tutorial this choice makes no difference.

-At this point, we should have both a virtual machine configured with a managed identity and a Cosmos DB Account. Before we continue, we need to grant the managed identity a couple of different roles.

-Getting access to Cosmos using managed identities may be achieved using the Azure.identity library to enable authentication in your application. You can call [ManagedIdentityCredential](/dotnet/api/azure.identity.managedidentitycredential) directly or use [DefaultAzureCredential](/dotnet/api/azure.identity.defaultazurecredential).

-Initialize your Cosmos DB client:

-Initialize your Cosmos DB client:

-Initialize your Cosmos DB client:

-Learn more about Azure Cosmos

-This tutorial shows you how to use a system-assigned managed identity for a Windows virtual machine (VM) to access Cosmos DB. You learn how to:

-> * Create a Cosmos DB account

-> * Grant a Windows VM system-assigned managed identity access to the Cosmos DB account access keys

-> * Get access keys from Azure Resource Manager to make Cosmos DB calls

-## Create a Cosmos DB account

-If you don't already have one, create a Cosmos DB account. You can skip this step and use an existing Cosmos DB account.

-3. Enter an **ID** for the Cosmos DB account, which you use later.

-5. Ensure the **Subscription** and **Resource Group** match the ones you specified when you created your VM in the previous step. Select a **Location** where Cosmos DB is available.

-Next, add a data collection in the Cosmos DB account that you can query in later steps.

-1. Navigate to your newly created Cosmos DB account.

-This section shows how to grant Windows VM system-assigned managed identity access to the Cosmos DB account access keys. Cosmos DB does not natively support Azure AD authentication. However, you can use a system-assigned managed identity to retrieve a Cosmos DB access key from Resource Manager, and use the key to access Cosmos DB. In this step, you grant your Windows VM system-assigned managed identity access to the keys to the Cosmos DB account.

-To grant the Windows VM system-assigned managed identity access to the Cosmos DB account in Azure Resource Manager using PowerShell, update the following values:

-Cosmos DB supports two levels of granularity when using access keys: read/write access to the account, and read-only access to the account. Assign the `DocumentDB Account Contributor` role if you want to get read/write keys for the account, or assign the `Cosmos DB Account Reader Role` role if you want to get read-only keys for the account. For this tutorial, assign the `Cosmos DB Account Reader Role`:

-This section shows how to get access keys from Azure Resource Manager to make Cosmos DB calls. We are using PowerShell to call Resource Manager using the access token we got earlier to retrieve the Cosmos DB account access key. Once we have the access key, we can query Cosmos DB. Use your own values to replace the entries below:

-Now that you have the access key for the Cosmos DB account you can pass it to a Cosmos DB SDK and make calls to access the account.

-In this tutorial, you learned how to use a Windows VM system-assigned identity to access Cosmos DB. To learn more about Cosmos DB see:

-In this tutorial, you'll learn how to integrate Cirrus Identity Bridge for Azure AD with Azure Active Directory (Azure AD). When you integrate Cirrus Identity Bridge for Azure AD with Azure AD, you can:

-* Control in Azure AD who has access to Cirrus Identity Bridge for Azure AD.

-* Enable your users to be automatically signed-in to Cirrus Identity Bridge for Azure AD with their Azure AD accounts.

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

- `https://<SUBDOMAIN>.cirrusidentity.com/bridge`

- > These values are not real. Update these values with the actual Identifier and Sign on URL. If you have not yet subscribed to the Cirrus Bridge, please visit the [registration page](https://info.cirrusidentity.com/cirrus-identity-azure-ad-app-gallery-registration). If you are an existing Cirrus Bridge customer, contact [Cirrus Identity Bridge for Azure AD Client support team](https://www.cirrusidentity.com/resources/service-desk) to get these values. You can also refer to the patterns shown in the **Basic SAML Configuration** section in the Azure portal.

-1. In addition to above, Cirrus Identity Bridge for Azure AD 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.

- | displayname | user.displayname |

-To configure single sign-on on **Cirrus Identity Bridge for Azure AD** side, you need to send the **App Federation Metadata Url** to [Cirrus Identity Bridge for Azure AD support team](https://www.cirrusidentity.com/resources/service-desk). They set this setting to have the SAML SSO connection set properly on both sides.

- 

-1. On the **Set up single sign-on with SAML** page, perform the following steps:

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

- `https://<SUBDOMAIN>.factset.com/services/saml2/`

- > [!NOTE]

- > The Sign-on URL value is not real. Update the value with the actual Sign-on URL. Contact the [FactSet Support Team](https://www.factset.com/contact-us) to get the value. You can also refer to the patterns shown in the **Basic SAML Configuration** section in the Azure portal.

- 

- 

-description: Learn how to configure single sign-on between Azure Active Directory and NAVEX IRM (Lockpath/Keylight).

-# Tutorial: Azure Active Directory integration with NAVEX IRM (Lockpath/Keylight)

-In this tutorial, you'll learn how to integrate NAVEX IRM (Lockpath/Keylight) with Azure Active Directory (Azure AD). When you integrate NAVEX IRM (Lockpath/Keylight) with Azure AD, you can:

-* Control in Azure AD who has access to NAVEX IRM (Lockpath/Keylight).

-* Enable your users to be automatically signed-in to NAVEX IRM (Lockpath/Keylight) with their Azure AD accounts.

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

-## Prerequisites

-To configure Azure AD integration with NAVEX IRM (Lockpath/Keylight), you need the following items:

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

-* NAVEX IRM (Lockpath/Keylight) single sign-on enabled subscription.

-## Scenario description

-In this tutorial, you configure and test Azure AD single sign-on in a test environment.

-* NAVEX IRM (Lockpath/Keylight) supports **SP** initiated SSO.

-* NAVEX IRM (Lockpath/Keylight) supports **Just In Time** user provisioning.

-## Add NAVEX IRM (Lockpath/Keylight) from the gallery

-To configure the integration of NAVEX IRM (Lockpath/Keylight) into Azure AD, you need to add NAVEX IRM (Lockpath/Keylight) from the gallery to your list of managed SaaS apps.

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

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

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

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

-1. In the **Add from the gallery** section, type **NAVEX IRM (Lockpath/Keylight)** in the search box.

-1. Select **NAVEX IRM (Lockpath/Keylight)** from results panel and then add the app. Wait a few seconds while the app is added to your tenant.

- 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, assign roles, as well as walk through the SSO configuration as well. [Learn more about Microsoft 365 wizards.](/microsoft-365/admin/misc/azure-ad-setup-guides)

-## Configure and test Azure AD SSO for NAVEX IRM (Lockpath/Keylight)

-Configure and test Azure AD SSO with NAVEX IRM (Lockpath/Keylight) using a test user called **B.Simon**. For SSO to work, you need to establish a link relationship between an Azure AD user and the related user in NAVEX IRM (Lockpath/Keylight).

-To configure and test Azure AD SSO with NAVEX IRM (Lockpath/Keylight), perform the following steps:

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

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

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

-1. **[Configure NAVEX IRM (Lockpath/Keylight) SSO](#configure-navex-irm-lockpathkeylight-sso)** - to configure the single sign-on settings on application side.

- 1. **[Create NAVEX IRM (Lockpath/Keylight) test user](#create-navex-irm-lockpathkeylight-test-user)** - to have a counterpart of B.Simon in NAVEX IRM (Lockpath/Keylight) that is linked to the Azure AD representation of user.

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

-## Configure Azure AD SSO

-In this section, you enable Azure AD single sign-on in the Azure portal.

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

-1. In the Azure portal, on the **NAVEX IRM (Lockpath/Keylight)** application integration page, find the **Manage** section and select **single sign-on**.

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

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

- 

-4. On the **Basic SAML Configuration** section, perform the following steps:

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

- `https://<COMPANY_NAME>.keylightgrc.com`

- b. In the **Reply URL** textbox, type a URL using the following pattern: `https://<COMPANY_NAME>.keylightgrc.com/Login.aspx`

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

- `https://<COMPANY_NAME>.keylightgrc.com/`

- > [!NOTE]

- > These values are not real. Update these values with the actual Identifier, Reply URL and Sign on URL. Contact [NAVEX IRM (Lockpath/Keylight) Client support team](https://www.lockpath.com/contact/) to get these values. You can also refer to the patterns shown in the **Basic SAML Configuration** section in the Azure portal.

-5. On the **Set up Single Sign-On with SAML** page, in the **SAML Signing Certificate** section, click **Download** to download the **Certificate (Raw)** from the given options as per your requirement and save it on your computer.

- 

-6. On the **Set up NAVEX IRM (Lockpath/Keylight)** section, copy the appropriate URL(s) as per your requirement.

- 

-### Create an Azure AD test user

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

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

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

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

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

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

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

- 1. Click **Create**.

-### Assign the Azure AD test user

-In this section, you'll enable B.Simon to use Azure single sign-on by granting access to NAVEX IRM (Lockpath/Keylight).

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

-1. In the applications list, select **NAVEX IRM (Lockpath/Keylight)**.

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

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

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

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

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

-## Configure NAVEX IRM (Lockpath/Keylight) SSO

-1. To enable SSO in NAVEX IRM (Lockpath/Keylight), perform the following steps:

- a. Sign-on to your NAVEX IRM (Lockpath/Keylight) account as administrator.

- b. In the menu on the top, click **User Icon**, and select **Setup**.

- 

- c. In the treeview on the left, click **SAML**.

- 

- d. On the **SAML Settings** dialog, click **Edit**.

- 

-1. On the **Edit SAML Settings** dialog page, perform the following steps:

- 

- a. Set **SAML authentication** to **Active**.

- b. In the **Identity Provider Login URL** textbox, paste the **Login URL** value which you have copied from the Azure portal.

- c. In the **Identity Provider Logout URL** textbox, paste the **Logout URL** value which you have copied from the Azure portal.

- d. Click **Choose File** to select your downloaded NAVEX IRM (Lockpath/Keylight) certificate, and then click **Open** to upload the certificate.

- e. Set **SAML User Id location** to **NameIdentifier element of the subject statement**.

- f. Provide the **Service Provider Entity Id** using the following pattern: `https://<CompanyName>.keylightgrc.com`.

- g. Set **Auto-provision users** to **Active**.

- h. Set **Auto-provision account type** to **Full User**.

- i. Set **Auto-provision security role**, select **Standard User with SAML**.

- j. Set **Auto-provision security config**, select **Standard User Configuration**.

- k. In the **Email attribute** textbox, type `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`.

- l. In the **First name attribute** textbox, type `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname`.

- m. In the **Last name attribute** textbox, type `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname`.

- n. Click **Save**.

-### Create NAVEX IRM (Lockpath/Keylight) test user

-In this section, a user called Britta Simon is created in NAVEX IRM (Lockpath/Keylight). NAVEX IRM (Lockpath/Keylight) supports just-in-time user provisioning, which is enabled by default. There is no action item for you in this section. If a user doesn't already exist in NAVEX IRM (Lockpath/Keylight), a new one is created after authentication. If you need to create a user manually, you need to contact the [NAVEX IRM (Lockpath/Keylight) Customer support team](https://www.lockpath.com/contact/).

-## 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 NAVEX IRM (Lockpath/Keylight) Sign-on URL where you can initiate the login flow.

-* Go to NAVEX IRM (Lockpath/Keylight) Sign-on URL directly and initiate the login flow from there.

-* You can use Microsoft My Apps. When you click the NAVEX IRM (Lockpath/Keylight) tile in the My Apps, this will redirect to NAVEX IRM (Lockpath/Keylight) Sign-on URL. For more information about the My Apps, see [Introduction to the My Apps](https://support.microsoft.com/account-billing/sign-in-and-start-apps-from-the-my-apps-portal-2f3b1bae-0e5a-4a86-a33e-876fbd2a4510).

-## Next steps

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

- 

- 

-### Create Kronos Workforce Dimensions test user

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

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

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

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

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

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

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

- * For agency staff, contractors, and partners, phishing-resistant MFA is required. For public users, phishing-resistant MFA must be an option.

-* Password policies must not require the use of special characters or regular rotation.

-description: In this tutorial, you learn how to configure your tenant to support the Verifiable Credentials service.

-> - Set up the Verifiable Credentials service.

- 

-1. To save the changes, select **Save**.

- 1. **Organization name**: Enter a name to reference your business within Verifiable Credentials. Your customers don't see this name.

-

-

- > The only way to change the trust system is to opt-out of verifiable credentials and redo the onboarding.

-

- 

- 

- 

-

- 

-

- 

- 

-1. Navigate to the Verified ID in the Azure portal.

-## Cosmos DB

-Your Azure Cosmos DB free tier account is currently containing resources with a total provisioned throughput exceeding 1000 Request Units per second (RU/s). Because Azure Cosmos DB's free tier only covers the first 1000 RU/s of throughput provisioned across your account, any throughput beyond 1000 RU/s will be billed at the regular pricing. As a result, we anticipate that you will get charged for the throughput currently provisioned on your Azure Cosmos DB account.

-Learn more about [Cosmos DB account - CosmosDBFreeTierOverage (Review the configuration of your Azure Cosmos DB free tier account)](../cosmos-db/understand-your-bill.md#azure-free-tier).

-Learn more about [Cosmos DB account - CosmosDBIdleContainers (Consider taking action on your idle Azure Cosmos DB containers)](/azure/cosmos-db/how-to-provision-container-throughput).

-Learn more about [Cosmos DB account - CosmosDBAutoscaleRecommendations (Enable autoscale on your Azure Cosmos DB database or container)](../cosmos-db/provision-throughput-autoscale.md).

-Learn more about [Cosmos DB account - CosmosDBMigrateToManualThroughputFromAutoscale (Configure manual throughput instead of autoscale on your Azure Cosmos DB database or container)](../cosmos-db/how-to-choose-offer.md).

-### Consider Cosmos DB reserved instance to save over your pay-as-you-go costs

-We analyzed your Cosmos DB usage pattern over last 30 days and calculate reserved instance purchase that maximizes your savings. With reserved instance you can pre-purchase Cosmos DB hourly usage and save over your pay-as-you-go costs. Reserved instance is a billing benefit and will automatically apply to new or existing deployments. Saving estimates are calculated for individual subscriptions and usage pattern over last 30 days. Shared scope recommendations are available in reservation purchase experience and can increase savings even more.

-Learn more about [Subscription - CosmosDBReservedCapacity (Consider Cosmos DB reserved instance to save over your pay-as-you-go costs)](https://aka.ms/rirecommendations).

-## Cosmos DB

-We noticed that your Azure Cosmos collection is using the legacy attachments feature. We recommend migrating attachments to Azure Blob Storage to improve the resiliency and scalability of your blob data.

-Learn more about [Cosmos DB account - CosmosDBAttachments (Migrate Azure Cosmos DB attachments to Azure Blob Storage)](../cosmos-db/attachments.md#migrating-attachments-to-azure-blob-storage).

-Learn more about [Cosmos DB account - CosmosDBMigrateToContinuousBackup (Improve resiliency by migrating your Azure Cosmos DB accounts to continuous backup)](../cosmos-db/continuous-backup-restore-introduction.md).

-## Cosmos DB

-You are using the query page size of 100 for queries for your Azure Cosmos container. We recommend using a page size of -1 for faster scans.

-Learn more about [Cosmos DB account - CosmosDBQueryPageSize (Configure your Azure Cosmos DB query page size (MaxItemCount) to -1)](/azure/cosmos-db/sql-api-query-metrics#max-item-count).

-Learn more about [Cosmos DB account - CosmosDBOrderByHighRUCharge (Add composite indexes to your Azure Cosmos DB container)](../cosmos-db/index-policy.md#composite-indexes).

-Learn more about [Cosmos DB account - CosmosDBDefaultIndexingWithManyPaths (Optimize your Azure Cosmos DB indexing policy to only index what's needed)](../cosmos-db/index-policy.md).

-Learn more about [Cosmos DB account - CosmosDBHierarchicalPartitionKey (Use hierarchical partition keys for optimal data distribution)](https://devblogs.microsoft.com/cosmosdb/hierarchical-partition-keys-private-preview/).

-We noticed that your Azure Cosmos DB applications are using Gateway mode via the Cosmos DB .NET or Java SDKs. We recommend switching to Direct connectivity for lower latency and higher scalability.

-Learn more about [Cosmos DB account - CosmosDBGatewayMode (Configure your Azure Cosmos DB applications to use Direct connectivity in the SDK)](/azure/cosmos-db/performance-tips#networking).

-## Cosmos DB

-### Configure Consistent indexing mode on your Azure Cosmos container

-We noticed that your Azure Cosmos container is configured with the Lazy indexing mode, which may impact the freshness of query results. We recommend switching to Consistent mode.

-Learn more about [Cosmos DB account - CosmosDBLazyIndexing (Configure Consistent indexing mode on your Azure Cosmos container)](/azure/cosmos-db/how-to-manage-indexing-policy).

-Learn more about [Cosmos DB account - CosmosDBUpgradeOldSDK (Upgrade your old Azure Cosmos DB SDK to the latest version)](../cosmos-db/index.yml).

-Learn more about [Cosmos DB account - CosmosDBUpgradeOutdatedSDK (Upgrade your outdated Azure Cosmos DB SDK to the latest version)](../cosmos-db/index.yml).

-Learn more about [Cosmos DB account - CosmosDBFixedCollections (Configure your Azure Cosmos DB containers with a partition key)](../cosmos-db/partitioning-overview.md#choose-partitionkey).

-### Upgrade your Azure Cosmos DB API for MongoDB account to v4.0 to save on query/storage costs and utilize new features

-Your Azure Cosmos DB API for MongoDB account is eligible to upgrade to version 4.0. Upgrading to v4.0 can reduce your storage costs by up to 55% and your query costs by up to 45% by leveraging a new storage format. Numerous additional features such as multi-document transactions are also included in v4.0.

-Learn more about [Cosmos DB account - CosmosDBMongoSelfServeUpgrade (Upgrade your Azure Cosmos DB API for MongoDB account to v4.0 to save on query/storage costs and utilize new features)](/azure/cosmos-db/mongodb-version-upgrade).

-Learn more about [Cosmos DB account - CosmosDBSingleRegionProdAccounts (Add a second region to your production workloads on Azure Cosmos DB)](../cosmos-db/high-availability.md).

-### Enable Server Side Retry (SSR) on your Azure Cosmos DB's API for MongoDB account

-Learn more about [Cosmos DB account - CosmosDBMongoServerSideRetries (Enable Server Side Retry (SSR) on your Azure Cosmos DB's API for MongoDB account)](/azure/cosmos-db/cassandra/prevent-rate-limiting-errors).

-### Migrate your Azure Cosmos DB API for MongoDB account to v4.0 to save on query/storage costs and utilize new features

-Migrate your database account to a new database account to take advantage of Azure Cosmos DB's API for MongoDB v4.0. Upgrading to v4.0 can reduce your storage costs by up to 55% and your query costs by up to 45% by leveraging a new storage format. Numerous additional features such as multi-document transactions are also included in v4.0. When upgrading, you must also migrate the data in your existing account to a new account created using version 4.0. Azure Data Factory or Studio 3T can assist you in migrating your data.

-Learn more about [Cosmos DB account - CosmosDBMongoMigrationUpgrade (Migrate your Azure Cosmos DB API for MongoDB account to v4.0 to save on query/storage costs and utilize new features)](/azure/cosmos-db/mongodb-feature-support-40).

-### Your Cosmos DB account is unable to access its linked Azure Key Vault hosting your encryption key

-It appears that your key vault's configuration is preventing your Cosmos DB account from contacting the key vault to access your managed encryption keys. If you've recently performed a key rotation, make sure that the previous key or key version remains enabled and available until Cosmos DB has completed the rotation. The previous key or key version can be disabled after 24 hours, or after the Azure Key Vault audit logs don't show activity from Azure Cosmos DB on that key or key version anymore.

-Learn more about [Cosmos DB account - CosmosDBKeyVaultWrap (Your Cosmos DB account is unable to access its linked Azure Key Vault hosting your encryption key)](../cosmos-db/how-to-setup-cmk.md).

-We found a high number of metadata operations on your account. Your data in Cosmos DB, including metadata about your databases and collections is distributed across partitions. Metadata operations have a system-reserved request unit (RU) limit. Avoid being rate limited from metadata operations by using static Cosmos DB client instances in your code and caching the names of databases and collections.

-Learn more about [Cosmos DB account - CosmosDBHighMetadataOperations (Avoid being rate limited from metadata operations)](/azure/cosmos-db/performance-tips).

-### Use the new 3.6+ endpoint to connect to your upgraded Azure Cosmos DB's API for MongoDB account

-We observed some of your applications are connecting to your upgraded Azure Cosmos DB's API for MongoDB account using the legacy 3.2 endpoint - [accountname].documents.azure.com. Use the new endpoint - [accountname].mongo.cosmos.azure.com (or its equivalent in sovereign, government, or restricted clouds).

-Learn more about [Cosmos DB account - CosmosDBMongoNudge36AwayFrom32 (Use the new 3.6+ endpoint to connect to your upgraded Azure Cosmos DB's API for MongoDB account)](/azure/cosmos-db/mongodb-feature-support-40).

-Learn more about [Cosmos DB account - CosmosDBMaxGlobalLSNReachedV2 (Upgrade to 2.6.14 version of the Async Java SDK v2 to avoid a critical issue or upgrade to Java SDK v4 as Async Java SDK v2 is being deprecated)](../cosmos-db/sql/sql-api-sdk-async-java.md).

-Learn more about [Cosmos DB account - CosmosDBMaxGlobalLSNReachedV4 (Upgrade to the current recommended version of the Java SDK v4 to avoid a critical issue)](../cosmos-db/sql/sql-api-sdk-java-v4.md).

-Try to avoid overriding the hostname when configuring Application Gateway. Having a different domain on the frontend of Application Gateway than the one which is used to access the backend can potentially lead to cookies or redirect urls being broken. Note that this might not be the case in all situations and that certain categories of backends (like REST API's) in general are less sensitive to this. Make sure the backend is able to deal with this or update the Application Gateway configuration so the hostname does not need to be overwritten towards the backend. When used with App Service, attach a custom domain name to the Web App and avoid use of the *.azurewebsites.net host name towards the backend.

-* The Azure CLI version 2.42.0 or higher. Run `az --version` to find your version. If you need to install or upgrade, see [Install Azure CLI][azure-cli-install].

-description: Learn more about using Dapr on your Azure Kubernetes Service (AKS) cluster to develop applications.

-# Dapr

-Distributed Application Runtime (Dapr) offers APIs that simplify microservice development and implementation. Running as a sidecar process in tandem with your applications, Dapr APIs abstract away common complexities developers regularly encounter when building distributed applications, such as service discovery, message broker integration, encryption, observability, and secret management. Whether your inter-application communication is direct service-to-service, or pub/sub messaging, Dapr helps you write simple, portable, resilient, and secured microservices.

-Dapr is incrementally adoptable ΓÇô the API building blocks can be used as the need arises. Use one, several, or all to develop your application faster.

-## Capabilities and features

-Dapr provides the following set of capabilities to help with your microservice development on AKS:

-* Easy provisioning of Dapr on AKS through [cluster extensions][cluster-extensions].

-* Portability enabled through HTTP and gRPC APIs which abstract underlying technologies choices

-* Reliable, secure, and resilient service-to-service calls through HTTP and gRPC APIs

-* Publish and subscribe messaging made easy with support for CloudEvent filtering and ΓÇ£at-least-onceΓÇ¥ semantics for message delivery

-* Pluggable observability and monitoring through Open Telemetry API collector

-* Works independent of language, while also offering language specific SDKs

-* Integration with VS Code through the Dapr extension

-* [More APIs for solving distributed application challenges][dapr-blocks]

-## Frequently asked questions

-### How do Dapr and Service meshes compare?

-A: Where a service mesh is defined as a networking service mesh, Dapr is not a service mesh. While Dapr and service meshes do offer some overlapping capabilities, a service mesh is focused on networking concerns, whereas Dapr is focused on providing building blocks that make it easier for developers to build applications as microservices. Dapr is developer-centric, while service meshes are infrastructure-centric.

-Some common capabilities that Dapr shares with service meshes include:

-* Secure service-to-service communication with mTLS encryption

-* Service-to-service metric collection

-* Service-to-service distributed tracing

-* Resiliency through retries

-In addition, Dapr provides other application-level building blocks for state management, pub/sub messaging, actors, and more. However, Dapr does not provide capabilities for traffic behavior such as routing or traffic splitting. If your solution would benefit from the traffic splitting a service mesh provides, consider using [Open Service Mesh][osm-docs].

-For more information on Dapr and service meshes, and how they can be used together, visit the [Dapr documentation][dapr-docs].

-### How does the Dapr secrets API compare to the Secrets Store CSI driver?

-Both the Dapr secrets API and the managed Secrets Store CSI driver allow for the integration of secrets held in an external store, abstracting secret store technology from application code. The Secrets Store CSI driver mounts secrets held in Azure Key Vault as a CSI volume for consumption by an application. Dapr exposes secrets via a RESTful API that can be called by application code and can be configured with assorted secret stores. The following table lists the capabilities of each offering:

-| | Dapr secrets API | Secrets Store CSI driver |

-| | | |

-| **Supported secrets stores** | Local environment variables (for Development); Local file (for Development); Kubernetes Secrets; AWS Secrets Manager; Azure Key Vault secret store; Azure Key Vault with Managed Identities on Kubernetes; GCP Secret Manager; HashiCorp Vault | Azure Key Vault secret store|

-| **Accessing secrets in application code** | Call the Dapr secrets API | Access the mounted volume or sync mounted content as a Kubernetes secret and set an environment variable |

-| **Secret rotation** | New API calls obtain the updated secrets | Polls for secrets and updates the mount at a configurable interval |

-| **Logging and metrics** | The Dapr sidecar generates logs, which can be configured with collectors such as Azure Monitor, emits metrics via Prometheus, and exposes an HTTP endpoint for health checks | Emits driver and Azure Key Vault provider metrics via Prometheus |

-For more information on the secret management in Dapr, see the [secrets management building block overview][dapr-secrets-block].

-For more information on the Secrets Store CSI driver and Azure Key Vault provider, see the [Secrets Store CSI driver overview][csi-secrets-store].

-### How does the managed Dapr cluster extension compare to the open source Dapr offering?

-The managed Dapr cluster extension is the easiest method to provision Dapr on an AKS cluster. With the extension, you're able to offload management of the Dapr runtime version by opting into automatic upgrades. Additionally, the extension installs Dapr with smart defaults (for example, provisioning the Dapr control plane in high availability mode).

-When installing Dapr OSS via helm or the Dapr CLI, runtime versions and configuration options are the responsibility of developers and cluster maintainers.

-Lastly, the Dapr extension is an extension of AKS, therefore you can expect the same support policy as other AKS features.

-[Learn more about migrating from Dapr OSS to the Dapr extension for AKS][dapr-migration].

-### How can I switch to using the Dapr extension if IΓÇÖve already installed Dapr via a method, such as Helm?

-Recommended guidance is to completely uninstall Dapr from the AKS cluster and reinstall it via the cluster extension.

-If you install Dapr through the AKS extension, our recommendation is to continue using the extension for future management of Dapr instead of the Dapr CLI. Combining the two tools can cause conflicts and result in undesired behavior.

-## Next Steps

-After learning about Dapr and some of the challenges it solves, try [Deploying an application with the Dapr cluster extension][dapr-quickstart].

-<!-- Links Internal -->

-[csi-secrets-store]: ./csi-secrets-store-driver.md

-[osm-docs]: ./open-service-mesh-about.md

-[cluster-extensions]: ./cluster-extensions.md

-[dapr-quickstart]: ./quickstart-dapr.md

-[dapr-migration]: ./dapr-migration.md

-<!-- Links External -->

-[dapr-docs]: https://docs.dapr.io/

-[dapr-blocks]: https://docs.dapr.io/concepts/building-blocks-concept/

-[dapr-secrets-block]: https://docs.dapr.io/developing-applications/building-blocks/secrets/secrets-overview/

-The feature to enable storing customer data in a single region is currently only available in the Southeast Asia Region (Singapore) of the Asia Pacific Geo and Brazil South (Sao Paulo State) Region of Brazil Geo. For all other regions, customer data is stored in Geo.

-[keda-troubleshoot]: keda-troubleshoot.md

-You can troubleshoot troubleshoot KEDA add-on problems in [this article][keda-troubleshoot].

-[keda-troubleshoot]: keda-troubleshoot.md

-You can troubleshoot troubleshoot KEDA add-on problems in [this article][keda-troubleshoot].

-[keda-troubleshoot]: keda-troubleshoot.md

-[keda-troubleshoot]: keda-troubleshoot.md

-description: How to troubleshoot Kubernetes Event-driven Autoscaling add-on

-# Kubernetes Event-driven Autoscaling (KEDA) AKS add-on Troubleshooting Guides

-When you deploy the KEDA AKS add-on, you could possibly experience problems associated with configuration of the application autoscaler.

-The following guide will assist you on how to troubleshoot errors and resolve common problems with the add-on, in addition to the official KEDA [FAQ][keda-faq] & [troubleshooting guide][keda-troubleshooting].

-## Verifying and Troubleshooting KEDA components

-### Check available KEDA version

-You can check the available KEDA version by using the `kubectl` command:

-```azurecli-interactive

-kubectl get crd/scaledobjects.keda.sh -o custom-columns='APP:.metadata.labels.app\.kubernetes\.io/version'

-```

-An overview will be provided with the installed KEDA version:

-```Output

-APP

-2.7.0

-```

-### Ensuring the cluster firewall is configured correctly

-It might happen that KEDA isn't scaling applications because it can't start up.

-When checking the operator logs, you might find errors similar to the following:

-```output

-1.6545953013458195e+09 ERROR Failed to get API Group-Resources {"error": "Get \"https://10.0.0.1:443/api?timeout=32s\": EOF"}

-sigs.k8s.io/controller-runtime/pkg/cluster.New

-/go/pkg/mod/sigs.k8s.io/controller-runtime@v0.11.2/pkg/cluster/cluster.go:160

-sigs.k8s.io/controller-runtime/pkg/manager.New

-/go/pkg/mod/sigs.k8s.io/controller-runtime@v0.11.2/pkg/manager/manager.go:313

-main.main

-/workspace/main.go:87

-runtime.main

-/usr/local/go/src/runtime/proc.go:255

-1.6545953013459463e+09 ERROR setup unable to start manager {"error": "Get \"https://10.0.0.1:443/api?timeout=32s\": EOF"}

-main.main

-/workspace/main.go:97

-runtime.main

-/usr/local/go/src/runtime/proc.go:255

-```

-While in the metric server you might notice that it's not able to start up:

-```output

-I0607 09:53:05.297924 1 main.go:147] keda_metrics_adapter "msg"="KEDA Version: 2.7.1"

-I0607 09:53:05.297979 1 main.go:148] keda_metrics_adapter "msg"="KEDA Commit: "

-I0607 09:53:05.297996 1 main.go:149] keda_metrics_adapter "msg"="Go Version: go1.17.9"

-I0607 09:53:05.298006 1 main.go:150] keda_metrics_adapter "msg"="Go OS/Arch: linux/amd64"

-E0607 09:53:15.344324 1 logr.go:279] keda_metrics_adapter "msg"="Failed to get API Group-Resources" "error"="Get \"https://10.0.0.1:443/api?timeout=32s\": EOF"

-E0607 09:53:15.344360 1 main.go:104] keda_metrics_adapter "msg"="failed to setup manager" "error"="Get \"https://10.0.0.1:443/api?timeout=32s\": EOF"

-E0607 09:53:15.344378 1 main.go:209] keda_metrics_adapter "msg"="making provider" "error"="Get \"https://10.0.0.1:443/api?timeout=32s\": EOF"

-E0607 09:53:15.344399 1 main.go:168] keda_metrics_adapter "msg"="unable to run external metrics adapter" "error"="Get \"https://10.0.0.1:443/api?timeout=32s\": EOF"

-```

-This most likely means that the KEDA add-on isn't able to start up due to a misconfigured firewall.

-In order to make sure it runs correctly, make sure to configure the firewall to meet [the requirements][aks-firewall-requirements].

-### Enabling add-on on clusters with self-managed open-source KEDA installations

-While Kubernetes only allows one metric server to be installed, you can in theory install KEDA multiple times. However, it isn't recommended given only one installation will work.

-When the KEDA add-on is installed in an AKS cluster, the previous installation of open-source KEDA will be overridden and the add-on will take over.

-This means that the customization and configuration of the self-installed KEDA deployment will get lost and no longer be applied.

-While there's a possibility that the existing autoscaling will keep on working, it introduces a risk given it will be configured differently and won't support features such as managed identity.

-It's recommended to uninstall existing KEDA installations before enabling the KEDA add-on given the installation will succeed without any error.

-In order to determine which metrics adapter is being used by KEDA, use the `kubectl` command:

-```azurecli-interactive

-kubectl get APIService/v1beta1.external.metrics.k8s.io -o custom-columns='NAME:.spec.service.name,NAMESPACE:.spec.service.namespace'

-```

-An overview will be provided showing the service and namespace that Kubernetes will use to get metrics:

-```Output

-NAME NAMESPACE

-keda-operator-metrics-apiserver kube-system

-```

-> [!WARNING]

-> If the namespace is not `kube-system`, then the AKS add-on is being ignored and another metric server is being used.

-[aks-firewall-requirements]: limit-egress-traffic.md#azure-global-required-network-rules

-[keda-troubleshooting]: https://keda.sh/docs/latest/troubleshooting/

-[keda-faq]: https://keda.sh/docs/latest/faq/

-In addition to the above platform metrics, Azure Monitor container insights collects [these custom metrics](../azure-monitor/containers/container-insights-metric-alerts.md#metrics-collected) for nodes, pods, containers, and persistent volumes.

-[Prometheus](https://prometheus.io/) and [Grafana](https://www.prometheus.io/docs/visualization/grafan) has native integration with AKS, collecting critical metrics and logs, alerting on identified issues, and providing visualization with workbooks. It also collects certain Prometheus metrics, and many native Azure Monitor insights are built-up on top of Prometheus metrics. Container insights complements and completes E2E monitoring of AKS including log collection which Prometheus as stand-alone tool doesnΓÇÖt provide. Many customers use Prometheus integration and Azure Monitor together for E2E monitoring.

-Container insights allows you to collect certain Prometheus metrics in your Log Analytics workspace without requiring a Prometheus server. You can analyze this data using Azure Monitor features along with other data collected by Container insights. See [Configure scraping of Prometheus metrics with Container insights](../azure-monitor/containers/container-insights-prometheus-integration.md) for details on this configuration.

-There is a cost for sending resource logs to a workspace, so you should only collect those log categories that you intend to use. Send logs to an Azure storage account to reduce costs if you need to retain the information but don't require it to be readily available for analysis. See [Resource logs](monitor-aks-reference.md#resource-logs) for a description of the categories that are available for AKS and See [Azure Monitor Logs pricing details](../azure-monitor/logs/cost-logs.md) for details for details on the cost of ingesting and retaining log data. Start by collecting a minimal number of categories and then modify the diagnostic setting to collect additional categories as your needs increase and as you understand your associated costs.

-| Advisor | recommendations Recommendations for the current cluster from Azure Advisor. |

-Use the **Kubelet** workbook to view the health and performance of each kubelet. See [Resource Monitoring workbooks](../azure-monitor/containers/container-insights-reports.md#resource-monitoring-workbooks) for details on this workbooks. For troubleshooting scenarios, you can access kubelet logs using the process described at [Get kubelet logs from Azure Kubernetes Service (AKS) cluster nodes](kubelet-logs.md).

-Now create a second function. This example will be deployed using the OpenFaaS CLI and includes a custom container image and retrieving data from a Cosmos DB. Several items need to be configured before creating the function.

-First, create a new resource group for the Cosmos DB.

-Deploy a CosmosDB instance of kind `MongoDB`. The instance needs a unique name, update `openfaas-cosmos` to something unique to your environment.

-Get the Cosmos database connection string and store it in a variable.

-Update the value for the `--resource-group` argument to the name of your resource group, and the `--name` argument to the name of your Cosmos DB.

-Now populate the Cosmos DB with test data. Create a file named `plans.json` and copy in the following json.

-Use the *mongoimport* tool to load the CosmosDB instance with data.

-To access other Azure resources, like Cosmos DB, Key Vault, or Blob Storage, the pod needs authentication credentials. You could define authentication credentials with the container image or inject them as a Kubernetes secret. Either way, you would need to manually create and assign them. Usually, these credentials are reused across pods and aren't regularly rotated.

-[workload-identity-overview]: workload-identity-overview.md

-Dapr can use a number of different state stores (Redis, Cosmos DB, DynamoDB, Cassandra, etc.) to persist and retrieve state. For this example, we will use Redis.

-# Use Confidential Virtual Machines (CVM) in Azure Kubernetes Service (AKS) cluster (Preview)

-You can use the generally available [confidential VM sizes (DCav5/ECav5)][cvm-announce] to add a node pool to your AKS cluster with CVM. Confidential VMs with AMD SEV-SNP support bring a new set of security features to protect date-in-use with full VM memory encryption. These features enable node pools with CVM to target the migration of highly sensitive container workloads to AKS without any code refactoring while benefiting from the features of AKS. The nodes in a node pool created with CVM use a customized Ubuntu 20.04 image specially configured for CVM. For more details on CVM, see [Confidential VM node pools support on AKS with AMD SEV-SNP confidential VMs][cvm].

-> KMS only supports Konnectivity. You can use `kubectl get po -n kube-system` to check if a 'konnectivity-agent-xxx' pod is running.

-* Volume mounting Azure Files share support [General-purpose V1](../storage/common/storage-account-overview.md#types-of-storage-accounts). Follow the instructions for mounting [a volume with Azure Files share](azure-files-volume.md)

-## Elements

-

-description: Learn about community widgets for the API Management developer portal and how to inject and use them in your code.

-# Use community widgets in the developer portal

-All developers place their community-contributed widgets in the `/community/widgets/` folder of the API Management developer portal [GitHub repository](https://github.com/Azure/api-management-developer-portal). Each has been accepted by the developer portal team. You can use the widgets by injecting them into your managed developer portal or a [self-hosted version](developer-portal-self-host.md) of the portal.

-> [!NOTE]

-> The developer portal team thoroughly inspects contributed widgets and their dependencies. However, the team canΓÇÖt guarantee itΓÇÖs safe to load the widgets. Use your own judgment when deciding to use a widget contributed by the community. Refer to our [widget contribution guidelines](developer-portal-widget-contribution-guidelines.md#contribution-guidelines) to learn about our preventive measures.

-## Inject and use external widget - managed portal

-For guidance to create and use a development environment to scaffold and upload a custom widget, see [Create and upload custom widget](developer-portal-extend-custom-functionality.md#create-and-upload-custom-widget).

-## Inject and use external widget - self-hosted portal

-1. Set up a [local environment](developer-portal-self-host.md#step-1-set-up-local-environment) for the latest release of the developer portal.

-1. Go to the widget's folder in the `/community/widgets` directory. Read the widget's description in the `readme.md` file.

-1. Register the widget in the portal's modules:

- 1. `src/apim.design.module.ts` - a module that registers design-time dependencies.

-

- ```typescript

- import { WidgetNameDesignModule } from "../community/widgets/<widget-name>/widget.design.module";

-

- ...

-

- injector.bindModule(new WidgetNameDesignModule());

- ```

-

- 1. `src/apim.publish.module.ts` - a module that registers publish-time dependencies.

-

- ```typescript

- import { WidgetNamePublishModule } from "../community/widgets/<widget-name>/widget.publish.module";

-

- ...

-

- injector.bindModule(new WidgetNamePublishModule());

- ```

-

- 1. `src/apim.runtime.module.ts` - a module that registers run-time dependencies.

-

- ```typescript

- import { WidgetNameRuntimeModule } from "../community/widgets/<widget-name>/widget.runtime.module";

-

- ...

-

- injector.bindModule(new WidgetNameRuntimeModule());

- ```

-1. Check if the widget has an `npm_dependencies` file.

-1. If so, copy the commands from the file and run them in the repository's top directory.

- Doing so will install the widget's dependencies.

-1. Run `npm start`.

-You can see the widget in the **Community** category in the widget selector.

-## Next steps

-Learn more about the developer portal:

-description: Learn about recommended guidelines to follow when you contribute a widget to the API Management developer portal repository.

-# How to contribute widgets to the API Management developer portal

-If you'd like to contribute a widget to the API Management developer portal [GitHub repository](https://github.com/Azure/api-management-developer-portal), follow this three-step process:

-1. Fork the repository.

-1. Implement the widget.

-1. Open a pull request to include your widget in the official repository.

-Your widget will inherit the repository's license. It will be available for [opt-in installation](developer-portal-use-community-widgets.md) in either the managed developer portal or a [self-hosted version](developer-portal-self-host.md) of the portal. The developer portal team may decide to also include it in the managed version of the portal.

-For an example of how to develop your own widget and upload it to your developer portal, see [Create and upload custom widget](developer-portal-extend-custom-functionality.md#create-and-upload-custom-widget).

-## Contribution guidelines

-This guidance is intended to ensure the safety and privacy of our customers and the visitors to their portals. Follow these guidelines to ensure your contribution is accepted:

-1. Place your widget in the `community/widgets/<your-widget-name>` folder.

-1. Your widget's name must be lowercase and alphanumeric with dashes separating the words. For example, `my-new-widget`.

-1. The folder must contain a screenshot of your widget in a published portal.

-1. The folder must contain a `readme.md` file, which follows the template from the `/scaffolds/widget/readme.md` file.

-1. The folder can contain an `npm_dependencies` file with npm commands to install or manage the widget's dependencies.

- Explicitly specify the version of every dependency. For example:

- ```console

- npm install azure-storage@2.10.3 axios@0.19.1

- ```

- Your widget should require minimal dependencies. Every dependency will be carefully inspected by the reviewers. In particular, the core logic of your widget should be open-sourced in your widget's folder. Don't wrap it in an npm package.

-1. Changes to any files outside your widget's folder aren't allowed as part of a widget contribution. That includes, but isn't limited to, the `/package.json` file.

-1. Injecting tracking scripts or sending customer-authored data to custom services isn't allowed.

- > [!NOTE]

- > You can only collect customer-authored data through the `Logger` interface.

-## Next steps

-You can configure an inbound [ip-filter](/api-management-access-restriction-policies.md#CheckHTTPHeader) policy in API Management to allow only Front Door-related traffic, which includes:

-Requests routed through Front Door include headers specific to your Front Door configuration. You can configure the [check-header](/api-management-access-restriction-policies.md#CheckHTTPHeader) policy to filter incoming requests based on the unique value of the `X-Azure-FDID` HTTP request header that is sent to API Management. This header value is the **Front Door ID**, which is shown in the portal on the **Overview** page of the Front Door profile.

-The minimum size of the subnet in which API Management can be deployed is /29, which gives three usable IP addresses. Each extra scale [unit](api-management-capacity.md) of API Management requires two more IP addresses. The minimum size requirement is based on the following considerations:

- * **/29 subnet**: 8 possible IP addresses - 5 reserved Azure IP addresses - 2 API Management IP addresses for one instance - 1 IP for internal load balancer, if used in internal mode = 0 remaining IP addresses left for scaling units.

- * **/28 subnet**: 16 possible IP addresses - 5 reserved Azure IP addresses - 2 API Management IP addresses for one instance - 1 IP for internal load balancer, if used in internal mode = 8 remaining IP addresses left for four scale-out units (2 IP addresses/scale-out unit) for a total of five units. **This subnet efficiently maximizes Basic and Standard SKU scale-out limits.**

- * **/27 subnet**: 32 possible IP addresses - 5 reserved Azure IP addresses - 2 API Management IP addresses for one instance - 1 IP for internal load balancer, if used in internal mode = 24 remaining IP addresses left for twelve scale-out units (2 IP addresses/scale-out unit) for a total of thirteen units. **This subnet efficiently maximizes the soft-limit Premium SKU scale-out limit.**

- * **/26 subnet**: 64 possible IP addresses - 5 reserved Azure IP addresses - 2 API Management IP addresses for one instance - 1 IP for internal load balancer, if used in internal mode = 56 remaining IP addresses left for twenty-eight scale-out units (2 IP addresses/scale-out unit) for a total of twenty-nine units. It is possible, with an Azure Support ticket, to scale the Premium SKU past twelve units. If you foresee such high demand, consider the /26 subnet.

- * **/25 subnet**: 128 possible IP addresses - 5 reserved Azure IP addresses - 2 API Management IP addresses for one instance - 1 IP for internal load balancer, if used in internal mode = 120 remaining IP addresses left for sixty scale-out units (2 IP addresses/scale-out unit) for a total of sixty-one units. This is an extremely large, theoretical number of scale-out units.

-| * / 443 | Outbound | TCP | VirtualNetwork / AzureActiveDirectory | [Azure Active Directory](api-management-howto-aad.md) dependency (optional) | External & Internal |

-#zone_pivot_groups: app-service-platform-windows-linux

-* [Cosmos DB](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-cosmosdb)

-| [Connect an app to Cosmos DB](./scripts/cli-connect-to-documentdb.md) | Creates an App Service app and a Cosmos DB, then adds the Cosmos DB connection details to the app settings. |

-description: Learn how to use the Azure CLI to automate deployment and management of your App Service app. This sample shows how to connect an app to MongoDB (Cosmos DB).

-# Connect an App Service app to Cosmos DB using CLI

-This sample script creates an Azure Cosmos DB account using the Azure Cosmos DB's API for MongoDB and an App Service app. It then links a MongoDB connection string to the web app using app settings.

-This script uses the following commands to create a resource group, App Service app, Cosmos DB, and all related resources. Each command in the table links to command specific documentation.

-| [`az cosmosdb create`](/cli/azure/cosmosdb#az-cosmosdb-create) | Creates a Cosmos DB account. |

-| [`az cosmosdb list-connection-strings`](/cli/azure/cosmosdb#az-cosmosdb-list-connection-strings) | Lists connection strings for the specified Cosmos DB account. |

-This script uses the following commands to create a resource group, App Service app, Cosmos DB, and all related resources. Each command in the table links to command specific documentation.

-> This tutorial doesn't include guidance for [Azure Cosmos DB](../cosmos-db/index.yml), which supports Azure Active Directory authentication differently. For information, see Cosmos DB documentation. For example: [Use system-assigned managed identities to access Azure Cosmos DB data](../cosmos-db/managed-identity-based-authentication.md).

-description: Learn how to get a data-driven Linux Java app working in Azure App Service, with connection to a MongoDB running in Azure (Cosmos DB).

-> * Create a Cosmos DB database.

-This tutorial uses a sample TODO list app with a web UI that calls a Spring REST API backed by [Spring Data Azure Cosmos DB](https://github.com/Microsoft/spring-data-cosmosdb). The code for the app is available [on GitHub](https://github.com/Microsoft/spring-todo-app). To learn more about writing Java apps using Spring and Cosmos DB, see the [Spring Boot Starter with the Azure Cosmos DB SQL API tutorial](/java/azure/spring-framework/configure-spring-boot-starter-java-app-with-cosmos-db) and the [Spring Data Azure Cosmos DB quick start](https://github.com/Microsoft/spring-data-cosmosdb#quick-start).

-The name of Cosmos DB must use only lower case letters. Note down the `documentEndpoint` field in the response from the command.

-Open a terminal on your computer. Copy the sample script file in the cloned repo so you can customize it for your Cosmos DB database you just created.

-Cosmos DB connection info. For the App Service Linux configuration, use the same region as before (`your-resource-group-region`) and resource group (`your-azure-group-name`) used when creating the Cosmos DB database. Choose a WEBAPP_NAME that is unique since it cannot duplicate any web app name in any Azure deployment.

-Then the sample app uses the `@Document` annotation imported from `com.microsoft.azure.spring.data.cosmosdb.core.mapping.Document` to set up an entity type to be stored and managed by Cosmos DB:

-[Spring Data for Cosmos DB](/azure/developer/java/spring-framework/configure-spring-boot-starter-java-app-with-cosmos-db),

-description: This article shows you have to deploy a Node.js app using Express.js and a MongoDB database to Azure. Azure App Service is used to host the web application and Azure Cosmos DB to host the database using the 100% compatible MongoDB API built into Cosmos DB.

-[Azure App Service](overview.md) provides a highly scalable, self-patching web hosting service using the Linux operating system. This tutorial shows how to create a secure Node.js app in Azure App Service that's connected to a MongoDB database (using [Azure Cosmos DB with MongoDB API](../cosmos-db/mongodb/mongodb-introduction.md)). When you're finished, you'll have an Express.js app running on Azure App Service on Linux.

-## 1. Create App Service and Cosmos DB

-In this step, you create the Azure resources. The steps used in this tutorial create a set of secure-by-default resources that include App Service and Azure Cosmos DB API for MongoDB that's. For the creation process, you'll specify:

- 1. **Cosmos DB API for MongoDB** is selected by default as the database engine. Azure Cosmos DB is a cloud native database offering a 100% MongoDB compatible API. Note the database name that's generated for you (*\<app-name>-database*). You'll need it later.

- - **Cosmos DB API for MongoDB** &rarr; Accessible only from behind the private endpoint. A database and a user are created for you on the server.

- - **Private DNS zone** &rarr; Enables DNS resolution of the Cosmos DB server in the virtual network.

-#### How do I connect to the Cosmos DB server that's secured behind the virtual network with other tools?

-* [Azure CosmosDB trigger](#azure-cosmosdb-trigger-configuration-version-3x)

-#### Azure CosmosDB trigger configuration (version 3.*x*)

-For more information, see the [Azure CosmosDB binding](../azure-functions/functions-bindings-cosmosdb-v2.md#hostjson-settings) article.

-Application Gateway uses a secret identifier in Key Vault to reference the certificates. For Azure PowerShell, the Azure CLI, or Azure Resource Manager, we strongly recommend that you use a secret identifier that doesn't specify a version. This way, Application Gateway will automatically rotate the certificate if a newer version is available in your Key Vault. An example of a secret URI without a version is `https://myvault.vault.azure.net/secrets/mysecret/`.

-description: Learn how to ensure your training data set is optimized for training a Form Recognizer model.

-#Customer intent: As a user of the Form Recognizer custom model service, I want to ensure I'm training my model in the best way.

-# Build a training data set for a custom model

-When you use the Form Recognizer custom model, you provide your own training data to the [Train Custom Model](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-v2-1/operations/TrainCustomModelAsync) operation, so that the model can train to your industry-specific forms. Follow this guide to learn how to collect and prepare data to train the model effectively.

-You need at least five filled-in forms of the same type.

-If you want to use manually labeled training data, you must start with at least five filled-in forms of the same type. You can still use unlabeled forms in addition to the required data set.

-## Custom model input requirements

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

-## Training data tips

-Follow these additional tips to further optimize your data set for training.

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

-* For filled-in forms, use examples that have all of their fields filled in.

-* Use forms with different values in each field.

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

-## Upload your training data

-When you've put together the set of form documents that you'll use for training, you need to upload it to an Azure blob storage container. If you don't know how to create an Azure storage account with a container, follow the [Azure Storage quickstart for Azure portal](../../storage/blobs/storage-quickstart-blobs-portal.md). Use the standard performance tier.

-If you want to use manually labeled data, you'll also have to upload the *.labels.json* and *.ocr.json* files that correspond to your training documents. You can use the [Sample Labeling tool](label-tool.md) (or your own UI) to generate these files.

-### Organize your data in subfolders (optional)

-By default, the [Train Custom Model](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-v2-1/operations/TrainCustomModelAsync) API will only use form documents that are located at the root of your storage container. However, you can train with data in subfolders if you specify it in the API call. Normally, the body of the [Train Custom Model](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-v2-1/operations/TrainCustomModelAsync) call has the following format, where `<SAS URL>` is the Shared access signature URL of your container:

-```json

-{

- "source":"<SAS URL>"

-}

-```

-If you add the following content to the request body, the API will train with documents located in subfolders. The `"prefix"` field is optional and will limit the training data set to files whose paths begin with the given string. So a value of `"Test"`, for example, will cause the API to look at only the files or folders that begin with the word "Test".

-```json

-{

- "source": "<SAS URL>",

- "sourceFilter": {

- "prefix": "<prefix string>",

- "includeSubFolders": true

- },

- "useLabelFile": false

-}

-```

-## Next steps

-Now that you've learned how to build a training data set, follow a quickstart to train a custom Form Recognizer model and start using it on your forms.

-* [Train a model and extract form data using the client library or REST API](quickstarts/try-sdk-rest-api.md)

-* [Train with labels using the sample labeling tool](label-tool.md)

-## See also

-* [What is Form Recognizer?](./overview.md)

-description: Learn how to create, compose use, and manage custom models with Form Recognizer v2.1

-recommendations: false

-# Compose custom models v2.1

-> [!NOTE]

-> This how-to guide references Form Recognizer v2.1 . To try Form Recognizer v3.0 , see [Compose custom models v3.0](compose-custom-models-v3.md).

-Form Recognizer uses advanced machine-learning technology to detect and extract information from document images and return the extracted data in a structured JSON output. With Form Recognizer, you can train standalone custom models or combine custom models to create composed models.

-* **Custom models**. Form Recognizer custom models enable you to analyze and extract data from forms and documents specific to your business. Custom models are trained for your distinct data and use cases.

-* **Composed models**. A composed model is created by taking a collection of custom models and assigning them to a single model that encompasses your form types. When a document is submitted to a composed model, the service performs a classification step to decide which custom model accurately represents the form presented for analysis.

-In this article, you'll learn how to create Form Recognizer custom and composed models using our [Form Recognizer Sample Labeling tool](label-tool.md), [REST APIs](quickstarts/client-library.md?branch=main&pivots=programming-language-rest-api#train-a-custom-model), or [client-library SDKs](quickstarts/client-library.md?branch=main&pivots=programming-language-csharp#train-a-custom-model).

-## Sample Labeling tool

-Try extracting data from custom forms using our Sample Labeling tool. You'll need the following resources:

-* An Azure subscriptionΓÇöyou can [create one for free](https://azure.microsoft.com/free/cognitive-services/)

-* A [Form Recognizer instance](https://portal.azure.com/#create/Microsoft.CognitiveServicesFormRecognizer) in the Azure portal. You can use the free pricing tier (`F0`) to try the service. After your resource deploys, select **Go to resource** to get your key and endpoint.

- :::image type="content" source="media/containers/keys-and-endpoint.png" alt-text="Screenshot: keys and endpoint location in the Azure portal.":::

-> [!div class="nextstepaction"]

-> [Try it](https://fott-2-1.azurewebsites.net/projects/create)

-In the Form Recognizer UI:

-1. Select **Use Custom to train a model with labels and get key value pairs**.

- :::image type="content" source="media/label-tool/fott-use-custom.png" alt-text="Screenshot of the FOTT tool select custom model option.":::

-1. In the next window, select **New project**:

- :::image type="content" source="media/label-tool/fott-new-project.png" alt-text="Screenshot of the FOTT tool select new project option.":::

-## Create your models

-The steps for building, training, and using custom and composed models are as follows:

-* [**Assemble your training dataset**](#assemble-your-training-dataset)

-* [**Upload your training set to Azure blob storage**](#upload-your-training-dataset)

-* [**Train your custom model**](#train-your-custom-model)

-* [**Compose custom models**](#create-a-composed-model)

-* [**Analyze documents**](#analyze-documents-with-your-custom-or-composed-model)

-* [**Manage your custom models**](#manage-your-custom-models)

-## Assemble your training dataset

-Building a custom model begins with establishing your training dataset. You'll need a minimum of five completed forms of the same type for your sample dataset. They can be of different file types (jpg, png, pdf, tiff) and contain both text and handwriting. Your forms must follow the [input requirements](build-training-data-set.md#custom-model-input-requirements) for Form Recognizer.

-## Upload your training dataset

-You'll need to [upload your training data](build-training-data-set.md#upload-your-training-data)

-to an Azure blob storage container. If you don't know how to create an Azure storage account with a container, *see* [Azure Storage quickstart for Azure portal](../../storage/blobs/storage-quickstart-blobs-portal.md). You can use the free pricing tier (F0) to try the service, and upgrade later to a paid tier for production.

-## Train your custom model

-You [train your model](./quickstarts/try-sdk-rest-api.md#train-a-custom-model) with labeled data sets. Labeled datasets rely on the prebuilt-layout API, but supplementary human input is included such as your specific labels and field locations. Start with at least five completed forms of the same type for your labeled training data.

-When you train with labeled data, the model uses supervised learning to extract values of interest, using the labeled forms you provide. Labeled data results in better-performing models and can produce models that work with complex forms or forms containing values without keys.

-Form Recognizer uses the [Layout](concept-layout.md) API to learn the expected sizes and positions of typeface and handwritten text elements and extract tables. Then it uses user-specified labels to learn the key/value associations and tables in the documents. We recommend that you use five manually labeled forms of the same type (same structure) to get started when training a new model. Add more labeled data as needed to improve the model accuracy. Form Recognizer enables training a model to extract key value pairs and tables using supervised learning capabilities.

-[Get started with Train with labels](label-tool.md)

-> [!VIDEO https://learn.microsoft.com/Shows/Docs-Azure/Azure-Form-Recognizer/player]

-## Create a composed model

-> [!NOTE]

-> **Model Compose is only available for custom models trained _with_ labels.** Attempting to compose unlabeled models will produce an error.

-With the Model Compose operation, you can assign up to 100 trained custom models to a single model ID. When you call Analyze with the composed model ID, Form Recognizer will first classify the form you submitted, choose the best matching assigned model, and then return results for that model. This operation is useful when incoming forms may belong to one of several templates.

-Using the Form Recognizer Sample Labeling tool, the REST API, or the Client-library SDKs, follow the steps below to set up a composed model:

-1. [**Gather your custom model IDs**](#gather-your-custom-model-ids)

-1. [**Compose your custom models**](#compose-your-custom-models)

-#### Gather your custom model IDs

-Once the training process has successfully completed, your custom model will be assigned a model ID. You can retrieve a model ID as follows:

-### [**Form Recognizer Sample Labeling tool**](#tab/fott)

-When you train models using the [**Form Recognizer Sample Labeling tool**](https://fott-2-1.azurewebsites.net/), the model ID is located in the Train Result window:

-### [**REST API**](#tab/rest-api)

-The [**REST API**](./quickstarts/try-sdk-rest-api.md?pivots=programming-language-rest-api#train-a-custom-model) will return a `201 (Success)` response with a **Location** header. The value of the last parameter in this header is the model ID for the newly trained model:

-### [**Client-library SDKs**](#tab/sdks)

- The [**client-library SDKs**](./quickstarts/try-sdk-rest-api.md?pivots=programming-language-csharp#train-a-custom-model) return a model object that can be queried to return the trained model ID:

-* C\# | [CustomFormModel Class](/dotnet/api/azure.ai.formrecognizer.training.customformmodel?view=azure-dotnet&preserve-view=true#properties "Azure SDK for .NET")

-* Java | [CustomFormModelInfo Class](/java/api/com.azure.ai.formrecognizer.training.models.customformmodelinfo?view=azure-java-stable&preserve-view=true#methods "Azure SDK for Java")

-* JavaScript | CustomFormModelInfo interface

-* Python | [CustomFormModelInfo Class](/python/api/azure-ai-formrecognizer/azure.ai.formrecognizer.customformmodelinfo?view=azure-python&preserve-view=true&branch=main#variables "Azure SDK for Python")

-#### Compose your custom models

-After you've gathered your custom models corresponding to a single form type, you can compose them into a single model.

-### [**Form Recognizer Sample Labeling tool**](#tab/fott)

-The **Sample Labeling tool** enables you to quickly get started training models and composing them to a single model ID.

-After you have completed training, compose your models as follows:

-1. On the left rail menu, select the **Model Compose** icon (merging arrow).

-1. In the main window, select the models you wish to assign to a single model ID. Models with the arrows icon are already composed models.

-1. Choose the **Compose button** from the upper-left corner.

-1. In the pop-up window, name your newly composed model and select **Compose**.

-When the operation completes, your newly composed model will appear in the list.

- :::image type="content" source="media/custom-model-compose.png" alt-text="Screenshot of the model compose window." lightbox="media/custom-model-compose-expanded.png":::

-### [**REST API**](#tab/rest-api)

-Using the **REST API**, you can make a [**Compose Custom Model**](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-2022-08-31/operations/ComposeDocumentModel) request to create a single composed model from existing models. The request body requires a string array of your `modelIds` to compose and you can optionally define the `modelName`.

-### [**Client-library SDKs**](#tab/sdks)

-Use the programming language code of your choice to create a composed model that will be called with a single model ID. Below are links to code samples that demonstrate how to create a composed model from existing custom models:

-* [**C#/.NET**](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/formrecognizer/Azure.AI.FormRecognizer/samples/Sample_ModelCompose.md).

-* [**Java**](https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/formrecognizer/azure-ai-formrecognizer/src/samples/java/com/azure/ai/formrecognizer/administration/ComposeDocumentModel.java).

-* [**JavaScript**](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/formrecognizer/ai-form-recognizer/samples/v3/javascript/createComposedModel.js).

-* [**Python**](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/formrecognizer/azure-ai-formrecognizer/samples/v3.2/sample_compose_model.py)

-## Analyze documents with your custom or composed model

- The custom form **Analyze** operation requires you to provide the `modelID` in the call to Form Recognizer. You can provide a single custom model ID or a composed model ID for the `modelID` parameter.

-### [**Form Recognizer Sample Labeling tool**](#tab/fott)

-1. On the tool's left-pane menu, select the **Analyze icon** (light bulb).

-1. Choose a local file or image URL to analyze.

-1. Select the **Run Analysis** button.

-1. The tool will apply tags in bounding boxes and report the confidence percentage for each tag.

-### [**REST API**](#tab/rest-api)

-Using the REST API, you can make an [Analyze Document](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-2022-08-31/operations/AnalyzeDocument) request to analyze a document and extract key-value pairs and table data.

-### [**Client-library SDKs**](#tab/sdks)

-Using the programming language of your choice to analyze a form or document with a custom or composed model. You'll need your Form Recognizer endpoint, key, and model ID.

-* [**C#/.NET**](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/formrecognizer/Azure.AI.FormRecognizer/samples/Sample_ModelCompose.md)

-* [**Java**](https://github.com/Azure/azure-sdk-for-javocumentFromUrl.java)

-* [**JavaScript**](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/formrecognizer/ai-form-recognizer/samples/v3/javascript/recognizeCustomForm.js)

-* [**Python**](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/formrecognizer/azure-ai-formrecognizer/samples/v3.1/sample_recognize_custom_forms.py)

-Test your newly trained models by [analyzing forms](./quickstarts/try-sdk-rest-api.md#analyze-forms-with-a-custom-model) that weren't part of the training dataset. Depending on the reported accuracy, you may want to do further training to improve the model. You can continue further training to [improve results](label-tool.md#improve-results).

-## Manage your custom models

-You can [manage your custom models](./quickstarts/try-sdk-rest-api.md#manage-custom-models) throughout their lifecycle by viewing a [list of all custom models](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-2022-08-31/operations/GetModels) under your subscription, retrieving information about [a specific custom model](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-2022-08-31/operations/GetModel), and [deleting custom models](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-2022-08-31/operations/DeleteModel) from your account.

-Great! You've learned the steps to create custom and composed models and use them in your Form Recognizer projects and applications.

-## Next steps

-Learn more about the Form Recognizer client library by exploring our API reference documentation.

-> [!div class="nextstepaction"]

-> [Form Recognizer API reference](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-2022-08-31/operations/AnalyzeDocument)

->

-description: Learn how to create, use, and manage Form Recognizer v2.0 custom and composed models

-recommendations: false

-# Compose custom models v3.0

-> [!NOTE]

-> This how-to guide references Form Recognizer v3.0 . To use Form Recognizer v2.1 , see [Compose custom models v2.1](compose-custom-models-v2-1.md).

-A composed model is created by taking a collection of custom models and assigning them to a single model ID. You can assign up to 100 trained custom models to a single composed model ID. When a document is submitted to a composed model, the service performs a classification step to decide which custom model accurately represents the form presented for analysis. Composed models are useful when you've trained several models and want to group them to analyze similar form types. For example, your composed model might include custom models trained to analyze your supply, equipment, and furniture purchase orders. Instead of manually trying to select the appropriate model, you can use a composed model to determine the appropriate custom model for each analysis and extraction.

-To learn more, see [Composed custom models](concept-composed-models.md).

-In this article, you'll learn how to create and use composed custom models to analyze your forms and documents.

-## Prerequisites

-To get started, you'll need the following resources:

-* **An Azure subscription**. You can [create a free Azure subscription](https://azure.microsoft.com/free/cognitive-services/).

-* **A Form Recognizer instance**. Once you have your Azure subscription, [create a Form Recognizer resource](https://portal.azure.com/#create/Microsoft.CognitiveServicesFormRecognizer) in the Azure portal to get your key and endpoint. If you have an existing Form Recognizer resource, navigate directly to your resource page. You can use the free pricing tier (F0) to try the service, and upgrade later to a paid tier for production.

- 1. After the resource deploys, select **Go to resource**.

- 1. Copy the **Keys and Endpoint** values from the Azure portal and paste them in a convenient location, such as *Microsoft Notepad*. You'll need the key and endpoint values to connect your application to the Form Recognizer API.

- :::image border="true" type="content" source="media/containers/keys-and-endpoint.png" alt-text="Still photo showing how to access resource key and endpoint URL.":::

- > [!TIP]

- > For more information, see [**create a Form Recognizer resource**](create-a-form-recognizer-resource.md).

-* **An Azure storage account.** If you don't know how to create an Azure storage account, follow the [Azure Storage quickstart for Azure portal](../../storage/blobs/storage-quickstart-blobs-portal.md). You can use the free pricing tier (F0) to try the service, and upgrade later to a paid tier for production.

-## Create your custom models

-First, you'll need a set of custom models to compose. You can use the Form Recognizer Studio, REST API, or client-library SDKs. The steps are as follows:

-* [**Assemble your training dataset**](#assemble-your-training-dataset)

-* [**Upload your training set to Azure blob storage**](#upload-your-training-dataset)

-* [**Train your custom models**](#train-your-custom-model)

-## Assemble your training dataset

-Building a custom model begins with establishing your training dataset. You'll need a minimum of five completed forms of the same type for your sample dataset. They can be of different file types (jpg, png, pdf, tiff) and contain both text and handwriting. Your forms must follow the [input requirements](build-training-data-set.md#custom-model-input-requirements) for Form Recognizer.

->[!TIP]

-> Follow these tips to optimize your data set for training:

->

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

-> * For filled-in forms, use examples that have all of their fields filled in.

-> * Use forms with different values in each field.

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

-See [Build a training data set](./build-training-data-set.md) for tips on how to collect your training documents.

-## Upload your training dataset

-When you've gathered a set of training documents, you'll need to [upload your training data](build-training-data-set.md#upload-your-training-data) to an Azure blob storage container.

-If you want to use manually labeled data, you'll also have to upload the *.labels.json* and *.ocr.json* files that correspond to your training documents.

-## Train your custom model

-When you [train your model](https://formrecognizer.appliedai.azure.com/studio/custommodel/projects) with labeled data, the model uses supervised learning to extract values of interest, using the labeled forms you provide. Labeled data results in better-performing models and can produce models that work with complex forms or forms containing values without keys.

-Form Recognizer uses the [prebuilt-layout model](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-2022-08-31/operations/AnalyzeDocument) API to learn the expected sizes and positions of typeface and handwritten text elements and extract tables. Then it uses user-specified labels to learn the key/value associations and tables in the documents. We recommend that you use five manually labeled forms of the same type (same structure) to get started with training a new model. Then, add more labeled data, as needed, to improve the model accuracy. Form Recognizer enables training a model to extract key-value pairs and tables using supervised learning capabilities.

-### [Form Recognizer Studio](#tab/studio)

-To create custom models, start with configuring your project:

-1. From the Studio homepage, select [**Create new**](https://formrecognizer.appliedai.azure.com/studio/custommodel/projects) from the Custom model card.

-1. Use the Γ₧ò **Create a project** command to start the new project configuration wizard.

-1. Enter project details, select the Azure subscription and resource, and the Azure Blob storage container that contains your data.

-1. Review and submit your settings to create the project.

-While creating your custom models, you may need to extract data collections from your documents. The collections may appear one of two formats. Using tables as the visual pattern:

-* Dynamic or variable count of values (rows) for a given set of fields (columns)

-* Specific collection of values for a given set of fields (columns and/or rows)

-See [Form Recognizer Studio: labeling as tables](quickstarts/try-v3-form-recognizer-studio.md#labeling-as-tables)

-### [REST API](#tab/rest)

-Training with labels leads to better performance in some scenarios. To train with labels, you need to have special label information files (*\<filename\>.pdf.labels.json*) in your blob storage container alongside the training documents.

-Label files contain key-value associations that a user has entered manually. They're needed for labeled data training, but not every source file needs to have a corresponding label file. Source files without labels will be treated as ordinary training documents. We recommend five or more labeled files for reliable training. You can use a UI tool like [Form Recognizer Studio](https://formrecognizer.appliedai.azure.com/studio/customform/projects) to generate these files.

-Once you have your label files, you can include them with by calling the training method with the *useLabelFile* parameter set to `true`.

-### [Client-libraries](#tab/sdks)

-Training with labels leads to better performance in some scenarios. To train with labels, you need to have special label information files (*\<filename\>.pdf.labels.json*) in your blob storage container alongside the training documents. Once you've them, you can call the training method with the *useTrainingLabels* parameter set to `true`.

-|Language |Method|

-|--|--|

-|**C#**|**StartBuildModel**|

-|**Java**| [**beginBuildModel**](/java/api/com.azure.ai.formrecognizer.documentanalysis.administration.documentmodeladministrationclient.beginbuildmodel)|

-|**JavaScript** | [**beginBuildModel**](/javascript/api/@azure/ai-form-recognizer/documentmodeladministrationclient?view=azure-node-latest#@azure-ai-form-recognizer-documentmodeladministrationclient-beginbuildmodel&preserve-view=true)|

-| **Python** | [**begin_build_model**](/python/api/azure-ai-formrecognizer/azure.ai.formrecognizer.aio.documentmodeladministrationclient?view=azure-python#azure-ai-formrecognizer-aio-documentmodeladministrationclient-begin-build-model&preserve-view=true)

-## Create a composed model

-> [!NOTE]

-> **the `create compose model` operation is only available for custom models trained _with_ labels.** Attempting to compose unlabeled models will produce an error.

-With the [**create compose model**](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-2022-08-31/operations/ComposeDocumentModel) operation, you can assign up to 100 trained custom models to a single model ID. When analyze documents with a composed model, Form Recognizer first classifies the form you submitted, then chooses the best matching assigned model, and returns results for that model. This operation is useful when incoming forms may belong to one of several templates.

-### [Form Recognizer Studio](#tab/studio)

-Once the training process has successfully completed, you can begin to build your composed model. Here are the steps for creating and using composed models:

-* [**Gather your custom model IDs**](#gather-your-model-ids)

-* [**Compose your custom models**](#compose-your-custom-models)

-* [**Analyze documents**](#analyze-documents)

-* [**Manage your composed models**](#manage-your-composed-models)

-#### Gather your model IDs

-When you train models using the [**Form Recognizer Studio**](https://formrecognizer.appliedai.azure.com/), the model ID is located in the models menu under a project:

-#### Compose your custom models

-1. Select a custom models project.

-1. In the project, select the ```Models``` menu item.

-1. From the resulting list of models, select the models you wish to compose.

-1. Choose the **Compose button** from the upper-left corner.

-1. In the pop-up window, name your newly composed model and select **Compose**.

-1. When the operation completes, your newly composed model will appear in the list.

-1. Once the model is ready, use the **Test** command to validate it with your test documents and observe the results.

-#### Analyze documents

-The custom model **Analyze** operation requires you to provide the `modelID` in the call to Form Recognizer. You should provide the composed model ID for the `modelID` parameter in your applications.

-#### Manage your composed models

-You can manage your custom models throughout life cycles:

-* Test and validate new documents.

-* Download your model to use in your applications.

-* Delete your model when its lifecycle is complete.

-### [REST API](#tab/rest)

-Once the training process has successfully completed, you can begin to build your composed model. Here are the steps for creating and using composed models:

-* [**Compose your custom models**](#compose-your-custom-models)

-* [**Analyze documents**](#analyze-documents)

-* [**Manage your composed models**](#manage-your-composed-models)

-#### Compose your custom models

-The [compose model API](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-2022-08-31/operations/ComposeDocumentModel) accepts a list of model IDs to be composed.

-#### Analyze documents

-To make an [**Analyze document**](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-2022-08-31/operations/AnalyzeDocument) request, use a unique model name in the request parameters.

-#### Manage your composed models

-You can manage custom models throughout your development needs including [**copying**](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-2022-08-31/operations/CopyDocumentModelTo), [**listing**](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-2022-08-31/operations/GetModels), and [**deleting**](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-2022-08-31/operations/DeleteModel) your models.

-### [Client-libraries](#tab/sdks)

-Once the training process has successfully completed, you can begin to build your composed model. Here are the steps for creating and using composed models:

-* [**Create a composed model**](#create-a-composed-model)

-* [**Analyze documents**](#analyze-documents)

-* [**Manage your composed models**](#manage-your-composed-models)

-#### Create a composed model

-You can use the programming language of your choice to create a composed model:

-| Programming language| Code sample |

-|--|--|

-|**C#** | [Model compose](https://github.com/Azure/azure-sdk-for-net/blob/Azure.AI.FormRecognizer_4.0.0/sdk/formrecognizer/Azure.AI.FormRecognizer/samples/Sample_ModelCompose.md)

-|**Java** | [Model compose](https://github.com/Azure/azure-sdk-for-java/blob/afa0d44fa42979ae9ad9b92b23cdba493a562127/sdk/formrecognizer/azure-ai-formrecognizer/src/samples/java/com/azure/ai/formrecognizer/administration/ComposeDocumentModel.java)

-|**JavaScript** | [Compose model](https://github.com/witemple-msft/azure-sdk-for-js/blob/7e3196f7e529212a6bc329f5f06b0831bf4cc174/sdk/formrecognizer/ai-form-recognizer/samples/v4/javascript/composeModel.js)

-|**Python** | [Create composed model](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/formrecognizer/azure-ai-formrecognizer/samples/v3.2/sample_compose_model.py)

-#### Analyze documents

-Once you've built your composed model, you can use it to analyze forms and documents. Use your composed `model ID` and let the service decide which of your aggregated custom models fits best according to the document provided.

-|Programming language| Code sample |

-|--|--|

-|**C#** | [Analyze a document with a custom/composed model using model ID](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/formrecognizer/Azure.AI.FormRecognizer/samples/Sample_AnalyzeWithCustomModel.md)

-|**Java** | [Analyze a document with a custom/composed model using model ID](https://github.com/Azure/azure-sdk-for-javocumentFromUrl.java)

-|**JavaScript** | [Analyze a document with a custom/composed model using model ID](https://github.com/witemple-msft/azure-sdk-for-js/blob/7e3196f7e529212a6bc329f5f06b0831bf4cc174/sdk/formrecognizer/ai-form-recognizer/samples/v4/javascript/analyzeDocumentByModelId.js)

-|**Python** | [Analyze a document with a custom/composed model using model ID](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/formrecognizer/azure-ai-formrecognizer/samples/v3.2/sample_analyze_custom_documents.py)

-## Manage your composed models

-You can manage a custom model at each stage in its life cycles. You can copy a custom model between resources, view a list of all custom models under your subscription, retrieve information about a specific custom model, and delete custom models from your account.

-|Programming language| Code sample |

-|--|--|

-|**C#** | [Copy a custom model between Form Recognizer resources](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/formrecognizer/Azure.AI.FormRecognizer/samples/Sample_CopyCustomModel.md#copy-a-custom-model-between-form-recognizer-resources)|

-|**Java** | [Copy a custom model between Form Recognizer resources](https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/formrecognizer/azure-ai-formrecognizer/src/samples/java/com/azure/ai/formrecognizer/administration/CopyDocumentModel.java)|

-|**JavaScript** | [Copy a custom model between Form Recognizer resources](https://github.com/witemple-msft/azure-sdk-for-js/blob/7e3196f7e529212a6bc329f5f06b0831bf4cc174/sdk/formrecognizer/ai-form-recognizer/samples/v4/javascript/copyModel.js)|

-|**Python** | [Copy a custom model between Form Recognizer resources](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/formrecognizer/azure-ai-formrecognizer/samples/v3.2/sample_copy_model_to.py)|

-## Next steps

-Try one of our Form Recognizer quickstarts:

-> [!div class="nextstepaction"]

-> [Form Recognizer Studio](quickstarts/try-v3-form-recognizer-studio.md)

-> [!div class="nextstepaction"]

-> [REST API](quickstarts/get-started-v3-sdk-rest-api.md)

-> [!div class="nextstepaction"]

-> [C#](quickstarts/get-started-v3-sdk-rest-api.md#prerequisites)

-> [!div class="nextstepaction"]

-> [Java](quickstarts/get-started-v3-sdk-rest-api.md)

-> [!div class="nextstepaction"]

-> [JavaScript](quickstarts/get-started-v3-sdk-rest-api.md)

-> [!div class="nextstepaction"]

-> [Python](quickstarts/get-started-v3-sdk-rest-api.md)

- * If the documents are dissimilar, split your training data into different folders and train a model for each variation. You can then [compose](compose-custom-models-v2-1.md#create-a-composed-model) the different variations into a single model.

-|**Business card model**| <ul><li>[**Form Recognizer Studio**](https://formrecognizer.appliedai.azure.com)</li><li>[**REST API**](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-2022-08-31/operations/AnalyzeDocument)</li><li>[**C# SDK**](quickstarts/get-started-v3-sdk-rest-api.md)</li><li>[**Python SDK**](quickstarts/get-started-v3-sdk-rest-api.md)</li><li>[**Java SDK**](quickstarts/get-started-v3-sdk-rest-api.md)</li><li>[**JavaScript SDK**](quickstarts/get-started-v3-sdk-rest-api.md)</li></ul>|**prebuilt-businessCard**|

-|Custom model type |Models trained with version 2.1 and v2.0 | Custom template models (3.0) preview | Custom neural models 3.0 Preview |Custom neural models 3.0 GA|

-| Models trained with version 2.1 and v2.0 | Supported | Supported | Not Supported | Not Supported |

-| Custom template models (3.0) preview | Supported |Supported | Not Supported | Not Supported |

-| Custom template models 3.0 GA | Not Supported |Not Supported | Supported | Not Supported |

-| Custom neural models 3.0 Preview | Not Supported | NotSupported | Supported | Not Supported |

-|Custom Neural models 3.0 GA| Not Supported | NotSupported |NotSupported |Supported |

-|_**Custom model**_| <ul><li>[Form Recognizer Studio](https://formrecognizer.appliedai.azure.com/studio/custommodel/projects)</li><li>[REST API](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-2022-08-31/operations/AnalyzeDocument)</li><li>[C# SDK](quickstarts/get-started-v3-sdk-rest-api.md)</li><li>[Java SDK](quickstarts/get-started-v3-sdk-rest-api.md)</li><li>[JavaScript SDK](quickstarts/get-started-v3-sdk-rest-api.md)</li><li>[Python SDK](quickstarts/get-started-v3-sdk-rest-api.md)</li></ul>|

-> [**Form Recognizer v2.1**](compose-custom-models-v2-1.md)

-| Custom document | [Form Recognizer 3.0 ](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-2022-08-31/operations/AnalyzeDocument)| [Form Recognizer SDK](quickstarts/get-started-v3-sdk-rest-api.md)| [Form Recognizer Studio](https://formrecognizer.appliedai.azure.com/studio)

-* Train a custom model:

- > [!div class="nextstepaction"]

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

-* Learn more about custom template models:

- > [!div class="nextstepaction"]

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

-* View the REST API:

- > [!div class="nextstepaction"]

- > [Form Recognizer API v3.0](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-2022-08-31/operations/AnalyzeDocument)

-| Custom template | [Form Recognizer 3.0 ](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-2022-08-31/operations/AnalyzeDocument)| [Form Recognizer SDK](quickstarts/get-started-v3-sdk-rest-api.md)| [Form Recognizer Studio](https://formrecognizer.appliedai.azure.com/studio)|

-* * Train a custom model:

- > [!div class="nextstepaction"]

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

-* Learn more about custom neural models:

- > [!div class="nextstepaction"]

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

-* View the REST API:

- > [!div class="nextstepaction"]

- > [Form Recognizer API v2.1](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-v2-1/operations/AnalyzeWithCustomForm)

-|Custom model| <ul><li>[Form Recognizer Studio](https://formrecognizer.appliedai.azure.com/studio/customform/projects)</li><li>[REST API](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-2022-08-31/operations/AnalyzeDocument)</li><li>[C# SDK](quickstarts/get-started-v3-sdk-rest-api.md)</li><li>[Python SDK](quickstarts/get-started-v3-sdk-rest-api.md)</li></ul>|***custom-model-id***|

-| Custom template 3.0 | [Form Recognizer 3.0 ](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-2022-08-31/operations/AnalyzeDocument)| [Form Recognizer SDK](quickstarts/get-started-v3-sdk-rest-api.md)| [Form Recognizer Studio](https://formrecognizer.appliedai.azure.com/studio)|

-| Custom neural | [Form Recognizer 3.0 ](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-2022-08-31/operations/AnalyzeDocument)| [Form Recognizer SDK](quickstarts/get-started-v3-sdk-rest-api.md)| [Form Recognizer Studio](https://formrecognizer.appliedai.azure.com/studio)

-[Form Recognizer Studio](https://formrecognizer.appliedai.azure.com/) is an online tool for visually exploring, understanding, and integrating features from the Form Recognizer service into your applications. Use the [Form Recognizer Studio quickstart](quickstarts/try-v3-form-recognizer-studio.md) to get started analyzing documents with pre-trained models. Build custom template models and reference the models in your applications using the [Python SDK v3.0](quickstarts/get-started-v3-sdk-rest-api.md) and other quickstarts.

-* **Read**: Try out Form Recognizer's Read feature to extract text lines, words, detected languages, and handwritten style if detected. Start with the [Studio Read feature](https://formrecognizer.appliedai.azure.com/studio/read). Explore with sample documents and your documents. Use the interactive visualization and JSON output to understand how the feature works. See the [Read overview](concept-read.md) to learn more and get started with the [Python SDK quickstart for Layout](quickstarts/get-started-v3-sdk-rest-api.md).

-* **Layout**: Try out Form Recognizer's Layout feature to extract text, tables, selection marks, and structure information. Start with the [Studio Layout feature](https://formrecognizer.appliedai.azure.com/studio/layout). Explore with sample documents and your documents. Use the interactive visualization and JSON output to understand how the feature works. See the [Layout overview](concept-layout.md) to learn more and get started with the [Python SDK quickstart for Layout](quickstarts/get-started-v3-sdk-rest-api.md#layout-model).

-* **General Documents**: Try out Form Recognizer's General Documents feature to extract key-value pairs and entities. Start with the [Studio General Documents feature](https://formrecognizer.appliedai.azure.com/studio/document). Explore with sample documents and your documents. Use the interactive visualization and JSON output to understand how the feature works. See the [General Documents overview](concept-general-document.md) to learn more and get started with the [Python SDK quickstart for Layout](quickstarts/get-started-v3-sdk-rest-api.md#general-document-model).

-* **Prebuilt models**: Form Recognizer's pre-built models enable you to add intelligent document processing to your apps and flows without having to train and build your own models. As an example, start with the [Studio Invoice feature](https://formrecognizer.appliedai.azure.com/studio/prebuilt?formType=invoice). Explore with sample documents and your documents. Use the interactive visualization, extracted fields list, and JSON output to understand how the feature works. See the [Models overview](concept-model-overview.md) to learn more and get started with the [Python SDK quickstart for Prebuilt Invoice](quickstarts/get-started-v3-sdk-rest-api.md#prebuilt-model).

-* Explore our [**v3.0 SDK quickstarts**](quickstarts/get-started-v3-sdk-rest-api.md) to try the v3.0 features in your applications using the new SDKs.

-* Refer to our [**v3.0 REST API quickstarts**](quickstarts/get-started-v3-sdk-rest-api.md) to try the v3.0features using the new REST API.

-| **General document model**|<ul ><li>[**Form Recognizer Studio**](https://formrecognizer.appliedai.azure.com)</li><li>[**REST API**](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-2022-08-31/operations/AnalyzeDocument)</li><li>[**C# SDK**](quickstarts/get-started-v3-sdk-rest-api.md)</li><li>[**Python SDK**](quickstarts/get-started-v3-sdk-rest-api.md)</li><li>[**Java SDK**](quickstarts/get-started-v3-sdk-rest-api.md)</li><li>[**JavaScript SDK**](quickstarts/get-started-v3-sdk-rest-api.md)</li></ul>|**prebuilt-document**|

-Keys can also exist in isolation when the model detects that a key exists, with no associated value or when processing optional fields. For example, a middle name field may be left blank on a form in some instances. Key-value pairs are spans of text contained in the document. If you have documents where the same value is described in different ways, for example, customer and user, the associated key will be either customer or user, based on context.

-|**ID document model**|<ul><li> [**Form Recognizer Studio**](https://formrecognizer.appliedai.azure.com)</li><li>[**REST API**](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-2022-08-31/operations/AnalyzeDocument)</li><li>[**C# SDK**](quickstarts/get-started-v3-sdk-rest-api.md)</li><li>[**Python SDK**](quickstarts/get-started-v3-sdk-rest-api.md)</li><li>[**Java SDK**](quickstarts/get-started-v3-sdk-rest-api.md)</li><li>[**JavaScript SDK**](quickstarts/get-started-v3-sdk-rest-api.md)</li></ul>|**prebuilt-idDocument**|

-|**Invoice model** | <ul><li>[**Form Recognizer Studio**](https://formrecognizer.appliedai.azure.com)</li><li>[**REST API**](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-2022-08-31/operations/AnalyzeDocument)</li><li>[**C# SDK**](quickstarts/get-started-v3-sdk-rest-api.md)</li><li>[**Python SDK**](quickstarts/get-started-v3-sdk-rest-api.md)</li><li>[**Java SDK**](quickstarts/get-started-v3-sdk-rest-api.md)</li><li>[**JavaScript SDK**](quickstarts/get-started-v3-sdk-rest-api.md)</li></ul>|**prebuilt-invoice**|

-Keys can also exist in isolation when the model detects that a key exists, with no associated value or when processing optional fields. For example, a middle name field may be left blank on a form in some instances. key-value pairs are always spans of text contained in the document. If you have documents where the same value is described in different ways, for example, a customer or a user, the associated key will be either customer or user based on context.

-|**Layout model**| <ul><li>[**Form Recognizer Studio**](https://formrecognizer.appliedai.azure.com)</li><li>[**REST API**](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-2022-08-31/operations/AnalyzeDocument)</li><li>[**C# SDK**](quickstarts/get-started-v3-sdk-rest-api.md)</li><li>[**Python SDK**](quickstarts/get-started-v3-sdk-rest-api.md)</li><li>[**Java SDK**](quickstarts/get-started-v3-sdk-rest-api.md)</li><li>[**JavaScript SDK**](quickstarts/get-started-v3-sdk-rest-api.md)</li></ul>|**prebuilt-layout**|

- {

- "spans": [],

- "boundingRegions": [],

- "content": "While healthcare is still in the early stages of its Al journey, we are seeing pharmaceutical and other life sciences organizations making major investments in Al and related technologies.\" TOM LAWRY | National Director for Al, Health and Life Sciences | Microsoft"

- }

- {

- "pageNumber": 1,

- "angle": 0,

- "width": 915,

- "height": 1190,

- "unit": "pixel",

- "words": [],

- "lines": [],

- "spans": [],

- "kind": "document"

- }

-|**prebuilt-read**| <ul><li>[**Form Recognizer Studio**](https://formrecognizer.appliedai.azure.com)</li><li>[**REST API**](how-to-guides/v3-0-sdk-rest-api.md)</li><li>[**C# SDK**](how-to-guides/v3-0-sdk-rest-api.md?pivots=programming-language-csharp)</li><li>[**Python SDK**](how-to-guides/v3-0-sdk-rest-api.md?pivots=programming-language-python)</li><li>[**Java SDK**](how-to-guides/v3-0-sdk-rest-api.md?pivots=programming-language-java)</li><li>[**JavaScript**](how-to-guides/v3-0-sdk-rest-api.md?pivots=programming-language-javascript)</li></ul>|**prebuilt-read**|

-Use the parameter `api-version=2022-06-30-preview when using the REST API or the corresponding SDKs of that API version to preview the support for Microsoft Word, Excel, PowerPoint, and HTML files.

-> * [**REST API**](how-to-guides/v3-0-sdk-rest-api.md)

-> * [**C# SDK**](how-to-guides/v3-0-sdk-rest-api.md?pivots=programming-language-csharp)

-> * [**Python SDK**](how-to-guides/v3-0-sdk-rest-api.md?pivots=programming-language-python)

-> * [**Java SDK**](how-to-guides/v3-0-sdk-rest-api.md?pivots=programming-language-java)

-> * [**JavaScript**](how-to-guides/v3-0-sdk-rest-api.md?pivots=programming-language-javascript)</li></ul>

-|**Receipt model**| <ul><li>[**Form Recognizer Studio**](https://formrecognizer.appliedai.azure.com)</li><li>[**REST API**](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-2022-08-31/operations/AnalyzeDocument)</li><li>[**C# SDK**](quickstarts/get-started-v3-sdk-rest-api.md)</li><li>[**Python SDK**](quickstarts/get-started-v3-sdk-rest-api.md)</li></ul>|**prebuilt-receipt**|

-|**W-2 model**|<ul><li> [**Form Recognizer Studio**](https://formrecognizer.appliedai.azure.com)</li><li>[**REST API**](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-2022-08-31/operations/AnalyzeDocument)</li><li>[**C# SDK**](quickstarts/get-started-v3-sdk-rest-api.md#prebuilt-model)</li><li>[**Python SDK**](quickstarts/get-started-v3-sdk-rest-api.md#prebuilt-model)</li><li>[**Java SDK**](quickstarts/get-started-v3-sdk-rest-api.md#prebuilt-model)</li><li>[**JavaScript SDK**](quickstarts/get-started-v3-sdk-rest-api.md#prebuilt-model)</li></ul>|**prebuilt-tax.us.w2**|

-> * [**REST API**](quickstarts/get-started-v3-sdk-rest-api.md)

-> * [**C# SDK**](quickstarts/get-started-v3-sdk-rest-api.md#prebuilt-model)

-> * [**Python SDK**](quickstarts/get-started-v3-sdk-rest-api.md#prebuilt-model)

-> * [**Java SDK**](quickstarts/get-started-v3-sdk-rest-api.md#prebuilt-model)

-> * [**JavaScript**](quickstarts/get-started-v3-sdk-rest-api.md#prebuilt-model)</li></ul>

- * [C#](quickstarts/get-started-v3-sdk-rest-api.md)

- * [Python](quickstarts/get-started-v3-sdk-rest-api.md)

- * [Java](quickstarts/get-started-v3-sdk-rest-api.md)

- * [JavaScript](quickstarts/get-started-v3-sdk-rest-api.md)

-> * *See* our [**REST API**](quickstarts/get-started-v3-sdk-rest-api.md) or [**C#**](quickstarts/get-started-v3-sdk-rest-api.md), [**Java**](quickstarts/get-started-v3-sdk-rest-api.md), [**JavaScript**](quickstarts/get-started-v3-sdk-rest-api.md), or [Python](quickstarts/get-started-v3-sdk-rest-api.md) SDK quickstarts to get started with the v3.0 version.

-1. After you've tried Form Recognizer Studio, use the [**C#**](quickstarts/get-started-v3-sdk-rest-api.md), [**Java**](quickstarts/get-started-v3-sdk-rest-api.md), [**JavaScript**](quickstarts/get-started-v3-sdk-rest-api.md) or [**Python**](quickstarts/get-started-v3-sdk-rest-api.md) client libraries or the [**REST API**](quickstarts/get-started-v3-sdk-rest-api.md) to get started incorporating Form Recognizer models into your own applications.

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

-# Build your training dataset for a custom model

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

-## Custom model input requirements

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

-## Training data tips

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

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

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

-* Use forms with different values in each field.

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

-## Upload your training data

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

-## Create a project in the Form Recognizer Studio

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

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

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

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

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

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

- > [!IMPORTANT]

- > Custom neural models models are only available in a few regions. If you plan on training a neural model, please select or create a resource in one of [these supported regions](../concept-custom-neural.md#supported-regions).

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

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

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

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

-## Label your data

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

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

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

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

-1. Enter a name for the field.

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

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

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

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

-## Train your model

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

-1. On the train model dialog, provide a unique model ID and, optionally, a description. The model ID accepts a string data type.

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

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

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

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

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

-## Test the model

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

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

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

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

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

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

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

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

-## Next steps

-> [!div class="nextstepaction"]

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

-> [!div class="nextstepaction"]

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

-description: How to use a Form Recognizer SDKs or REST API (v2.1) to create apps that extract key data from documents.

-zone_pivot_groups: programming-languages-set-formre

-recommendations: false

-<!-- markdownlint-disable MD051 -->

-# Use Form Recognizer SDKs or REST API | v2.1

- In this how-to guide, you'll learn how to add Form Recognizer to your applications and workflows using an SDK, in a programming language of your choice, or the REST API. Azure Form Recognizer is a cloud-based Azure Applied AI Service that uses machine learning to extract key-value pairs, text, and tables from your documents. We recommend that you use the free service when you're learning the technology. Remember that the number of free pages is limited to 500 per month.

-You'll use the following APIs to extract structured data from forms and documents:

-* [Authenticate the client](#authenticate-the-client)

-* [Analyze Layout](#analyze-layout)

-* [Analyze receipts](#analyze-receipts)

-* [Analyze business cards](#analyze-business-cards)

-* [Analyze invoices](#analyze-invoices)

-* [Analyze ID documents](#analyze-id-documents)

-* [Train a custom model](#train-a-custom-model)

-* [Analyze forms with a custom model](#analyze-forms-with-a-custom-model)

-* [Manage custom models](#manage-custom-models)

-description: How to use Form Recognizer SDKs or REST API (v3.0) to create apps to extract key data from documents.

-zone_pivot_groups: programming-languages-set-formre

-recommendations: false

-<!-- markdownlint-disable MD051 -->

-# Use Form Recognizer SDKs or REST API | v3.0

- In this guide, you'll learn how to add Form Recognizer to your applications and workflows using a programming language SDK of your choice or the REST API. Azure Form Recognizer is a cloud-based Azure Applied AI Service that uses machine learning to extract key text and structure elements from documents. We recommend that you use the free service as you're learning the technology. Remember that the number of free pages is limited to 500 per month.

-Choose from the following Form Recognizer models to analyze and extract data and values from forms and documents:

-> [!div class="checklist"]

->

-> * The [prebuilt-read](../concept-read.md) model is at the core of all Form Recognizer models and can detect lines, words, locations, and languages. Layout, general document, prebuilt, and custom models all use the read model as a foundation for extracting texts from documents.

->

-> * The [prebuilt-layout](../concept-layout.md) model extracts text and text locations, tables, selection marks, and structure information from documents and images.

->

-> * The [prebuilt-document](../concept-general-document.md) model extracts key-value pairs, tables, and selection marks from documents and can be used as an alternative to training a custom model without labels.

->

-> * The [prebuilt-tax.us.w2](../concept-w2.md) model extracts information reported on US Internal Revenue Service (IRS) tax forms.

->

-> * The [prebuilt-invoice](../concept-invoice.md) model extracts key fields and line items from sales invoices in various formats and quality including phone-captured images, scanned documents, and digital PDFs.

->

-> * The [prebuilt-receipt](../concept-receipt.md) model extracts key information from printed and handwritten sales receipts.

->

-> * The [prebuilt-idDocument](../concept-id-document.md) model extracts key information from US drivers licenses, international passport biographical pages, US state IDs, social security cards, and permanent resident (green) cards.

->

-> * The [prebuilt-businessCard](../concept-business-card.md) model extracts key information from business card images.

-## Next steps

-Congratulations! You've learned to use Form Recognizer models to analyze various documents in different ways. Next, explore the Form Recognizer Studio and reference documentation.

->[!div class="nextstepaction"]

-> [**Try the Form Recognizer Studio**](https://formrecognizer.appliedai.azure.com/studio)

-> [!div class="nextstepaction"]

-> [**Explore the Form Recognizer REST API v3.0**](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-2022-08-31/operations/AnalyzeDocument)

-keywords: document processing

-> * *See* our [**REST API**](quickstarts/get-started-v3-sdk-rest-api.md) or [**C#**](quickstarts/get-started-v3-sdk-rest-api.md), [**Java**](quickstarts/get-started-v3-sdk-rest-api.md), [**JavaScript**](quickstarts/get-started-v3-sdk-rest-api.md), or [Python](quickstarts/get-started-v3-sdk-rest-api.md) SDK quickstarts to get started with the V3.0.

-The following lists include the currently GA languages in for the v2.1 version and the most recent v3.0 version. These languages are supported by Read, Layout, and Custom form (template) model features.

-To use the v3.0-supported languages, refer to the [v3.0 REST API migration guide](v3-migration-guide.md) to understand the differences from the v2.1 GA API and explore the [v3.0 SDK and REST API quickstarts](quickstarts/get-started-v3-sdk-rest-api.md).

-### Handwritten text (v3.0 and v2.1)

-### Print text

-This section lists the supported languages for extracting printed texts using version v3.0.

-|Angika (Devanagari) | `anp`|Lakota | `lkt`

-|Arabic | `ar`|Latin | `la`

-|Awadhi-Hindi (Devanagari) | `awa`|Lithuanian | `lt`

-|Azerbaijani (Latin) | `az`|Lower Sorbian | `dsb`

-|Bagheli | `bfy`|Lule Sami | `smj`

-|Belarusian (Cyrillic) | `be`, `be-cyrl`|Mahasu Pahari (Devanagari) | `bfz`

-|Belarusian (Latin) | `be`, `be-latn`|Maltese | `mt`

-|Bhojpuri-Hindi (Devanagari) | `bho`|Malto (Devanagari) | `kmj`

-|Bodo (Devanagari) | `brx`|Maori | `mi`

-|Bosnian (Latin) | `bs`|Marathi | `mr`

-|Brajbha | `bra`|Mongolian (Cyrillic) | `mn`

-|Bulgarian | `bg`|Montenegrin (Cyrillic) | `cnr-cyrl`

-|Bundeli | `bns`|Montenegrin (Latin) | `cnr-latn`

-|Buryat (Cyrillic) | `bua`|Nepali | `ne`

-|Chamling | `rab`|Niuean | `niu`

-|Chhattisgarhi (Devanagari)| `hne`|Nogay | `nog`

-|Croatian | `hr`|Northern Sami (Latin) | `sme`

-|Dari | `prs`|Ossetic | `os`

-|Dhimal (Devanagari) | `dhi`|Pashto | `ps`

-|Dogri (Devanagari) | `doi`|Persian | `fa`

-|Erzya (Cyrillic) | `myv`|Punjabi (Arabic) | `pa`

-|Faroese | `fo`|Ripuarian | `ksh`

-|Gagauz (Latin) | `gag`|Romanian | `ro`

-|Gondi (Devanagari) | `gon`|Russian | `ru`

-|Gurung (Devanagari) | `gvr`|Sadri (Devanagari) | `sck`

-|Halbi (Devanagari) | `hlb`|Samoan (Latin) | `sm`

-|Haryanvi | `bgc`|Sanskrit (Devanagari) | `sa`

-|Hawaiian | `haw`|Santali(Devanagiri) | `sat`

-|Hindi | `hi`|Serbian (Latin) | `sr`, `sr-latn`

-|Ho(Devanagiri) | `hoc`|Sherpa (Devanagari) | `xsr`

-|Icelandic | `is`|Sirmauri (Devanagari) | `srx`

-|Inari Sami | `smn`|Skolt Sami | `sms`

-|Jaunsari (Devanagari) | `Jns`|Slovak | `sk`

-|Kangri (Devanagari) | `xnr`|Somali (Arabic) | `so`

-|Karachay-Balkar | `krc`|Southern Sami | `sma`

-|Kara-Kalpak (Cyrillic) | `kaa-cyrl`|Tajik (Cyrillic) | `tg`

-|Kazakh (Cyrillic) | `kk-cyrl`|Thangmi | `thf`

-|Kazakh (Latin) | `kk-latn`|Tongan | `to`

-|Khaling | `klr`|Turkmen (Latin) | `tk`

-|Korku | `kfq`|Tuvan | `tyv`

-|Koryak | `kpy`|Urdu | `ur`

-|Kosraean | `kos`|Uyghur (Arabic) | `ug`

-|Kumyk (Cyrillic) | `kum`|Uzbek (Arabic) | `uz-arab`

-|Kurdish (Arabic) | `ku-arab`|Uzbek (Cyrillic) | `uz-cyrl`

-|Kurukh (Devanagari) | `kru`|Welsh | `cy`

-|Kyrgyz (Cyrillic) | `ky`

-### Print text

-This section lists the supported languages for extracting printed texts in the latest GA version.

-|Afrikaans|`af`|Japanese | `ja` |

-|Albanian |`sq`|Javanese | `jv` |

-|Asturian |`ast`|K'iche' | `quc` |

-|Basque |`eu`|Kabuverdianu | `kea` |

-|Bislama |`bi`|Kachin (Latin) | `kac` |

-|Breton |`br`|Kara-Kalpak (Latin) | `kaa` |

-|Catalan |`ca`|Kashubian | `csb` |

-|Cebuano |`ceb`|Khasi | `kha` |

-|Chamorro |`ch`|Korean | `ko` |

-|Chinese Simplified | `zh-Hans`|Kurdish (Latin) | `ku-latn`

-|Chinese Traditional | `zh-Hant`|Luxembourgish | `lb` |

-|Cornish |`kw`|Malay (Latin) | `ms` |

-|Corsican |`co`|Manx | `gv` |

-|Crimean Tatar (Latin)|`crh`|Neapolitan | `nap` |

-|Czech | `cs` |Norwegian | `no` |

-|Danish | `da` |Occitan | `oc` |

-|Dutch | `nl` |Polish | `pl` |

-|English | `en` |Portuguese | `pt` |

-|Estonian |`et`|Romansh | `rm` |

-|Fijian |`fj`|Scots | `sco` |

-|Filipino |`fil`|Scottish Gaelic | `gd` |

-|Finnish | `fi` |Slovenian | `sl` |

-|French | `fr` |Spanish | `es` |

-|Friulian | `fur` |Swahili (Latin) | `sw` |

-|Galician | `gl` |Swedish | `sv` |

-|German | `de` |Tatar (Latin) | `tt` |

-|Gilbertese | `gil` |Tetum | `tet` |

-|Greenlandic | `kl` |Turkish | `tr` |

-|Haitian Creole | `ht` |Upper Sorbian | `hsb` |

-|Hani | `hni` |Uzbek (Latin) | `uz` |

-|Hmong Daw (Latin)| `mww` |Volap├╝k | `vo` |

-|Hungarian | `hu` |Walser | `wae` |

-|Indonesian | `id` |Western Frisian | `fy` |

-|Interlingua | `ia` |Yucatec Maya | `yua` |

-|Inuktitut (Latin) | `iu` |Zhuang | `za` |

-|Irish | `ga` |Zulu | `zu` |

-|Italian | `it` |

-### [Form Recognizer v3.0](#tab/v3-0)

-The following models and development options are supported by the Form Recognizer service v3.0. You can Use Form Recognizer to automate your data processing in applications and workflows, enhance data-driven strategies, and enrich document search capabilities. Use the links in the table to learn more about each model and browse the API references.

-|[ **Read**](concept-read.md)|Extract text lines, words, detected languages, and handwritten style if detected.| <ul><li>Contract processing. </li><li>Financial or medical report processing.</li></ul>|<ul ><li>[**Form Recognizer Studio**](https://formrecognizer.appliedai.azure.com/studio/read)</li><li>[**REST API**](how-to-guides/v3-0-sdk-rest-api.md)</li><li>[**C# SDK**](how-to-guides/v3-0-sdk-rest-api.md?pivots=programming-language-csharp)</li><li>[**Python SDK**](how-to-guides/v3-0-sdk-rest-api.md?pivots=programming-language-python)</li><li>[**Java SDK**](how-to-guides/v3-0-sdk-rest-api.md?pivots=programming-language-java)</li><li>[**JavaScript**](how-to-guides/v3-0-sdk-rest-api.md?pivots=programming-language-javascript)</li></ul> |

-|[**General document model**](concept-general-document.md)|Extract text, tables, structure, and key-value pairs.|<ul><li>Key-value pair extraction.</li><li>Form processing.</li><li>Survey data collection and analysis.</li></ul>|<ul ><li>[**Form Recognizer Studio**](https://formrecognizer.appliedai.azure.com/studio/document)</li><li>[**REST API**](quickstarts/get-started-v3-sdk-rest-api.md)</li><li>[**C# SDK**](quickstarts/get-started-v3-sdk-rest-api.md#general-document-model)</li><li>[**Python SDK**](quickstarts/get-started-v3-sdk-rest-api.md#general-document-model)</li><li>[**Java SDK**](quickstarts/get-started-v3-sdk-rest-api.md#general-document-model)</li><li>[**JavaScript**](quickstarts/get-started-v3-sdk-rest-api.md#general-document-model)</li></ul> |

-|[**Layout model**](concept-layout.md) | Extract text, selection marks, and tables structures, along with their bounding box coordinates, from forms and documents.</br></br> Layout API has been updated to a prebuilt model. |<ul><li>Document indexing and retrieval by structure.</li><li>Preprocessing prior to OCR analysis.</li></ul> |<ul><li>[**Form Recognizer Studio**](https://formrecognizer.appliedai.azure.com/studio/layout)</li><li>[**REST API**](quickstarts/get-started-v3-sdk-rest-api.md)</li><li>[**C# SDK**](quickstarts/get-started-v3-sdk-rest-api.md#layout-model)</li><li>[**Python SDK**](quickstarts/get-started-v3-sdk-rest-api.md#layout-model)</li><li>[**Java SDK**](quickstarts/get-started-v3-sdk-rest-api.md#layout-model)</li><li>[**JavaScript**](quickstarts/get-started-v3-sdk-rest-api.md#layout-model)</li></ul>|

-|[**Custom model (updated)**](concept-custom.md) | Extraction and analysis of data from forms and documents specific to distinct business data and use cases.</br></br>Custom model API v3.0 supports **signature detection for custom template (custom form) models**.</br></br>Custom model API v3.0 now supports two model types:ul><li>[**Custom Template model**](concept-custom-template.md) (custom form) is used to analyze structured and semi-structured documents.</li><li> [**Custom Neural model**](concept-custom-neural.md) (custom document) is used to analyze unstructured documents.</li></ul>|<ul><li>Identification and compilation of data, unique to your business, impacted by a regulatory change or market event.</li><li>Identification and analysis of previously overlooked unique data.</li></ul> |[**Form Recognizer Studio**](https://formrecognizer.appliedai.azure.com/studio/custommodel/projects)</li><li>[**REST API**](quickstarts/get-started-v3-sdk-rest-api.md)</li><li>[**C# SDK**](quickstarts/get-started-v3-sdk-rest-api.md)</li><li>[**Python SDK**](quickstarts/get-started-v3-sdk-rest-api.md)</li><li>[**Java SDK**](quickstarts/get-started-v3-sdk-rest-api.md)</li><li>[**JavaScript**](quickstarts/get-started-v3-sdk-rest-api.md)</li></ul>|

-|[ **W-2 Form**](concept-w2.md) | Extract information reported in each box on a W-2 form.|<ul><li>Automated tax document management.</li><li>Mortgage loan application processing.</li></ul> |<ul ><li>[**Form Recognizer Studio**](https://formrecognizer.appliedai.azure.com/studio/prebuilt?formType=tax.us.w2)<li>[**REST API**](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-v3-0-preview-2/operations/AnalyzeDocument)</li><li>[**C# SDK**](quickstarts/get-started-v3-sdk-rest-api.md#prebuilt-model)</li><li>[**Python SDK**](quickstarts/get-started-v3-sdk-rest-api.md#prebuilt-model)</li><li>[**Java SDK**](quickstarts/get-started-v3-sdk-rest-api.md#prebuilt-model)</li><li>[**JavaScript**](quickstarts/get-started-v3-sdk-rest-api.md#prebuilt-model)</li></ul> |

-|[**Invoice model**](concept-invoice.md) | Automated data processing and extraction of key information from sales invoices. |<ul><li>Accounts payable processing.</li><li>Automated tax recording and reporting.</li></ul> |<ul><li>[**Form Recognizer Studio**](https://formrecognizer.appliedai.azure.com/studio/prebuilt?formType=invoice)</li><li>[**REST API**](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-2022-08-31/operations/AnalyzeDocument)</li><li>[**C# SDK**](quickstarts/get-started-v3-sdk-rest-api.md#prebuilt-model)</li><li>[**Python SDK**](quickstarts/get-started-v3-sdk-rest-api.md#prebuilt-model)</li></ul>|

-|[**Receipt model (updated)**](concept-receipt.md) | Automated data processing and extraction of key information from sales receipts.</br></br>Receipt model v3.0 supports processing of **single-page hotel receipts**.|<ul><li>Expense management.</li><li>Consumer behavior data analysis.</li><li>Customer loyalty program.</li><li>Merchandise return processing.</li><li>Automated tax recording and reporting.</li></ul> |<ul><li>[**Form Recognizer Studio**](https://formrecognizer.appliedai.azure.com/studio/prebuilt?formType=receipt)</li><li>[**REST API**](quickstarts/get-started-v3-sdk-rest-api.md)</li><li>[**C# SDK**](quickstarts/get-started-v3-sdk-rest-api.md#prebuilt-model)</li><li>[**Python SDK**](quickstarts/get-started-v3-sdk-rest-api.md#prebuilt-model)</li><li>[**Java SDK**](quickstarts/get-started-v3-sdk-rest-api.md#prebuilt-model)</li><li>[**JavaScript**](quickstarts/get-started-v3-sdk-rest-api.md#prebuilt-model)</li></ul>|

-|[**ID document model (updated)**](concept-id-document.md) |Automated data processing and extraction of key information from US driver's licenses and international passports.</br></br>Prebuilt ID document API supports the **extraction of endorsements, restrictions, and vehicle classifications from US driver's licenses**. |<ul><li>Know your customer (KYC) financial services guidelines compliance.</li><li>Medical account management.</li><li>Identity checkpoints and gateways.</li><li>Hotel registration.</li></ul> |<ul><li> [**Form Recognizer Studio**](https://formrecognizer.appliedai.azure.com/studio/prebuilt?formType=idDocument)</li><li>[**REST API**](quickstarts/get-started-v3-sdk-rest-api.md)</li><li>[**C# SDK**](quickstarts/get-started-v3-sdk-rest-api.md#prebuilt-model)</li><li>[**Python SDK**](quickstarts/get-started-v3-sdk-rest-api.md#prebuilt-model)</li><li>[**Java SDK**](quickstarts/get-started-v3-sdk-rest-api.md#prebuilt-model)</li><li>[**JavaScript**](quickstarts/get-started-v3-sdk-rest-api.md#prebuilt-model)</li></ul>|

-|[**Business card model**](concept-business-card.md) |Automated data processing and extraction of key information from business cards.|<ul><li>Sales lead and marketing management.</li></ul> |<ul><li>[**Form Recognizer Studio**](https://formrecognizer.appliedai.azure.com/studio/prebuilt?formType=businessCard)</li><li>[**REST API**](quickstarts/get-started-v3-sdk-rest-api.md)</li><li>[**C# SDK**](quickstarts/get-started-v3-sdk-rest-api.md#prebuilt-model)</li><li>[**Python SDK**](quickstarts/get-started-v3-sdk-rest-api.md#prebuilt-model)</li><li>[**Java SDK**](quickstarts/get-started-v3-sdk-rest-api.md#prebuilt-model)</li><li>[**JavaScript**](quickstarts/get-started-v3-sdk-rest-api.md#prebuilt-model)</li></ul>|

-### [Form Recognizer GA (v2.1)](#tab/v2-1)

-|[**Layout API**](concept-layout.md) | Extraction and analysis of text, selection marks, tables, and bounding box coordinates, from forms and documents. | <ul><li>[**Form Recognizer labeling tool**](quickstarts/try-sample-label-tool.md#analyze-layout)</li><li>[**REST API**](quickstarts/get-started-v2-1-sdk-rest-api.md#try-it-layout-model)</li><li>[**Client-library SDK**](quickstarts/try-sdk-rest-api.md)</li><li>[**Form Recognizer Docker container**](containers/form-recognizer-container-install-run.md?branch=main&tabs=layout#run-the-container-with-the-docker-compose-up-command)</li></ul>|

-|[**Invoice model**](concept-invoice.md) | Automated data processing and extraction of key information from sales invoices. | <ul><li>[**Form Recognizer labeling tool**](quickstarts/try-sample-label-tool.md#analyze-using-a-prebuilt-model)</li><li>[**REST API**](quickstarts/get-started-v2-1-sdk-rest-api.md#try-it-prebuilt-model)</li><li>[**Client-library SDK**](quickstarts/try-sdk-rest-api.md)</li><li>[**Form Recognizer Docker container**](containers/form-recognizer-container-install-run.md?tabs=invoice#run-the-container-with-the-docker-compose-up-command)</li></ul>|

-|[**Receipt model**](concept-receipt.md) | Automated data processing and extraction of key information from sales receipts.| <ul><li>[**Form Recognizer labeling tool**](quickstarts/try-sample-label-tool.md#analyze-using-a-prebuilt-model)</li><li>[**REST API**](quickstarts/get-started-v2-1-sdk-rest-api.md#try-it-prebuilt-model)</li><li>[**Client-library SDK**](how-to-guides/try-sdk-rest-api.md)</li><li>[**Form Recognizer Docker container**](containers/form-recognizer-container-install-run.md?tabs=receipt#run-the-container-with-the-docker-compose-up-command)</li></ul>|

-|[**ID document model**](concept-id-document.md) | Automated data processing and extraction of key information from US driver's licenses and international passports.| <ul><li>[**Form Recognizer labeling tool**](quickstarts/try-sample-label-tool.md#analyze-using-a-prebuilt-model)</li><li>[**REST API**](quickstarts/get-started-v2-1-sdk-rest-api.md#try-it-prebuilt-model)</li><li>[**Client-library SDK**](how-to-guides/try-sdk-rest-api.md)</li><li>[**Form Recognizer Docker container**](containers/form-recognizer-container-install-run.md?tabs=id-document#run-the-container-with-the-docker-compose-up-command)</li></ul>|

-|[**Business card model**](concept-business-card.md) | Automated data processing and extraction of key information from business cards.| <ul><li>[**Form Recognizer labeling tool**](quickstarts/try-sample-label-tool.md#analyze-using-a-prebuilt-model)</li><li>[**REST API**](quickstarts/get-started-v2-1-sdk-rest-api.md#try-it-prebuilt-model)</li><li>[**Client-library SDK**](how-to-guides/try-sdk-rest-api.md)</li><li>[**Form Recognizer Docker container**](containers/form-recognizer-container-install-run.md?tabs=business-card#run-the-container-with-the-docker-compose-up-command)</li></ul>|

-### [Form Recognizer v3.0](#tab/v3-0)

-### [Form Recognizer v2.1](#tab/v2-1)

-Azure Form Recognizer is a cloud-based [Azure Applied AI Service](../../applied-ai-services/index.yml) that uses machine-learning models to extract key-value pairs, text, and tables from your documents. Form Recognizer analyzes your forms and documents, extracts text and data, maps field relationships as key-value pairs, and returns a structured JSON output. You quickly get accurate results that are tailored to your specific content without excessive manual intervention or extensive data science expertise. Use Form Recognizer to automate your data processing in applications and workflows, enhance data-driven strategies, and enrich document search capabilities.

-Form Recognizer uses the following models to easily identify, extract, and analyze document data:

-**Document analysis models**

-* [**Read model**](concept-read.md) | Extract text lines, words, locations, and detected languages from documents and images.

-* [**Layout model**](concept-layout.md) | Extract text, tables, selection marks, and structure information from documents and images.

-* [**General document model**](concept-general-document.md) | Extract text, tables, selection marks, structure information, key-value pairs, and entities from documents.

-**Prebuilt models**

-* [**W-2 form model**](concept-w2.md) | Extract text and key information from US W2 tax forms.

-* [**Invoice model**](concept-invoice.md) | Extract text, selection marks, tables, key-value pairs, and key information from invoices.

-* [**Receipt model**](concept-receipt.md) | Extract text and key information from receipts.

-* [**ID document model**](concept-id-document.md) | Extract text and key information from driver licenses and international passports.

-* [**Business card model**](concept-business-card.md) | Extract text and key information from business cards.

-**Custom models**

-* [**Custom model**](concept-custom.md) | Extract and analyze distinct data and use cases from forms and documents specific to your business.

-* [**Composed model**](concept-model-overview.md) | Compose a collection of custom models and assign them to a single model built from your form types.

-## Which Form Recognizer feature should I use?

-This section helps you decide which Form Recognizer v3.0 supported feature you should use for your application:

-| What type of document do you want to analyze?| How is the document formatted? | Your best solution |

-| --|-| -|

-|<ul><li>**W-2 Form**</li></yl>| Is your W-2 document composed in United States English (en-US) text?|<ul><li>If **Yes**, use the [**W-2 Form**](concept-w2.md) model.<li>If **No**, use the [**Layout**](concept-layout.md) or [**General document **](concept-general-document.md) model.</li></ul>|

-|<ul><li>**Primarily text content**</li></yl>| Is your document _printed_ in a [supported language](language-support.md#read-layout-and-custom-form-template-model) and are you only interested in text and not tables, selection marks, and the structure?|<ul><li>If **Yes** to text-only extraction, use the [**Read**](concept-read.md) model.<li>If **No**, because you also need structure information, use the [**Layout**](concept-layout.md) model.</li></ul>

-|<ul><li>**General structured document**</li></yl>| Is your document mostly structured and does it contain a few fields and values that may not be covered by the other prebuilt models?|<ul><li>If **Yes**, use the [**General document **](concept-general-document.md) model.</li><li> If **No**, because the fields and values are complex and highly variable, train and build a [**Custom**](how-to-guides/build-custom-model-v3.md) model.</li></ul>

-|<ul><li>**Invoice**</li></yl>| Is your invoice document composed in a [supported language](language-support.md#invoice-model) text?|<ul><li>If **Yes**, use the [**Invoice**](concept-invoice.md) model.<li>If **No**, use the [**Layout**](concept-layout.md) or [**General document **](concept-general-document.md) model.</li></ul>

-|<ul><li>**Receipt**</li><li>**Business card**</li></ul>| Is your receipt or business card document composed in English text? | <ul><li>If **Yes**, use the [**Receipt**](concept-receipt.md) or [**Business Card**](concept-business-card.md) model.</li><li>If **No**, use the [**Layout**](concept-layout.md) or [**General document **](concept-general-document.md) model.</li></ul>|

-|<ul><li>**ID document**</li></ul>| Is your ID document a US driver's license or an international passport?| <ul><li>If **Yes**, use the [**ID document**](concept-id-document.md) model.</li><li>If **No**, use the [**Layout**](concept-layout.md) or [**General document **](concept-general-document.md) model</li></ul>|

- |<ul><li>**Form** or **Document**</li></ul>| Is your form or document an industry-standard format commonly used in your business or industry?| <ul><li>If **Yes**, use the [**Layout**](concept-layout.md) or [**General document **](concept-general-document.md).</li><li>If **No**, you can [**Train and build a custom model**](quickstarts/try-sample-label-tool.md#train-a-custom-form-model).

-## Form Recognizer features and development options

-### [Form Recognizer v3.0](#tab/v3-0)

-The following features and development options are supported by the Form Recognizer service v3.0. Use the links in the table to learn more about each feature and browse the API references.

-| Feature | Description | Development options |

-|[ **Read**](concept-read.md)|Extract text lines, words, detected languages, and handwritten style if detected.|<ul ><li>[**Form Recognizer Studio**](https://formrecognizer.appliedai.azure.com/studio/read)</li><li>[**REST API**](how-to-guides/v3-0-sdk-rest-api.md)</li><li>[**C# SDK**](how-to-guides/v3-0-sdk-rest-api.md?pivots=programming-language-csharp)</li><li>[**Python SDK**](how-to-guides/v3-0-sdk-rest-api.md?pivots=programming-language-python)</li><li>[**Java SDK**](how-to-guides/v3-0-sdk-rest-api.md?pivots=programming-language-java)</li><li>[**JavaScript**](how-to-guides/v3-0-sdk-rest-api.md?pivots=programming-language-javascript)</li></ul> |

-|[ **W-2 Form**](concept-w2.md) | Extract information reported in each box on a W-2 form.|<ul ><li>[**Form Recognizer Studio**](https://formrecognizer.appliedai.azure.com/studio/prebuilt?formType=tax.us.w2)<li>[**REST API**](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-2022-08-31/operations/AnalyzeDocument)</li><li>[**C# SDK**](quickstarts/get-started-v3-sdk-rest-api.md#prebuilt-model)</li><li>[**Python SDK**](quickstarts/get-started-v3-sdk-rest-api.md#prebuilt-model)</li><li>[**Java SDK**](quickstarts/get-started-v3-sdk-rest-api.md#prebuilt-model)</li><li>[**JavaScript**](quickstarts/get-started-v3-sdk-rest-api.md#prebuilt-model)</li></ul> |

-|[**General document model**](concept-general-document.md)|Extract text, tables, structure, key-value pairs and, named entities.|<ul ><li>[**Form Recognizer Studio**](https://formrecognizer.appliedai.azure.com/studio/document)</li><li>[**REST API**](quickstarts/get-started-v3-sdk-rest-api.md)</li><li>[**C# SDK**](quickstarts/get-started-v3-sdk-rest-api.md#general-document-model)</li><li>[**Python SDK**](quickstarts/get-started-v3-sdk-rest-api.md#general-document-model)</li><li>[**Java SDK**](quickstarts/get-started-v3-sdk-rest-api.md#general-document-model)</li><li>[**JavaScript**](quickstarts/get-started-v3-sdk-rest-api.md#general-document-model)</li></ul> |

-|[**Layout model**](concept-layout.md) | Extract text, selection marks, and tables structures, along with their bounding box coordinates, from forms and documents.</br></br> Layout API has been updated to a prebuilt model. | <ul><li>[**Form Recognizer Studio**](https://formrecognizer.appliedai.azure.com/studio/layout)</li><li>[**REST API**](quickstarts/get-started-v3-sdk-rest-api.md)</li><li>[**C# SDK**](quickstarts/get-started-v3-sdk-rest-api.md#layout-model)</li><li>[**Python SDK**](quickstarts/get-started-v3-sdk-rest-api.md#layout-model)</li><li>[**Java SDK**](quickstarts/get-started-v3-sdk-rest-api.md#layout-model)</li><li>[**JavaScript**](quickstarts/get-started-v3-sdk-rest-api.md#layout-model)</li></ul>|

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

-|[**Invoice model**](concept-invoice.md) | Automated data processing and extraction of key information from sales invoices. | <ul><li>[**Form Recognizer Studio**](https://formrecognizer.appliedai.azure.com/studio/prebuilt?formType=invoice)</li><li>[**REST API**](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-2022-08-31/operations/AnalyzeDocument)</li><li>[**C# SDK**](quickstarts/get-started-v3-sdk-rest-api.md#prebuilt-model)</li><li>[**Python SDK**](quickstarts/get-started-v3-sdk-rest-api.md#prebuilt-model)</li></ul>|

-|[**Receipt model (updated)**](concept-receipt.md) | Automated data processing and extraction of key information from sales receipts.</br></br>Receipt model v3.0 supports processing of **single-page hotel receipts**.| <ul><li>[**Form Recognizer Studio**](https://formrecognizer.appliedai.azure.com/studio/prebuilt?formType=receipt)</li><li>[**REST API**](quickstarts/get-started-v3-sdk-rest-api.md)</li><li>[**C# SDK**](quickstarts/get-started-v3-sdk-rest-api.md#prebuilt-model)</li><li>[**Python SDK**](quickstarts/get-started-v3-sdk-rest-api.md#prebuilt-model)</li><li>[**Java SDK**](quickstarts/get-started-v3-sdk-rest-api.md#prebuilt-model)</li><li>[**JavaScript**](quickstarts/get-started-v3-sdk-rest-api.md#prebuilt-model)</li></ul>|

-|[**ID document model (updated)**](concept-id-document.md) |Automated data processing and extraction of key information from US driver's licenses and international passports.</br></br>Prebuilt ID document API supports the **extraction of endorsements, restrictions, and vehicle classifications from US driver's licenses**. |<ul><li> [**Form Recognizer Studio**](https://formrecognizer.appliedai.azure.com/studio/prebuilt?formType=idDocument)</li><li>[**REST API**](quickstarts/get-started-v3-sdk-rest-api.md)</li><li>[**C# SDK**](quickstarts/get-started-v3-sdk-rest-api.md#prebuilt-model)</li><li>[**Python SDK**](quickstarts/get-started-v3-sdk-rest-api.md#prebuilt-model)</li><li>[**Java SDK**](quickstarts/get-started-v3-sdk-rest-api.md#prebuilt-model)</li><li>[**JavaScript**](quickstarts/get-started-v3-sdk-rest-api.md#prebuilt-model)</li></ul>|

-|[**Business card model**](concept-business-card.md) |Automated data processing and extraction of key information from business cards.| <ul><li>[**Form Recognizer Studio**](https://formrecognizer.appliedai.azure.com/studio/prebuilt?formType=businessCard)</li><li>[**REST API**](quickstarts/get-started-v3-sdk-rest-api.md)</li><li>[**C# SDK**](quickstarts/get-started-v3-sdk-rest-api.md#prebuilt-model)</li><li>[**Python SDK**](quickstarts/get-started-v3-sdk-rest-api.md#prebuilt-model)</li><li>[**Java SDK**](quickstarts/get-started-v3-sdk-rest-api.md#prebuilt-model)</li><li>[**JavaScript**](quickstarts/get-started-v3-sdk-rest-api.md#prebuilt-model)</li></ul>|

-### [Form Recognizer GA (v2.1)](#tab/v2-1)

-The following features are supported by Form Recognizer v2.1. Use the links in the table to learn more about each feature and browse the API references.

-| Feature | Description | Development options |

-|-|--|-|

-|[**Layout API**](concept-layout.md) | Extraction and analysis of text, selection marks, tables, and bounding box coordinates, from forms and documents. | <ul><li>[**Form Recognizer labeling tool**](quickstarts/try-sample-label-tool.md#analyze-layout)</li><li>[**REST API**](quickstarts/get-started-v2-1-sdk-rest-api.md#try-it-layout-model)</li><li>[**Client-library SDK**](quickstarts/try-sdk-rest-api.md)</li><li>[**Form Recognizer Docker container**](containers/form-recognizer-container-install-run.md?branch=main&tabs=layout#run-the-container-with-the-docker-compose-up-command)</li></ul>|

-|[**Invoice model**](concept-invoice.md) | Automated data processing and extraction of key information from sales invoices. | <ul><li>[**Form Recognizer labeling tool**](quickstarts/try-sample-label-tool.md#analyze-using-a-prebuilt-model)</li><li>[**REST API**](quickstarts/get-started-v2-1-sdk-rest-api.md#try-it-prebuilt-model)</li><li>[**Client-library SDK**](quickstarts/try-sdk-rest-api.md)</li><li>[**Form Recognizer Docker container**](containers/form-recognizer-container-install-run.md?tabs=invoice#run-the-container-with-the-docker-compose-up-command)</li></ul>|

-|[**Receipt model**](concept-receipt.md) | Automated data processing and extraction of key information from sales receipts.| <ul><li>[**Form Recognizer labeling tool**](quickstarts/try-sample-label-tool.md#analyze-using-a-prebuilt-model)</li><li>[**REST API**](quickstarts/get-started-v2-1-sdk-rest-api.md#try-it-prebuilt-model)</li><li>[**Client-library SDK**](how-to-guides/try-sdk-rest-api.md)</li><li>[**Form Recognizer Docker container**](containers/form-recognizer-container-install-run.md?tabs=receipt#run-the-container-with-the-docker-compose-up-command)</li></ul>|

-|[**ID document model**](concept-id-document.md) | Automated data processing and extraction of key information from US driver's licenses and international passports.| <ul><li>[**Form Recognizer labeling tool**](quickstarts/try-sample-label-tool.md#analyze-using-a-prebuilt-model)</li><li>[**REST API**](quickstarts/get-started-v2-1-sdk-rest-api.md#try-it-prebuilt-model)</li><li>[**Client-library SDK**](how-to-guides/try-sdk-rest-api.md)</li><li>[**Form Recognizer Docker container**](containers/form-recognizer-container-install-run.md?tabs=id-document#run-the-container-with-the-docker-compose-up-command)</li></ul>|

-|[**Business card model**](concept-business-card.md) | Automated data processing and extraction of key information from business cards.| <ul><li>[**Form Recognizer labeling tool**](quickstarts/try-sample-label-tool.md#analyze-using-a-prebuilt-model)</li><li>[**REST API**](quickstarts/get-started-v2-1-sdk-rest-api.md#try-it-prebuilt-model)</li><li>[**Client-library SDK**](how-to-guides/try-sdk-rest-api.md)</li><li>[**Form Recognizer Docker container**](containers/form-recognizer-container-install-run.md?tabs=business-card#run-the-container-with-the-docker-compose-up-command)</li></ul>|

-### [Form Recognizer v3.0](#tab/v3-0)

-### [Form Recognizer v2.1](#tab/v2-1)

-description: Use the Form Recognizer client library SDKs or REST API to create a forms processing app that extracts key/value pairs and table data from your custom documents.

-zone_pivot_groups: programming-languages-set-formre

-recommendations: false

-# Get started with Form Recognizer client library SDKs or REST API

-Get started with Azure Form Recognizer using the programming language of your choice. Azure Form Recognizer is a cloud-based Azure Applied AI Service that uses machine learning to extract key-value pairs, text, and tables from your documents. You can easily call Form Recognizer models by integrating our client library SDKs into your workflows and applications. We recommend that you use the free service when you're learning the technology. Remember that the number of free pages is limited to 500 per month.

-To learn more about Form Recognizer features and development options, visit our [Overview](../overview.md#form-recognizer-features-and-development-options) page.

-description: Use a Form Recognizer SDK or the REST API to create a forms processing app that extracts key data from your documents.

-zone_pivot_groups: programming-languages-set-formre

-recommendations: false

-# Quickstart: Form Recognizer SDKs | REST API v3.0

-Get started with the latest version of Azure Form Recognizer. Azure Form Recognizer is a cloud-based Azure Applied AI Service that uses machine learning to extract key-value pairs, text, tables and key data from your documents. You can easily integrate Form Recognizer models into your workflows and applications by using an SDK in the programming language of your choice or calling the REST API. For this quickstart, we recommend that you use the free service while you're learning the technology. Remember that the number of free pages is limited to 500 per month.

-To learn more about Form Recognizer features and development options, visit our [Overview](../overview.md#form-recognizer-features-and-development-options) page.

-That's it, congratulations!

-In this quickstart, you used a form Form Recognizer model to analyze various forms and documents. Next, explore the Form Recognizer Studio and reference documentation to learn about Form Recognizer API in depth.

-## Next steps

->[!div class="nextstepaction"]

-> [**Try the Form Recognizer Studio**](https://formrecognizer.appliedai.azure.com/studio)

-> [!div class="nextstepaction"]

-> [**Explore our how-to documentation and take a deeper dive into Form Recognizer models**](../how-to-guides/v3-0-sdk-rest-api.md)

-keywords: document processing

-> * *See* our [**REST API**](get-started-v3-sdk-rest-api.md) or [**C#**](get-started-v3-sdk-rest-api.md), [**Java**](get-started-v3-sdk-rest-api.md), [**JavaScript**](get-started-v3-sdk-rest-api.md), or [Python](get-started-v3-sdk-rest-api.md) SDK quickstarts to get started with the v3.0 version.

-* **Model ID** - The ID of the model that was created and trained. Each training call creates a new model with its own ID. Copy this string to a secure location; you'll need it if you want to do prediction calls through the [REST API](./try-sdk-rest-api.md?pivots=programming-language-rest-api) or [client library](./try-sdk-rest-api.md).

-[Form Recognizer Studio](https://formrecognizer.appliedai.azure.com/) is an online tool for visually exploring, understanding, and integrating features from the Form Recognizer service in your applications. You can get started by exploring the pre-trained models with sample or your own documents. You can also create projects to build custom template models and reference the models in your applications using the [Python SDK](get-started-v3-sdk-rest-api.md) and other quickstarts.

-* [ **Read**](https://formrecognizer.appliedai.azure.com/studio/read): extract text lines, words, their locations, detected languages, and handwritten style if detected from documents (PDF, TIFF) and images (JPG, PNG, BMP).

-* Explore our [**v3.0 SDK quickstarts**](get-started-v3-sdk-rest-api.md) to try the v3.0 features in your applications using the new SDKs.

-* Refer to our [**v3.0 REST API quickstarts**](get-started-v3-sdk-rest-api.md) to try the v3.0 features using the new REST API.

-|[.NET/C# → 4.0.0 (latest GA release)](quickstarts/get-started-v3-sdk-rest-api.md?pivots=programming-language-csharp#set-up)| [NuGet](https://www.nuget.org/packages/Azure.AI.FormRecognizer/4.0.0) | [Azure SDK for .NET](https://azuresdkdocs.blob.core.windows.net/$web/dotnet/Azure.AI.FormRecognizer/4.0.0/https://docsupdatetracker.net/index.html)|[**v3.0**](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-2022-08-31/operations/AnalyzeDocument)</br> [**v2.1**](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-v2-1/operations/AnalyzeBusinessCardAsync)</br>[**v2.0**](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-v2/operations/AnalyzeLayoutAsync) |[Windows, macOS, Linux, Docker](https://dotnet.microsoft.com/download)|

-|[Java → 4.0.0 (latest GA release)](quickstarts/get-started-v3-sdk-rest-api.md?pivots=programming-language-java#set-up) |[Maven](https://oss.sonatype.org/#nexus-search;quick~azure-ai-formrecognizer) | [Azure SDK for Java](https://azuresdkdocs.blob.core.windows.net/$web/java/azure-ai-formrecognizer/4.0.0/https://docsupdatetracker.net/index.html)|[**v3.0**](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-2022-08-31/operations/AnalyzeDocument)</br> [**v2.1**](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-v2-1/operations/AnalyzeBusinessCardAsync)</br>[**v2.0**](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-v2/operations/AnalyzeLayoutAsync) |[Windows, macOS, Linux](/java/openjdk/install)|

-|[JavaScript → 4.0.0 (latest GA release)](quickstarts/get-started-v3-sdk-rest-api.md?pivots=programming-language-javascript#set-up)| [npm](https://www.npmjs.com/package/@azure/ai-form-recognizer)| [Azure SDK for JavaScript](https://azuresdkdocs.blob.core.windows.net/$web/javascript/azure-ai-form-recognizer/4.0.0/https://docsupdatetracker.net/index.html) | [**v3.0**](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-2022-08-31/operations/AnalyzeDocument)</br> [**v2.1**](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-v2-1/operations/AnalyzeBusinessCardAsync)</br>[**v2.0**](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-v2/operations/AnalyzeLayoutAsync) | [Browser, Windows, macOS, Linux](https://nodejs.org/en/download/) |

-|[Python → 3.2.0 (latest GA release)](quickstarts/get-started-v3-sdk-rest-api.md?pivots=programming-language-python#set-up) | [PyPI](https://pypi.org/project/azure-ai-formrecognizer/3.2.0/)| [Azure SDK for Python](https://azuresdkdocs.blob.core.windows.net/$web/python/azure-ai-formrecognizer/3.2.0/https://docsupdatetracker.net/index.html)| [**v3.0**](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-2022-08-31/operations/AnalyzeDocument)</br> [**v2.1**](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-v2-1/operations/AnalyzeBusinessCardAsync)</br>[**v2.0**](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-v2/operations/AnalyzeLayoutAsync) |[Windows, macOS, Linux](/azure/developer/python/configure-local-development-environment?tabs=windows%2Capt%2Ccmd#use-the-azure-cli)

-First, you'll create a client object to interact with the Form Recognizer SDK, and then call methods on that client object to interact with the service. The SDKs provide both synchronous and asynchronous methods. For more insight, try a [quickstart](quickstarts/get-started-v3-sdk-rest-api.md) in a language of your choice.

-> [**Try a Form Recognizer quickstart**](quickstarts/get-started-v3-sdk-rest-api.md)

-For the usage with [Form Recognizer SDK](quickstarts/get-started-v3-sdk-rest-api.md), [Form Recognizer REST API](quickstarts/get-started-v3-sdk-rest-api.md), [Form Recognizer Studio](quickstarts/try-v3-form-recognizer-studio.md) and [Sample Labeling Tool](https://fott-2-1.azurewebsites.net/).

-| **Max document size** | 500 MB | 500 MB |

-> * *See* our [**REST API**](quickstarts/get-started-v3-sdk-rest-api.md) or [**C#**](quickstarts/get-started-v3-sdk-rest-api.md), [**Java**](quickstarts/get-started-v3-sdk-rest-api.md), [**JavaScript**](quickstarts/get-started-v3-sdk-rest-api.md), or [Python](quickstarts/get-started-v3-sdk-rest-api.md) SDK quickstarts to get started with version v3.0.

- > Remember to remove the key from your code when you're done, and never post it publicly. For production, use a secure way of storing and accessing your credentials like [Azure Key Vault](../../key-vault/general/overview.md). For more information, *see* Cognitive Services [security](../../cognitive-services/cognitive-services-security.md).

-* [Form Recognizer REST API](quickstarts/get-started-v3-sdk-rest-api.md) has been redesigned for better usability.

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

-Get started with the new [REST API](https://westus2.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-v2-1/operations/AnalyzeWithCustomForm), [Python](quickstarts/get-started-v3-sdk-rest-api.md), or [.NET](quickstarts/get-started-v3-sdk-rest-api.md) SDK for the v3.0 preview API.

-TLS 1.2 is now enforced for all HTTP requests to this service. For more information, see [Azure Cognitive Services security](../../cognitive-services/cognitive-services-security.md).

- ``` JSON

- ``` JSON

-* **Connection string**: The connection string to access your Azure Cosmos DB. This can be found in the Azure Cosmos DB resource in the Azure portal, in **Keys**. For more information, see [Secure access to data in Azure Cosmos DB](../../cosmos-db/secure-access-to-data.md).

- ``` JSON

- ``` JSON

- Single JSON object

-

- ``` JSON

- JSON array

-A data feed is what Metrics Advisor ingests from your data source, such as Cosmos DB or a SQL server. A data feed contains rows of:

- Some data sources such as Cosmos DB or Azure Blob Storage do not support certain calculations like *group by* or *cube*. Metrics Advisor provides the roll up option to automatically generate a data cube during ingestion.

-| South East Asia | `https://sharedsasia.sasia.attest.azure.net` |

-| Australia SouthEast | `https://sharedsau.sau.attest.azure.net` |

- "apiVersion": "2021-04-30-preview",

- "apiVersion": "2021-04-30-preview",

-> You can preview onboarding Automanage machine best practices during VM creation in the Azure portal using [this link](https://aka.ms/ws2022ae-portal-preview).

- * You can preview onboarding Automanage machine best practices during VM creation in the Azure portal using [this link](https://aka.ms/ws2022ae-portal-preview).

- * If you create a VM using [this link](https://aka.ms/ws2022ae-portal-preview), on the Management tab under section 'Azure Automanage', select 'Dev/Test' or 'Production' for 'Azure Automanage environment' to evaluate Automanage machine best practices while in preview.

-Automanage released a new version of the machine best practices offering in November 2021. The new API now supports creating custom profiles where you can pick and choose the services and settings you want to apply to your machines. Also, with this new version, the Automanage account is no longer required. This article describes the differences in the versions and how to upgrade.

-Below are the set of instructions on how to upgrade your machines to the latest API version of Automanage.

-### Prerequisites

-If you don't have an Azure subscription, [create an account](https://azure.microsoft.com/pricing/purchase-options/pay-as-you-go/) before you begin.

-> [!NOTE]

-> Free trial accounts do not have access to the virtual machines used in this tutorial. Please upgrade to a Pay-As-You-Go subscription.

-> [!IMPORTANT]

-> The following Azure RBAC permission is needed to enable Automanage for the first time on a subscription with the new Automanage version: **Owner** role, or **Contributor** along with **User Access Administrator** roles.

-### Sign in to Azure

-Sign in to the [Azure portal](https://portal.azure.com/).

-### Check to see which machines need to be upgraded

-All machines that need to be upgraded will have the status **Needs upgrade**. You will also see a banner on the Automanage overview page indicating that you need to upgrade you machines.

-In the previous version of Automanage, the Automanage Account was used as an MSI to preform actions on your machine. However, in the latest version of Automanage, Automanage uses a first party application (Application Id : d828acde-4b48-47f5-a6e8-52460104a052) to order to perform actions on the Automanage machines.

-https://management.azure.com/subscriptions/<yourSubscription>/providers/Microsoft.Automanage/configurationProfiles?api-version=2021-04-30-preview

-$listConfigurationProfilesURI = "https://management.azure.com/subscriptions/<yourSubscription>/providers/Microsoft.Automanage/configurationProfiles?api-version=2021-04-30-preview"

-$profileId = "https://management.azure.com/subscriptions/yourSubscription/resourceGroups/yourResourceGroup/providers/Microsoft.Automanage/configurationProfiles/testProfile1?api-version=2021-04-30-preview"

-description: Learn about Azure Automanage for virtual machines.

-This article covers information about Azure Automanage for machine best practices, which have the following benefits:

-The Automanage service will grant **Contributor** permission to this first party application (Automanage API Application Id: d828acde-4b48-47f5-a6e8-52460104a052) to perform actions on Automanaged machines. Guest users will need to have the **directory reader role** assigned to enable Automanage.

-# Automanage virtual machine statuses

-In the Azure portal, go to the **Automanage ΓÇô Azure machine best practices** page which lists all of your automanage machines. Here you will see the overall status of each machine.

-## States of an Automanaged virtual machine

-description: Learn about the Azure Automanage for virtual machines best practices for services that are automatically onboarded and configured for you.

-These Azure services are automatically onboarded for you when you use Automanage for virtual machines. They are essential to our best practices white paper, which you can find in our [Cloud Adoption Framework](/azure/cloud-adoption-framework/manage/azure-server-management).

- "apiVersion": "2021-04-30-preview",

-2. Select the VM for which you want to enable Update Management. VMs can exist in any region, no matter the location of your Automation account. You

-description: In this tutorial, you learn how to dynamically update the configuration data for ASP.NET Core apps

-#Customer intent: I want to dynamically update my app to use the latest configuration data in App Configuration.

-# Tutorial: Use dynamic configuration in an ASP.NET Core app

-ASP.NET Core has a pluggable configuration system that can read configuration data from a variety of sources. It can handle changes dynamically without causing an application to restart. ASP.NET Core supports the binding of configuration settings to strongly typed .NET classes. It injects them into your code by using `IOptionsSnapshot<T>`, which automatically reloads the application's configuration when the underlying data changes.

-This tutorial shows how you can implement dynamic configuration updates in your code. It builds on the web app introduced in the quickstarts. Before you continue, finish [Create an ASP.NET Core app with App Configuration](./quickstart-aspnet-core-app.md) first.

-You can use any code editor to do the steps in this tutorial. [Visual Studio Code](https://code.visualstudio.com/) is an excellent option that's available on the Windows, macOS, and Linux platforms.

-> * Set up your application to update its configuration in response to changes in an App Configuration store.

-> * Inject the latest configuration in your application's controllers.

-To do this tutorial, install the [.NET Core SDK](https://dotnet.microsoft.com/download).

-Before you continue, finish [Create an ASP.NET Core app with App Configuration](./quickstart-aspnet-core-app.md) first.

-A *sentinel key* is a special key that you update after you complete the change of all other keys. Your application monitors the sentinel key. When a change is detected, your application refreshes all configuration values. This approach helps to ensure the consistency of configuration in your application and reduces the overall number of requests made to App Configuration, compared to monitoring all keys for changes.

-1. In the Azure portal, select **Configuration Explorer > Create > Key-value**.

-> [!NOTE]

-> If you aren't using a sentinel key, you need to manually register every key you want to monitor.

-1. Add a reference to the `Microsoft.Azure.AppConfiguration.AspNetCore` NuGet package by running the following command:

- ```dotnetcli

- dotnet add package Microsoft.Azure.AppConfiguration.AspNetCore

- ```

-1. Open *Program.cs*, and update the `CreateWebHostBuilder` method to add the `config.AddAzureAppConfiguration()` method.

- #### [.NET 5.x](#tab/core5x)

- public static IHostBuilder CreateHostBuilder(string[] args) =>

- Host.CreateDefaultBuilder(args)

- .ConfigureWebHostDefaults(webBuilder =>

- webBuilder.ConfigureAppConfiguration((hostingContext, config) =>

- {

- var settings = config.Build();

- config.AddAzureAppConfiguration(options =>

- {

- options.Connect(settings["ConnectionStrings:AppConfig"])

- .ConfigureRefresh(refresh =>

- {

- refresh.Register("TestApp:Settings:Sentinel", refreshAll: true)

- .SetCacheExpiration(new TimeSpan(0, 5, 0));

- });

- });

- })

- .UseStartup<Startup>());

- webBuilder.ConfigureAppConfiguration((hostingContext, config) =>

- var settings = config.Build();

- options.Connect(settings["ConnectionStrings:AppConfig"])

- .ConfigureRefresh(refresh =>

- {

- refresh.Register("TestApp:Settings:Sentinel", refreshAll: true)

- .SetCacheExpiration(new TimeSpan(0, 5, 0));

- });

- })

- .UseStartup<Startup>());

- ```

- #### [.NET Core 2.x](#tab/core2x)

- ```csharp

- public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>

- WebHost.CreateDefaultBuilder(args)

- .ConfigureAppConfiguration((hostingContext, config) =>

- {

- var settings = config.Build();

- config.AddAzureAppConfiguration(options =>

- {

- options.Connect(settings["ConnectionStrings:AppConfig"])

- .ConfigureRefresh(refresh =>

- {

- refresh.Register("TestApp:Settings:Sentinel", refreshAll: true)

- .SetCacheExpiration(new TimeSpan(0, 5, 0));

- });

- })

- .UseStartup<Startup>();

- In the `ConfigureRefresh` method, you register keys within your App Configuration store that you want to monitor for changes. The `refreshAll` parameter to the `Register` method indicates that all configuration values should be refreshed if the registered key changes. The `SetCacheExpiration` method specifies the minimum time that must elapse before a new request is made to App Configuration to check for any configuration changes. In this example, you override the default expiration time of 30 seconds specifying a time of 5 minutes instead. This reduces the potential number of requests made to your App Configuration store.

- > [!NOTE]

- > For testing purposes, you may want to lower the cache refresh expiration time.

- To actually trigger a configuration refresh, you'll use the App Configuration middleware. You'll see how to do this in a later step.

-1. Add a *Settings.cs* file in the Controllers directory that defines and implements a new `Settings` class. Replace the namespace with the name of your project.

- namespace TestAppConfig

- {

- public class Settings

- {

- public string BackgroundColor { get; set; }

- public long FontSize { get; set; }

- public string FontColor { get; set; }

- public string Message { get; set; }

- }

- }

- ```

-1. Open *Startup.cs*, and update the `ConfigureServices` method. Call `Configure<Settings>` to bind configuration data to the `Settings` class. Call `AddAzureAppConfiguration` to add App Configuration components to the service collection of your application.

- #### [.NET 5.x](#tab/core5x)

- ```csharp

- public void ConfigureServices(IServiceCollection services)

- {

- services.Configure<Settings>(Configuration.GetSection("TestApp:Settings"));

- services.AddControllersWithViews();

- services.AddAzureAppConfiguration();

- }

- services.Configure<Settings>(Configuration.GetSection("TestApp:Settings"));

- services.AddControllersWithViews();

- }

- ```

- #### [.NET Core 2.x](#tab/core2x)

- ```csharp

- public void ConfigureServices(IServiceCollection services)

- {

- services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1);

- services.AddAzureAppConfiguration();

- }

-1. Update the `Configure` method, and add a call to `UseAzureAppConfiguration`. It enables your application to use the App Configuration middleware to handle the configuration updates for you automatically.

- #### [.NET 5.x](#tab/core5x)

- public void Configure(IApplicationBuilder app, IWebHostEnvironment env)

- {

- if (env.IsDevelopment())

- {

- app.UseDeveloperExceptionPage();

- }

- else

- {

- app.UseExceptionHandler("/Home/Error");

- // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.

- app.UseHsts();

- }

- // Add the following line:

- app.UseAzureAppConfiguration();

- app.UseHttpsRedirection();

-

- app.UseStaticFiles();

- app.UseRouting();

- app.UseAuthorization();

- app.UseEndpoints(endpoints =>

- {

- endpoints.MapControllerRoute(

- name: "default",

- pattern: "{controller=Home}/{action=Index}/{id?}");

- });

- }

- ```

- #### [.NET Core 3.x](#tab/core3x)

- ```csharp

- public void Configure(IApplicationBuilder app, IWebHostEnvironment env)