Compartir a través de

Creación de definiciones

  • Artículo

Espacio de nombres: microsoft.graph

Importante

Las API de la versión /beta de Microsoft Graph están sujetas a cambios. No se admite el uso de estas API en aplicaciones de producción. Para determinar si una API está disponible en la versión 1.0, use el selector de Versión.

Cree un nuevo objeto accessReviewScheduleDefinition .

Esta API está disponible en las siguientes implementaciones nacionales de nube.

Servicio global Gobierno de EE. UU. L4 Us Government L5 (DOD) China operada por 21Vianet
✅ ✅ ✅ ❌

Permissions

Elija el permiso o los permisos marcados como con privilegios mínimos para esta API. Use un permiso o permisos con privilegios superiores solo si la aplicación lo requiere. Para obtener más información sobre los permisos delegados y de aplicación, consulte Tipos de permisos. Para obtener más información sobre estos permisos, consulte la referencia de permisos.

Tipo de permiso Permisos con privilegios mínimos Permisos con privilegios más altos
Delegado (cuenta profesional o educativa) AccessReview.ReadWrite.All No disponible.
Delegado (cuenta personal de Microsoft) No admitida. No admitida.
Aplicación AccessReview.ReadWrite.All No disponible.

Importante

En escenarios delegados con cuentas profesionales o educativas, al usuario que ha iniciado sesión se le debe asignar un rol de Microsoft Entra compatible o un rol personalizado con un permiso de rol admitido. Se admiten los siguientes roles con privilegios mínimos para esta operación.

  • Para escribir revisiones de acceso de un grupo o aplicación: Administrador de usuarios, Administrador de gobernanza de identidades
  • Para escribir revisiones de acceso de un rol de Microsoft Entra: Administrador de gobernanza de identidades, Administrador de roles con privilegios

Solicitud HTTP

POST /identityGovernance/accessReviews/definitions

Encabezados de solicitud

Nombre Descripción
Authorization {token} de portador. Obligatorio. Obtenga más información sobre la autenticación y la autorización.
Tipo de contenido application/json. Obligatorio.

Cuerpo de la solicitud

En el cuerpo de la solicitud, proporcione una representación JSON de un objeto accessReviewScheduleDefinition .

En la tabla siguiente se muestran las propiedades aceptadas para crear un accessReview.

Propiedad Tipo Descripción
additionalNotificationRecipients colección accessReviewNotificationRecipientItem Define la lista de usuarios o miembros de grupo adicionales a los que se va a notificar el progreso de la revisión de acceso.
descriptionForAdmins Cadena Contexto de la revisión proporcionada a los administradores. Obligatorio.
descriptionForReviewers Cadena Contexto de la revisión proporcionada a los revisores en las notificaciones por correo electrónico. Email notificaciones admiten hasta 256 caracteres. Obligatorio.
displayName Cadena Nombre de la serie de revisión de acceso. Obligatorio.
fallbackReviewers colección accessReviewReviewerScope Si se proporciona, se pide a los revisores de reserva que completen una revisión si los revisores principales no existen. Por ejemplo, si los administradores se seleccionan como reviewers y una entidad de seguridad en revisión no tiene un administrador en Microsoft Entra ID, se pide a los revisores de reserva que revisen esa entidad de seguridad.

NOTA: El valor de esta propiedad se omitirá si los revisores de reserva se asignan a través de la propiedad stageSettings .
instanceEnumerationScope accessReviewScope En el caso de una revisión de todos los grupos, esto determina el ámbito de los grupos que se revisarán. Consulte accessReviewScope y obtenga información sobre cómo configurar el ámbito de la definición de revisión de acceso.
Revisores colección accessReviewReviewerScope Define quiénes son los revisores. Si no se especifica ninguno, la revisión es una revisión automática (los usuarios revisan su propio acceso). Para obtener ejemplos de opciones para asignar revisores, consulte Asignación de revisores a la definición de revisión de acceso mediante microsoft Graph API.

NOTA: El valor de esta propiedad se omitirá si los revisores se asignan a través de la propiedad stageSettings .
ámbito accessReviewScope Define las entidades cuyo acceso se revisa. Consulte accessReviewScope y obtenga información sobre cómo configurar el ámbito de la definición de revisión de acceso. Obligatorio.
stageSettings colección accessReviewStageSettings Define cuántas fases tendrá cada instancia de una serie de revisión de acceso. Las fases se crearán secuencialmente en función de la propiedad dependsOn. Cada fase puede tener un conjunto diferente de revisores, revisores de reserva y configuración.

Cuando se define esta propiedad, se usan sus valores en lugar de los valores correspondientes en el objeto accessReviewScheduleDefinition y su propiedad settings . Opcional.
configuración accessReviewScheduleSettings La configuración de una serie de revisión de acceso. La periodicidad se determina aquí. Vea accessReviewScheduleSettings.
backupReviewers (en desuso) colección accessReviewReviewerScope Esta propiedad se ha reemplazado por fallbackReviewers. Sin embargo, al especificar backupReviewers o fallbackReviewers se rellenan automáticamente los mismos valores en la otra propiedad.

Respuesta

Si se ejecuta correctamente, este método devuelve un 201 Created código de respuesta y un objeto accessReviewScheduleDefinition en el cuerpo de la respuesta.

Ejemplos

Ejemplo 1: Creación de una revisión de acceso en un grupo

En el ejemplo siguiente se crea una revisión de acceso con la siguiente configuración:

  • La revisión revisa todos los miembros de un grupo con el identificador02f3bafb-448c-487c-88c2-5fd65ce49a41.
  • Un usuario específico con el identificador398164b1-5196-49dd-ada2-364b49f99b27 de usuario es el revisor.
  • Se repite semanalmente y continúa indefinidamente.

Solicitud

POST https://graph.microsoft.com/beta/identityGovernance/accessReviews/definitions
Content-type: application/json

{
  "displayName": "Test create",
  "descriptionForAdmins": "New scheduled access review",
  "descriptionForReviewers": "If you have any questions, contact jerry@contoso.com",
  "scope": {
    "@odata.type": "#microsoft.graph.accessReviewQueryScope",
    "query": "/groups/02f3bafb-448c-487c-88c2-5fd65ce49a41/transitiveMembers",
    "queryType": "MicrosoftGraph"
  },
  "reviewers": [
    {
      "query": "/users/398164b1-5196-49dd-ada2-364b49f99b27",
      "queryType": "MicrosoftGraph"
    }
  ],  
  "settings": {
    "mailNotificationsEnabled": true,
    "reminderNotificationsEnabled": true,
    "justificationRequiredOnApproval": true,
    "defaultDecisionEnabled": false,
    "defaultDecision": "None",
    "instanceDurationInDays": 1,
    "recommendationsEnabled": true,
    "recurrence": {
      "pattern": {
        "type": "weekly",
        "interval": 1
      },
      "range": {
        "type": "noEnd",
        "startDate": "2020-09-08T12:02:30.667Z"
      }
    }
  }
}

Respuesta

Nota: Se puede acortar el objeto de respuesta que se muestra aquí para mejorar la legibilidad.

HTTP/1.1 201 Created
Content-type: application/json

{
  "id": "29f2d16e-9ca6-4052-bbfe-802c48944448",
  "displayName": "Test create",
  "createdDateTime": "0001-01-01T00:00:00Z",
  "lastModifiedDateTime": "0001-01-01T00:00:00Z",
  "status": "NotStarted",
  "descriptionForAdmins": "Test create",
  "descriptionForReviewers": "Test create",
  "instanceEnumerationScope": null,
  "createdBy": {
    "id": "957f1027-c0ee-460d-9269-b8444459e0fe",
    "displayName": "MOD Administrator",
    "userPrincipalName": "admin@contoso.com"
  },
  "scope": {
    "@odata.type": "#microsoft.graph.accessReviewQueryScope",
    "query": "/groups/b74444cb-038a-4802-8fc9-b9d1ed0cf11f/transitiveMembers",
    "queryType": "MicrosoftGraph"
  },
  "reviewers": [
    {
      "query": "/users/7eae986b-d425-48b2-adf2-3c777f4444f3",
      "queryType": "MicrosoftGraph",
      "queryRoot": "decisions"
    }
  ],  
  "settings": {
    "mailNotificationsEnabled": true,
    "reminderNotificationsEnabled": true,
    "justificationRequiredOnApproval": true,
    "defaultDecisionEnabled": false,
    "defaultDecision": "None",
    "instanceDurationInDays": 1,
    "autoApplyDecisionsEnabled": false,
    "recommendationsEnabled": true,
    "recurrence": {
      "pattern": {
        "type": "weekly",
        "interval": 1,
        "month": 0,
        "dayOfMonth": 0,
        "daysOfWeek": [],
        "firstDayOfWeek": "sunday",
        "index": "first"
      },
      "range": {
        "type": "noEnd",
        "numberOfOccurrences": 0,
        "recurrenceTimeZone": null,
        "startDate": "2020-09-08",
        "endDate": null
      }
    },
  "applyActions": []
  },
  "additionalNotificationRecipients": []
}

Ejemplo 2: Creación de una revisión de acceso en todos los equipos con usuarios invitados inactivos

En el ejemplo siguiente se crea una revisión de acceso con la siguiente configuración:

  • La revisión revisa todos los equipos con usuarios invitados inactivos. El período de inactividad es de 30 días a partir de la fecha de inicio de la revisión de acceso.
  • Los propietarios del grupo son los revisores y se asignan los revisores de reserva.
  • Se repite el tercer día de cada trimestre y continúa indefinidamente.
  • autoApplyDecisionsEnabled se establece en true con defaultDecision establecido en Deny.

Solicitud

En el cuerpo de la solicitud, proporcione una representación JSON del objeto accessReviewScheduleDefinition .

POST https://graph.microsoft.com/beta/identityGovernance/accessReviews/definitions
Content-type: application/json

{
  "displayName": "Review inactive guests on teams",
  "descriptionForAdmins": "Control guest user access to our teams.",
  "descriptionForReviewers": "Information security is everyone's responsibility. Review our access policy for more.",
  "instanceEnumerationScope": {
    "@odata.type": "#microsoft.graph.accessReviewQueryScope",
    "query": "/groups?$filter=(groupTypes/any(c:c+eq+'Unified') and resourceProvisioningOptions/Any(x:x eq 'Team')')",
    "queryType": "MicrosoftGraph"
  },
  "scope": {
    "@odata.type": "#microsoft.graph.accessReviewInactiveUsersQueryScope",
    "query": "./members/microsoft.graph.user/?$filter=(userType eq 'Guest')",
    "queryType": "MicrosoftGraph",
    "inactiveDuration": "P30D"
    },
  "reviewers": [
    {
      "query": "./owners",
      "queryType": "MicrosoftGraph"
    }
  ],
  "fallbackReviewers": [
    {
      "query": "/users/fc9a2c2b-1ddc-486d-a211-5fe8ca77fa1f",
      "queryType": "MicrosoftGraph"
    }
  ],
  "settings": {
    "mailNotificationsEnabled": true,
    "reminderNotificationsEnabled": true,
    "justificationRequiredOnApproval": true,
    "recommendationsEnabled": true,
    "instanceDurationInDays": 3,
    "recurrence": {
      "pattern": {
        "type": "absoluteMonthly",
        "dayOfMonth": 5,
        "interval": 3
      },
      "range": {
        "type": "noEnd",
        "startDate": "2020-05-04T00:00:00.000Z"
      }
    },
    "defaultDecisionEnabled": true,
    "defaultDecision": "Deny",
    "autoApplyDecisionsEnabled": true
  }
}

Respuesta

Nota: Se puede acortar el objeto de respuesta que se muestra aquí para mejorar la legibilidad.

HTTP/1.1 201 Created
Content-type: application/json

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#identityGovernance/accessReviews/definitions/$entity",
  "id": "b0966e21-a01e-43c9-8f8b-9ba30ed5710a",
  "displayName": "Review inactive guests on teams",
  "createdDateTime": "2021-05-04T18:27:02.6719849Z",
  "lastModifiedDateTime": "2021-05-04T18:27:24.0889623Z",
  "status": "InProgress",
  "descriptionForAdmins": "Control guest user access to our teams.",
  "descriptionForReviewers": "Information security is everyone's responsibility. Review our access policy for more.",
  "createdBy": {
    "id": "fc9a2c2b-1ddc-486d-a211-5fe8ca77fa1f",
    "displayName": "MOD Administrator",
    "userPrincipalName": "admin@contoso.com"
  },
  "scope": {
    "@odata.type": "#microsoft.graph.accessReviewInactiveUsersQueryScope",
    "query": "./members/microsoft.graph.user/?$count=true&$filter=(userType eq 'Guest')",
    "queryType": "MicrosoftGraph",
    "queryRoot": null,
    "inactiveDuration": "P30D"
  },
  "instanceEnumerationScope": {
    "@odata.type": "#microsoft.graph.accessReviewQueryScope",
    "query": "/groups?$filter=(groupTypes/any(c:c+eq+'Unified') and resourceProvisioningOptions/Any(x:x eq 'Team'))&$count=true",
    "queryType": "MicrosoftGraph",
    "queryRoot": null
  },
  "reviewers": [
    {
      "query": "./owners",
      "queryType": "MicrosoftGraph",
      "queryRoot": null
    }
  ],
  "backupReviewers": [],
  "fallbackReviewers": [
    {
      "query": "/users/fc9a2c2b-1ddc-486d-a211-5fe8ca77fa1f",
      "queryType": "MicrosoftGraph",
      "queryRoot": null
    }
  ],
  "settings": {
    "mailNotificationsEnabled": true,
    "reminderNotificationsEnabled": true,
    "justificationRequiredOnApproval": true,
    "defaultDecisionEnabled": true,
    "defaultDecision": "Deny",
    "instanceDurationInDays": 3,
    "autoApplyDecisionsEnabled": true,
    "recommendationsEnabled": true,
    "recurrence": {
      "pattern": {
        "type": "absoluteMonthly",
        "interval": 3,
        "month": 0,
        "dayOfMonth": 5,
        "daysOfWeek": [],
        "firstDayOfWeek": "sunday",
        "index": "first"
      },
      "range": {
        "type": "noEnd",
        "numberOfOccurrences": 0,
        "recurrenceTimeZone": null,
        "startDate": "2021-05-05",
        "endDate": null
      }
    },
    "applyActions": []
  },
  "additionalNotificationRecipients": []
}

Ejemplo 3: Creación de una revisión de acceso de todos los usuarios a una aplicación

En el ejemplo siguiente se crea una revisión de acceso con la siguiente configuración:

  • La revisión revisa el acceso de los usuarios a una aplicación.
  • Los administradores de personas son los revisores y los revisores de reserva son miembros de un grupo.
  • Se repite semestralmente y finaliza 1 año a partir de startDate.

Solicitud

POST https://graph.microsoft.com/beta/identityGovernance/accessReviews/definitions
Content-type: application/json

{
  "displayName": "Review employee access to LinkedIn",
  "descriptionForAdmins": "Review employee access to LinkedIn",
  "scope": {
    "@odata.type": "#microsoft.graph.principalResourceMembershipsScope",
    "principalScopes": [
      {
        "@odata.type": "#microsoft.graph.accessReviewQueryScope",
        "query": "/users",
        "queryType": "MicrosoftGraph"
      }
    ],
    "resourceScopes": [
      {
        "@odata.type": "#microsoft.graph.accessReviewQueryScope",
        "query": "/servicePrincipals/bae11f90-7d5d-46ba-9f55-8112b59d92ae",
        "queryType": "MicrosoftGraph"
      }
    ]
  },
  "reviewers": [
    {
      "query": "./manager",
      "queryType": "MicrosoftGraph",
      "queryRoot": "decisions"
    }
  ],
  "backupReviewers": [
    {
      "query": "/groups/072ac5f4-3f13-4088-ab30-0a276f3e6322/transitiveMembers",
      "queryType": "MicrosoftGraph"
    }
  ],
  "fallbackReviewers": [
    {
      "query": "/groups/072ac5f4-3f13-4088-ab30-0a276f3e6322/transitiveMembers",
      "queryType": "MicrosoftGraph"
    }
  ],
  "settings": {
    "mailNotificationsEnabled": true,
    "reminderNotificationsEnabled": true,
    "justificationRequiredOnApproval": true,
    "defaultDecisionEnabled": true,
    "defaultDecision": "Recommendation",
    "instanceDurationInDays": 180,
    "autoApplyDecisionsEnabled": true,
    "recommendationsEnabled": true,
    "recurrence": {
      "pattern": {
        "type": "absoluteMonthly",
        "interval": 6,
        "dayOfMonth": 0
      },
      "range": {
        "type": "numbered",
        "startDate": "2021-05-05",
        "endDate": "2022-05-05"
      }
    }
  }
}

Respuesta

Nota: Se puede acortar el objeto de respuesta que se muestra aquí para mejorar la legibilidad.

HTTP/1.1 201 Created
Content-type: application/json

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#identityGovernance/accessReviews/definitions/$entity",
  "id": "1f79f34b-8667-40d9-875c-893b630b3dec",
  "scope": {
    "@odata.type": "#microsoft.graph.principalResourceMembershipsScope",
    "principalScopes": [
      {
        "@odata.type": "#microsoft.graph.accessReviewQueryScope",
        "query": "/users"
      }
    ],
    "resourceScopes": [
      {
        "@odata.type": "#microsoft.graph.accessReviewQueryScope",
        "query": "/servicePrincipals/bae11f90-7d5d-46ba-9f55-8112b59d92ae"
      }
    ]
  },
  "reviewers": [
    {
      "query": "./manager"
    }
  ],
  "fallbackReviewers": [
    {
      "query": "/groups/072ac5f4-3f13-4088-ab30-0a276f3e6322/transitiveMembers"
    }
  ]
}

Ejemplo 4: Creación de una revisión de acceso en un grupo con varias fases

En el ejemplo siguiente se crea una revisión de acceso con la siguiente configuración:

  • La revisión revisa todos los miembros de un grupo con el identificador02f3bafb-448c-487c-88c2-5fd65ce49a41.
  • Tiene dos fases:
    • Un usuario específico con el identificador398164b1-5196-49dd-ada2-364b49f99b27 de usuario es el revisor de la primera fase.
    • Los administradores de personas son los revisores y revisores de reserva de la segunda fase.
  • Se repite semanalmente y continúa indefinidamente.

Solicitud

POST https://graph.microsoft.com/beta/identityGovernance/accessReviews/definitions
Content-type: application/json

{
  "displayName": "Group Multi-stage Access Review",
  "descriptionForAdmins": "New scheduled access review",
  "descriptionForReviewers": "If you have any questions, contact jerry@contoso.com",
  "scope": {
    "@odata.type": "#microsoft.graph.accessReviewQueryScope",
    "query": "/groups/02f3bafb-448c-487c-88c2-5fd65ce49a41/transitiveMembers",
    "queryType": "MicrosoftGraph"
  },
  "stageSettings": [
    {
      "stageId": "1",
      "durationInDays": 2,
      "recommendationsEnabled": false,
      "decisionsThatWillMoveToNextStage": [
          "NotReviewed",
          "Approve"
      ],
      "reviewers": [
        {
          "query": "/users/398164b1-5196-49dd-ada2-364b49f99b27",
          "queryType": "MicrosoftGraph"
        }
      ]
    },
    {
      "stageId": "2",
      "dependsOn": [
          "1"
      ],
      "durationInDays": 2,
      "recommendationsEnabled": true,
      "reviewers": [
        {
          "query": "./manager",
          "queryType": "MicrosoftGraph",
          "queryRoot": "decisions"
        }
      ],
      "fallbackReviewers": [
        {
          "query": "/groups/072ac5f4-3f13-4088-ab30-0a276f3e6322/transitiveMembers",
          "queryType": "MicrosoftGraph"
        }
      ]
    }
  ],
  "settings": {
    "instanceDurationInDays": 4,
    "recurrence": {
      "pattern": {
        "type": "weekly",
        "interval": 1
      },
      "range": {
        "type": "noEnd",
        "startDate": "2020-09-08T12:02:30.667Z"
      }
    },
    "decisionHistoriesForReviewersEnabled": true
  }
}

Respuesta

Nota: Se puede acortar el objeto de respuesta que se muestra aquí para mejorar la legibilidad.

HTTP/1.1 201 Created
Content-type: application/json

{
  "id": "29f2d16e-9ca6-4052-bbfe-802c48944448",
  "displayName": "Group Multi-stage Access Review",
  "createdBy": {
    "id": "957f1027-c0ee-460d-9269-b8444459e0fe"
  },
  "scope": {
    "@odata.type": "#microsoft.graph.accessReviewQueryScope",
    "query": "/groups/b74444cb-038a-4802-8fc9-b9d1ed0cf11f/transitiveMembers"
  },
  "stageSettings": [
    {
      "stageId": "1",
      "durationInDays": 2,
      "recommendationsEnabled": false,
      "decisionsThatWillMoveToNextStage": [
          "NotReviewed",
          "Approve"
      ],
      "reviewers": [
        {
          "query": "/users/398164b1-5196-49dd-ada2-364b49f99b27",
          "queryType": "MicrosoftGraph"
        }
      ]
    },
    {
      "stageId": "2",
      "dependsOn": [
          "1"
      ],
      "durationInDays": 2,
      "recommendationsEnabled": true,
      "reviewers": [
        {
          "query": "./manager",
          "queryType": "MicrosoftGraph",
          "queryRoot": "decisions"
        }
      ],
      "fallbackReviewers": [
        {
          "query": "/groups/072ac5f4-3f13-4088-ab30-0a276f3e6322/transitiveMembers",
          "queryType": "MicrosoftGraph"
        }
      ]
    }
  ]
}

Ejemplo 5: Creación de una revisión de acceso en un grupo con información sobre la afiliación de usuario a grupo e inicio de sesión de usuario para obtener recomendaciones

En el ejemplo siguiente se crea una revisión de acceso con la siguiente configuración:

  • La revisión revisa todos los miembros de un grupo con el identificador02f3bafb-448c-487c-88c2-5fd65ce49a41.
  • Un usuario específico con el identificador398164b1-5196-49dd-ada2-364b49f99b27 de usuario es el revisor.
  • Se repite semanalmente y continúa indefinidamente.
  • Tanto la afiliación de usuario a grupo como el inicio de sesión de usuario son conclusiones para los revisores.

Solicitud

POST https://graph.microsoft.com/beta/identityGovernance/accessReviews/definitions
Content-type: application/json

{
    "displayName": "Test create",
    "descriptionForAdmins": "New scheduled access review",
    "descriptionForReviewers": "If you have any questions, contact jerry@contoso.com",
    "scope": {
        "@odata.type": "#microsoft.graph.accessReviewQueryScope",
        "query": "/groups/02f3bafb-448c-487c-88c2-5fd65ce49a41/transitiveMembers",
        "queryType": "MicrosoftGraph"
    },
    "reviewers": [
        {
            "query": "/users/398164b1-5196-49dd-ada2-364b49f99b27",
            "queryType": "MicrosoftGraph"
        }
    ],
    "settings": {
        "instanceDurationInDays": 1,
        "recurrence": {
            "pattern": {
                "type": "weekly",
                "interval": 1
            },
            "range": {
                "type": "noEnd",
                "startDate": "2020-09-08T12:02:30.667Z"
            }
        },
        "recommendationInsightSettings": [
            {
                "@odata.type": "#microsoft.graph.userLastSignInRecommendationInsightSetting",
                "recommendationLookBackDuration": "P30D",
                "signInScope": "tenant"
            },
            {
                "@odata.type": "#microsoft.graph.groupPeerOutlierRecommendationInsightSettings"
            }
        ]
    }
}

Respuesta

Nota: Se puede acortar el objeto de respuesta que se muestra aquí para mejorar la legibilidad.

HTTP/1.1 201 Created
Content-type: application/json

{
  "id": "29f2d16e-9ca6-4052-bbfe-802c48944448",
  "displayName": "Test create",
  "createdBy": {
    "id": "957f1027-c0ee-460d-9269-b8444459e0fe"
  },
  "scope": {
    "@odata.type": "#microsoft.graph.accessReviewQueryScope",
    "query": "/groups/b74444cb-038a-4802-8fc9-b9d1ed0cf11f/transitiveMembers"
  },
  "reviewers": [
    {
      "query": "/users/7eae986b-d425-48b2-adf2-3c777f4444f3"
    }
  ],
  "settings": {
    "recommendationInsightSettings": [
      {
        "@odata.type": "#microsoft.graph.userLastSignInRecommendationInsightSetting",
        "recommendationLookBackDuration": "P30D",
        "signInScope": "tenant"
      },
      {
        "@odata.type": "#microsoft.graph.groupPeerOutlierRecommendationInsightSettings"
      }
    ]
  }
}