Configure web and Direct Line channel security

Web and Direct Line channel security controls whether clients must provide a Direct Line secret or token to connect to your Copilot Studio agent. Without secured access, anyone who knows the agent ID can connect through the Demo website and Custom website channels.

Note

In the Teams-only experience, you can't generate secrets. Secure access tokens are created automatically, and secured access is on by default. For licensing requirements, refer to Microsoft Product Terms.

Turn on Require secured access to require clients to present a secret or token. These credentials authorize access to the Direct Line channel; they don't authenticate the end user or restrict access to a particular website by themselves. Configure user authentication separately when users need to sign in.

You can swap and regenerate secrets, refresh tokens, or turn off secured access when it's no longer needed.

Copilot Studio uses the Bot Framework Direct Line channel to connect your web page or app to the agent.

Turn web channel security on or off

You can enforce the use of secrets and tokens for each individual agent.

When you turn on this option, channels need the client to authenticate their requests either by using a secret or by using a token that is generated by using the secret, obtained at runtime.

Attempts to access the agent that don't provide this security measure don't work.

  1. Go to the Settings page for your agent, select Security, and then select Web channel security.

    Screenshot of Web channel security highlighted on the Settings flyout.

  2. Turn on Require secured access.

Warning

When you turn on or turn off Require secured access, it can take up to two hours for the new system settings to take effect. Until then, the previous setting is in effect. You don't need to publish the agent for this change to take effect.

Plan ahead to avoid exposing your agent unintentionally.

To turn off web channel security, turn off Require secured access and confirm the change. The change can take up to two hours to take effect.

Screenshot of the confirmation that turning off secured access makes the demo website and unsecured Direct Line channels available.

Use secrets or tokens

For a service-to-service app, specify the secret in the authorization header of requests from your service.

If you're writing an app where the client runs in a web browser or mobile app, or otherwise the code might be visible to customers, you must exchange your secret for a token. If you don't use a token, your secret can be compromised. When you're making the request to acquire the token in your service, specify the secret in the authorization header.

Tokens only work for a single conversation and expire unless refreshed.

Choose the security model that works best for your situation.

Warning

Don't expose the secret in any code that runs in the browser, either hard-coded or transferred through a network call.

Acquiring the token by using the secret in your service code is the most secure way to protect your Copilot Studio agent.

Obtain the secrets

You need the secret so you can specify it in your app's authorization header requests or similar.

  1. In the navigation menu, under Settings, select Security. Then select the Web channel security tile.

  2. Select Copy for either Secret 1 or Secret 2 to copy it to the clipboard. To reveal the secret, select the visibility icon and review the warning prompt.

Swap secrets

If you need to change the secret that your agent uses, you can change it without any downtime or interruption.

Copilot Studio provides you with two secrets, which work simultaneously. You can swap the secret that your agent uses with the other one. After the secrets are swapped and your users are all connected by using the new secret, you can regenerate the secret.

Regenerate a secret

To regenerate a secret, select Regenerate next to the secret.

Warning

The user profile that connects by using the original secret or a token obtained from that secret is disconnected.

Generate a token

You can generate a token to start a single agent conversation. This procedure exchanges a Direct Line secret for a conversation token in your service code. For the Copilot Studio token endpoint option, learn more in Get Direct Line token.

  1. Obtain the secret.

  2. In your service code, send the sample generate token request. Replace <DirectLineSecret> with the secret you copied.

Sample generate token request

POST https://directline.botframework.com/v3/directline/tokens/generate
Authorization: Bearer <DirectLineSecret>

Sample generate token response

HTTP/1.1 200 OK
[other headers]

{
  "conversationId": "abc123",
  "token": "<DirectLineToken>",
  "expires_in": 1800
}

If the request is successful, the response contains a token that's valid for one conversation and an expires_in value that indicates the number of seconds until the token expires.

To keep the token useful, you must refresh the token before it expires.

Refresh a token

You can refresh a token an unlimited number of times, as long as it isn't expired.

You can't refresh an expired token.

Send the sample refresh request. Replace <DirectLineToken> with the unexpired token you want to refresh. Use the conversation token, not the Direct Line secret.

Sample refresh request

POST https://directline.botframework.com/v3/directline/tokens/refresh
Authorization: Bearer <DirectLineToken>

Sample refresh response

If the request is successful, the response contains a new token that's valid for the same conversation as the previous token and an expires_in value that indicates the number of seconds until the new token expires.

To keep the new token useful, refresh the token again before it expires.

HTTP/1.1 200 OK
[other headers]

{
  "conversationId": "abc123",
  "token": "<DirectLineToken>",
  "expires_in": 1800
}

Learn more in Refresh a Direct Line token.

  • Last updated on