Skip to main content
Enterprise Connect for Azure OpenAI is available only for Unstructured dedicated instances hosted on Azure.
Enterprise Connect for Azure OpenAI requires two configurations:
  1. Create an App Registration with a federated identity credential and RBAC role assignment in Azure.
  2. Configure Azure OpenAI on the Unstructured AI Providers page by providing the App Registration details and your Azure OpenAI endpoint.
Enterprise Connect lets a workspace call your Azure OpenAI resource without storing an API key. The AI Providers configuration holds only your endpoint, API version, tenant ID, and client ID. None of these values is a secret. The configuration applies to Azure OpenAI model calls made by workflow jobs in the workspace. Each workspace references one App Registration. Unlike connectors, Azure OpenAI cannot be configured through the API. The AI Providers UI is the only configuration path. Existing Azure OpenAI configurations that use an API key continue to work unchanged.
Every workspace on a dedicated instance presents the same Subject to Microsoft Entra ID, and the tenant ID and client ID are not secrets. A separate App Registration for each workspace does not isolate workspaces from each other. Treat the dedicated instance as the trust boundary.

Setup requirements

Enterprise Connect for Azure OpenAI requires the following:
  • A dedicated instance hosted on Azure, with Enterprise Connect enabled. Contact your Unstructured account team or Unstructured Support to request access and have it enabled. Your account team provides the Issuer and Subject values for your instance.
  • An Azure OpenAI resource with at least one deployed model, and a custom subdomain name such as https://<your-resource>.openai.azure.com. Microsoft Entra ID authentication does not work with regional endpoints. See Authenticate with Microsoft Entra ID in the Azure documentation.
  • Permission in your Microsoft Entra tenant to create App Registrations, and permission to assign Azure RBAC roles on the target resources.

Set up Enterprise Connect authentication

This procedure covers creating an App Registration, adding a federated identity credential, and granting the App Registration access to your Azure OpenAI resource. For a conceptual overview of the App Registration and federated identity credential, see Enterprise Connect for Azure.
  1. Create an App Registration for Unstructured in Microsoft Entra ID. In your Azure subscription, follow the instructions in How to register an app in Microsoft Entra ID. Enter a meaningful name for your App Registration (for example, unstructured-azure-openai). For Supported account types, select Single tenant only. Do not create a client secret.
  2. Add a federated identity credential to the App Registration. Follow the instructions in Configure an app to trust an external identity provider. Navigate to your App Registration, select Certificates & secrets in the left navigation pane, select the Federated credentials tab, and select Add credential. For Federated credential scenario, select Other issuer. Set the following values:
  3. Add a role assignment to grant your App Registration access to your Azure OpenAI resource. See Assign Azure roles using the Azure portal. Use the following values:
    • Scope: the Azure OpenAI resource that hosts the models you want Unstructured to call.
    • Role: Cognitive Services OpenAI User.
    • Members: select User, group, or service principal, then search for and select the App Registration you created in Step 1.
    When you reach the Review + assign tab, click Review + assign to complete the assignment. Role assignments can take several minutes to take effect.
  4. Note the following values. You will need them when configuring Azure OpenAI in Unstructured.
    • The Tenant ID (also called Directory ID) and the Client ID of your App Registration. Both are on the Overview page of your App Registration in the Microsoft Entra admin center.
    • The endpoint of your Azure OpenAI resource, for example https://<your-resource>.openai.azure.com.
    • The API version your deployed models support, for example 2024-02-01.

Configure Azure OpenAI in the Unstructured AI Providers UI

  1. If you are not already signed in, sign in to your Unstructured account.
  2. In the top navigation bar, in the organizational account selector, select the organizational account that the target workspace belongs to.
  3. Next to the organizational account selector, click the workspace selector, and then select the target workspace.
  4. In the workspace navigation bar, click the AI Providers tab.
  5. Next to Azure OpenAI, click Configure.
  6. For Auth Method, select Workload identity. The Api Key field is hidden.
  7. For Azure Endpoint, enter the endpoint of your Azure OpenAI resource from Step 4 of Set up Enterprise Connect authentication.
  8. For Api Version, enter the API version from the same step, or keep the default.
  9. For Tenant Id, enter the Tenant ID of your App Registration.
  10. For Client Id, enter the Client ID of your App Registration.
  11. Click Save Configuration.
Azure OpenAI is now ready for all workflows in this workspace. To change the tenant ID or client ID later, use Update configuration and re-enter every required field.
Azure OpenAI Enterprise Connect can only be configured through the AI Providers UI. There is no API equivalent. The Auth Method field appears only on instances where Enterprise Connect is enabled.

Troubleshoot Enterprise Connect for Azure OpenAI

Enterprise Connect failures occur at one of two stages: the token exchange with Microsoft Entra ID, or the model request to your Azure OpenAI resource. Match the symptom to identify the cause and apply the fix.
  • Token exchange fails (AADSTS70021 or AADSTS700213, no matching federated identity record found). The federated identity credential does not match the token Unstructured presents.
    • Verify that the Issuer and Subject on the federated identity credential exactly match the values from your account team, including case and trailing characters. See Step 2 of Set up Enterprise Connect authentication.
    • Verify that the Audience is exactly api://AzureADTokenExchange.
    • If you created the federated identity credential in the last few minutes, wait a few minutes, and then run the workflow again. Microsoft Entra ID can take a short time to replicate a new credential.
    • If the values match, contact your Unstructured account team to confirm that your dedicated instance is configured for Enterprise Connect for Azure OpenAI.
  • Token exchange fails (AADSTS700016, application not found). The Tenant ID or Client ID in the AI Providers configuration does not identify an App Registration in your tenant.
  • Token exchange succeeds but model calls fail (AUTH_PERMISSION_DENIED, or an Azure authorization error such as HTTP 401, HTTP 403, or PermissionDenied). The App Registration does not have permission to call models on the Azure OpenAI resource.
    • Verify that the App Registration has the Cognitive Services OpenAI User role on the Azure OpenAI resource that Azure Endpoint points to. A role on an unrelated resource does not apply. A role on the resource group, subscription, or management group that contains the resource is inherited and does apply. See Step 3 of Set up Enterprise Connect authentication.
    • Wait several minutes after adding the role assignment, and then run the workflow again.
  • Endpoint not found or authentication rejected on a regional endpoint. Microsoft Entra ID authentication works only with a custom subdomain. Set Azure Endpoint to https://<your-resource>.openai.azure.com, not a regional endpoint such as https://eastus.api.cognitive.microsoft.com.