Microsoft Entra Grant App Role Assignment

arazzo: 1.0.1
info:
  title: Microsoft Entra Grant App Role Assignment
  summary: Grant an app role to a service principal then list its assignments.
  description: >-
    Grants an application permission (app role assignment) to a service
    principal in Microsoft Entra ID and then lists the service principal's app
    role assignments to confirm the grant. The grant supplies the principalId
    (the assignee), the resourceId (the resource service principal exposing the
    role), and the appRoleId to assign. Every request is inlined so the chain
    reads end to end.
  version: 1.0.0
  x-realizes-capability-ids:
  - BC-620.20
  x-capability-derivation:
    method: 'deterministic join: sourceDescriptions -> per-tag OpenAPI -> tag/capability edge. No classification at this step.'
    min_confidence: 0.7
    sources:
    - capability_id: BC-620.20
      capability_name: Identity & Access Management
      spec: microsoft-entra-serviceprincipals-api-openapi.yml
      confidence: 0.88
    model: Turbo EA Capabilities by Vincent Verdet — Turbo EA, https://github.com/vincentmakes/turbo-ea-capabilities, CC BY 4.0
sourceDescriptions:
- name: serviceprincipalsApi
  url: ../openapi/microsoft-entra-serviceprincipals-api-openapi.yml
  type: openapi
workflows:
- workflowId: grant-app-role-assignment
  summary: Grant an app role to a service principal, then verify assignments.
  description: >-
    Posts an app role assignment to a service principal and reads back its
    assignment collection to confirm the new grant.
  inputs:
    type: object
    required:
    - accessToken
    - servicePrincipalId
    - principalId
    - resourceId
    - appRoleId
    properties:
      accessToken:
        type: string
        description: OAuth 2.0 bearer token with AppRoleAssignment.ReadWrite.All.
      servicePrincipalId:
        type: string
        description: Object id of the service principal receiving the assignment.
      principalId:
        type: string
        description: Object id of the assignee (user, group, or service principal).
      resourceId:
        type: string
        description: Object id of the resource service principal exposing the role.
      appRoleId:
        type: string
        description: Id of the app role to grant (use all-zero GUID for default access).
        default: "00000000-0000-0000-0000-000000000000"
  steps:
  - stepId: grantAssignment
    description: >-
      Grant the app role assignment to the service principal, identifying the
      principal, resource, and role.
    operationId: grantServicePrincipalAppRoleAssignment
    parameters:
    - name: Authorization
      in: header
      value: "Bearer $inputs.accessToken"
    - name: servicePrincipal-id
      in: path
      value: $inputs.servicePrincipalId
    requestBody:
      contentType: application/json
      payload:
        principalId: $inputs.principalId
        resourceId: $inputs.resourceId
        appRoleId: $inputs.appRoleId
    successCriteria:
    - condition: $statusCode == 201
    outputs:
      assignmentId: $response.body#/id
  - stepId: listAssignments
    description: >-
      List the app role assignments granted to this service principal to
      confirm the new assignment is present.
    operationId: listServicePrincipalAppRoleAssignments
    parameters:
    - name: Authorization
      in: header
      value: "Bearer $inputs.accessToken"
    - name: servicePrincipal-id
      in: path
      value: $inputs.servicePrincipalId
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      assignments: $response.body#/value
  outputs:
    assignmentId: $steps.grantAssignment.outputs.assignmentId
    assignments: $steps.listAssignments.outputs.assignments