🔑 IAM Agent Specification¶

🎯 Purpose¶

The IAM (Identity and Access Management) Agent owns the identity architecture and access control layer of the ConnectSoft AI Software Factory. It designs, generates, and validates all identity-related configurations — including OAuth/OIDC flows, RBAC policies, tenant identity federation, SSO setup, and service-to-service authentication.

It ensures that every generated service, API, and tenant boundary is identity-aware, policy-governed, and zero-trust compliant from the moment of creation.

It guarantees that identity is never an afterthought — every component is born with the right authentication, authorization, and federation configuration.

🧭 Role in the Platform¶

The IAM Agent operates within the Security and Compliance cluster, translating high-level security architecture into concrete identity configurations that are consumed by engineering and deployment agents.

Factory Layer	Agent Role
Security Architecture	Translates security architect blueprints into identity configurations
Engineering	Provides RBAC policies and auth middleware for generated services
Multi-Tenancy	Configures tenant identity federation and isolation boundaries
DevOps & Delivery	Produces identity configs consumed by deployment pipelines
Compliance	Generates identity audit evidence and access control documentation

📊 Position Diagram¶

flowchart TD

  subgraph Architecture
    A[Security Architect Agent]
    B[Enterprise Architect Agent]
  end

  subgraph Security & Compliance
    C[IAM Agent]
    D[Security Engineer Agent]
  end

  subgraph Engineering
    E[Backend Developer Agent]
    F[API Gateway Generator Agent]
  end

  subgraph Multi-Tenancy
    G[Tenant Management Agent]
  end

  A --> C
  B --> C
  G --> C
  C --> D
  C --> E
  C --> F
  D --> C

Hold "Alt" / "Option" to enable pan & zoom

The IAM Agent receives identity requirements from architecture and tenant management, producing concrete configurations consumed by engineering and security enforcement layers.

📋 Triggering Events¶

Event	Source	Description
`architecture_blueprint_created`	Enterprise/Security Architect	New architecture blueprint requires identity design
`tenant_onboarded`	Tenant Management Agent	New tenant requires identity federation and SSO configuration
`rbac_policy_update_requested`	Security Engineer / Admin	RBAC policies need creation or modification
`service_generated`	Microservice Generator Agent	New service needs auth middleware and identity configuration
`identity_audit_requested`	Compliance / Audit Agent	Identity configurations require compliance review

📌 Responsibilities¶

🔧 Core Responsibilities¶

✅ 1. Identity Architecture Design¶

Translate security blueprints into identity architecture documents
Define authentication flows (OAuth2 Authorization Code, Client Credentials, Device Flow)
Design token lifecycle (issuance, refresh, revocation, expiry)
Specify identity provider integration patterns (Azure AD, OpenIddict, external IdPs)

identity_architecture:
  provider: azure-ad
  flows:
    - type: authorization_code
      audience: connectsoft-api
      scopes: [read, write, admin]
    - type: client_credentials
      audience: internal-services
      scopes: [service.read, service.write]
  token_config:
    access_token_lifetime: 3600
    refresh_token_lifetime: 86400
    issuer: "https://login.connectsoft.io"

✅ 2. OAuth/OIDC Configuration Generation¶

Generate OAuth2 and OIDC configuration for each service and API gateway
Produce client registrations, redirect URIs, and scope definitions
Configure token validation middleware parameters
Support multiple identity providers per tenant

✅ 3. RBAC Policy Generation¶

Define roles, permissions, and role-to-permission mappings
Generate Kubernetes RBAC manifests (Role, RoleBinding, ClusterRole)
Produce application-level RBAC policies for handler authorization
Support hierarchical roles with inheritance

rbac_policy:
  roles:
    - name: tenant-admin
      permissions:
        - users.read
        - users.write
        - billing.manage
        - settings.configure
    - name: tenant-viewer
      permissions:
        - users.read
        - billing.read
    - name: service-account
      permissions:
        - api.internal.read
        - api.internal.write
  bindings:
    - role: tenant-admin
      subjects:
        - kind: Group
          name: "cs-admins-{tenantId}"
    - role: service-account
      subjects:
        - kind: ServiceAccount
          name: "orderservice-sa"
          namespace: "cs-{tenantId}-order"

✅ 4. Tenant Identity Federation¶

Configure federated identity for multi-tenant scenarios
Set up trust relationships between ConnectSoft IdP and tenant IdPs
Map external claims to ConnectSoft roles and permissions
Support SAML 2.0 and OIDC federation protocols

✅ 5. SSO Setup and Configuration¶

Generate SSO configuration for web applications and developer portals
Configure silent authentication, session management, and logout flows
Produce SSO integration guides for tenant onboarding
Validate SSO flow correctness through automated testing

✅ 6. Service-to-Service Authentication¶

Configure mTLS and client certificate authentication for internal services
Generate managed identity configurations for Azure workloads
Define service mesh authentication policies (Istio AuthorizationPolicy)
Validate inter-service trust chains

📊 Responsibilities and Deliverables¶

Responsibility	Deliverable
Identity architecture	`identity-architecture.yaml` with flows, providers, token config
OAuth/OIDC configuration	`iam-config.json` with client registrations and scopes
RBAC policy generation	`rbac-policy.yaml` with roles, permissions, and bindings
Tenant federation	Federation trust configs and claim mapping documents
SSO setup	SSO configuration files and integration guides
Service auth	mTLS certs, managed identity configs, mesh auth policies

📤 Output Types¶

Output Type	Format	Description
`iam-config`	JSON	OAuth/OIDC client configurations, scopes, and provider settings
`rbac-policy`	YAML	Role definitions, permissions, and binding manifests
`identity-architecture`	YAML	High-level identity architecture with flows and token policies
`federation-config`	JSON	Tenant identity federation trust and claim mapping configurations
`sso-config`	JSON	SSO integration settings for web applications

🧾 Example `iam-config` Output¶

{
  "trace_id": "trace-iam-5523",
  "provider": "azure-ad",
  "tenant_id": "connectsoft-primary",
  "clients": [
    {
      "client_id": "cs-web-portal",
      "client_type": "public",
      "grant_types": ["authorization_code"],
      "redirect_uris": [
        "https://portal.connectsoft.io/callback",
        "https://portal.connectsoft.io/silent-renew"
      ],
      "scopes": ["openid", "profile", "api.read", "api.write"],
      "token_lifetime": 3600
    },
    {
      "client_id": "cs-orderservice",
      "client_type": "confidential",
      "grant_types": ["client_credentials"],
      "scopes": ["service.internal.read", "service.internal.write"],
      "token_lifetime": 1800
    }
  ],
  "issuer": "https://login.connectsoft.io",
  "jwks_uri": "https://login.connectsoft.io/.well-known/jwks.json",
  "agent": "iam-agent"
}

🧾 Example `rbac-policy` Output¶

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: orderservice-role
  namespace: cs-tenant-001-order
  labels:
    trace_id: trace-iam-5523
    generated_by: iam-agent
rules:
  - apiGroups: [""]
    resources: ["configmaps", "secrets"]
    verbs: ["get", "list"]
  - apiGroups: [""]
    resources: ["pods"]
    verbs: ["get", "list", "watch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: orderservice-binding
  namespace: cs-tenant-001-order
  labels:
    trace_id: trace-iam-5523
    generated_by: iam-agent
subjects:
  - kind: ServiceAccount
    name: orderservice-sa
    namespace: cs-tenant-001-order
roleRef:
  kind: Role
  name: orderservice-role
  apiGroup: rbac.authorization.k8s.io

🔄 Process Flow¶

flowchart TD
    A[Trigger Received] --> B[Load Security Blueprint + Tenant Context]
    B --> C[Design Identity Architecture]
    C --> D[Generate OAuth/OIDC Configurations]
    D --> E[Generate RBAC Policies]
    E --> F[Configure Federation / SSO if Required]
    F --> G[Validate All Identity Artifacts]
    G --> H{Validation Passes?}
    H -- Yes --> I[Emit iam-config + rbac-policy + Events]
    H -- No --> J{Retryable?}
    J -- Yes --> D
    J -- No --> K[Emit IdentityConfigurationFailed + Notify Ops]

Hold "Alt" / "Option" to enable pan & zoom

🪜 Step-by-Step Breakdown¶

Step	Action
1	Receive trigger with blueprint, tenant context, or RBAC update request
2	Load security architecture blueprint and tenant identity requirements
3	Design identity architecture: flows, providers, token policies
4	Generate OAuth/OIDC client configurations with scopes and redirect URIs
5	Generate RBAC policies: roles, permissions, Kubernetes manifests, app-level policies
6	Configure tenant federation and SSO if tenant onboarding or multi-IdP scenario
7	Validate all artifacts: schema correctness, scope coverage, binding integrity
8	If valid: emit configurations and `IdentityConfigurationReady` event
9	If invalid: retry or escalate with `IdentityConfigurationFailed`

🤝 Collaboration Patterns¶

📥 Upstream Inputs From¶

Agent	Input
Security Architect Agent	Identity architecture blueprints and policy constraints
Enterprise Architect Agent	Service boundaries and cross-service auth requirements
Tenant Management Agent	Tenant onboarding context, IdP details, federation requirements
Security Engineer Agent	Runtime security constraints and hardening baselines

📤 Downstream Consumers¶

Agent	Output Consumed
Security Engineer Agent	RBAC policies for enforcement in generated services
Backend Developer Agent	Auth middleware configuration and token validation settings
API Gateway Generator Agent	OAuth scopes, rate limiting, and identity verification configs
DevOps Engineer Agent	Kubernetes RBAC manifests for deployment pipelines
Infrastructure Engineer Agent	ServiceAccount and identity binding configurations

🔁 Event-Based Communication¶

Event	Trigger	Consumed By
`IdentityConfigurationReady`	Successful identity config generation	Security Engineer, Backend Developer, DevOps
`IdentityConfigurationFailed`	Validation failure in identity artifacts	HumanOpsAgent, Security Architect
`RBACPolicyGenerated`	RBAC policy created or updated	Security Engineer, Infrastructure Engineer
`TenantFederationConfigured`	Federation trust established for tenant	Tenant Management Agent, Security Engineer
`SSOConfigurationReady`	SSO setup completed and validated	Frontend Developer, Documentation Agent

🧩 Collaboration Sequence¶

sequenceDiagram
    participant SecArch as Security Architect Agent
    participant IAM as IAM Agent
    participant TenantMgr as Tenant Management Agent
    participant SecEng as Security Engineer Agent
    participant Backend as Backend Developer Agent

    SecArch->>IAM: Identity Blueprint
    TenantMgr->>IAM: Tenant Federation Requirements
    IAM->>IAM: Generate OAuth + RBAC + Federation
    IAM->>SecEng: Emit RBACPolicyGenerated
    IAM->>Backend: Emit IdentityConfigurationReady

Hold "Alt" / "Option" to enable pan & zoom

🧠 Memory and Knowledge¶

📌 Short-Term Memory (Execution Scope)¶

Field	Purpose
`trace_id`	Links identity operations to originating blueprint
`tenant_context`	Active tenant identity requirements being processed
`generated_policies`	In-flight RBAC and OAuth configurations
`validation_state`	Current validation status of identity artifacts

💾 Long-Term Memory (Persistent)¶

Memory Type	Purpose
Identity Architecture Registry	All identity architectures per project and tenant
RBAC Policy History	Version history of all RBAC policies with change tracking
Client Registration Registry	All OAuth client registrations with scopes and configurations
Federation Trust Store	Active federation relationships and claim mappings
SSO Configuration History	SSO settings per tenant and application with version tracking

📚 Knowledge Base¶

Knowledge Area	Description
OAuth2/OIDC Standards	RFC 6749, RFC 7519, OpenID Connect Core specifications
RBAC Design Patterns	Role hierarchy, permission models, least-privilege strategies
Federation Protocols	SAML 2.0, OIDC federation, claim mapping patterns
Azure AD Integration	App registrations, managed identities, B2B/B2C configurations
Multi-Tenant Identity Patterns	Tenant isolation, shared vs dedicated IdP, cross-tenant access
Zero Trust Architecture	mTLS, continuous verification, service mesh auth policies
ConnectSoft Identity Standards	Platform-specific naming, scoping, and policy conventions

✅ Validation¶

Category	Checks Performed
OAuth Configuration	Client IDs unique, redirect URIs valid, scopes properly defined
RBAC Integrity	All roles have permissions, bindings reference valid roles/subjects
Least Privilege	No overly broad permissions (e.g., wildcard verbs or resources)
Federation Trust	Trust relationships valid, claim mappings complete and non-conflicting
Token Policy	Lifetimes within acceptable ranges, refresh policies defined
Tenant Isolation	No cross-tenant permission leakage in RBAC or federation config
Schema Compliance	All outputs valid against Kubernetes RBAC and OAuth2 schemas

❌ Failure Actions¶

Failure Type	Action
Duplicate client ID detected	Reject and emit conflict error with existing registration
Overly broad RBAC permissions	Block generation, suggest least-privilege alternative
Invalid redirect URI	Reject with detailed URI validation error
Federation claim mapping conflict	Escalate to Security Architect for resolution
Cross-tenant permission leak	Critical block — halt all outputs and alert Security team
Token lifetime out of range	Apply platform default, log override

📊 Validation Output Format¶

{
  "trace_id": "trace-iam-5523",
  "validation_status": "passed",
  "checks": [
    { "category": "oauth_config", "status": "passed", "clients_validated": 2 },
    { "category": "rbac_integrity", "status": "passed", "roles_validated": 3 },
    { "category": "least_privilege", "status": "passed" },
    { "category": "tenant_isolation", "status": "passed" },
    { "category": "federation", "status": "skipped", "reason": "no_federation_required" }
  ],
  "agent": "iam-agent",
  "timestamp": "2025-06-10T12:30:00Z"
}

🧩 Skills and Kernel Functions¶

Skill	Purpose
`IdentityArchitectSkill`	Design identity architecture from security blueprints
`OAuthConfigGeneratorSkill`	Generate OAuth2/OIDC client configurations and scopes
`RBACPolicyGeneratorSkill`	Produce role definitions, permissions, and Kubernetes manifests
`FederationConfigurerSkill`	Set up tenant identity federation and claim mappings
`SSOSetupSkill`	Configure SSO flows, session management, and logout
`ServiceAuthConfigSkill`	Generate mTLS, managed identity, and mesh auth configurations
`IdentityValidatorSkill`	Validate all identity artifacts for correctness and security
`LeastPrivilegeCheckerSkill`	Audit RBAC policies for overly broad permissions
`EventEmitterSkill`	Emit identity lifecycle events
`TraceMetadataInjectorSkill`	Attach trace context to all identity artifacts

📈 Observability Hooks¶

Span Name	Description
`iam.architecture.design`	Identity architecture design phase
`iam.oauth.generate`	OAuth/OIDC configuration generation
`iam.rbac.generate`	RBAC policy generation
`iam.federation.configure`	Tenant federation setup
`iam.sso.configure`	SSO configuration generation
`iam.validate`	Identity artifact validation
`iam.complete`	Successful identity configuration emission
`iam.failed`	Identity configuration failure

Span Tags¶

trace_id, tenant_id, project_id
agent: iam-agent
status: ready | failed | skipped
clients_generated, roles_generated, federation_configured

🧠 Summary¶

The IAM Agent is the identity authority of the ConnectSoft AI Software Factory. It ensures that:

🔑 Every service is born with correct OAuth/OIDC configuration
🛡️ RBAC policies enforce least privilege across all layers
🌐 Tenant federation enables seamless multi-IdP integration
🔐 SSO flows are configured, validated, and documented
🔗 Service-to-service authentication follows zero-trust principles
📊 Identity configurations are traceable and auditable

It transforms identity management from a complex, error-prone manual task into an automated, policy-driven, trace-aware operation — ensuring the platform's identity layer is secure, consistent, and ready for enterprise-scale multi-tenancy.

🔑 IAM Agent Specification¶

🎯 Purpose¶

🧭 Role in the Platform¶

📊 Position Diagram¶

📋 Triggering Events¶

📌 Responsibilities¶

🔧 Core Responsibilities¶

✅ 1. Identity Architecture Design¶

✅ 2. OAuth/OIDC Configuration Generation¶

✅ 3. RBAC Policy Generation¶

✅ 4. Tenant Identity Federation¶

✅ 5. SSO Setup and Configuration¶

✅ 6. Service-to-Service Authentication¶

📊 Responsibilities and Deliverables¶

📤 Output Types¶

🧾 Example iam-config Output¶

🧾 Example rbac-policy Output¶

🔄 Process Flow¶

🪜 Step-by-Step Breakdown¶

🤝 Collaboration Patterns¶

📥 Upstream Inputs From¶

📤 Downstream Consumers¶

🔁 Event-Based Communication¶

🧩 Collaboration Sequence¶

🧠 Memory and Knowledge¶

📌 Short-Term Memory (Execution Scope)¶

💾 Long-Term Memory (Persistent)¶

📚 Knowledge Base¶

✅ Validation¶

❌ Failure Actions¶

📊 Validation Output Format¶

🧩 Skills and Kernel Functions¶

📈 Observability Hooks¶

Span Tags¶

🧠 Summary¶

🧾 Example `iam-config` Output¶

🧾 Example `rbac-policy` Output¶