Merge branch 'main' into users/tracyboehrer/remove-repo-docs

# Conflicts:
#	docs/index.md
#	samples/dotnet/auto-signin/README.md

Author: Tracy Boehrer

samples/python/README.md

@@ -4,8 +4,9 @@
 |----|----|----|
 |Quickstart|Simplest agent|N/A|
 |Auto Sign In|Simple OAuth agent using Graph and GitHub|[auto-signin](auto-signin/README.md)|
+|OBO Authorization|OBO flow to access a Copilot Studio Agent|[obo-authorization](obo-authorization/README.md)|
 |Semantic Kernel Integration|A weather agent built with Semantic Kernel|[semantic-kernel-multiturn](semantic-kernel-multiturn/README.md)|
 |Streaming Agent|Streams OpenAI responses|[azure-ai-streaming](azure-ai-streaming/README.md)|
 |Copilot Studio Client|Console app to consume a Copilot Studio Agent|[copilotstudio-client](copilotstudio-client/README.md)|
 |Cards Agent|Agent that uses rich cards to enhance conversation design |[cards](cards/README.md)|
-|Copilot Studio Skill|Call the echo bot from a Copilot Studio skill |[copilotstudio-skill](copilotstudio-skill/README.md)|
+|Copilot Studio Skill|Call the echo bot from a Copilot Studio skill |[copilotstudio-skill](copilotstudio-skill/README.md)|

samples/python/obo-authorization/README.md

@@ -0,0 +1,122 @@
+# OBO Auth Sample
+
+This Agent has been created using [Microsoft 365 Agents SDK](https://github.com/microsoft/agents-for-net), it shows how to use authorization in your Agent using OAuth and OBO.
+
+- The sample uses the Agent SDK User Authorization capabilities in [Azure Bot Service](https://docs.botframework.com), providing features to make it easier to develop an Agent that authorizes users with various identity providers such as Azure AD (Azure Active Directory), GitHub, Uber, etc.
+- This sample shows how to use an OBO Exchange to communicate with Microsoft Copilot Studio using the [CopilotClient class](https://learn.microsoft.com/python/api/microsoft-agents-copilotstudio-client/microsoft.agents.copilotstudio.client.copilotclient).
+
+## Prerequisites
+
+- [Python](https://www.python.org/) version 3.9 or higher
+- [dev tunnel](https://learn.microsoft.com/azure/developer/dev-tunnels/get-started?tabs=windows) (for local development)
+- Access to CopilotStudio to [create an Agent](https://learn.microsoft.com/microsoft-copilot-studio/fundamentals-get-started?tabs=web)
+
+## Local Setup
+
+### Configuration
+
+1. Create an Agent in Copilot Studio.
+   1. Publish your newly created Agent
+   1. Got to Settings => Advanced => Metadata and copy the following values. You will need them later:
+      1. Schema name
+      1. Environment ID
+
+1. [Create an Azure Bot](https://aka.ms/AgentsSDK-CreateBot)
+   - Record the Application ID, the Tenant ID, and the Client Secret for use below
+
+1. Open the `env.TEMPLATE` file in the root of the sample project, rename it to `.env` and configure the following values:
+   1. Set the **CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID** to the AppId of the bot identity.
+   2. Set the **CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET** to the Secret that was created for your identity. *This is the `Secret Value` shown in the AppRegistration*.
+   3. Set the **CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID** to the Tenant Id where your application is registered.
+
+1. Setting up OAuth for an exchangeable token 
+   1. Create a new App Registration
+      1. SingleTenant
+      1. Give it a name and click **Register**
+      1. **Authentication** tab
+         1. **Add Platform**, then **Web**, Set `Redirect URI` to `Web` and `https://token.botframework.com/.auth/web/redirect`
+         1. **Add Platform**, then **Mobile and desktop applications**, and add an additional `http://localhost` Uri.
+      1. **API Permissions** tab
+         1. **Dynamics CRM** with **user_impersonation**
+         1. **Graph** with **User.Read**
+         1. **Power Platform API** with **CopilotStudio.Copilots.Invoke**
+         1. Grant Admin Consent for your tenant.
+      1. **Expose an API** tab
+         1. Click **Add a Scope**
+         1. **Application ID URI** should be: `api://botid-{{appid}}`
+         1. **Scope Name** is "defaultScope"
+         1. **Who can consent** is **Admins and users**
+         1. Enter values for the required Consent fields
+      1. **Certificates & secrets**
+         1. Create a new secret and record the value. This will be used later.
+
+1. Create Azure Bot **OAuth Connection**
+   1. On the Azure Bot created in Step #2, Click **Configuration** tab then the **Add OAuth Connection Settings** button.
+   1. Enter a **Name**.  This will be used later.
+   1. For **Service Provider** select **Azure Active Directory v2**
+   1. **Client id** and **Client Secret** are the values created in step #4.
+   1. Enter the **Tenant ID**
+   1. **Scopes** is `api://botid-{{appid}}/defaultScope`. appid is the **Client id** value from #4.
+
+1. Configure the authorization handlers
+   1. Open the `.env` file and update:
+   1. Set the **CONNECTIONS__MCS__SETTINGS__CLIENTID** to the **Client id** from #4
+   1. Set the **CONNECTIONS__MCS__SETTINGS__CLIENTSECRET** to the **Client Secret** value from #4.
+   1. Set the **CONNECTIONS__MCS__SETTINGS__TENANTID** to the Tenant Id.
+   1. Keep **AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__MCS__SETTINGS__OBOCONNECTIONNAME=MCS**
+   1. Set **AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__MCS__SETTINGS__AZUREBOTOAUTHCONNECTIONNAME={{Name}}** where **Name** is the name of your OAuth connection created in step 5.
+
+1. Configure the sample to use your CopilotStudio Agent by modifying the following variables in the `.env` file based on the values obtained in step #1:
+
+```bash
+  COPILOTSTUDIOAGENT__ENVIRONMENTID="" # Environment ID of the Agent from MCS
+  COPILOTSTUDIOAGENT__SCHEMANAME="" # Schema Name of the Agent from MCS
+```   
+
+1. Run `dev tunnels`. See [Create and host a dev tunnel](https://learn.microsoft.com/azure/developer/dev-tunnels/get-started?tabs=windows) and host the tunnel with anonymous user access command as shown below:
+
+   ```bash
+   devtunnel host -p 3978 --allow-anonymous
+   ```
+
+1. Take note of the url shown after `Connect via browser:`
+
+1. On the Azure Bot, select **Settings**, then **Configuration**, and update the **Messaging endpoint** to `{tunnel-url}/api/messages`
+
+### Running the Agent
+
+1. Open this folder from your IDE or Terminal of preference
+1. (Optional but recommended) Set up virtual environment and activate it.
+1. Install dependencies
+
+```sh
+pip install -r requirements.txt
+```
+
+### Run in localhost, anonymous mode
+
+1. Start the application
+
+```sh
+python -m src.main
+```
+
+At this point you should see the message 
+
+```text
+======== Running on http://localhost:3978 ========
+```
+
+The agent is ready to accept messages.
+
+## Accessing the Agent
+
+### Using the Agent in WebChat
+
+1. Go to your Azure Bot Service resource in the Azure Portal and select **Test in WebChat**
+
+## Further reading
+
+To learn more about building Bots and Agents, see our [Microsoft 365 Agents SDK](https://github.com/microsoft/agents) repo.
+
+For more information on logging configuration, see the logging section in the Quickstart Agent sample README.

samples/python/obo-authorization/env.TEMPLATE

@@ -0,0 +1,13 @@
+CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID=
+CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET=
+CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID=
+
+CONNECTIONS__MCS__SETTINGS__CLIENTID=
+CONNECTIONS__MCS__SETTINGS__CLIENTSECRET=
+CONNECTIONS__MCS__SETTINGS__TENANTID=
+
+AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__MCS__SETTINGS__AZUREBOTOAUTHCONNECTIONNAME=
+AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__MCS__SETTINGS__OBOCONNECTIONNAME=MCS
+
+COPILOTSTUDIOAGENT__SCHEMANAME=
+COPILOTSTUDIOAGENT__ENVIRONMENTID=

samples/python/obo-authorization/requirements.txt

@@ -0,0 +1,7 @@
+python-dotenv
+aiohttp
+microsoft-agents-activity
+microsoft-agents-hosting-core
+microsoft-agents-hosting-aiohttp
+microsoft-agents-authentication-msal
+microsoft-agents-copilotstudio-client

samples/python/obo-authorization/src/agent.py

@@ -0,0 +1,83 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+import re
+from os import environ
+from dotenv import load_dotenv
+
+from microsoft.agents.hosting.core import (
+    Authorization,
+    TurnContext,
+    MemoryStorage,
+    AgentApplication,
+    TurnState,
+    MemoryStorage,
+)
+from microsoft.agents.activity import load_configuration_from_env, ActivityTypes
+from microsoft.agents.hosting.aiohttp import CloudAdapter
+from microsoft.agents.authentication.msal import MsalConnectionManager
+from microsoft.agents.copilotstudio.client import ConnectionSettings, CopilotClient, PowerPlatformEnvironment, PowerPlatformCloud
+
+# Load configuration from environment
+load_dotenv()
+agents_sdk_config = load_configuration_from_env(environ)
+
+# Create storage and connection manager
+STORAGE = MemoryStorage()
+CONNECTION_MANAGER = MsalConnectionManager(**agents_sdk_config)
+ADAPTER = CloudAdapter(connection_manager=CONNECTION_MANAGER)
+AUTHORIZATION = Authorization(STORAGE, CONNECTION_MANAGER, **agents_sdk_config)
+
+AGENT_APP = AgentApplication[TurnState](
+    storage=STORAGE, adapter=ADAPTER, authorization=AUTHORIZATION, **agents_sdk_config
+)
+
+# just for testing
+# in practice, use a more robust method to manage app state with conversation state
+mcs_convo_id = None
+
+async def get_client(context: TurnContext) -> CopilotClient:
+    
+    settings = ConnectionSettings(
+        environment_id=environ.get("COPILOTSTUDIOAGENT__ENVIRONMENTID"),
+        agent_identifier=environ.get("COPILOTSTUDIOAGENT__SCHEMANAME"),
+        cloud=PowerPlatformCloud.PROD,
+        copilot_agent_type=None,
+        custom_power_platform_cloud=None,
+    )
+
+    scope = PowerPlatformEnvironment.get_token_audience(settings)
+
+    # where are exchanging the token every time. You can be smarter about this.
+    token_response = await AGENT_APP.auth.exchange_token(context, [scope], "MCS")
+    mcs_client = CopilotClient(settings, token_response.token)
+
+    return mcs_client
+
+@AGENT_APP.message("/signout")
+async def signout(context: TurnContext, state: TurnState):
+    # Force a user signout to reset the user state
+    # This is needed to reset the token in Azure Bot Services if needed. 
+    # Typically this wouldn't be need in a production Agent.  Made available to assist it starting from scratch.
+    await AGENT_APP.auth.sign_out(context, state)
+    await context.send_activity("You have signed out")
+
+# Since Auto SignIn is enabled, by the time this is called the token is already available via Authorization.get_token or
+# Authorization.exchange_token.
+# NOTE: This is a slightly unusual way to handle incoming Activities (but perfectly) valid.  For this sample,
+# we just want to proxy messages to/from a Copilot Studio Agent.
+@AGENT_APP.message(re.compile(r".*"), auth_handlers=["MCS"])
+async def default_handler(context: TurnContext, _state: TurnState):
+    global mcs_convo_id
+
+    mcs_client = await get_client(context)
+
+    if not mcs_convo_id:
+        async for reply in mcs_client.start_conversation():
+            if reply.type == ActivityTypes.message:
+                await context.send_activity(reply.text)
+                mcs_convo_id = reply.conversation.id
+    elif context.activity.type == ActivityTypes.message:
+        async for reply in mcs_client.ask_question(context.activity.text, mcs_convo_id):
+            if reply.type == ActivityTypes.message:
+                await context.send_activity(reply.text)

samples/python/obo-authorization/src/main.py

@@ -0,0 +1,17 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+# enable logging for Microsoft Agents library
+# for more information, see README.md for Quickstart Agent
+import logging
+ms_agents_logger = logging.getLogger("microsoft.agents")
+ms_agents_logger.addHandler(logging.StreamHandler())
+ms_agents_logger.setLevel(logging.INFO)
+
+from .agent import AGENT_APP, CONNECTION_MANAGER
+from .start_server import start_server
+
+start_server(
+    agent_application=AGENT_APP,
+    auth_configuration=CONNECTION_MANAGER.get_default_connection_configuration(),
+)

samples/python/obo-authorization/src/start_server.py

@@ -0,0 +1,31 @@
+from os import environ
+from microsoft.agents.hosting.core import AgentApplication, AgentAuthConfiguration
+from microsoft.agents.hosting.aiohttp import (
+    start_agent_process,
+    jwt_authorization_middleware,
+    CloudAdapter,
+)
+from aiohttp.web import Request, Response, Application, run_app
+
+def start_server(
+    agent_application: AgentApplication, auth_configuration: AgentAuthConfiguration
+):
+    async def entry_point(req: Request) -> Response:
+        agent: AgentApplication = req.app["agent_app"]
+        adapter: CloudAdapter = req.app["adapter"]
+        return await start_agent_process(
+            req,
+            agent,
+            adapter,
+        )
+
+    APP = Application(middlewares=[jwt_authorization_middleware])
+    APP.router.add_post("/api/messages", entry_point)
+    APP["agent_configuration"] = auth_configuration
+    APP["agent_app"] = agent_application
+    APP["adapter"] = agent_application.adapter
+
+    try:
+        run_app(APP, host="localhost", port=environ.get("PORT", 3978))
+    except Exception as error:
+        raise error