Skip to content

Doc improvement for SSO #1549

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ericsche wants to merge 1 commit into
base: dev
Choose a base branch
from
Open

Doc improvement for SSO #1549

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 41 additions & 19 deletions ProxyAgent-CSharp/M365Agent/AZURE_DEPLOYMENT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -367,39 +367,61 @@ Location: Same as resource group
```
Display Name: {botDisplayName}
Sign-in Audience: AzureADMyOrg (Single Tenant)
App ID URI: api://botid-{BOT_ID}
Redirect URI: https://token.botframework.com/.auth/web/redirect
```

2. **OAuth2 Permission Scope**
```
Scope: access_as_user
Display Name: Access as the user
Type: User
```
**OAuth 2.0 Scopes:**

3. **Federated Identity Credential**
```
Subject: /eid1/c/pub/t/{encodedTenantId}/a/{encodedAppId}/{uniqueId}
Issuer: https://token.botframework.com/
Audience: api://botframework.com
```
| Scope | Type | Purpose | Consent Required |
|-------|------|---------|------------------|
| `access_as_user` | User | Default scope for Agent SSO access | User consent |

**Pre-Authorized Applications:**

Applications that can access the `access_as_user` scope without requiring user consent:

| Application | App ID | Purpose |
|-------------|--------|---------|
| Teams web client | `1fec8e78-bce4-4aaf-ab1b-5451cc387264` | Teams in browser |
| Teams desktop client | `5e3ce6c0-2b1f-4285-8d4b-75ee78787346` | Teams desktop app |
| Microsoft 365 web application | `4765445b-32c6-49b0-83e6-1d93765276ca` | Office.com portal |
| Microsoft 365 desktop application | `0ec893e0-5785-4de6-99da-4ed124e5296c` | Office desktop apps |
| Microsoft 365 mobile/Outlook desktop | `d3590ed6-52b3-4102-aeff-aad2292ab01c` | M365 mobile & Outlook desktop |
| Outlook web application | `bc59ab01-8403-45c6-8796-ac3ef710b3e3` | Outlook in browser |
| Outlook mobile application | `27922004-5251-4030-b22d-91ecd9a37ea4` | Outlook mobile app |

**Required API Permissions:**

| API | Permission | Type | Purpose |
|-----|------------|------|---------|
| Microsoft Graph | `openid` | Delegated | OpenID Connect sign-in |
| Microsoft Graph | `profile` | Delegated | User profile information |
| Microsoft Graph | `email` | Delegated | User email address |
| Microsoft Graph | `offline_access` | Delegated | Refresh token for long-lived sessions |
| Azure Machine Learning | `user_impersonation` | Delegated | Required for Azure AI Foundry Agent SSO |

**Federated Identity Credential:**

4. **Pre-authorized Client Applications**
- Microsoft Teams (Desktop/Mobile)
- Microsoft Teams (Web)
- Microsoft 365 Web Client
- Microsoft 365 Desktop Client
| Property | Value |
|----------|-------|
| Audience | `api://AzureADTokenExchange` |
| Issuer | `https://login.microsoftonline.com/{tenantId}/v2.0` |
| Subject | `/eid1/c/pub/t/{encodedTenantId}/a/9ExAW52n_ky4ZiS_jhpJIQ/{guid}` |
| Description | Federated credential for Bot Framework token exchange |

**Key Outputs:**
- `aadAppId`: Application (client) ID
- `aadAppObjectId`: Object ID
- `aadAppIdUri`: Application ID URI (e.g., `api://botprod123-app.azurewebsites.net/{guid}`)
- `aadAppIdUri`: Application ID URI (e.g., `api://botid-{BOT_ID}`)
- `servicePrincipalId`: Service Principal ID

**Features:**
- ✅ Federated credentials (no client secrets)
- ✅ Pre-configured for Teams SSO
- ✅ Proper OAuth scopes
- ✅ Secure token exchange
- ✅ Pre-authorized Microsoft 365 clients

**Note:** The module uses `guid-encoder.bicep` to properly encode GUIDs for federated credentials.

Expand Down Expand Up @@ -883,7 +905,7 @@ You've successfully deployed your M365 Agent to Azure! 🎉
5. ✅ Implement CI/CD for automated deployments

**Resources:**
- [Microsoft 365 Agents Toolkit Documentation](https://aka.ms/teams-toolkit-docs)
- [Microsoft 365 Agents Toolkit Documentation](https://learn.microsoft.com/en-us/microsoft-365/developer/overview-m365-agents-toolkit)
- [Azure Bot Service Documentation](https://learn.microsoft.com/azure/bot-service/)
- [Bicep Documentation](https://learn.microsoft.com/azure/azure-resource-manager/bicep/)
- [Microsoft 365 Agents SDK](https://github.com/microsoft/agents)
Expand Down
55 changes: 49 additions & 6 deletions ProxyAgent-CSharp/M365Agent/LOCAL_DEPLOYMENT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -442,11 +442,54 @@ Required for: Bot Service to verify bot identity
- Accessing user resources on behalf of user

**Configuration:**
```yaml
OAuth Scope: access_as_user
Federated Credentials: Azure Bot Service token issuer
Pre-authorized Clients: Teams, Outlook, M365 apps
No client secrets: More secure than password-based auth

**OAuth 2.0 Scopes:**

| Scope | Type | Purpose | Consent Required |
|-------|------|---------|------------------|
| `access_as_user` | User | Default scope for Agent SSO access | User consent |

**Pre-Authorized Applications:**

Applications that can access the `access_as_user` scope without requiring user consent:

| Application | App ID | Purpose |
|-------------|--------|---------|
| Teams web client | `1fec8e78-bce4-4aaf-ab1b-5451cc387264` | Teams in browser |
| Teams desktop client | `5e3ce6c0-2b1f-4285-8d4b-75ee78787346` | Teams desktop app |
| Microsoft 365 web application | `4765445b-32c6-49b0-83e6-1d93765276ca` | Office.com portal |
| Microsoft 365 desktop application | `0ec893e0-5785-4de6-99da-4ed124e5296c` | Office desktop apps |
| Microsoft 365 mobile/Outlook desktop | `d3590ed6-52b3-4102-aeff-aad2292ab01c` | M365 mobile & Outlook desktop |
| Outlook web application | `bc59ab01-8403-45c6-8796-ac3ef710b3e3` | Outlook in browser |
| Outlook mobile application | `27922004-5251-4030-b22d-91ecd9a37ea4` | Outlook mobile app |

**Required API Permissions:**

| API | Permission | Type | Purpose |
|-----|------------|------|---------|
| Microsoft Graph | `openid` | Delegated | OpenID Connect sign-in |
| Microsoft Graph | `profile` | Delegated | User profile information |
| Microsoft Graph | `email` | Delegated | User email address |
| Microsoft Graph | `offline_access` | Delegated | Refresh token for long-lived sessions |
| Azure Machine Learning | `user_impersonation` | Delegated | Required for Azure AI Foundry Agent SSO |

**Federated Identity Credential:**

| Property | Value |
|----------|-------|
| Audience | `api://AzureADTokenExchange` |
| Issuer | `https://login.microsoftonline.com/{tenantId}/v2.0` |
| Subject | `/eid1/c/pub/t/{encodedTenantId}/a/9ExAW52n_ky4ZiS_jhpJIQ/{guid}` |
| Description | Federated credential for Bot Framework token exchange |

**App ID URI:**
```
api://botid-{BOT_ID}
```

**Redirect URIs:**
```
https://token.botframework.com/.auth/web/redirect
```

**Why Two Apps?**
Expand Down Expand Up @@ -1223,7 +1266,7 @@ Production uses:
### Resources

**Documentation:**
- [Microsoft 365 Agents Toolkit](https://aka.ms/teams-toolkit-docs)
- [Microsoft 365 Agents Toolkit](https://learn.microsoft.com/en-us/microsoft-365/developer/overview-m365-agents-toolkit)
- [Microsoft 365 Agents SDK for .NET](https://github.com/microsoft/agents)
- [Dev Tunnels Documentation](https://learn.microsoft.com/azure/developer/dev-tunnels/)
- [Teams Platform](https://learn.microsoft.com/microsoftteams/platform/)
Expand Down