Fix 'Untrusted Content' Warnings In Copilot Adaptive Cards

Hey guys! Ever been building out an awesome Adaptive Card for your Microsoft 365 Copilot Declarative Agent or API plugin, all proud of your work, only to hit a snag when users click an Action.OpenUrl button? You know the one: that pesky "URL may lead to untrusted content" warning message popping up? It's a real buzzkill, right? It can make your meticulously crafted user experience feel… well, a little untrustworthy. Nobody wants their users feeling uncertain or hesitant when interacting with their tools, especially within a critical platform like Microsoft 365 Copilot or Microsoft Teams. This isn't just a minor annoyance; it’s a direct hit to user confidence and the overall perceived quality of your solution. But don't you worry your developer brains, because this isn't a bug in Copilot or Teams; it's a security feature, and more importantly, it's totally fixable! We're here to walk you through exactly why this happens and, more importantly, how to squash that warning for good, ensuring your users have a smooth, secure, and truly seamless experience. Let's dive in and get those URLs trusted!

Understanding the 'Untrusted Content' Warning Message

So, first things first, let's unpack why you're seeing that "URL may lead to untrusted content" warning message in the first place when users click on an Action.OpenUrl button from an Adaptive Card inside Microsoft 365 Copilot chat or even in regular Microsoft Teams apps. It's crucial to understand that this isn't the platform trying to sabotage your efforts; quite the opposite, actually. This warning is a security safeguard, a digital bouncer, if you will, ensuring that users aren't accidentally or maliciously redirected to potentially harmful websites. Think about it: in an environment as central and sensitive as Microsoft 365, where users are sharing data and interacting with critical business processes, security is paramount. Microsoft has invested heavily in creating a secure ecosystem, and part of that involves being cautious about where external links might lead. When your Adaptive Card attempts to open a URL that hasn't been explicitly verified by your app's configuration, Copilot or Teams steps in with this warning as a protective measure. It's essentially saying, "Hold up, user! This link isn't on our approved list, so proceed with caution!" While it might seem like an extra hoop to jump through, this mechanism is there to prevent phishing attacks, malware distribution, and other malicious activities that could compromise user data or system integrity. Without such checks, any app could potentially send users to dangerous corners of the internet, undermining the trust users place in the Microsoft 365 platform. So, instead of viewing it as an obstacle, it's better to see it as a reminder of the platform's robust commitment to user safety and privacy. This security-first approach is fundamental to maintaining a reliable and secure environment for everyone, from individual users to large enterprises. By understanding this underlying principle, developers can appreciate the necessity of these safeguards and then take the appropriate steps to integrate their external content securely.

The Core Culprit: Missing validDomains in Your App Manifest

Alright, folks, now that we know why the "URL may lead to untrusted content" warning message appears, let's talk about the specific configuration that's causing it and, more importantly, how to fix it. The core culprit for this warning message appearing when you use an Action.OpenUrl in an Adaptive Card within Microsoft 365 Copilot or Teams is almost always a missing or incomplete validDomains section in your app's package manifest. For those unfamiliar, the app package manifest is essentially the blueprint of your Microsoft Teams app or your Declarative Agent with API plugin for Copilot. It's a manifest.json file that contains all the essential metadata, capabilities, and configurations that define how your application integrates with the Microsoft 365 ecosystem. One of the most critical sections within this manifest, especially when dealing with external web content, is the validDomains array. This array is where you explicitly tell Microsoft 365 Copilot and Teams which external domains your application is allowed to interact with or navigate to. When your Action.OpenUrl attempts to open a URL whose domain is not listed in this validDomains section, the platform throws up that trust warning because it hasn't been given explicit permission to trust that particular destination. It's like a bouncer at a club checking an ID against an approved guest list – if the name isn't there, they're not getting in without a second look! The validDomains array expects a list of root domains (e.g., example.com, api.mycompany.com) that your app will legitimately interact with. It's not about specific URLs, but the top-level domain or subdomains. For instance, if your Action.OpenUrl points to https://www.mycompanyservice.com/users/profile, you need to add www.mycompanyservice.com (or often just mycompanyservice.com to cover subdomains) to your validDomains list. This security measure is fundamental to the platform's design, preventing apps from randomly redirecting users to unapproved external sites, which could be malicious. It ensures that any external interactions initiated by your app are pre-approved and vetted by you, the developer, thereby maintaining a secure and controlled user experience. Without properly configuring validDomains, your otherwise stellar Adaptive Cards will always be flagged, creating friction and eroding user trust. So, remember, adding the URL domain to the validDomains section of your app package manifest is the golden ticket to a warning-free user experience. This requirement applies whether you're developing for Microsoft Teams directly or building a Declarative Agent with an API plugin that surfaces Adaptive Cards within Microsoft 365 Copilot chat. It's a universal security requirement for external links within the Microsoft 365 extensibility framework.

Step-by-Step Guide: How to Fix the 'URL May Lead to Untrusted Content' Warning

Alright, it's showtime! Let's get down to brass tacks and fix the 'URL may lead to untrusted content' warning once and for all. This process is straightforward, but it requires precision. Follow these steps, and you'll have those Microsoft 365 Copilot Adaptive Cards opening external links without a hitch, giving your users that seamless experience they deserve.

Step 1: Identify All Problematic URLs

First things first, you need to pinpoint every single URL that your Action.OpenUrl actions are trying to access. Go through all your Adaptive Card JSON payloads that include Action.OpenUrl. List out the full URLs, like https://docs.mycompany.com/support/faq or https://analytics.dashboard.com/report/123. This comprehensive list is crucial because you'll need to extract the root domains from each of them. Don't miss any, or that warning will pop right back up for the overlooked ones! For example, if you have https://docs.microsoft.com/en-us/microsoft-365/extensibility/ and https://adaptivecards.io/, your domains to consider are docs.microsoft.com and adaptivecards.io.

Step 2: Locate Your App's manifest.json File

Next up, you need to find your application's manifest.json file. This file is at the heart of your Microsoft Teams app or Declarative Agent with API plugin package. If you're developing locally, it's usually in the root directory of your project folder. For existing apps, if you downloaded the app package, you'd find it inside the .zip file. This manifest.json is where all the magic happens for configuring your app's interaction with the Microsoft 365 ecosystem. Open it up in your favorite code editor – VS Code is a great choice for this.

Step 3: Find or Create the validDomains Array

Once you have your manifest.json open, you'll need to locate the validDomains property. This property is usually found at the root level of the JSON object. If you already have it, great! If not, you'll need to add it. It should be an array of strings. The structure looks something like this:

{
  "$schema": "https://developer.microsoft.com/json/teams/v1.17/MicrosoftTeams.schema.json",
  "manifestVersion": "1.17",
  "id": "YOUR_APP_ID",
  "version": "1.0.0",
  "validDomains": [
    "*.example.com",
    "anotherservice.net"
  ],
  // ... other manifest properties
}

Step 4: Add the Root Domains to validDomains

Now, take the list of domains you identified in Step 1 and add them to the validDomains array. Crucially, you only need to add the root domain or the specific subdomain that hosts your content. For instance, if your URLs were https://docs.mycompany.com/faq and https://blog.mycompany.com/updates, you would add docs.mycompany.com and blog.mycompany.com to your validDomains list. You can also use wildcards for subdomains, like *.mycompany.com, to cover all subdomains under mycompany.com. However, be mindful with wildcards – only use them if you truly trust all subdomains. If your domain is example.com, you'd add example.com. If it's a specific subdomain like app.service.com, you'd add app.service.com. Always use HTTPS for your actual URLs, but the domain entries in validDomains do not include https://.

Here’s an example of how your validDomains section might look after adding a few common domains for an API plugin or agent:

"validDomains": [
  "contoso.com",
  "login.microsoftonline.com",
  "api.yourcompany.com",
  "*.externaldata.net"
]

Step 5: Re-package and Re-upload/Re-deploy Your App

This is a critical step! Merely saving your manifest.json isn't enough. For the changes to take effect, you must re-package your app (typically as a .zip file containing manifest.json and your icons) and then re-upload or re-deploy it to Microsoft 365 Copilot or Teams. If you're testing locally, you'll need to uninstall the old version and then side-load the updated package. For production deployments, this means going through your standard app deployment process again. The platform needs to ingest the new manifest with its updated trusted domain list.

Step 6: Clear Cache (If Necessary) and Test Thoroughly

Sometimes, especially during development, the changes might not appear immediately due to caching. If you've re-deployed and still see the warning, try clearing your Teams or Copilot cache (often by logging out and back in, or for Teams desktop, clearing the cache folder manually). Once you've done that, test thoroughly! Click every Action.OpenUrl button in your Adaptive Cards to ensure that the warning message is completely gone for all links. This meticulous testing ensures a completely smooth user experience.

By diligently following these steps, you'll successfully eliminate the "URL may lead to untrusted content" warning, fostering greater trust and providing a significantly better experience for users interacting with your Declarative Agent with API plugin or Microsoft Teams app within the Microsoft 365 ecosystem. This attention to detail in your app's manifest is key to secure and reliable external content integration.

Best Practices for Adaptive Cards and URL Handling in Microsoft 365 Copilot/Teams

Beyond just fixing that immediate "URL may lead to untrusted content" warning message, let's talk about some best practices for handling URLs and designing your Adaptive Cards within Microsoft 365 Copilot and Teams. Following these guidelines won't just keep the warnings at bay; it'll also enhance the security, usability, and overall quality of your applications, making them a joy for users to interact with. A well-designed and secure application builds immense user trust and encourages greater adoption and engagement with your Declarative Agent with API plugin.

Firstly, always use HTTPS for all your URLs. This might seem obvious in 2024, but it's worth reiterating. HTTP connections are unencrypted and vulnerable to eavesdropping and tampering, which can compromise user data and even lead to content injection. Modern browsers and platforms, including Microsoft 365, heavily penalize or outright block insecure HTTP content. Ensuring all your external links start with https:// is a fundamental security practice that protects your users and maintains the integrity of the data being transmitted. Never, ever link to an http:// endpoint if an https:// alternative exists.

Secondly, minimize redirects and ensure transparent URL destinations. While it might be convenient to use a URL shortener or an internal redirection service, too many redirects can obscure the final destination of a link, potentially raising flags for security scanners and users alike. If a user clicks a button expecting to go to mycompany.com/report but lands on thirdpartyservice.net/redirect?to=mycompany.com/report first, it can create confusion and distrust. Always strive for direct links to the final content whenever possible. If redirects are absolutely necessary (e.g., for analytics or SSO flows), ensure the initial redirection domain is also included in your validDomains if it's external to your primary domain, and that the redirects are secure and transparent.

Thirdly, be mindful of sensitive data in URLs. Never pass sensitive information, such as API keys, personal identifiable information (PII), or confidential data, directly in URL query parameters when using Action.OpenUrl. URLs can be logged in browser histories, server logs, and shared, making them an insecure channel for sensitive data. Instead, if authentication or specific user context is needed, leverage secure authentication flows like OAuth or link to a secure endpoint that retrieves user-specific data after the user has authenticated within the target web service. This separation of concerns ensures that clicking an external link doesn't inadvertently expose private information.

Fourth, test thoroughly across different environments and user types. What works perfectly in your development environment might behave differently in a corporate network with stricter firewall rules or on a mobile device. Always test your Adaptive Cards and Action.OpenUrl actions in various scenarios: on the desktop client, web client, and mobile clients for Microsoft Teams/Copilot. Test with different user roles and permissions if your external links have access control. This comprehensive testing helps catch any edge cases or platform-specific quirks that could lead to the warning message reappearing or a broken user experience.

Lastly, consider alternative actions for in-app experiences. While Action.OpenUrl is great for external content, sometimes you might want to keep the user within the Microsoft 365 ecosystem for a more integrated experience. For displaying simple forms, data, or interactive elements, consider using Task Modules instead of opening a full browser tab. Task Modules can render web content or other Adaptive Cards within a pop-up window right inside Teams or Copilot, providing a more cohesive user experience without navigating away. This is especially useful for actions that are part of a workflow within your app. By adhering to these best practices, you're not just avoiding warnings; you're building robust, secure, and user-friendly solutions that truly add value within Microsoft 365 Copilot and Teams, boosting your credibility as a developer.

Why This Matters: Enhancing User Trust and Experience

Seriously, guys, fixing that little-but-mighty "URL may lead to untrusted content" warning message isn't just about tidying up your code or ticking a box. It fundamentally matters because it's all about enhancing user trust and experience within Microsoft 365 Copilot and Teams. Think about it from a user's perspective: they're interacting with your super-smart Declarative Agent with API plugin, expecting a smooth, intelligent interaction. They get a response, an Adaptive Card pops up, and there's a button to learn more or perform an action. They click it, and boom! A bright yellow (or red, depending on the context) warning message screams, "Untrusted content!" What does that do? It immediately introduces doubt. It makes them hesitate. It forces them to wonder if your application, which is supposed to be helpful and reliable, is actually safe. This friction isn't just annoying; it erodes confidence in your solution, and by extension, in the entire Microsoft 365 platform's extensibility. Users might simply opt not to click the link, missing out on valuable information or functionality, which defeats the entire purpose of your Adaptive Card! Worse, they might stop using your agent or plugin altogether if they perceive it as unreliable or a potential security risk.

On the flip side, when you meticulously add those domains to your validDomains in the app package manifest, you're not just silencing a warning; you're actively building trust. You're telling the user, and the platform, that you've done your due diligence. You've vetted this external content, and you stand by its safety. This leads to a seamless experience where a click leads directly to the intended destination without any security pop-ups or nagging doubts. A smooth flow encourages users to explore more, engage deeper, and rely on your agent or plugin for their daily tasks. This positive experience directly contributes to the adoption and stickiness of your solution. For developers, this translates into a stronger reputation. A developer who pays attention to security and user experience details is seen as competent and reliable. It signals that you care about the end-user's safety and satisfaction, which is invaluable in the competitive world of enterprise applications. Moreover, a friction-free experience allows your users to focus on the value your solution provides, rather than being distracted by security concerns. It ensures that the innovation you've poured into your API plugin and Adaptive Cards is actually utilized and appreciated. Ultimately, this isn't just a technical fix; it's a strategic move to secure your user base, enhance the perceived quality of your work, and fully leverage the powerful capabilities of Microsoft 365 Copilot and Teams. Let's make sure our users feel secure and confident every step of the way!

Conclusion

So there you have it, folks! That infamous "URL may lead to untrusted content" warning message in your Microsoft 365 Copilot Adaptive Cards is no longer a mystery, nor is it an insurmountable hurdle. We've explored exactly why this security feature exists, how the crucial validDomains array in your app manifest acts as the gatekeeper, and most importantly, a clear, step-by-step guide on how to fix it. Remember, this isn't just about making a warning disappear; it's about proactively enhancing user trust and experience, ensuring your Declarative Agent with API plugin delivers a seamless and secure interaction every single time. By meticulously identifying your external URLs, updating your app's manifest.json with the correct validDomains, and re-deploying your application, you're not just silencing a notification – you're building a foundation of reliability and professionalism. Always strive for the best practices, like using HTTPS and transparent URL handling, to further solidify your app's integrity. Your users deserve a smooth journey, free from unnecessary security pop-ups, allowing them to fully appreciate the value your innovative solutions bring to the Microsoft 365 ecosystem. Go forth and build trusted experiences!