id: microsoft_entra_id
name: Microsoft Entra ID
version: 1.0.0
description: "Microsoft Entra ID (Microsoft Graph, users) — identity response and lifecycle: look up/list users, create/update/delete, disable and re-enable accounts, revoke sign-in sessions, force password reset, and read groups, manager and authentication methods. Azure AD OAuth 2.0 client-credentials authentication. Stdlib-only, no extra Python dependencies."
changelog: "1.0.0 — Initial release: user get/list/create/update/delete, account disable/enable, session revocation, password reset, and group/manager/auth-method reads."
category: identity

# Per-instance configuration. Register an Azure AD application, grant it the
# Microsoft Graph application permissions (User.ReadWrite.All, Group.Read.All,
# User.RevokeSessions.All, UserAuthenticationMethod.Read.All, Directory.Read.All)
# and admin-consent them. The scripts request a Microsoft Graph token
# (client-credentials) and call https://graph.microsoft.com/v1.0.
config_schema:
  properties:
    tenant_id:
      type: string
      description: "Azure AD tenant (directory) ID"
    client_id:
      type: string
      description: "Application (client) ID"
    client_secret:
      type: string
      description: "Client secret"
      x-soar-sensitive: true
  required:
    - tenant_id
    - client_id
    - client_secret

# Every command that targets a user accepts user_id — the object ID or the
# userPrincipalName (email) of the account.
commands:
  - id: list_users
    name: microsoft-entra-id-list-users
    description: "List directory users, optionally filtered."
    risk: read
    inputs_schema:
      properties:
        filter: { type: string, description: "OData $filter (e.g. startswith(displayName,'A'))" }
        search: { type: string, description: "Free-text $search (e.g. displayName:john)" }
        limit: { type: number, description: "Maximum users (default 50)" }
      required: []
    outputs_schema: { properties: {} }
  - id: get_user
    name: microsoft-entra-id-get-user
    description: "Get a user's profile by object ID or userPrincipalName."
    risk: read
    inputs_schema:
      properties:
        user_id: { type: string, description: "User object ID or userPrincipalName" }
      required: [user_id]
    outputs_schema: { properties: {} }
  - id: create_user
    name: microsoft-entra-id-create-user
    description: "Create a user account."
    inputs_schema:
      properties:
        user_principal_name: { type: string, description: "userPrincipalName (email), e.g. jdoe@contoso.com" }
        display_name: { type: string, description: "Display name" }
        mail_nickname: { type: string, description: "Mail nickname (defaults to the UPN local part)" }
        password: { type: string, description: "Initial password" }
        force_change_password: { type: boolean, description: "Require a password change at next sign-in (default true)" }
        account_enabled: { type: boolean, description: "Whether the account is enabled (default true)" }
        given_name: { type: string, description: "First name" }
        surname: { type: string, description: "Last name" }
        job_title: { type: string, description: "Job title" }
        department: { type: string, description: "Department" }
      required: [user_principal_name, display_name, password]
    outputs_schema: { properties: {} }
  - id: update_user
    name: microsoft-entra-id-update-user
    description: "Update a user's profile fields."
    inputs_schema:
      properties:
        user_id: { type: string, description: "User object ID or userPrincipalName" }
        display_name: { type: string, description: "Display name" }
        given_name: { type: string, description: "First name" }
        surname: { type: string, description: "Last name" }
        job_title: { type: string, description: "Job title" }
        department: { type: string, description: "Department" }
        mobile_phone: { type: string, description: "Mobile phone" }
        fields_json: { type: string, description: "Raw Graph user fields as a JSON object (advanced; merged last)" }
      required: [user_id]
    outputs_schema: { properties: {} }
  - id: delete_user
    name: microsoft-entra-id-delete-user
    description: "Delete a user account."
    inputs_schema:
      properties:
        user_id: { type: string, description: "User object ID or userPrincipalName" }
      required: [user_id]
    outputs_schema: { properties: {} }
  - id: disable_account
    name: microsoft-entra-id-disable-account
    description: "Disable a user account (accountEnabled = false)."
    inputs_schema:
      properties:
        user_id: { type: string, description: "User object ID or userPrincipalName" }
      required: [user_id]
    outputs_schema: { properties: {} }
  - id: enable_account
    name: microsoft-entra-id-enable-account
    description: "Re-enable a user account (accountEnabled = true)."
    inputs_schema:
      properties:
        user_id: { type: string, description: "User object ID or userPrincipalName" }
      required: [user_id]
    outputs_schema: { properties: {} }
  - id: revoke_sessions
    name: microsoft-entra-id-revoke-sessions
    description: "Revoke all refresh tokens / sign-in sessions for a user (forces re-authentication)."
    inputs_schema:
      properties:
        user_id: { type: string, description: "User object ID or userPrincipalName" }
      required: [user_id]
    outputs_schema: { properties: {} }
  - id: reset_password
    name: microsoft-entra-id-reset-password
    description: "Set a user's password (optionally forcing a change at next sign-in)."
    inputs_schema:
      properties:
        user_id: { type: string, description: "User object ID or userPrincipalName" }
        password: { type: string, description: "New password" }
        force_change: { type: boolean, description: "Require a change at next sign-in (default true)" }
      required: [user_id, password]
    outputs_schema: { properties: {} }
  - id: get_user_groups
    name: microsoft-entra-id-get-user-groups
    description: "List the groups a user is a member of."
    risk: read
    inputs_schema:
      properties:
        user_id: { type: string, description: "User object ID or userPrincipalName" }
        limit: { type: number, description: "Maximum groups (default 50)" }
      required: [user_id]
    outputs_schema: { properties: {} }
  - id: get_user_manager
    name: microsoft-entra-id-get-user-manager
    description: "Get a user's manager."
    risk: read
    inputs_schema:
      properties:
        user_id: { type: string, description: "User object ID or userPrincipalName" }
      required: [user_id]
    outputs_schema: { properties: {} }
  - id: assign_manager
    name: microsoft-entra-id-assign-manager
    description: "Set a user's manager."
    inputs_schema:
      properties:
        user_id: { type: string, description: "User object ID or userPrincipalName" }
        manager_id: { type: string, description: "Manager's user object ID or userPrincipalName" }
      required: [user_id, manager_id]
    outputs_schema: { properties: {} }
  - id: get_auth_methods
    name: microsoft-entra-id-get-auth-methods
    description: "List a user's registered authentication methods."
    risk: read
    inputs_schema:
      properties:
        user_id: { type: string, description: "User object ID or userPrincipalName" }
      required: [user_id]
    outputs_schema: { properties: {} }

  - id: test_connection
    name: microsoft-entra-id-test-connection
    description: "Verify connectivity and credentials (used by the Test button)."
    risk: read
    inputs_schema:
      properties: {}
      required: []
    outputs_schema: { properties: {} }