[TESTING][INTEGRATION]: OAuth/OIDC Providers, SSO, and External Identity Integration

[crivetimihai]

[TESTING][INTEGRATION]: OAuth/OIDC Providers, SSO, and External Identity Integration

Goal

Produce a comprehensive manual test plan for validating third-party authentication and identity provider integrations including OAuth 2.0/OIDC flows, SAML SSO, and major identity providers.

Why Now?

Enterprise authentication is a GA requirement:

1. Enterprise Adoption: Organizations require SSO integration
2. Security Compliance: IdP integration enables centralized auth
3. User Experience: Single sign-on reduces friction
4. Identity Federation: Must work with existing identity systems
5. Token Lifecycle: External tokens need proper handling

---

User Stories

US-1: Enterprise User - SSO Login

As an enterprise user
I want to login via my company's SSO
So that I use my corporate credentials

Acceptance Criteria:

Feature: SSO Login

  Scenario: OIDC login with Okta
    Given Okta is configured as an identity provider
    When I click "Login with Okta"
    And authenticate with my corporate credentials
    Then I receive a gateway session token
    And can access protected resources

US-2: Admin - Provider Configuration

As an administrator
I want to configure multiple identity providers
So that different teams can use their preferred IdP

Acceptance Criteria:

Feature: IdP Configuration

  Scenario: Configure Azure AD provider
    Given admin credentials
    When I add Azure AD OIDC configuration
    Then the provider should be available for login
    And group mappings should work correctly

---

Architecture

                     SSO/OIDC INTEGRATION FLOW
+------------------------------------------------------------------------+
|                                                                        |
|   User              Gateway              IdP (Okta/Azure/Keycloak)     |
|   ----              -------              -------------------------     |
|                                                                        |
|   +---------+      +-----------+         +------------------+          |
|   | Browser |----->| /auth/    |-------->| Authorization    |          |
|   | Login   |      | oauth/    |         | Endpoint         |          |
|   +---------+      | authorize |         +------------------+          |
|       ^            +-----------+                  |                    |
|       |                                           v                    |
|       |                                  +------------------+          |
|       |                                  | User Login       |          |
|       |                                  | (IdP UI)         |          |
|       |                                  +------------------+          |
|       |                                           |                    |
|       |            +-----------+                  |                    |
|       |<-----------| /auth/    |<-----------------+                    |
|       |  Session   | oauth/    |   code + state                        |
|       |  Token     | callback  |                                       |
|       |            +-----------+                                       |
|       |                 |                                              |
|       |                 v                                              |
|       |            +-----------+         +------------------+          |
|       |            | Exchange  |-------->| Token Endpoint   |          |
|       |            | Code      |<--------| (id_token, etc)  |          |
|       |            +-----------+         +------------------+          |
|                                                                        |
+------------------------------------------------------------------------+

---

Test Environment Setup

# Gateway configuration
export GATEWAY_URL="http://localhost:8000"

# Keycloak (local testing)
docker run -d --name keycloak -p 8080:8080 \
  -e KEYCLOAK_ADMIN=admin \
  -e KEYCLOAK_ADMIN_PASSWORD=admin \
  quay.io/keycloak/keycloak:latest start-dev

# Wait for Keycloak
sleep 30
curl -s http://localhost:8080/health/ready

# Configure Keycloak realm and client
# (See Keycloak admin console or use kcadm CLI)

# Gateway OIDC configuration
export OIDC_ISSUER_URL="http://localhost:8080/realms/mcpgateway"
export OIDC_CLIENT_ID="mcpgateway-client"
export OIDC_CLIENT_SECRET="client-secret-here"

---

Manual Test Cases

Case	Provider	Flow	Expected Result
INT-01	Generic OIDC	Authorization code	Login works
INT-02	Keycloak	OIDC + groups	Group mapping
INT-03	Okta	OIDC + roles	Role mapping
INT-04	Azure AD	OIDC	Microsoft login
INT-05	Google	OAuth 2.0	Basic auth
INT-06	Token refresh	Any OIDC	Tokens refresh
INT-07	Logout	Any	Session terminated

---

INT-01: Generic OIDC Authorization Code Flow

Steps:

# 1. Get authorization URL
AUTH_RESPONSE=$(curl -s "$GATEWAY_URL/api/auth/oauth/authorize?provider=keycloak")
AUTH_URL=$(echo "$AUTH_RESPONSE" | jq -r '.url')
STATE=$(echo "$AUTH_RESPONSE" | jq -r '.state')

echo "Visit in browser: $AUTH_URL"

# 2. After browser login, capture callback URL
# The callback URL will contain: ?code=AUTH_CODE&state=STATE

# 3. Exchange code for token
curl -s -X POST "$GATEWAY_URL/api/auth/oauth/callback" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "AUTH_CODE_FROM_CALLBACK",
    "state": "'$STATE'",
    "provider": "keycloak"
  }' | jq .

Validation:

# Extract gateway token
GATEWAY_TOKEN=$(... from response above ...)

# Test authenticated access
curl -s "$GATEWAY_URL/api/users/me" \
  -H "Authorization: Bearer $GATEWAY_TOKEN" | jq .

# Verify user info
curl -s "$GATEWAY_URL/api/users/me" \
  -H "Authorization: Bearer $GATEWAY_TOKEN" | jq '{email, name, roles}'

Expected Result:

• Authorization URL redirects to IdP
• After IdP login, callback returns code
• Code exchange returns gateway token
• Token works for API access

INT-02: Keycloak with Group Mapping

Keycloak Setup:

# Create groups in Keycloak
# - admin-group
# - developer-group

# Assign user to groups in Keycloak admin console

# Configure gateway group mapping
export OIDC_GROUP_CLAIM="groups"
export OIDC_ADMIN_GROUPS="admin-group"
export OIDC_DEVELOPER_GROUPS="developer-group"

Test Steps:

# Login as user in admin-group
# (Follow INT-01 flow)

# Verify group mapping
curl -s "$GATEWAY_URL/api/users/me" \
  -H "Authorization: Bearer $GATEWAY_TOKEN" | jq '.roles'

# Should include admin role if user is in admin-group

Expected Result:

• Groups from IdP map to gateway roles
• Admin group users get admin permissions
• Group changes in IdP reflect in gateway

INT-03: Okta OIDC Integration

Okta Setup:

1. Create Okta application (Web, OIDC)
2. Configure redirect URI: $GATEWAY_URL/api/auth/oauth/callback
3. Enable groups claim in ID token

Gateway Configuration:

export OIDC_PROVIDER_OKTA_ISSUER="https://your-org.okta.com"
export OIDC_PROVIDER_OKTA_CLIENT_ID="okta-client-id"
export OIDC_PROVIDER_OKTA_CLIENT_SECRET="okta-secret"

Test Steps:

# Initiate Okta login
curl -s "$GATEWAY_URL/api/auth/oauth/authorize?provider=okta" | jq '.url'

# After login, verify token
curl -s "$GATEWAY_URL/api/users/me" \
  -H "Authorization: Bearer $OKTA_GATEWAY_TOKEN" | jq .

Expected Result:

• Okta login works
• ID token claims extracted
• Groups/roles mapped correctly

INT-04: Azure AD OIDC Integration

Azure AD Setup:

1. Register application in Azure AD
2. Add redirect URI: $GATEWAY_URL/api/auth/oauth/callback
3. Configure API permissions (OpenID, email, profile)

Gateway Configuration:

export OIDC_PROVIDER_AZURE_ISSUER="https://login.microsoftonline.com/TENANT_ID/v2.0"
export OIDC_PROVIDER_AZURE_CLIENT_ID="azure-client-id"
export OIDC_PROVIDER_AZURE_CLIENT_SECRET="azure-secret"

Test Steps:

# Initiate Azure login
curl -s "$GATEWAY_URL/api/auth/oauth/authorize?provider=azure" | jq '.url'

# Verify Microsoft identity
curl -s "$GATEWAY_URL/api/users/me" \
  -H "Authorization: Bearer $AZURE_GATEWAY_TOKEN" | jq '{email, name}'

Expected Result:

• Microsoft login screen appears
• Token exchange succeeds
• User identity correct

INT-06: Token Refresh Flow

Steps:

# Get tokens (includes refresh_token)
TOKENS=$(curl -s -X POST "$GATEWAY_URL/api/auth/oauth/callback" \
  -H "Content-Type: application/json" \
  -d '{"code": "AUTH_CODE", "provider": "keycloak"}')

ACCESS_TOKEN=$(echo "$TOKENS" | jq -r '.access_token')
REFRESH_TOKEN=$(echo "$TOKENS" | jq -r '.refresh_token')

# Wait for access token to expire (or use short-lived token)
sleep 300  # If token expires in 5 min

# Refresh token
curl -s -X POST "$GATEWAY_URL/api/auth/oauth/refresh" \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "'$REFRESH_TOKEN'"}' | jq .

Expected Result:

• New access token returned
• Old access token invalidated (if configured)
• Refresh works before expiry

INT-07: Logout and Session Termination

Steps:

# Logout from gateway
curl -s -X POST "$GATEWAY_URL/api/auth/logout" \
  -H "Authorization: Bearer $GATEWAY_TOKEN" | jq .

# Verify token no longer works
curl -s "$GATEWAY_URL/api/users/me" \
  -H "Authorization: Bearer $GATEWAY_TOKEN"
# Should return 401

# Optional: Verify IdP logout (back-channel)
curl -s "$IDP_URL/logout?client_id=$CLIENT_ID"

Expected Result:

• Gateway session terminated
• Token returns 401 after logout
• IdP session optionally terminated

---

Test Matrix

Provider	Flow	Group Mapping	Token Refresh	Logout	Pass Criteria
Keycloak	Authorization Code	Yes	Yes	Yes	Full flow works
Okta	Authorization Code	Yes	Yes	Yes	Enterprise SSO
Azure AD	Authorization Code	Yes	Yes	Yes	Microsoft login
Google	OAuth 2.0	No	Yes	Yes	Basic auth
Generic OIDC	Authorization Code	Configurable	Yes	Yes	Standards compliant

---

Success Criteria

• Keycloak OIDC integration works end-to-end
• Okta integration tested with production-like config
• Azure AD integration works with group mapping
• Google OAuth basic authentication works
• Token refresh handles correctly for all providers
• Logout terminates gateway session
• Group/role mapping works correctly

---

Related Files

• mcpgateway/routers/auth.py - OAuth endpoints
• mcpgateway/services/auth_service.py - Auth logic
• mcpgateway/middleware/auth.py - Token validation
• mcpgateway/config.py - OIDC configuration

---

Related Issues

• [TESTING][E2E]: User journey - SSO authentication end-to-end test (OAuth flow, token exchange, session management) #2456 - SSO E2E testing
• [TESTING][SECURITY]: SSO and OAuth manual test plan (Keycloak, EntraID, OIDC, PKCE, token exchange) #2391 - SSO and OAuth (security)
• [TESTING][SECURITY]: Core authentication manual test plan (JWT, Basic Auth, API tokens, email/password) #2390 - Core authentication