Azure AD Identity and Access Management

naftiko: "1.0.0-alpha1"

info:
  label: "Azure AD Identity and Access Management"
  description: "Unified identity and access management workflow combining user lifecycle, group management, application registration, and service principal operations. Used by IT administrators and identity engineers to manage enterprise identity infrastructure."
  tags:
    - Microsoft Entra
    - Identity
    - Access Management
    - Azure Active Directory
  created: "2026-04-18"
  modified: "2026-04-18"

binds:
  - namespace: env
    keys:
      MICROSOFT_GRAPH_ACCESS_TOKEN: MICROSOFT_GRAPH_ACCESS_TOKEN

capability:
  consumes:
    - import: graph-identity
      location: ./shared/microsoft-graph-identity.yaml

  exposes:
    - type: rest
      port: 8080
      namespace: azure-ad-iam-api
      description: "Unified REST API for Azure AD identity and access management."
      resources:
        - path: /v1/users
          name: users
          description: "User lifecycle management."
          operations:
            - method: GET
              name: list-users
              description: "List directory users."
              call: "graph-identity.list-users"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: POST
              name: create-user
              description: "Create a new user."
              call: "graph-identity.create-user"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/users/{userId}
          name: user-detail
          description: "Single user operations."
          operations:
            - method: GET
              name: get-user
              description: "Get user details."
              call: "graph-identity.get-user"
              with:
                userId: "rest.userId"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: PATCH
              name: update-user
              description: "Update user properties."
              call: "graph-identity.update-user"
              with:
                userId: "rest.userId"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: DELETE
              name: delete-user
              description: "Delete a user."
              call: "graph-identity.delete-user"
              with:
                userId: "rest.userId"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/groups
          name: groups
          description: "Group management."
          operations:
            - method: GET
              name: list-groups
              description: "List groups."
              call: "graph-identity.list-groups"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: POST
              name: create-group
              description: "Create a group."
              call: "graph-identity.create-group"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/groups/{groupId}
          name: group-detail
          description: "Single group operations."
          operations:
            - method: GET
              name: get-group
              description: "Get group details."
              call: "graph-identity.get-group"
              with:
                groupId: "rest.groupId"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/groups/{groupId}/members
          name: group-members
          description: "Group membership."
          operations:
            - method: GET
              name: list-group-members
              description: "List group members."
              call: "graph-identity.list-group-members"
              with:
                groupId: "rest.groupId"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: POST
              name: add-group-member
              description: "Add a group member."
              call: "graph-identity.add-group-member"
              with:
                groupId: "rest.groupId"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/applications
          name: applications
          description: "App registration management."
          operations:
            - method: GET
              name: list-applications
              description: "List app registrations."
              call: "graph-identity.list-applications"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/service-principals
          name: service-principals
          description: "Service principal management."
          operations:
            - method: GET
              name: list-service-principals
              description: "List service principals."
              call: "graph-identity.list-service-principals"
              outputParameters:
                - type: object
                  mapping: "$."

    - type: mcp
      port: 9090
      namespace: azure-ad-iam-mcp
      transport: http
      description: "MCP server for AI-assisted Azure AD identity and access management."
      tools:
        - name: list-users
          description: "List Azure AD users with optional filtering."
          hints:
            readOnly: true
            idempotent: true
            openWorld: true
          call: "graph-identity.list-users"
          outputParameters:
            - type: object
              mapping: "$."
        - name: create-user
          description: "Create a new Azure AD user account."
          hints:
            readOnly: false
          call: "graph-identity.create-user"
          with:
            display_name: "tools.display_name"
            mail_nickname: "tools.mail_nickname"
            user_principal_name: "tools.user_principal_name"
            password: "tools.password"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-user
          description: "Get Azure AD user details by ID or UPN."
          hints:
            readOnly: true
            idempotent: true
          call: "graph-identity.get-user"
          with:
            userId: "tools.userId"
          outputParameters:
            - type: object
              mapping: "$."
        - name: update-user
          description: "Update Azure AD user properties."
          hints:
            readOnly: false
            idempotent: true
          call: "graph-identity.update-user"
          with:
            userId: "tools.userId"
          outputParameters:
            - type: object
              mapping: "$."
        - name: delete-user
          description: "Delete an Azure AD user account."
          hints:
            readOnly: false
            destructive: true
            idempotent: true
          call: "graph-identity.delete-user"
          with:
            userId: "tools.userId"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-user-memberships
          description: "List groups and roles a user belongs to."
          hints:
            readOnly: true
            idempotent: true
          call: "graph-identity.list-user-member-of"
          with:
            userId: "tools.userId"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-groups
          description: "List Azure AD groups with optional filtering."
          hints:
            readOnly: true
            idempotent: true
            openWorld: true
          call: "graph-identity.list-groups"
          outputParameters:
            - type: object
              mapping: "$."
        - name: create-group
          description: "Create a new Azure AD group."
          hints:
            readOnly: false
          call: "graph-identity.create-group"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-group
          description: "Get Azure AD group details."
          hints:
            readOnly: true
            idempotent: true
          call: "graph-identity.get-group"
          with:
            groupId: "tools.groupId"
          outputParameters:
            - type: object
              mapping: "$."
        - name: delete-group
          description: "Delete an Azure AD group."
          hints:
            readOnly: false
            destructive: true
            idempotent: true
          call: "graph-identity.delete-group"
          with:
            groupId: "tools.groupId"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-group-members
          description: "List members of an Azure AD group."
          hints:
            readOnly: true
            idempotent: true
          call: "graph-identity.list-group-members"
          with:
            groupId: "tools.groupId"
          outputParameters:
            - type: object
              mapping: "$."
        - name: add-group-member
          description: "Add a member to an Azure AD group."
          hints:
            readOnly: false
          call: "graph-identity.add-group-member"
          with:
            groupId: "tools.groupId"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-applications
          description: "List Azure AD application registrations."
          hints:
            readOnly: true
            idempotent: true
            openWorld: true
          call: "graph-identity.list-applications"
          outputParameters:
            - type: object
              mapping: "$."
        - name: create-application
          description: "Register a new application in Azure AD."
          hints:
            readOnly: false
          call: "graph-identity.create-application"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-application
          description: "Get an application registration by ID."
          hints:
            readOnly: true
            idempotent: true
          call: "graph-identity.get-application"
          with:
            applicationId: "tools.applicationId"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-service-principals
          description: "List Azure AD service principals."
          hints:
            readOnly: true
            idempotent: true
            openWorld: true
          call: "graph-identity.list-service-principals"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-service-principal
          description: "Get a service principal by ID."
          hints:
            readOnly: true
            idempotent: true
          call: "graph-identity.get-service-principal"
          with:
            servicePrincipalId: "tools.servicePrincipalId"
          outputParameters:
            - type: object
              mapping: "$."