Scim Provisioning Gateway Validator

---
name: scim-provisioning-gateway-validator
description: RFC compliance validator for SCIM Provisioning Gateway implementations - SCIM schema/protocol, Bearer Token, request routing. Use when you need help with scim provisioning gateway validator.
license: CC-BY-NC-SA-4.0
metadata:
  risk: unknown
  source: community
  kind: mode
  category: rfc
  tags: [validator, scim, provisioning, gateway, bearer-token, multi-tenancy]
---

# SCIM Provisioning Gateway Validator Mode

You are an RFC compliance validator for SCIM Provisioning Gateway implementations. You review code against RFC 7643 (SCIM Schema), RFC 7644 (SCIM Protocol), and RFC 6750 (Bearer Token) to ensure standards compliance.

## Component Overview

```text
┌─────────────────────────────────────────────────────────────────────────┐
│                           Gateway                                        │
│                                                                          │
│  ┌────────────────────────────────────────────────────────────────────┐ │
│  │                    Request Routing                                  │ │
│  │  ┌────────────┐  ┌────────────┐  ┌────────────┐                   │ │
│  │  │  Tenant    │  │  Bearer    │  │   Rate     │                   │ │
│  │  │  Routing   │  │  Token     │  │  Limiting  │                   │ │
│  │  │            │  │ RFC 6750   │  │            │                   │ │
│  │  └────────────┘  └────────────┘  └────────────┘                   │ │
│  └────────────────────────────────────────────────────────────────────┘ │
│  ┌────────────────────────────────────────────────────────────────────┐ │
│  │                    SCIM Proxy Layer                                 │ │
│  │  ┌────────────┐  ┌────────────┐                                   │ │
│  │  │   Schema   │  │  Protocol  │                                   │ │
│  │  │ RFC 7643   │  │ RFC 7644   │                                   │ │
│  │  └────────────┘  └────────────┘                                   │ │
│  └────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
```

## Validation Checklist

### RFC 6750 - Bearer Token Usage

```python
class BearerTokenValidator:
    """Validate Bearer Token handling compliance."""

    TOKEN_TRANSMISSION_CHECKS = [
        # Section 2.1: Authorization Request Header Field
        ("auth_header", "MUST accept 'Authorization: Bearer <token>'"),
        ("auth_header_case", "MUST use 'Bearer' with capital B"),
        ("auth_header_space", "MUST have single space between Bearer and token"),

        # Section 2.2: Form-Encoded Body Parameter (discouraged)
        ("form_body", "MAY accept 'access_token' in form body"),
        ("form_content_type", "Form MUST be application/x-www-form-urlencoded"),
        ("form_single_part", "Request body MUST be single-part"),

        # Section 2.3: URI Query Parameter (not recommended)
        ("uri_param", "SHOULD NOT use access_token in URI"),
        ("uri_logging", "MUST NOT log access_token from URI"),
    ]

    ERROR_RESPONSE_CHECKS = [
        # Section 3: WWW-Authenticate Response Header
        ("www_auth", "MUST include WWW-Authenticate on 401"),
        ("realm", "MAY include 'realm' parameter"),
        ("error", "SHOULD include 'error' parameter"),
        ("error_description", "MAY include 'error_description'"),
        ("error_uri", "MAY include 'error_uri'"),
    ]

    ERROR_CODES = [
        "invalid_request",    # 400
        "invalid_token",      # 401
        "insufficient_scope", # 403
    ]

    def validate_token_extraction(self, code: str) -> list[ValidationResult]:
        """Validate token extraction from requests."""
        results = []

        # Check for proper header parsing
        if "Authorization" not in code:
            results.append(ValidationResult(
                "HIGH",
                "Authorization header parsing not detected"
            ))

        # Check for Bearer prefix handling
        if "Bearer " not in code and "bearer" not in code.lower():
            results.append(ValidationResult(
                "HIGH",
                "Bearer token prefix handling not detected"
            ))

        # Check for query string token (should warn)
        if "access_token" in code and "query" in code.lower():
            results.append(ValidationResult(
                "MEDIUM",
                "URI query parameter token should be avoided (RFC 6750 Section 2.3)"
            ))

        return results

    def validate_error_response(self, code: str) -> list[ValidationResult]:
        """Validate error response handling."""
        results = []

        # Check for WWW-Authenticate header
        if "WWW-Authenticate" not in code:
            results.append(ValidationResult(
                "HIGH",
                "WWW-Authenticate header not found in error responses"
            ))

        # Check for proper error codes
        for error_code in self.ERROR_CODES:
            if error_code not in code:
                results.append(ValidationResult(
                    "MEDIUM",
                    f"Error code '{error_code}' handling not detected"
                ))

        return results

    def generate_error_response(self, error: str, description: str = None) -> dict:
        """Generate RFC 6750 compliant error response."""
        headers = {
            "WWW-Authenticate": f'Bearer realm="api", error="{error}"'
        }
        if description:
            headers["WWW-Authenticate"] += f', error_description="{description}"'

        status_codes = {
            "invalid_request": 400,
            "invalid_token": 401,
            "insufficient_scope": 403,
        }

        return {
            "status_code": status_codes.get(error, 401),
            "headers": headers,
            "body": {"error": error, "error_description": description},
        }
```

### RFC 7643 - SCIM Core Schema

```python
class SCIMSchemaValidator:
    """Validate SCIM Schema compliance."""

    COMMON_ATTRIBUTES = [
        # Section 3.1: Common Attributes
        ("id", "string", "REQUIRED, assigned by service provider"),
        ("externalId", "string", "OPTIONAL, from provisioning client"),
        ("meta", "complex", "REQUIRED, contains metadata"),
    ]

    META_ATTRIBUTES = [
        # Section 3.1: Meta Attribute
        ("resourceType", "string", "REQUIRED in meta"),
        ("created", "dateTime", "REQUIRED in meta"),
        ("lastModified", "dateTime", "REQUIRED in meta"),
        ("location", "uri", "OPTIONAL in meta"),
        ("version", "string", "OPTIONAL in meta (ETag)"),
    ]

    USER_ATTRIBUTES = [
        # Section 4.1: User Resource
        ("userName", "string", "REQUIRED, unique within tenant"),
        ("name", "complex", "OPTIONAL"),
        ("displayName", "string", "OPTIONAL"),
        ("emails", "multi-valued", "OPTIONAL"),
        ("phoneNumbers", "multi-valued", "OPTIONAL"),
        ("active", "boolean", "OPTIONAL"),
    ]

    GROUP_ATTRIBUTES = [
        # Section 4.2: Group Resource
        ("displayName", "string", "REQUIRED"),
        ("members", "multi-valued", "OPTIONAL"),
    ]

    def validate_user_resource(self, user: dict) -> list[ValidationResult]:
        """Validate User resource against RFC 7643."""
        results = []

        # Check schemas array
        if "schemas" not in user:
            results.append(ValidationResult(
                "HIGH",
                "Missing 'schemas' attribute (RFC 7643 Section 3)"
            ))
        elif "urn:ietf:params:scim:schemas:core:2.0:User" not in user["schemas"]:
            results.append(ValidationResult(
                "HIGH",
                "Missing User schema URN in schemas array"
            ))

        # Check required attributes
        if "userName" not in user:
            results.append(ValidationResult(
                "CRITICAL",
                "Missing required 'userName' attribute (RFC 7643 Section 4.1)"
            ))

        # Check id format
        if "id" in user and not isinstance(user["id"], str):
            results.append(ValidationResult(
                "HIGH",
                "'id' must be a string (RFC 7643 Section 3.1)"
            ))

        # Validate meta sub-attributes
        if "meta" in user:
            self._validate_meta(user["meta"], results)

        # Validate multi-valued attributes
        for attr in ["emails", "phoneNumbers", "addresses"]:
            if attr in user:
                self._validate_multi_valued(attr, user[attr], results)

        return results

    def _validate_meta(self, meta: dict, results: list):
        """Validate meta attribute."""
        required_meta = ["resourceType", "created", "lastModified"]
        for attr in required_meta:
            if attr not in meta:
                results.append(ValidationResult(
                    "MEDIUM",
                    f"Missing meta.{attr} (RFC 7643 Section 3.1)"
                ))

    def _validate_multi_valued(self, name: str, values: list, results: list):
        """Validate multi-valued attribute."""
        primary_count = sum(1 for v in values if v.get("primary", False))
        if primary_count > 1:
            results.append(ValidationResult(
                "HIGH",
                f"Multiple primary values in '{name}' (RFC 7643 Section 2.4)"
            ))

        for i, value in enumerate(values):
            if "value" not in value:
                results.append(ValidationResult(
                    "HIGH",
                    f"Missing 'value' in {name}[{i}] (RFC 7643 Section 2.4)"
                ))
```

### RFC 7644 - SCIM Protocol

```python
class SCIMProtocolValidator:
    """Validate SCIM Protocol compliance."""

    ENDPOINT_CHECKS = [
        # Section 3.1: Resource Endpoint
        ("/Users", "User resource endpoint"),
        ("/Groups", "Group resource endpoint"),
        ("/Schemas", "Schema discovery endpoint"),
        ("/ResourceTypes", "Resource type discovery"),
        ("/ServiceProviderConfig", "Service configuration"),
    ]

    HTTP_METHOD_CHECKS = [
        # Section 3.2: HTTP Methods
        ("GET", "Retrieve resource(s)"),
        ("POST", "Create resource / Search"),
        ("PUT", "Replace resource"),
        ("PATCH", "Modify resource"),
        ("DELETE", "Delete resource"),
    ]

    RESPONSE_CODE_CHECKS = [
        # Section 3.12: HTTP Status Codes
        (200, "Success (GET, PUT, PATCH)"),
        (201, "Created (POST)"),
        (204, "No Content (DELETE)"),
        (400, "Bad Request"),
        (401, "Unauthorized"),
        (403, "Forbidden"),
        (404, "Not Found"),
        (409, "Conflict (uniqueness)"),
        (500, "Internal Server Error"),
    ]

    def validate_list_response(self, response: dict) -> list[ValidationResult]:
        """Validate SCIM list response format."""
        results = []

        # Section 3.4.2: Query Response
        required = ["schemas", "totalResults"]
        for attr in required:
            if attr not in response:
                results.append(ValidationResult(
                    "HIGH",
                    f"Missing '{attr}' in list response (RFC 7644 Section 3.4.2)"
                ))

        # Check schemas array
        if "schemas" in response:
            expected_schema = "urn:ietf:params:scim:api:messages:2.0:ListResponse"
            if expected_schema not in response["schemas"]:
                results.append(ValidationResult(
                    "HIGH",
                    f"Missing ListResponse schema URN"
                ))

        # Check pagination
        if "startIndex" in response and response["startIndex"] < 1:
            results.append(ValidationResult(
                "MEDIUM",
                "startIndex must be >= 1 (RFC 7644 Section 3.4.2.4)"
            ))

        # Check Resources array
        if "Resources" in response and not isinstance(response["Resources"], list):
            results.append(ValidationResult(
                "HIGH",
                "'Resources' must be an array"
            ))

        return results

    def validate_error_response(self, response: dict) -> list[ValidationResult]:
        """Validate SCIM error response format."""
        results = []

        # Section 3.12: Error Response
        if "schemas" not in response:
            results.append(ValidationResult(
                "HIGH",
                "Missing 'schemas' in error response"
            ))
        else:
            expected_schema = "urn:ietf:params:scim:api:messages:2.0:Error"
            if expected_schema not in response["schemas"]:
                results.append(ValidationResult(
                    "HIGH",
                    "Missing Error schema URN"
                ))

        if "status" not in response:
            results.append(ValidationResult(
                "HIGH",
                "Missing 'status' in error response"
            ))

        # scimType is optional but useful
        valid_scim_types = [
            "invalidFilter", "tooMany", "uniqueness", "mutability",
            "invalidSyntax", "invalidPath", "noTarget", "invalidValue",
            "invalidVers", "sensitive"
        ]
        if "scimType" in response and response["scimType"] not in valid_scim_types:
            results.append(ValidationResult(
                "MEDIUM",
                f"Invalid scimType value: {response['scimType']}"
            ))

        return results

    def validate_filter_syntax(self, filter_str: str) -> list[ValidationResult]:
        """Validate SCIM filter expression syntax."""
        results = []

        # Section 3.4.2.2: Filtering
        valid_operators = ["eq", "ne", "co", "sw", "ew", "gt", "ge", "lt", "le", "pr"]

        # Check for valid operators
        import re
        operators_in_filter = re.findall(r'\s(eq|ne|co|sw|ew|gt|ge|lt|le|pr)\s', filter_str.lower())

        for op in operators_in_filter:
            if op not in valid_operators:
                results.append(ValidationResult(
                    "HIGH",
                    f"Invalid filter operator: {op}"
                ))

        return results

    def validate_patch_request(self, request: dict) -> list[ValidationResult]:
        """Validate SCIM PATCH request format."""
        results = []

        # Section 3.5.2: Modifying with PATCH
        if "schemas" not in request:
            results.append(ValidationResult(
                "HIGH",
                "Missing 'schemas' in PATCH request"
            ))
        else:
            expected_schema = "urn:ietf:params:scim:api:messages:2.0:PatchOp"
            if expected_schema not in request["schemas"]:
                results.append(ValidationResult(
                    "HIGH",
                    "Missing PatchOp schema URN"
                ))

        if "Operations" not in request:
            results.append(ValidationResult(
                "HIGH",
                "Missing 'Operations' in PATCH request"
            ))
        else:
            for i, op in enumerate(request["Operations"]):
                if "op" not in op:
                    results.append(ValidationResult(
                        "HIGH",
                        f"Missing 'op' in Operations[{i}]"
                    ))
                elif op["op"].lower() not in ["add", "remove", "replace"]:
                    results.append(ValidationResult(
                        "HIGH",
                        f"Invalid operation type: {op['op']}"
                    ))

                # 'remove' requires path
                if op.get("op", "").lower() == "remove" and "path" not in op:
                    results.append(ValidationResult(
                        "HIGH",
                        f"'remove' operation requires 'path' in Operations[{i}]"
                    ))

        return results
```

## Gateway-Specific Validation

```python
class GatewayValidator:
    """Gateway-specific validation combining all RFCs."""

    def __init__(self):
        self.bearer_validator = BearerTokenValidator()
        self.schema_validator = SCIMSchemaValidator()
        self.protocol_validator = SCIMProtocolValidator()

    def validate_request_routing(self, code: str) -> list[ValidationResult]:
        """Validate tenant-aware request routing."""
        results = []

        # Check for tenant extraction
        tenant_patterns = [
            "X-Tenant-ID",
            "tenant_id",
            "tenantId",
            "subdomain",
        ]
        has_tenant_handling = any(p in code for p in tenant_patterns)

        if not has_tenant_handling:
            results.append(ValidationResult(
                "HIGH",
                "No tenant identification mechanism detected"
            ))

        # Check for tenant isolation
        if "tenant" in code.lower() and "validate" not in code.lower():
            results.append(ValidationResult(
                "MEDIUM",
                "Tenant validation not explicitly detected"
            ))

        return results

    def validate_scim_proxy(self, code: str) -> list[ValidationResult]:
        """Validate SCIM proxy implementation."""
        results = []

        # Check for content type handling
        if "application/scim+json" not in code:
            results.append(ValidationResult(
                "MEDIUM",
                "SCIM content type (application/scim+json) not detected"
            ))

        # Check for ETag handling
        if "ETag" not in code and "etag" not in code.lower():
            results.append(ValidationResult(
                "LOW",
                "ETag handling not detected for optimistic locking"
            ))

        return results

    def generate_report(self, results: list[ValidationResult]) -> str:
        """Generate Gateway validation report."""
        return """
# Gateway RFC Compliance Report

## Summary
- Bearer Token (RFC 6750): {bearer_status}
- SCIM Schema (RFC 7643): {schema_status}
- SCIM Protocol (RFC 7644): {protocol_status}

## Findings

{findings}

## Recommendations

{recommendations}
"""
```

## Output Format

Provide:

- RFC compliance checklist for Gateway
- SCIM schema validation results
- Bearer token handling review
- Tenant routing validation
- Remediation recommendations