This topic outlines the steps to configure Microsoft Entra ID (formerly Azure AD) authentication for custom model definitions within AI Agent Studio, enabling seamless integration of your models with Automation 360.

Entra ID is supported only through OAuth2 authentication, and this method is required when integrating with Microsoft-hosted models that mandate Entra-based access tokens.
  • Use Entra ID when the target model vendor only supports OAuth2 authentication.
  • This is often the case with Azure-hosted services when API Key authentication cannot be used in parallel with OAuth2.
  • For example, Azure OpenAI models default to API Key authentication, but if your security requirements enforce OAuth2 via Entra ID, you must configure the model through the custom model definition route.

To download and use the Postman collection (Entra ID sample), click this link Postman collection - Entra ID sample.

Prerequisites

  • An Azure account with Entra ID enabled. Collect the required details:
    • Client ID
    • Client Secret
    • Authorization URL
    • Token URL
  • Configure an OAuth connection using Entra ID. For more information, refer to Microsoft Entra ID configuration.

Why use custom model and Entra ID?

Azure OpenAI is supported with API Key auth in the UI; if you require OAuth2/Entra ID instead, define it via the Custom Model API because a vendor can only expose one auth mechanism in the UI at a time.

Procedure

  1. Once the OAuth connection is in place, you can create the custom model definition using the Create Custom model API. This API requires a JSON payload schema that describes your model, including vendor name, model name, authentication protocols, and API endpoint details.
  2. Use the following authAction block to create a custom model connection using the configured Entra ID. Note the key authentication parameters: 
    "authAction": {
  "authType": "OAUTH2",
  "oAuth": {
    "location": "header",
    "keyName": "Authorization",
    "prefix": "Bearer "
  }
}
    • authType: must be OAUTH2
    • location: header
    • keyName: Authorization
    • prefix: Bearer and include the token (include a space after Bearer)
  3. Send the request. The request is described in the example below. On success, the Custom Model definition is created and becomes selectable when you create a Model connection in AI Agent Studio.

Custom model definition using Entra ID

Here is a simplified example for an Azure OpenAI GPT-4.1 mini deployment, using Entra OAuth2:

POST https:/{{ControlRoomURL}}/gai/prompttools/v1/custommodel
Request body:
{
	"name": "AAI Docs Example - Entra",
	"version": "0",
	"authAction": {
		"authType": "OAUTH2",
		"oAuth": {
			"location": "header",
			"keyName": "Authorization",
			"prefix": "Bearer "
		}
	},
	"apiType": "REST",
	"actions": [
		{
			"name": "gpt-4.1-mini",
			"displayName": "GPT-4.1 mini",
			"description": "GPT-4.1 mini provides a balance between intelligence, speed, and cost that makes it an attractive model for many use cases.",
			"method": "POST",
			"uri": "https://{resourceName}.openai.azure.com/openai/deployments/{deployment}/chat/completions?api-version={apiVersion}",
			"params": [
				{
					"type": "PATH_PARAM",
					"attribute": [
						{
							"name": "resourceName",
							"label": "Resource Name",
							"value": {
								"type": "TEXT",
								"string": "genaitemplateplatformeastca"
							}
						}
					]
				},
				{
					"type": "PATH_PARAM",
					"attribute": [
						{
							"name": "deployment",
							"label": "Deployment",
							"value": {
								"type": "TEXT",
								"string": "deploy-gpt-4.1"
							}
						}
					]
				},
				{
					"type": "PATH_PARAM",
					"attribute": [
						{
							"name": "apiVersion",
							"label": "API Version",
							"value": {
								"type": "TEXT",
								"string": "2025-01-01-preview"
							}
						}
					]
				}
			],
			"request": {
				"raw": {
					"body": "{\"model\": \"gpt-4.1\",\"messages\":[{\"role\":\"system\",\"content\":\"system prompt\"},{\"role\":\"user\",\"content\":\"some prompt query\"}],\"max_completion_tokens\":500}",
					"variables": [
						{
							"path": "$.max_completion_tokens",
							"attribute": {
								"name": "max_completion_tokens",
								"label": "Max tokens",
								"value": {
									"type": "INTEGER",
									"number": "2048"
								},
								"annotations": [
									"MODEL_PARAMETER"
								],
								"canonicalName": "choices[0].completionTokens"
							}
						},
						{
							"path": "$.messages[1].content",
							"attribute": {
								"name": "prompt",
								"label": "prompt",
								"value": {
									"type": "TEXT"
								},
								"annotations": [
									"PROMPT_QUERY"
								]
							}
						},
						{
							"path": "$.messages[0].content",
							"attribute": {
								"name": "systemPrompt",
								"label": "System Prompt",
								"value": {
									"type": "TEXT"
								},
								"annotations": [
									"SYSTEM_PROMPT_MESSAGE"
								]
							}
						}
					]
				}
			},
			"response": {
				"body": "{\n    \"id\": \"chatcmpl-APwQdLa9WCQAdZg0dO5OjGr2ER4sX\",\n    \"object\": \"chat.completion\",\n    \"created\": 1730746163,\n    \"model\": \"o3-mini-2025-01-31\",\n    \"choices\": [\n        {\n            \"index\": 0,\n            \"message\": {\n                \"role\": \"assistant\",\n                \"content\": \"Sure! They are one of the most mysterious and exciting objects in space.\",\n                \"refusal\": null\n            },\n            \"finish_reason\": \"stop\"\n        }\n    ],\n    \"usage\": {\n        \"prompt_tokens\": 17,\n        \"completion_tokens\": 959,\n        \"total_tokens\": 976,\n        \"prompt_tokens_details\": {\n            \"cached_tokens\": 0\n        },\n        \"completion_tokens_details\": {\n            \"reasoning_tokens\": 64\n        }\n    },\n    \"system_fingerprint\": \"fp_35c19d48ca\"\n}",
				"variables": [
					{
						"path": "$.usage.completion_tokens",
						"attribute": {
							"name": "completion_tokens",
							"label": "completion_tokens",
							"value": {
								"type": "INTEGER"
							},
							"annotations": [
								"RESPONSE_PARAMETER"
							],
							"canonicalName": "choices[0].completionTokens"
						}
					},
					{
						"path": "$.choices[0].message.content",
						"attribute": {
							"name": "content",
							"label": "content",
							"value": {
								"type": "TEXT",
								"string": "Some response from LLM"
							},
							"annotations": [
								"RESPONSE_PARAMETER"
							],
							"canonicalName": "choices[0].value"
						}
					},
					{
						"path": "$.model",
						"attribute": {
							"name": "model",
							"label": "model",
							"value": {
								"type": "TEXT"
							},
							"annotations": [
								"RESPONSE_PARAMETER"
							],
							"canonicalName": "model_name"
						}
					},
					{
						"path": "$.usage.prompt_tokens",
						"attribute": {
							"name": "prompt_tokens",
							"label": "prompt_tokens",
							"value": {
								"type": "INTEGER"
							},
							"annotations": [
								"RESPONSE_PARAMETER"
							],
							"canonicalName": "choices[0].promptTokens"
						}
					},
					{
						"path": "$.usage.total_tokens",
						"attribute": {
							"name": "total_tokens",
							"label": "total_tokens",
							"value": {
								"type": "INTEGER"
							},
							"annotations": [
								"RESPONSE_PARAMETER"
							],
							"canonicalName": "choices[0].totalTokens"
						}
					}
				]
			}
		}
	]
}