Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
Important
Items marked preview in this article are currently in preview. This preview is provided without a service-level agreement, and Microsoft doesn't recommend it for production workloads. Certain features might not be supported or might have constrained capabilities. For more information, see Supplemental Terms of Use for Microsoft Azure Previews.
Many organizations secure internal services with certificates issued by their own private certificate authority (CA) instead of a public CA. When a Microsoft Foundry agent calls one of these services, the TLS handshake fails because the agent doesn't trust your CA. Private CA trust fixes this problem: you register your CA's public certificate once on the Foundry resource, and Foundry Agent Service trusts it for outbound HTTPS calls while certificate and hostname verification stay on.
Use private CA trust when your agents need to reach:
- Internal MCP servers, for example an MCP server on your Azure Kubernetes Service (AKS) cluster that serves a certificate from your enterprise CA.
- Internal REST APIs that you call through OpenAPI tools.
- Your own AI gateway that fronts your models, when you bring your own model and the gateway uses an internal certificate.
- Internal services called directly from hosted agent code, without baking CA files into your container image.
With private CA trust, you don't need to run an extra reverse proxy, expose a service on a public port, embed root certificates in container images, or turn off certificate verification.
In this article, you store your CA certificate in Azure Key Vault, add it to your Foundry resource's trust configuration, and verify that an agent accepts your trusted endpoint and rejects a certificate from an unregistered CA.
How private CA trust works
You configure trust once, on the Foundry resource (the Microsoft.CognitiveServices/accounts resource). Every project in that resource uses the same trust configuration.
- Upload your CA's public certificate, in PEM format, to Azure Key Vault as a secret.
- Grant the Foundry resource's managed identity permission to read that secret.
- Add a reference to the secret, pinned to a specific secret version, in the resource's
trustedCertificateSourcesproperty. - Foundry reads the certificate and adds it as a trust anchor for outbound TLS. Public CAs stay trusted. Your CA is added, not substituted.
Where trust applies depends on how the agent reaches your service:
| Connection path | Examples | Where your CA is trusted | When a change takes effect |
|---|---|---|---|
| Tools and models called through the project's data proxy | Prompt agent with an OpenAPI or MCP tool, a toolbox tool used by a hosted agent, a bring-your-own-model gateway connection | The project's single-tenant data proxy, in your virtual network | Usually within a minute after the resource update succeeds. Foundry applies the change to every project capability host in the resource. You don't need to recreate capability hosts. |
| Direct HTTPS calls from hosted agent code | Your Python code calls https://api.contoso.internal with requests or httpx |
The hosted agent's session sandbox trust store, installed before your code starts | When a new session sandbox is provisioned. For existing sessions, see Refresh trust in existing hosted agent sessions. |
For more information about the data proxy and how agent traffic flows, see Deep dive into Foundry Agent Service networking.
Private CA trust doesn't change network access or authentication:
- It doesn't open a network path. The agent must already be able to resolve and reach your service through private DNS, routes, firewall rules, and egress policy.
- It doesn't authenticate the agent. Keep your existing authentication, such as API keys, OAuth, or managed identity, on the service.
- It doesn't make a bad certificate valid. The server must present a certificate that matches its DNS name and is within its validity period, plus any intermediate certificates.
Prerequisites
- A Foundry resource and project that use private networking for Foundry Agent Service (standard agent setup with your own virtual network). Tools, toolboxes, and bring-your-own-model gateway calls use private CA trust only through the project's data proxy, which exists in this setup.
- A managed identity on the Foundry resource. A system-assigned identity is the simplest option. For identity rules, see Grant the Foundry resource access to the secret.
- An Azure Key Vault that uses Azure role-based access control (RBAC). The vault can be in a different resource group or region from the Foundry resource. This article assumes the vault is in the same subscription.
- The public certificate of your root CA, in PEM format. Get it from your PKI or security team. Never upload a private key, a PFX file, or a P12 file.
- An HTTPS service that presents a certificate chain issued by that CA, reachable from your agent's virtual network.
- Permissions:
- To update the Foundry resource, for example Contributor on the resource.
- To upload secrets, Key Vault Secrets Officer on the vault.
- To create the role assignment for the resource's identity, Role Based Access Control Administrator or User Access Administrator on the vault. Contributor alone can't create role assignments.
- The latest version of the Azure CLI, signed in with
az login. The examples use Bash. In PowerShell, keep JSON in files and pass them with@fileto avoid quoting problems. - OpenSSL, to inspect certificates.
- For hosted agents that make direct HTTPS calls, a hosted agent deployed to the same project. For more information, see Deploy a hosted agent.
Check your CA certificate
Check the certificate before you upload it. It's easier to find problems with the certificate chain on your own machine than from an agent's error message.
Confirm the file contains only certificates, with no private key:
grep -q "PRIVATE KEY" root-ca.pem && echo "STOP: this file contains a private key"Check that the certificate is a CA certificate that's currently valid:
openssl x509 -in root-ca.pem -noout -subject -dates -fingerprint -sha256 -ext basicConstraints,keyUsage,subjectKeyIdentifier,authorityKeyIdentifierLook for
CA:TRUEandCertificate Signin the output, and anotAfterdate in the future. Record the SHA-256 fingerprint so you can confirm later that you registered the right certificate.Confirm that your service's certificate chains to the root CA with strict checks:
# Leaf issued directly by the root: openssl verify -x509_strict -CAfile root-ca.pem leaf.pem # Leaf issued by an intermediate CA: openssl verify -x509_strict -CAfile root-ca.pem -untrusted intermediates.pem leaf.pemThe command must print
leaf.pem: OK.
Keep these rules in mind:
- Register the root CA. Configure your server to send its leaf certificate plus every intermediate certificate during the TLS handshake. Don't rely on clients fetching missing intermediates.
- Include key identifiers. Every certificate in the chain needs a Subject Key Identifier (SKI) and an Authority Key Identifier (AKI). Some TLS clients, including Python 3.13 and later, turn on strict certificate checks by default and reject chains that are missing them. If your certificates lack these extensions, ask your PKI team to reissue them. Don't turn off strict verification.
- Bundle multiple CAs if you need to. A single secret can contain several PEM certificates concatenated into one file, for example when different teams use different issuing CAs.
- Register only valid CA certificates. Foundry doesn't reject a leaf certificate or an expired CA when you save the configuration, so check every certificate with the commands in this section first.
Store the CA certificate in Key Vault
Store the certificate as a Key Vault secret, not as a Key Vault certificate object. Foundry reads the secret's PEM text.
Set variables for your environment:
SUBSCRIPTION_ID="<subscription-id>" RESOURCE_GROUP="<foundry-resource-group>" ACCOUNT_NAME="<foundry-resource-name>" KV_RESOURCE_GROUP="<key-vault-resource-group>" KV_NAME="<key-vault-name>" SECRET_NAME="corp-root-ca" API_VERSION="2026-07-15-preview" ACCOUNT_ID=$(az cognitiveservices account show --subscription "$SUBSCRIPTION_ID" \ -g "$RESOURCE_GROUP" -n "$ACCOUNT_NAME" --query id -o tsv) KV_ID=$(az keyvault show --subscription "$SUBSCRIPTION_ID" \ -g "$KV_RESOURCE_GROUP" -n "$KV_NAME" --query id -o tsv)Upload the PEM file and capture the secret version:
SECRET_VERSION=$(az keyvault secret set --subscription "$SUBSCRIPTION_ID" \ --vault-name "$KV_NAME" --name "$SECRET_NAME" \ --file root-ca.pem --encoding utf-8 \ --content-type "application/x-pem-file" \ --query id -o tsv | awk -F/ '{print $NF}') echo "$SECRET_VERSION"
Foundry uses the exact secret version you reference. Uploading a new version later doesn't change what Foundry trusts until you update the reference. This pinning prevents an accidental or unauthorized change to the vault from changing what your agents trust.
Allow access to a network-restricted vault
If your vault has public network access disabled or limited by firewall rules, open the vault's Networking settings in the Azure portal and select Allow trusted Microsoft services to bypass this firewall. You can also run:
az keyvault update --subscription "$SUBSCRIPTION_ID" -g "$KV_RESOURCE_GROUP" -n "$KV_NAME" \
--bypass AzureServices
This exception doesn't replace authorization. The Foundry resource's identity still needs the role assignment in the next section.
Grant the Foundry resource access to the secret
The Foundry resource's managed identity reads the secret. The project's identity isn't used.
- If the resource has only a system-assigned identity, that identity reads the secret.
- If the resource has a user-assigned identity, the user-assigned identity reads the secret, even when a system-assigned identity is also attached.
- If you add a user-assigned identity to a resource that already reads the secret with its system-assigned identity, the switch can take 30 minutes or more. During the change, grant access to both identities.
Assign Key Vault Secrets User to the identity on the vault. This example uses the system-assigned identity:
PRINCIPAL_ID=$(az cognitiveservices account show --subscription "$SUBSCRIPTION_ID" \
-g "$RESOURCE_GROUP" -n "$ACCOUNT_NAME" --query identity.principalId -o tsv)
az role assignment create --subscription "$SUBSCRIPTION_ID" \
--assignee-object-id "$PRINCIPAL_ID" --assignee-principal-type ServicePrincipal \
--role "Key Vault Secrets User" --scope "$KV_ID"
A vault-scoped assignment lets the identity read every secret in the vault. To limit access, use a dedicated vault for CA certificates or assign the role at the secret scope ($KV_ID/secrets/$SECRET_NAME). If the resource uses a user-assigned identity, assign the role to that identity's principal ID instead. Role assignments can take a few minutes to take effect.
Add the CA to the Foundry resource
The trustedCertificateSources property holds the full list of trusted certificate references. An update replaces the whole list, so always start from the current value and add to it. If more than one person manages the resource, agree on who makes the change.
Save the current configuration:
az resource show --ids "$ACCOUNT_ID" --api-version "$API_VERSION" \ --query "properties.trustedCertificateSources" -o json > trust-before.json cat trust-before.jsonIf the output is
nullor[], no CA is registered yet. If it lists references, include every one of them in the next step unless you intend to remove it.Create a file with the new list. This example registers one secret. To keep existing references, add them to the
certificateBundleReferencesarray.cat > trust-sources.json <<EOF [ { "type": "AzureKeyVault", "resourceId": "${KV_ID}", "certificateBundleReferences": [ { "secretName": "${SECRET_NAME}", "secretVersion": "${SECRET_VERSION}" } ] } ] EOFApply the update:
az resource update --ids "$ACCOUNT_ID" --api-version "$API_VERSION" \ --set properties.trustedCertificateSources=@trust-sources.json \ --query "{state:properties.provisioningState, trust:properties.trustedCertificateSources}" -o jsonFoundry reads each referenced secret, validates the certificates, and applies the configuration to every project in the resource. The command waits until the update finishes, which usually takes under a minute. On success, it prints
Succeededand the new list. On failure, it exits with an error that explains the cause, and Foundry keeps the previous configuration. See Troubleshoot.
If you call the REST API directly with PATCH, the request returns 202 Accepted before Foundry validates your secrets. Poll the URL in the Azure-AsyncOperation response header until it reports Succeeded or Failed. Any other status, such as Accepted or Updating, means the update is still running. A GET on the resource after a failed update shows the previous configuration and no error.
Property reference
| Property | Required | Description |
|---|---|---|
trustedCertificateSources |
Yes | List of certificate sources. Supports one source per Foundry resource. |
trustedCertificateSources[].type |
Yes | Source type. Use AzureKeyVault. |
trustedCertificateSources[].resourceId |
Yes | Azure Resource Manager ID of the key vault. |
trustedCertificateSources[].certificateBundleReferences |
Yes | One to 25 secret references. |
certificateBundleReferences[].secretName |
Yes | Name of the Key Vault secret that holds one or more PEM-encoded CA certificates. |
certificateBundleReferences[].secretVersion |
Yes | Exact secret version. References without a version aren't supported. |
Use Bicep or Terraform
You can set the same property in infrastructure as code. In Bicep:
resource account 'Microsoft.CognitiveServices/accounts@2026-07-15-preview' = {
name: accountName
location: location
kind: 'AIServices'
sku: { name: 'S0' }
identity: { type: 'SystemAssigned' }
properties: {
// ...your existing properties...
trustedCertificateSources: [
{
type: 'AzureKeyVault'
resourceId: keyVault.id
certificateBundleReferences: [
{ secretName: 'corp-root-ca', secretVersion: caSecretVersion }
]
}
]
}
}
Bicep might show warning BCP037 (the property isn't allowed) or BCP081 (no type information for this API version). These warnings don't block deployment.
Foundry doesn't validate the trust configuration when you create the resource. It only validates the trust configuration when you update an existing resource. Also, the resource's identity needs the Key Vault role assignment before Foundry can read the secret, and a new system-assigned identity doesn't exist until the resource is created. For both reasons, create the resource and the role assignment first. Then set trustedCertificateSources in a second deployment, or use the CLI steps in the previous section. This approach ensures Foundry validates your references.
In Terraform, set the same property on the Microsoft.CognitiveServices/accounts resource by using the azapi provider. Use the same two-step approach.
Verify trust from your agent
A successful resource update shows that Foundry accepted the configuration. It doesn't prove your agent can reach your service. Test from the agent itself, using two endpoints:
- A trusted endpoint whose certificate chains to the CA you registered.
- A negative-test endpoint whose certificate comes from a separate CA that you didn't register. Ask your PKI team for a nonproduction certificate for this test.
Verify a prompt agent tool
- In the Foundry portal, open your project, and create or open a prompt agent that uses a tool-capable model.
- Add an OpenAPI tool or MCP tool that points to a read-only operation on your trusted endpoint, with its normal authentication.
- In the agent playground, ask the agent to call the operation and report the tool's actual result.
- Open the run details and check the tool call. The tool call returns your service's response.
- Repeat with a tool that points to the negative-test endpoint. The call fails. The response error includes
The SSL connection could not be establishedand the endpoint's host name.
Check the tool call output in the run details, not only the agent's reply. A model can describe a call that didn't succeed. For a failed call, read the response's error message. The stored tool output only says remote tool call failed.
The error doesn't include the certificate reason. Besides an untrusted CA, it can mean a host name mismatch, an expired certificate, or a missing intermediate. If the error appears, check the certificate chain as described in Troubleshoot. An HTTP 401, 403, or 404 from your service means TLS succeeded and the request reached your service, so it isn't a trust problem.
Verify a bring-your-own-model gateway
If you use bring your own model with a gateway that uses your private CA, run a prompt against an agent that uses the gateway model. Before you register the CA, the call fails with an SSL error. After the update succeeds, the model responds.
Verify a hosted agent
Hosted agents make direct HTTPS calls from your code by using the session's trust store. Foundry installs your registered CA certificates in each new session sandbox before your code starts. This setup works for code-based deployments and custom container images, with no changes to your Dockerfile and no CA files in your image.
Deploy or update your hosted agent after the resource update succeeds.
Start a new session and call your trusted endpoint by using your normal HTTP client, with certificate verification enabled. For example, in Python:
import ssl import urllib.request context = ssl.create_default_context() with urllib.request.urlopen("https://api.contoso.internal/health", context=context, timeout=20) as response: print(response.status)Call the negative-test endpoint the same way. Expect an
ssl.SSLCertVerificationError(or your client's equivalent).Call a public HTTPS endpoint to confirm public CAs are still trusted.
Keep these behaviors in mind:
- Use your client's default trust settings. If your code or image sets its own CA bundle, for example with
REQUESTS_CA_BUNDLE,SSL_CERT_FILE,NODE_EXTRA_CA_CERTS, or a custom certificate store, that setting can override the installed trust. Remove the override, or test each client you use. Java and .NET applications that use their own certificate stores need separate verification. - Trust updates require a fresh sandbox. To refresh an existing session, use the steps in Refresh trust in existing hosted agent sessions.
- Calls through tools use the data proxy. If your hosted agent calls your service through a toolbox tool instead of directly, verify that path separately as described in Verify a prompt agent tool.
Refresh trust in existing hosted agent sessions
After you update the trust configuration, existing sessions pick up the change when a new sandbox is provisioned. The steps depend on whether the session uses a persistent data volume:
Volume-backed sessions: Call the session's stop endpoint:
POST https://{account}.services.ai.azure.com/api/projects/{project}/agents/{agentName}/endpoint/sessions/{sessionId}:stop?api-version=v1The next invocation of that session provisions a fresh sandbox with the updated CA trust and retains its persistent data volume.
Non-volume sessions: After eight hours of inactivity, the next invocation provisions a new sandbox with the updated CA trust. For earlier pickup, create a new agent version and invoke that version.
Rotate or remove a CA
Plan rotation before your CA certificate expires.
To rotate a CA without downtime:
- Create a PEM bundle that contains both the current CA and the new CA. Upload it as a new version of your secret.
- Update the reference to the new secret version. Agents now trust both CAs.
- Move your services to certificates from the new CA, and verify your agents.
- Upload a version that contains only the new CA, and update the reference again.
Because each reference pins a secret version, nothing changes in Foundry until you update the reference.
To remove a CA, apply the full list without the reference you want to remove. To remove all private CAs, set an empty list:
az resource update --ids "$ACCOUNT_ID" --api-version "$API_VERSION" \
--set properties.trustedCertificateSources=[]
Setting the property to null doesn't remove the configuration. A full PUT of the resource, or a Bicep or ARM deployment that omits the property, also leaves the existing configuration in place. Use an empty list to remove it.
Removing a CA affects every project in the Foundry resource. Check with the owners of each project first. Don't delete a secret or vault that a configuration still references.
Limits
| Item | Limit |
|---|---|
| Certificate sources per Foundry resource | One Azure Key Vault |
| Secret references | Up to 25 |
| Certificates per secret | One or more PEM-encoded CA certificates |
| Total CA certificates | Up to 100 across all referenced secrets |
| Secret version | Required. References without a version aren't supported. |
| Supported source | Key Vault secrets. |
The 25-reference limit counts secret references, not certificates. If you have many CAs, combine them into a few bundle secrets.
Known limitations
- You configure private CA trust by using the REST API, Azure CLI, Bicep, or Terraform. The Foundry portal doesn't show the configuration yet.
- Tools, toolboxes, and bring-your-own-model gateways use private CA trust only in projects that use private networking with your own virtual network. Projects without it don't have a data proxy, so their tool calls don't use your CA.
- Hosted agent sessions pick up trust changes only when a new session sandbox is provisioned.
- For hosted agents, the following paths aren't covered yet: Node.js trust after a memory-snapshot resume with egress traffic inspection, and egress proxy trust for sessions restored from a snapshot. Validate these paths before you depend on them.
- Remote builds of hosted agent code don't use your private CA. Dependencies from private package feeds that use a private CA aren't supported during remote build. Use bundled dependencies or a custom image instead.
- Mutual TLS (client certificates) isn't part of this feature.
Move from the private preview API
If you used private CA trust during the private preview, update your scripts and templates to the new property names. The private preview property names aren't supported for updates. Agents keep using the configuration you already set.
| Private preview | Public preview |
|---|---|
trustedCertificates |
trustedCertificateSources |
sourceType |
type |
keyVaultId |
resourceId |
certificates |
certificateBundleReferences |
certificates[].name |
certificateBundleReferences[].secretName |
certificates[].version |
certificateBundleReferences[].secretVersion |
You no longer need to delete and recreate a project's capability host after you change trust. Foundry applies updates to every project in the resource.
Troubleshoot
| Symptom | Likely cause | What to do |
|---|---|---|
| Update fails: Key Vault DNS name can't be resolved, or vault not found | The resourceId points to a vault that doesn't exist |
Copy the vault's resource ID from az keyvault show --query id. |
| Update fails: secret or version not found | Wrong secret name or version, or the version was deleted | Check the name and the full 32-character version in Key Vault. |
| Update fails: secret version is disabled | The referenced version is disabled in Key Vault | Enable the version or reference an enabled one. |
| Update fails: access denied, with a principal ID | The identity in the message can't read the secret, or the vault firewall blocks Foundry | Assign Key Vault Secrets User to that principal ID and wait a few minutes. If the vault restricts network access, turn on Allow trusted Microsoft services to bypass this firewall. |
| Update fails: not a valid certificate bundle | The secret contains a private key, DER data, or a truncated PEM | Upload only complete PEM-encoded public CA certificates. |
| Update fails: more than 100 certificates | The referenced secrets contain more than 100 certificates in total | Remove certificates you don't need. |
| Update rejected: too many items | More than 25 references or more than one source | Combine certificates into fewer bundle secrets. |
| Update rejected: requires a newer API version | You used an older api-version |
Use 2026-07-15-preview or later. |
| Update rejected: Key Vault secret is too large | A Key Vault secret holds up to 25,600 characters | Split the certificates across several secrets. |
| Update succeeded but some projects still fail | Some projects couldn't apply the new configuration. The resource keeps the new configuration, and those projects keep the previous one. | Check the operation's error details. Fix the cause, then submit a changed configuration, for example a new secret version, because resubmitting the same configuration might not retry. If the problem continues, contact Azure support. |
Tool call fails with The SSL connection could not be established after a successful update |
The server doesn't send its intermediates, the hostname doesn't match, the certificate expired, or the wrong root is registered | Test the chain with openssl verify -x509_strict and openssl s_client -connect <host>:443 -servername <host> -showcerts. Compare the root fingerprint with the one you recorded. |
| Tool call fails with a timeout, DNS, or connection error | A network problem, not trust | Check private DNS, routes, firewall, and egress rules from the agent's virtual network. |
| An agent call fails right after a successful update, for example with a database authentication error | Projects are still applying the update | Wait a minute and retry. |
| Hosted agent works in one session and fails in another | An existing session hasn't provisioned a fresh sandbox with the updated trust, or your code overrides the CA bundle | Refresh trust in existing hosted agent sessions. Remove CA bundle overrides. |
| Python 3.13 or later rejects the chain, but older clients accept it | Certificates are missing SKI or AKI extensions | Reissue the certificates with both extensions. Don't turn off strict verification. |