Microsoft Azure AI Foundry Integration

Connect your Microsoft Azure AI Foundry environment to Capsule Security for complete visibility into your AI agents, tools, knowledge bases, and conversation history. The integration covers both the classic Azure AI Foundry portal and the new Foundry experience.

Capsule supports two setup paths for this integration:

• Standard Setup - Capsule automatically discovers resources and assigns the required RBAC roles during the OAuth consent flow. This is the recommended path for most organizations. See Step 1: Configure the Integration.
• Manual Setup - You pre-assign RBAC roles to the Capsule service principal yourself, then connect via OAuth. This is designed for organizations with strict least-privilege policies that do not allow the consenting admin to have role assignment permissions. See Alternative Setup: Manual Setup.

This integration uses Microsoft Entra ID (Azure AD) authentication to sync:

• Agents - AI assistants across the classic and new Foundry experiences
• Tools - Code Interpreter, File Search, Azure AI Search, Bing Grounding, OpenAPI, MCP (Foundry IQ), and Functions
• Knowledge Bases - Vector stores and files attached to agents
• Conversations - Thread messages and chat history
• Audit - Run history with tool invocations and session tracking
• Deployments & Connections - Model deployments and connection metadata
• Inference Logs - Model request and response data via Azure Monitor diagnostic logs
• Invocation - Send prompts to agents and capture responses for security assessments

Before you begin, ensure you have:

• An active Azure subscription with Azure AI Foundry resources deployed
• An Azure Entra ID account in your own tenant to run setup, with the permissions listed in Permissions for the account that runs setup
• Access to the Capsule Security portal

With Standard Setup, Capsule assigns the roles it needs to its own service principal during the OAuth consent flow - you do not pre-assign them yourself. Capsule uses two built-in roles:

• Azure AI Developer - control-plane access to discover and read accounts, projects, deployments, and connections
• Azure AI User - data-plane access to read and invoke agents, threads, responses, and assets

The optional Inference Logs feature additionally requires Monitoring Contributor (to configure diagnostic settings) and Log Analytics Reader (to query the logs).

Capsule's app also uses Microsoft Graph Application.Read.All to resolve its own service principal during setup. This is best-effort and not required for the integration to function.

For more information about Azure RBAC roles, see Azure role-based access control.

Standard Setup assigns the roles above to Capsule's service principal, so the account you sign in with needs both role assignment and read permissions:

User Access Administrator satisfies both requirements. Contributor does not: it can create and manage resources but cannot assign roles.

If your tenant requires admin approval for new applications, an Entra administrator consents to the Capsule application once before setup can complete.

If your organization does not permit the account running setup to assign roles, use Alternative Setup: Manual Setup instead.

Start the integration setup from the Capsule Security portal.

1. Log in to the Capsule Security portal

2. Click Integrations in the left sidebar

3. Find the Azure AI Foundry card and click Set up Integration

4. Click Connect with Microsoft

5. You'll be redirected to Microsoft's sign-in page

Grant Capsule the necessary permissions to access your Azure AI Foundry resources.

1. Sign in with your Azure/Microsoft account that has the required permissions (see Prerequisites)

2. Review the permissions requested by the Capsule application

3. Click Accept to grant consent

During the OAuth consent flow, the consenting admin's token is used to assign roles and discover resources. After setup, Capsule uses its own service principal credentials for ongoing data synchronization. Capsule also uses Microsoft Graph Application.Read.All to resolve its own service principal during setup (best-effort; not required to function).

Capsule assigns and uses these roles:

For the permissions the account running setup needs, see Permissions for the account that runs setup.

Azure AI User provides the following data-plane permissions on AI Services accounts and projects:

Azure AI Developer provides the following control-plane permissions used during discovery:

Log Analytics Reader provides the following permissions on the Log Analytics workspace:

Additional permissions required on the AI Services account for automated diagnostic logging setup:

For more information, see:

• Azure AI Foundry role-based access control
• Azure built-in roles for AI + machine learning
• Enable diagnostic logging for Azure AI Services
• Monitor Azure OpenAI
• User and admin consent in Azure

After you grant consent, Capsule automatically configures the integration.

• All Azure subscriptions you have access to are discovered
• AI Foundry projects within those subscriptions are detected
• Capsule assigns the Azure AI User and Azure AI Developer roles to its own service principal on the discovered resources, then begins syncing
• Capsule creates a diagnostic setting on each AI Services resource
• The Audit and RequestResponse log categories are enabled
• Logs are sent to a Log Analytics workspace for querying

No manual project configuration is needed.

For more information, see Enable diagnostic logging for Azure AI Services and Monitor Azure OpenAI.

Once the integration is configured:

• Initial sync begins automatically
• First sync may take several minutes depending on data volume
• View synced agents in Inventory → Agents
• View conversations in Observability → Filter Activity Type - Session

Capsule syncs your AI Foundry data as its own service principal, so ongoing access depends on that service principal holding the Azure AI User role on your AI Foundry resources. Use the read-only checks below to confirm the assignment is in place.

These checks apply to the project-based Foundry experience - Microsoft.CognitiveServices accounts of kind AIServices.

Everything in this step is read-only and needs only Reader on the scope you are checking. Check at whichever level you expect the assignment to exist: a subscription, a resource group, or an individual AI Services account.

In the Azure portal:

1. Open the subscription, resource group, or AI Services account
2. Go to Access control (IAM) → Check access
3. Search for and select the Capsule service principal
4. Read the result. Azure AI User (or Foundry User) should be listed under Role assignments, which includes assignments inherited from a parent scope

If the role is listed and no deny assignment applies, access is in place; contact Capsule support if data is still missing. If the role is absent, see Granting the role.

The same result lists any Deny assignments that apply at that scope. Deny assignments are typically created by a managed application and are not overridden by a role assignment at any scope, including subscription scope. If one applies to the Capsule service principal, assigning a role will not resolve it - your Azure platform team has to exclude the service principal from the deny assignment.

The equivalent role check on the command line:

az role assignment list --assignee-object-id <SP_OBJECT_ID> --scope <SCOPE> --include-inherited -o table

Replace <SCOPE> with the resource ID of the level you are checking:

Replace <SP_OBJECT_ID> with the object ID of the Capsule service principal in your tenant. Capsule provides the Application (Client) ID to use as <CAPSULE_APP_ID>; the command below prints the object ID as a GUID, which you paste in place of <SP_OBJECT_ID>:

az ad sp show --id "<CAPSULE_APP_ID>" --query id -o tsv

The Azure AI User role carries the data-plane permissions Capsule needs. It is being renamed to Foundry User, so assign it by role definition ID rather than by name. This command writes a role assignment and requires Owner or User Access Administrator on <SCOPE>:

az role assignment create \
  --assignee-object-id <SP_OBJECT_ID> \
  --assignee-principal-type ServicePrincipal \
  --role 53ca6127-db72-4b80-b1b0-d745d6d5456d \
  --scope <SCOPE>

Assigning at subscription or resource group scope covers every AI Services account beneath it, including accounts created later. Account scope also works and is narrower.

To do the same in the Azure portal: open the subscription, resource group, or AI Services account and go to Access control (IAM) → Add → Add role assignment. Search for Azure AI User (or Foundry User), confirm its role definition ID is 53ca6127-db72-4b80-b1b0-d745d6d5456d, then choose the User, group, or service principal member type and select the Capsule service principal.

You do not need to reconnect the integration in Capsule. The new assignment takes effect automatically.

Use this setup path if your organization requires least-privilege access and wants full control over the permissions granted to the Capsule service principal.

With Manual Setup, you run a setup script that creates a custom Azure role with only the exact permissions Capsule needs, then complete the standard OAuth consent flow. Capsule skips automatic role assignment during setup.

The setup script creates a least-privilege custom role called Capsule AI Foundry Reader with only the permissions Capsule needs:

The role grants connection metadata read only (connections/read), never connections/listsecrets - secrets are never accessed. The consent flow also grants Microsoft Graph Application.Read.All for best-effort service principal lookup.

The setup script creates this custom Azure role and assigns it to the Capsule service principal.

The setup script automates the entire manual setup process - creating the service principal, defining the custom role, assigning it, and verifying the configuration.

Prerequisites:

• Azure CLI installed and logged in (az login)
• Owner or User Access Administrator on the target subscription (to create role definitions and assignments)
• The Capsule Application (Client) ID - contact the Capsule team to obtain this

Save the script below to a file, make it executable, and run it:

#!/usr/bin/env bash
set -euo pipefail

readonly RED='\033[0;31m'
readonly GREEN='\033[0;32m'
readonly YELLOW='\033[1;33m'
readonly BLUE='\033[0;34m'
readonly NC='\033[0m'

info()    { echo -e "${BLUE}[INFO]${NC}  $*"; }
success() { echo -e "${GREEN}[OK]${NC}    $*"; }
warn()    { echo -e "${YELLOW}[WARN]${NC}  $*"; }
fail()    { echo -e "${RED}[ERROR]${NC} $*" >&2; exit 1; }

usage() {
  cat <<EOF
Azure AI Foundry - Capsule Manual Setup

Provisions the minimum RBAC roles for the Capsule service principal on your
Azure AI Foundry (AI Services) account.

Usage:
  $(basename "$0") [OPTIONS]

Required:
  --capsule-app-id    Application (client) ID of the Capsule multi-tenant app
  --subscription-id   Azure subscription ID containing the AI Services account
  --resource-group    Resource group containing the AI Services account
  --ai-account-name   Name of the Azure AI Services account

Options:
  --no-custom-role    Use three built-in Azure roles instead of creating a custom role
  --help              Show this help message

By default, the script creates a least-privilege custom role "Capsule AI Foundry Reader"
with only the exact permissions required. Use --no-custom-role to assign built-in roles instead.
EOF
  exit 0
}

CAPSULE_APP_ID=""
SUBSCRIPTION_ID=""
RESOURCE_GROUP=""
AI_ACCOUNT_NAME=""
USE_CUSTOM_ROLE=true

while [[ $# -gt 0 ]]; do
  case "$1" in
    --capsule-app-id)   CAPSULE_APP_ID="$2"; shift 2 ;;
    --subscription-id)  SUBSCRIPTION_ID="$2"; shift 2 ;;
    --resource-group)   RESOURCE_GROUP="$2"; shift 2 ;;
    --ai-account-name)  AI_ACCOUNT_NAME="$2"; shift 2 ;;
    --no-custom-role)   USE_CUSTOM_ROLE=false; shift ;;
    --help)             usage ;;
    *)                  fail "Unknown option: $1. Use --help for usage." ;;
  esac
done

[[ -n "$CAPSULE_APP_ID"  ]] || fail "--capsule-app-id is required"
[[ -n "$SUBSCRIPTION_ID" ]] || fail "--subscription-id is required"
[[ -n "$RESOURCE_GROUP"  ]] || fail "--resource-group is required"
[[ -n "$AI_ACCOUNT_NAME" ]] || fail "--ai-account-name is required"

readonly AI_ACCOUNT_SCOPE="/subscriptions/${SUBSCRIPTION_ID}/resourceGroups/${RESOURCE_GROUP}/providers/Microsoft.CognitiveServices/accounts/${AI_ACCOUNT_NAME}"
readonly SUBSCRIPTION_SCOPE="/subscriptions/${SUBSCRIPTION_ID}"

readonly ROLE_AI_USER="53ca6127-db72-4b80-b1b0-d745d6d5456d"
readonly ROLE_AI_DEVELOPER="64702f94-c441-49e6-a78b-ef80e0188fee"
readonly ROLE_READER="acdd72a7-3385-48ef-bd42-f606fba81ae7"

info "Validating prerequisites..."

if ! command -v az &>/dev/null; then
  fail "Azure CLI (az) is not installed. See https://aka.ms/install-azure-cli"
fi

if ! az account show &>/dev/null; then
  fail "Not logged into Azure CLI. Run 'az login' first."
fi

az account set --subscription "$SUBSCRIPTION_ID" 2>/dev/null \
  || fail "Cannot access subscription $SUBSCRIPTION_ID. Verify the ID and your permissions."

success "Azure CLI authenticated - subscription $SUBSCRIPTION_ID selected"

az resource show --ids "$AI_ACCOUNT_SCOPE" --query "id" -o tsv &>/dev/null \
  || fail "AI Services account '${AI_ACCOUNT_NAME}' not found in resource group '${RESOURCE_GROUP}'"

success "AI Services account '${AI_ACCOUNT_NAME}' found"

info "Ensuring Capsule service principal exists in your tenant..."

if ! az ad sp create --id "$CAPSULE_APP_ID" -o none 2>/dev/null; then
  info "Service principal already exists - continuing"
fi

SP_OBJECT_ID=$(az ad sp show --id "$CAPSULE_APP_ID" --query "id" -o tsv 2>/dev/null) \
  || fail "Could not retrieve service principal for app ID $CAPSULE_APP_ID"

success "Service principal object ID: ${SP_OBJECT_ID}"

assign_role() {
  local role_id="$1"
  local scope="$2"
  local label="$3"

  info "Assigning ${label}..."

  if az role assignment create \
       --assignee-object-id "$SP_OBJECT_ID" \
       --assignee-principal-type ServicePrincipal \
       --role "$role_id" \
       --scope "$scope" \
       -o none 2>/dev/null; then
    success "${label} assigned"
  else
    if az role assignment list \
         --assignee-object-id "$SP_OBJECT_ID" \
         --role "$role_id" \
         --scope "$scope" \
         --query "[0].id" -o tsv 2>/dev/null | grep -q .; then
      info "${label} already assigned - skipping"
    else
      fail "Failed to assign ${label}. Ensure you have Owner or User Access Administrator permissions."
    fi
  fi
}

readonly CUSTOM_ROLE_NAME="Capsule AI Foundry Reader"

if [[ "$USE_CUSTOM_ROLE" == "true" ]]; then
  info "Creating custom role '${CUSTOM_ROLE_NAME}'..."

  EXISTING_SCOPE=$(az role definition list --name "$CUSTOM_ROLE_NAME" \
    --query "[0].assignableScopes[0]" -o tsv 2>/dev/null)

  if [[ -n "$EXISTING_SCOPE" ]]; then
    if [[ "$EXISTING_SCOPE" == "$SUBSCRIPTION_SCOPE" ]]; then
      info "Custom role already exists with correct scope - skipping creation"
    else
      fail "Custom role '${CUSTOM_ROLE_NAME}' exists but is scoped to ${EXISTING_SCOPE}, not ${SUBSCRIPTION_SCOPE}. Delete the existing role or use --no-custom-role."
    fi
  else
    az role definition create --role-definition '{
      "Name": "'"$CUSTOM_ROLE_NAME"'",
      "Description": "Least-privilege permissions for Capsule Security AI Foundry integration",
      "Actions": [
        "Microsoft.Resources/subscriptions/read",
        "Microsoft.CognitiveServices/accounts/read",
        "Microsoft.CognitiveServices/accounts/projects/read",
        "Microsoft.CognitiveServices/accounts/connections/read",
        "Microsoft.CognitiveServices/accounts/deployments/read",
        "Microsoft.CognitiveServices/accounts/privateEndpointConnections/read"
      ],
      "DataActions": [
        "Microsoft.CognitiveServices/accounts/AIServices/agents/read",
        "Microsoft.CognitiveServices/accounts/AIServices/agents/write",
        "Microsoft.CognitiveServices/accounts/AIServices/assets/read",
        "Microsoft.CognitiveServices/accounts/AIServices/responses/read",
        "Microsoft.CognitiveServices/accounts/AIServices/responses/write",
        "Microsoft.CognitiveServices/accounts/AIServices/applications/invoke/action"
      ],
      "NotActions": [],
      "NotDataActions": [],
      "AssignableScopes": [
        "/subscriptions/'"$SUBSCRIPTION_ID"'"
      ]
    }' -o none || fail "Failed to create custom role definition"
    success "Custom role '${CUSTOM_ROLE_NAME}' created"
  fi

  info "Waiting for role definition to propagate..."
  for i in $(seq 1 36); do
    if az role definition list --name "$CUSTOM_ROLE_NAME" --query "[0].id" -o tsv 2>/dev/null | grep -q .; then
      success "Custom role is available"
      break
    fi
    if [[ $i -eq 36 ]]; then
      fail "Custom role '${CUSTOM_ROLE_NAME}' not visible after 3 minutes. Azure role propagation may be delayed - retry shortly."
    fi
    sleep 5
  done

  assign_role "$CUSTOM_ROLE_NAME" "$SUBSCRIPTION_SCOPE" "$CUSTOM_ROLE_NAME"
else
  assign_role "$ROLE_AI_USER"     "$AI_ACCOUNT_SCOPE"   "Azure AI User"
  assign_role "$ROLE_AI_DEVELOPER" "$AI_ACCOUNT_SCOPE"   "Azure AI Developer"
  assign_role "$ROLE_READER"       "$SUBSCRIPTION_SCOPE" "Reader"
fi

info "Verifying role assignments..."

ASSIGNED_ROLES=$(az role assignment list \
  --assignee-object-id "$SP_OBJECT_ID" \
  --query "[].{role:roleDefinitionName, scope:scope}" \
  -o table 2>/dev/null) || fail "Could not list role assignments"

echo ""
echo "$ASSIGNED_ROLES"
echo ""
success "All role assignments verified"

info "Discovering AI Foundry project endpoints..."

PROJECTS=$(az rest \
  --method GET \
  --url "https://management.azure.com${AI_ACCOUNT_SCOPE}/projects?api-version=2025-04-01-preview" \
  --query "value[].{name:name, endpoint:properties.endpoints.\"AI Foundry API\"}" \
  -o table 2>/dev/null) || true

echo ""
echo -e "${GREEN}════════════════════════════════════════════════════════════════${NC}"
echo -e "${GREEN}  Capsule Azure AI Foundry setup complete${NC}"
echo -e "${GREEN}════════════════════════════════════════════════════════════════${NC}"
echo ""
echo "Use the following values in Capsule configuration:"
echo ""
echo -e "  ${BLUE}Subscription ID:${NC}       ${SUBSCRIPTION_ID}"
echo -e "  ${BLUE}Resource Group:${NC}        ${RESOURCE_GROUP}"
echo -e "  ${BLUE}AI Account Name:${NC}       ${AI_ACCOUNT_NAME}"
echo -e "  ${BLUE}SP Object ID:${NC}          ${SP_OBJECT_ID}"

if [[ -n "${PROJECTS:-}" ]]; then
  echo ""
  echo "Discovered projects:"
  echo "$PROJECTS"
fi

echo ""
echo -e "  ${BLUE}Roles Assigned:${NC}"
if [[ "$USE_CUSTOM_ROLE" == "true" ]]; then
  echo "    - ${CUSTOM_ROLE_NAME}  on  subscription ${SUBSCRIPTION_ID}"
  echo "      (least-privilege custom role - replaces the built-in roles)"
else
  echo "    - Azure AI User       on  ${AI_ACCOUNT_NAME}"
  echo "    - Azure AI Developer   on  ${AI_ACCOUNT_NAME}"
  echo "    - Reader               on  subscription ${SUBSCRIPTION_ID}"
fi
echo ""

chmod +x azure-ai-foundry-manual-setup.sh

./azure-ai-foundry-manual-setup.sh \
  --capsule-app-id "<provided-by-capsule>" \
  --subscription-id "<your-subscription-id>" \
  --resource-group "<your-resource-group>" \
  --ai-account-name "<your-ai-services-account-name>"

The script will:

1. Create the Capsule service principal in your tenant (idempotent)
2. Create the least-privilege Capsule AI Foundry Reader custom role with the permissions listed above
3. Assign the custom role to the service principal at subscription scope
4. Verify the role assignment
5. Discover AI Foundry project endpoints in your account

1. Follow Step 1: Configure the Integration in Capsule to start the setup
2. Enable the Manual Setup option before connecting
3. Complete the OAuth consent flow - Capsule will discover your projects using the pre-assigned role and skip automatic role assignment
4. Verify your agents appear in Inventory → Agents after the initial sync

./azure-ai-foundry-manual-setup.sh \
  --capsule-app-id "<provided-by-capsule>" \
  --subscription-id "<your-subscription-id>" \
  --resource-group "<your-resource-group>" \
  --ai-account-name "<your-ai-services-account-name>" \
  --no-custom-role

1. Consent failed or permissions error

   • Verify the account running setup meets Permissions for the account that runs setup (Standard Setup assigns the Azure AI Developer and Azure AI User roles during consent)
   • For Manual Setup, verify the Capsule service principal already has the required roles assigned
   • Ensure your account has access to the subscriptions containing AI Foundry resources

2. No projects discovered

   • Confirm AI Foundry resources exist in your Azure subscriptions
   • Check that the resources are in subscriptions the account that ran setup can read - see Permissions for the account that runs setup

3. Sync not completing

   • Allow several minutes for the initial sync to complete
   • Confirm the Capsule service principal holds the Azure AI User role on your AI Foundry resources - see Verifying Access After Setup
   • Contact support if the issue persists

4. No inference logs appearing

   • Verify the Capsule service principal has the Monitoring Contributor role at the subscription level (required to create diagnostic settings)
   • Verify the Capsule service principal has the Log Analytics Reader role on the Log Analytics workspace
   • It can take up to two hours for logs to appear after diagnostic settings are configured
   • Check that the AI Services resource has a diagnostic setting with the RequestResponse category enabled in the Azure portal under Monitoring → Diagnostic settings

5. Role assignment command fails with "principal not found"

   • Ensure you ran az ad sp create --id <CAPSULE_APP_ID> first to create the service principal in your tenant
   • Verify the Capsule Application ID is correct

6. Agent sync fails after Manual Setup

   • Verify the Azure AI User role is assigned on the correct AI Services account (not just the subscription)
   • Run az role assignment list --assignee-object-id <SP_OBJECT_ID> --scope <AI_ACCOUNT_RESOURCE_ID> -o table to check

7. No projects discovered with Manual Setup

   • Verify the Azure AI Developer role is assigned on the AI Services account
   • Verify the Reader role is assigned on the subscription
   • Confirm that the AI Services account has AI Foundry projects deployed

For help with this integration:

• Email: support@capsule.security
• Include: Your organization ID, integration status, and any error messages

For Azure-specific issues:

• Azure AI Foundry documentation
• Azure support