Issue: 401 Unauthorized Error When Connecting Custom Engine Agent to Copilot Studio

[sharetech-in]

Description

I'm experiencing a 401 authentication error when trying to connect a Custom Engine Agent (M365 SDK Agent) to Copilot Studio for conversation handoff. The connector in Copilot Studio is successfully calling the agent endpoint, but Bot Framework authentication is failing.

Environment

• Agent Type: Custom Engine Agent (M365 SDK)
• Bot Framework SDK: @microsoft/agents-hosting (latest)
• Deployment: Azure App Service
• Authentication: Managed Identity (User-assigned)
• Node.js Version: 24.x

Setup Details

Azure Configuration

Managed Identity:

• Type: User-assigned Managed Identity
• Client ID: <Client ID>
• Tenant ID: <Tenant ID>
• Object ID: <Object ID>

Azure App Service Settings:

{
  "clientId": "<Client ID>",
  "tenantId": "<Tenant ID>"
}

Bot Registration:

• Bot Type: Azure Bot (registered via Bicep)
• MSA App Type: UserAssignedMSI
• Endpoint: https://<appservice-name>.azurewebsites.net/api/messages

Code Implementation

Backend (index.ts):

import { authorizeJWT, CloudAdapter, getAuthConfigWithDefaults, Request } from "@microsoft/agents-hosting";

const server = express();
const adapter = agentApp.adapter as CloudAdapter;
const authConfig = getAuthConfigWithDefaults();

server.post(
  "/api/messages",
  authorizeJWT(authConfig),
  (req: Request, res: Response) => adapter.process(req, res, (context) => agentApp.run(context))
);

Manifest (manifest.json):

{
  "copilotAgents": {
    "customEngineAgents": [
      {
        "type": "bot",
        "id": "${{BOT_ID}}"
      }
    ]
  },
  "bots": [
    {
      "botId": "${{BOT_ID}}",
      "scopes": ["copilot", "personal", "team"]
    }
  ]
}

Problem

When Copilot Studio attempts to invoke the agent through the configured connector, the request fails with:

connectorRequestFailure
The connector returned an HTTP error with code 401.

What I've Tried

1. ✅ Verified clientId and tenantId are correctly set in Azure App Service Configuration
2. ✅ Confirmed Managed Identity is assigned to the App Service
3. ✅ Verified Bot Registration has correct MSI configuration
4. ✅ Tested that the endpoint is accessible (/api/messages returns 401, which is expected without valid auth)
5. ✅ Checked that Bot ID in manifest matches the Managed Identity Client ID
6. ⏳ App Service restart pending to load new environment variables

Questions

1. Is Managed Identity authentication supported when Copilot Studio calls Custom Engine Agents via Bot Framework?

2. What authentication mechanism does Copilot Studio use when calling the /api/messages endpoint?

   • Does it send a Bot Framework JWT token?
   • What should be in the audience claim of the token?
   • Should it match clientId or something else?

3. How should getAuthConfigWithDefaults() be configured for Managed Identity authentication?

   • Does it automatically read clientId and tenantId from environment variables?
   • Are there additional settings needed for Copilot Studio integration?

4. Is there special configuration needed in Copilot Studio when connecting to an agent using Managed Identity vs. App Password?

5. Are there logs or diagnostics I can check to see exactly why Bot Framework is rejecting the authentication?

Expected Behavior

1. User interacts with Copilot Studio agent
2. Agent triggers handoff/escalation action
3. Copilot Studio calls my Custom Engine Agent at /api/messages
4. Bot Framework validates the JWT token from Copilot Studio
5. My agent receives the message and processes handoff

Actual Behavior

Step 4 fails with 401 Unauthorized error from authorizeJWT(authConfig) middleware.

Documentation Gaps

I couldn't find clear documentation on:

• How to configure Managed Identity authentication for Custom Engine Agents called by Copilot Studio
• What the authentication flow looks like between Copilot Studio and Custom Engine Agents
• Whether Copilot Studio uses Bot Framework protocol or a different mechanism
• How to debug Bot Framework authentication issues in this scenario

Request

Please provide guidance on:

1. Correct configuration for Managed Identity + Copilot Studio integration
2. Expected authentication flow and token format
3. Debugging steps to identify the authentication failure
4. Whether this scenario is supported or if App Password authentication is required

Steps to Reproduce

1. Create a Custom Engine Agent:

   • Install Microsoft 365 Agents Toolkit extension in VS Code
   • Create a new Custom Engine Agent (M365 SDK Agent) project
   • Deploy the agent to Azure App Service with Managed Identity authentication
   • Ensure Bot registration is configured with UserAssignedMSI type

2. Configure Copilot Studio:

   • Open Copilot Studio and create/open an agent
   • Go to the Agents tab
   • Select Microsoft SDK option
   • Configure the connection:
     • Authentication: None
     • Endpoint: https://your-app.azurewebsites.net/api/messages

3. Create Handoff Topic:

   • Create a topic in Copilot Studio with handoff/escalation action
   • Configure it to transfer conversation to your Custom Engine Agent

4. Test the Handoff:

   • Start a conversation in Copilot Studio
   • Trigger the handoff action
   • Observe the 401 authentication error

Related Links

• Custom Engine Agents Documentation
• Bot Framework Authentication
• Managed Identity for Bot Service
• Microsoft 365 Agents Toolkit

---

Environment: Custom Engine Agent created using Microsoft 365 Agents Toolkit extension in VS Code

[m365-agent-toolkit-assistant]

👋 Hi ShareTech (@sharetech-in),

Thank you for reporting this issue! We want to let you know that:

⏱️ Our team will personally review your issue
🎯 You can expect a response within 2 business days

✨ This is an AI-generated initial response
🤖 AI-Generated Preliminary Analysis:

Based on similar issues, your scenario involves a crucial authentication nuance:

Key Points & Answers

1. Managed Identity authentication is NOT currently supported for Bot-to-Copilot Studio Custom Engine Agent calls.

   • Copilot Studio expects either "App Password" (client secret/certificate-based) or, in some cases, no authentication, but not Managed Identity for bot endpoints.
   • Managed Identity is supported for Teams/Graph, not Copilot Studio calls.

2. Copilot Studio likely does NOT send a Bot Framework JWT token (with correct audience/issuer) expected for Managed Identity.

   • If you configure Copilot Studio "Authentication: None," no auth header is present.
   • If set as a bot, Copilot Studio expects a traditional App Password model.

3. getAuthConfigWithDefaults only works if incoming JWT is valid for your Managed Identity, which is not the case here.

4. Workaround:

   • Switch your agent to "App Password" authentication (App Registration with client secret/cert).
   • Supply the App ID and secret during bot registration/config, and test Copilot Studio again.

5. Debugging:

   • Check Azure App Service logs and enable verbose logging for your bot.
   • Add code to log all headers and token validation failures.

6. Docs Gaps:

   • There's currently no Microsoft doc describing Copilot Studio→Custom Agent authentication with MSI. This is a common source of confusion.

Summary:
Switch to "App Password" for your bot registration, redeploy, reconfigure Copilot Studio, and you should resolve the 401. Managed Identity won't work for this scenario due to protocol differences.

References:

• Custom Engine Agent main doc
• Bot Framework Auth Models
• Related GitHub Issue

Let me know if you need a step-by-step App Password switch!

✨We'd love your feedback! Please take a moment to fill out our survey.

---

Note: This is an automated first response generated by AI. A human team member will review your issue and provide a more detailed response soon. We appreciate your patience!

[sharetech-in]

Alice Wang (@wh-alice) & Yu Zhang (@summzhan) — do you have any idea about this issue? I’ve tried using OAuth 2.0 as well to connect the Copilot Studio agent with the SDK agent, but it’s still not working. It seems to be an issue with bot-to-bot communication.

[summzhan]

ShareTech (@sharetech-in), thanks for reaching out, you issue looks like an issue of Copilot Studio(MCS), the issue occurs in the step of select Agents SDK in MCS. As Agents Toolkit I can help when you are having issues with any operations in ATK but we are not sure the right operation of MCS. Could you report this issue to MCS team?

[MattB-msft]

ShareTech (@sharetech-in) Can you give me a bit more detail about how your calling into Copilot Studio?
Are you using the CopilotStudioClient from the microsoft/agents-copilotstudio-client package
or some other method?

if your using the copilotStudio-Client package... Please take a moment to review the readme here: https://github.com/microsoft/Agents/tree/main/samples/nodejs/copilotstudio-client

[sharetech-in]

@sharetech-in, thanks for reaching out, you issue looks like an issue of Copilot Studio(MCS), the issue occurs in the step of select Agents SDK in MCS. As Agents Toolkit I can help when you are having issues with any operations in ATK but we are not sure the right operation of MCS. Could you report this issue to MCS team?

Thanks for your response, Yu Zhang (@summzhan).

I understand that the issue could be on the Copilot Studio side, related to Azure configuration, or possibly within the Agent SDK. However, I’d really appreciate it if you could try creating a simple custom engine agent (like an echo bot), deploy it on Azure following the Microsoft Agent SDK deployment lifecycle, and then attempt to connect it with a Copilot Studio agent from your end.

I just want to ensure that I’m not missing anything or doing something incorrectly, especially since Microsoft has communicated that this feature should be working.

For additional support, I’ve also raised a ticket with Microsoft regarding the Copilot Studio integration.

[sharetech-in]

@sharetech-in Can you give me a bit more detail about how your calling into Copilot Studio? Are you using the CopilotStudioClient from the microsoft/agents-copilotstudio-client package or some other method?

if your using the copilotStudio-Client package... Please take a moment to review the readme here: https://github.com/microsoft/Agents/tree/main/samples/nodejs/copilotstudio-client

Thank you for your response, MattB (@MattB-msft).

I am currently using a simple Custom Engine SDK agent and attempting to connect it with a Copilot Studio agent, where the handoff is expected to occur from the Copilot Studio agent to the SDK agent.

Could you please confirm if this setup is supported and whether there are any specific configurations or prerequisites I might be missing?

[MattB-msft]

to clarify.

You have an MCS Agent and your trying to hand off to a custom engine agent.
if yes. there are several ways that this is done + variations.
How is Copilot Studio configured to communicate with the agent?

• Copilot Studio Skill ( botSkill )
• Agent's section where you added an AgentSDK agent
• Tool where your using a custom connector ?

[sharetech-in]

to clarify.

You have an MCS Agent and your trying to hand off to a custom engine agent. if yes. there are several ways that this is done + variations. How is Copilot Studio configured to communicate with the agent?

• Copilot Studio Skill ( botSkill )
• Agent's section where you added an AgentSDK agent
• Tool where your using a custom connector ?

Hi MattB (@MattB-msft)

Thank you for looking into this and helping with the investigation.

You are absolutely right—there are multiple approaches to achieve this:
1. Skills approach – We have already explored this option, and it was working fine for us. However, as confirmed by Microsoft, this approach is not recommended going forward and may be deprecated in the future.
2. Agents tab in Copilot Studio (MCS) – We are currently trying the “Connect external agent” option as recommended. The SDK agent works perfectly fine as an independent agent (both locally and when deployed on the server). However, when we try to connect it with MCS, it throws a 401 Unauthorized error. Based on our analysis, it seems like the JWT token validation might be failing during the handoff.

Could you please help clarify the recommended configuration for this setup, specifically:
• In Copilot Studio (Agents tab) – what is the expected authentication configuration for external agents?
• In Azure App Service / Bot Service – any specific authentication or token validation settings required?
• In Azure App Registration – what scopes, audience (aud), and permissions should be configured for this scenario?

Any guidance or reference documentation for the correct setup would be really helpful.

Thanks again for your support!