Enterprise SSO & SAML Identity Propagation in watsonx Orchestrate: Connecting Microsoft Entra ID

By Markus van Kempen | Series: WXO Labs & Tutorial Guide (Part 10 of 15)
Interactive Lab Portal: https://markusvankempen.github.io/wxo-labs/
GitHub Repository: https://github.com/markusvankempen/wxo-labs

Why This Pattern Matters

Large enterprises mandate Single Sign-On (SSO) through Microsoft Entra ID (formerly Azure Active Directory). Employees log in once using their corporate credentials and Multi-Factor Authentication (MFA), and their identity automatically propagates to all watsonx Orchestrate agents.

📋 Prerequisites & Setup

Ensure your environment has the required dependencies:

pip install ibm-watsonx-orchestrate

Verify active environment:

orchestrate env list

🛠️ Step 1: Implement the Logic (sso_identity_probe.py)

try:
    from ibm_watsonx_orchestrate.run.context import AgentRun
except ImportError:
    AgentRun = object

from ibm_watsonx_orchestrate import tool

@tool(context_access_enabled=True)
def verify_sso_identity(agent_run: AgentRun) -> str:
    """
    Probe and validate federated identity attributes propagated from Entra ID SAML tokens.
    """
    context = agent_run.context if hasattr(agent_run, 'context') else {}
    
    email = context.get('wxo_email_id', 'Not provided')
    tenant = context.get('tenant_id', '')
    upn = context.get('user_principal_name', email)
    groups = context.get('groups', ['Cloud-Admins', 'WXO-Users'])

    return f"""
🔐 Microsoft Entra ID SSO Identity Verified
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Principal:  {upn}
Email:      {email}
Tenant ID:  {tenant}
Groups:     {", ".join(groups)}
Auth Type:  SAML 2.0 Federated Assertion
"""

📦 Step 2: Declare Dependencies (requirements.txt)

ibm-watsonx-orchestrate>=2.9.0

🤖 Step 3: Configure the AI Agent (agent.yaml)

spec_version: v1
kind: native
name: sso_directory_agent
title: "SSO Directory Agent"
description: "Federated corporate directory agent backed by Entra ID."
model: ibm/granite-3-8b-instruct
tools:
  - verify_sso_identity

🚀 Step 4: Import & Test Live in Terminal

Import tool and test conversationally:

orchestrate chat ask -n sso_directory_agent "Verify my corporate login status"

Live Response:

╭─ 🤖 sso_directory_agent ───────────────────────────────────────────────╮
│                                                                        │
│  🔐 Microsoft Entra ID SSO Identity Verified                           │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━                             │
│  Principal:  mvk@ca.ibm.com                                            │
│  Email:      mvk@ca.ibm.com                                            │
│  Tenant ID:                                            │
│  Groups:     Cloud-Admins, WXO-Users                                   │
│  Auth Type:  SAML 2.0 Federated Assertion                              │
╰────────────────────────────────────────────────────────────────────────╯

💡 Pro Tips & Gotchas

• Attribute Mapping in Entra ID: Ensure `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` is mapped to `user.mail` in the Azure Portal Enterprise Applications panel.
• Reply URL (ACS): Double-check your Watsonx Orchestrate ACS URL matches the regional deployment URL.

🏷️ Recommended Community Tags

When publishing this blog post, select or enter the following tags in the community editor:

watsonx Orchestrate, Single Sign-On, SSO, Microsoft Entra ID, Azure AD, SAML 2.0, Identity Federation

🗺️ Series Roadmap (15 Hands-On Labs)

This tutorial is Part 10 of 15 in the complete enterprise hands-on series:

• 🟢 Part 1: Building Your First Custom Python Tool & AI Agent in 15 Minutes
• 🟢 Part 2: Input Defaults & UI Patterns (Pydantic Schemas)
• 🟢 Part 3: File Upload & Spreadsheet Analytics (Pandas Pipeline)
• 🟡 Part 4: Ambient User Context & Identity Injection
• 🟡 Part 5: Asynchronous Non-Blocking Workers & Polling
• 🟡 Part 6: Dynamic PDF Generation & File Streaming
• 🟡 Part 7: Model Context Protocol (MCP) STDIO Basics
• 🔴 Part 8: MCP Enterprise Security & Bearer Token Injection
• 🔴 Part 9: Role-Based Access Control (RBAC) Pre-Invoke Plugins
• 🔴 Part 10: Microsoft Entra ID (Azure AD) SSO & SAML Federation
• 🔴 Part 11: Agent CI/CD Lifecycle & Automated Multi-Env Promotion
• 🏆 Part 12: Tamper-Proof Audit Vault & Conversation Archiving
• 🏆 Part 13: Real-Time Telemetry & Token Observability Dashboard
• 🏆 Part 14: Quantitative RAG Pipeline Evaluation with Ragas
• 🔴 Part 15: Remote Containerized MCP Gateways on IBM Cloud Code Engine

Explore the interactive curriculum and code repository:

• 🌐 Interactive Portal: https://markusvankempen.github.io/wxo-labs/
• 📦 GitHub Repository: https://github.com/markusvankempen/wxo-labs
• 🏢 Author Research: https://markusvankempen.github.io/