This document describes the security roles, duties, and privileges included in the D365 Copilot Toolbox.

The Copilot Toolbox follows the standard D365 F&O role-based security pattern:

graph TD
    AdminRole["COTXCopilotAdminRole<br/>(Copilot Administrator)"]
    UserRole["COTXCopilotUserRole<br/>(Copilot User)"]
    AdminDuty["COTXCopilotAdminDuty"]
    UserDuty["COTXCopilotUserDuty"]
    SidePanel["COTXCopilotSidePanelDisplay<br/>(Read access to side panel)"]
    ParamView["COTXCopilotParameterView<br/>(View agent parameters)"]
    ParamMaintain["COTXCopilotParameterMaintain<br/>(Full CRUD on agent parameters)"]

    AdminRole --> AdminDuty
    AdminDuty --> SidePanel
    AdminDuty --> ParamView
    AdminDuty --> ParamMaintain
    UserRole --> UserDuty
    UserDuty --> SidePanel

graph TD
    Settings["Settings menu<br/>(SysMenuSettings)"]
    SysAdmin["System Administration"]
    Setup["Setup"]
    CopilotToolbox["Copilot Toolbox"]
    CopilotAgent["Copilot Agent"]
    AgentParams["Agent Parameters"]
    SidePanelForm["COTXCopilotHostSidePanel"]
    ParamsForm["COTXCopilotAgentParameters"]

    Settings --> CopilotAgent --> SidePanelForm
    SysAdmin --> Setup --> CopilotToolbox --> AgentParams --> ParamsForm

The SPA app registration used by the Copilot Toolbox:

• Type: Single Page Application (public client)
• No client secret required
• Redirect URI: Must point to the MSAL v5 redirect bridge: https://<your-d365-environment>/resources/html/COTXMsalRedirectBridge.html
• API permission: Power Platform API > Application > CopilotStudio.Copilots.Invoke

1. User opens the Copilot control in D365
2. The MSAL v5 PublicClientApplication is created (or retrieved from a module-scoped cache keyed by clientId|tenantId — only the first call per pair creates a new instance)
3. MSAL.js checks for cached tokens in sessionStorage
4. If multiple accounts are cached (e.g. home-tenant + cross-tenant in a multi-tenant setup), acquireToken selects the account whose tenantId matches the agent’s configured tenant
5. If a matching account is found, acquires a token silently (no user interaction)
6. If not, shows a popup for interactive sign-in. The popup uses the MSAL v5 redirect bridge (COTXMsalRedirectBridge.html) for COOP-compatible authentication
7. The token is used to connect to Copilot Studio via the Agent SDK
8. Tokens are short-lived and scoped to the Power Platform API (CopilotStudio.Copilots.Invoke)

Note: The MSAL instance cache persists for the lifetime of the browser page. When a user restarts a chat conversation or opens a new tab, the existing MSAL instance is reused — no re-initialisation or duplicate instances are created.

MSAL v5 introduces stricter Cross-Origin-Opener-Policy (COOP) requirements. The D365 F&O host page may set COOP headers that prevent the popup window from communicating directly with the opener. To handle this:

• A redirect bridge page (COTXMsalRedirectBridge.html + COTXMsalRedirectBridge.js) is bundled as AxResource items
• The popup authentication flow redirects through this bridge page, which handles the token response in a separate window context and relays it back to MSAL
• No configuration is required — the bridge is used automatically when MSAL detects a COOP restriction

When an organisation uses agents in multiple Entra ID tenants (e.g. a home-tenant agent and a partner-tenant agent), the MSAL session-storage cache may contain accounts for more than one tenant. The control handles this by:

1. Filtering PublicClientApplication.getAllAccounts() by account.tenantId
2. Selecting only the account that matches the agent’s configured TenantId
3. Falling back to interactive (popup) auth if no matching account is found

This prevents the wrong identity from being used and ensures each agent gets a token for the correct tenant.