Compartir a través de


Concesión o revocación de permisos de API mediante programación

Al conceder permisos de API a una aplicación cliente en Microsoft Entra ID, las concesiones de permisos se registran como objetos a los que se puede acceder, actualizar o eliminar como cualquier otro dato. El uso de Microsoft Graph para crear directamente concesiones de permisos es una alternativa mediante programación al consentimiento interactivo y puede ser útil para escenarios de automatización, administración masiva u otras operaciones personalizadas en su organización.

En este artículo, aprenderá a conceder y revocar roles de aplicación para una aplicación mediante Microsoft Graph. Los roles de aplicación, también denominados permisos de aplicación o permisos de acceso directo, permiten a una aplicación llamar a una API con su propia identidad. Obtenga más información sobre los permisos de aplicación.

Precaución

¡Ten cuidado! Los permisos concedidos mediante programación no están sujetos a revisión ni confirmación. Surten efecto inmediatamente.

Requisitos previos

Para completar estas instrucciones, necesita los siguientes recursos y privilegios:

  • Un inquilino de Microsoft Entra válido.
  • Las solicitudes se ejecutan en este artículo en un contexto delegado. Debe completar los pasos siguientes:
    • Inicie sesión en un cliente de API, como Graph Explorer , como un usuario con privilegios para crear aplicaciones en el inquilino. Los privilegios para crear concesiones de permisos pueden estar limitados o controlados en el inquilino a través de directivas de consentimiento de aplicaciones configuradas por el administrador.
    • En la aplicación en la que ha iniciado sesión, dé su consentimiento a los permisos delegados Application.Read.All y AppRoleAssignment.ReadWrite.All en nombre del usuario que ha iniciado sesión. No es necesario dar su consentimiento en nombre de su organización.
    • Obtenga el identificador de objeto de la entidad de servicio de cliente a la que concede roles de aplicación. En este artículo, la entidad de servicio de cliente se identifica mediante el identificador b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94. En el Centro de administración de Microsoft Entra, expanda el menú >Identidad, expanda Aplicaciones>, seleccione Aplicaciones empresariales>Aplicaciones de aplicaciones para buscar la entidad de servicio cliente. Selecciónelo y, en la página Información general , copie el valor de Id. de objeto.

Precaución

Solo los usuarios adecuados deben tener acceso a las aplicaciones a las que se les ha concedido el permiso AppRoleAssignment.ReadWrite.All .

Paso 1: Obtener los appRoles de la entidad de servicio de recursos

Para poder conceder roles de aplicación, primero debe identificar la entidad de servicio de recursos que expone los roles de aplicación que desea conceder. Los roles de aplicación se definen en el objeto appRoles de una entidad de servicio. En este artículo, usará la entidad de servicio de Microsoft Graph en el inquilino como entidad de servicio de recursos.

Solicitud

En la solicitud siguiente se recuperan los roles de aplicación definidos por la entidad de servicio de Microsoft Graph en el inquilino.

GET https://graph.microsoft.com/v1.0/servicePrincipals?$filter=displayName eq 'Microsoft Graph'&$select=id,displayName,appId,appRoles

Respuesta

En el ejemplo siguiente se muestra la 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/v1.0/$metadata#servicePrincipals(id,displayName,appId,appRoles)",
    "value": [
        {
            "id": "7ea9e944-71ce-443d-811c-71e8047b557a",
            "displayName": "Microsoft Graph",
            "appId": "00000003-0000-0000-c000-000000000000",
            "appRoles": [
                {
                    "allowedMemberTypes": [
                        "Application"
                    ],
                    "description": "Allows the app to read user profiles without a signed in user.",
                    "displayName": "Read all users' full profiles",
                    "id": "df021288-bdef-4463-88db-98f22de89214",
                    "isEnabled": true,
                    "origin": "Application",
                    "value": "User.Read.All"
                }
            ]
        }
    ]
}

Paso 2: Concesión de un rol de aplicación a una entidad de servicio cliente

En este paso, concederá a la aplicación un rol de aplicación expuesto por Microsoft Graph, lo que dará lugar a una asignación de roles de aplicación. En el paso 1, el identificador de objeto de Microsoft Graph es 7ea9e944-71ce-443d-811c-71e8047b557a y el rol User.Read.All de aplicación se identifica mediante el identificador df021288-bdef-4463-88db-98f22de89214.

Solicitud

La siguiente solicitud concede a la aplicación cliente (la entidad de identidad b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94) un rol de id df021288-bdef-4463-88db-98f22de89214 . de aplicación que expone una entidad de servicio de recursos de ID 7ea9e944-71ce-443d-811c-71e8047b557a.

Nota:

Si usa el SDK de Python, importe las siguientes bibliotecas:

from msgraph.generated.models.app_role_assignment import AppRoleAssignment
from msgraph.generated.models.service_principal import ServicePrincipal
POST https://graph.microsoft.com/v1.0/servicePrincipals/7ea9e944-71ce-443d-811c-71e8047b557a/appRoleAssignedTo
Content-Type: application/json

{
    "principalId": "b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94",
    "resourceId": "7ea9e944-71ce-443d-811c-71e8047b557a",
    "appRoleId": "df021288-bdef-4463-88db-98f22de89214"
}

Respuesta

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#servicePrincipals('7ea9e944-71ce-443d-811c-71e8047b557a')/appRoleAssignedTo/$entity",
    "id": "47nZsM8O_UuNq5Jz3QValCxBBiqJea9Drc9CMK4Ru_M",
    "deletedDateTime": null,
    "appRoleId": "df021288-bdef-4463-88db-98f22de89214",
    "createdDateTime": "2022-05-18T15:37:21.8215423Z",
    "principalDisplayName": "My application",
    "principalId": "b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94",
    "principalType": "ServicePrincipal",
    "resourceDisplayName": "Microsoft Graph",
    "resourceId": "7ea9e944-71ce-443d-811c-71e8047b557a"
}

Confirmación de la asignación de roles de aplicación

Para comprobar las entidades de seguridad con asignaciones de roles a la entidad de servicio de recursos, ejecute la siguiente solicitud.

Solicitud

GET https://graph.microsoft.com/v1.0/servicePrincipals/7ea9e944-71ce-443d-811c-71e8047b557a/appRoleAssignedTo

Respuesta

El objeto de respuesta incluye una colección de asignaciones de roles de aplicación a la entidad de servicio de recursos e incluye la asignación de roles de aplicación que creó en la solicitud anterior.

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#servicePrincipals('7ea9e944-71ce-443d-811c-71e8047b557a')/appRoleAssignedTo",
    "value": [
        {
            "id": "47nZsM8O_UuNq5Jz3QValCxBBiqJea9Drc9CMK4Ru_M",
            "deletedDateTime": null,
            "appRoleId": "df021288-bdef-4463-88db-98f22de89214",
            "createdDateTime": "2022-05-18T15:37:21.8997216Z",
            "principalDisplayName": "My application",
            "principalId": "b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94",
            "principalType": "ServicePrincipal",
            "resourceDisplayName": "Microsoft Graph",
            "resourceId": "7ea9e944-71ce-443d-811c-71e8047b557a"
        }
    ]
}

Paso 3: Revocar una asignación de roles de aplicación de una entidad de servicio cliente

Solicitud

DELETE https://graph.microsoft.com/v1.0/servicePrincipals/7ea9e944-71ce-443d-811c-71e8047b557a/appRoleAssignedTo/47nZsM8O_UuNq5Jz3QValCxBBiqJea9Drc9CMK4Ru_M

Respuesta

HTTP/1.1 204 No Content

Conclusión

Ha aprendido a administrar las concesiones de roles de aplicación para una entidad de servicio. Este método de concesión de permisos mediante Microsoft Graph es un consentimiento interactivo alternativo y se debe usar con precaución.

En este artículo, aprenderá a conceder y revocar permisos delegados para una aplicación mediante Microsoft Graph. Los permisos delegados, también denominados ámbitos o permisos de OAuth2, permiten a una aplicación llamar a una API en nombre de un usuario que ha iniciado sesión. Obtenga más información sobre los permisos delegados.

Precaución

¡Ten cuidado! Los permisos concedidos mediante programación no están sujetos a revisión ni confirmación. Surten efecto inmediatamente.

Requisitos previos

Para completar estas instrucciones, necesita los siguientes recursos y privilegios:

  • Un inquilino de Microsoft Entra válido.
  • Las solicitudes se ejecutan en este artículo como usuario. Debe completar los pasos siguientes:
    • Inicie sesión en un cliente de API como Graph Explorer como usuario con el rol Microsoft Entra de administrador de aplicaciones en la nube, que es el rol con privilegios mínimos para crear aplicaciones y conceder consentimiento a permisos delegados en el inquilino. Los privilegios para crear concesiones de permisos pueden estar limitados o controlados en el inquilino a través de directivas de consentimiento de aplicaciones configuradas por el administrador.
    • En la aplicación en la que ha iniciado sesión, dé su consentimiento a los permisos delegados Application.Read.All, DelegatedPermissionGrant.ReadWrite.All en nombre del usuario que ha iniciado sesión. No es necesario dar su consentimiento en nombre de su organización.
    • Obtenga el identificador de objeto de la entidad de servicio de cliente a la que concede permisos delegados en nombre de un usuario. En este artículo, la entidad de servicio de cliente se identifica mediante el identificador b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94. En el Centro de administración de Microsoft Entra, expanda el menú >Identidad, expanda Aplicaciones>, seleccione Aplicaciones empresariales>Aplicaciones de aplicaciones para buscar la entidad de servicio cliente. Selecciónelo y, en la página Información general , copie el valor de Id. de objeto.

Precaución

Solo los usuarios adecuados deben tener acceso a las aplicaciones a las que se les ha concedido el permiso DelegatedPermissionGrant.ReadWrite.All .

Paso 1: Obtener los permisos delegados de la entidad de servicio de recursos

Para poder conceder permisos delegados, primero debe identificar la entidad de servicio de recursos que expone los permisos delegados que desea conceder. Los permisos delegados se definen en el objeto oauth2PermissionScopes de una entidad de servicio. En este artículo, usará la entidad de servicio de Microsoft Graph en el inquilino como entidad de servicio de recursos.

Solicitud

La siguiente solicitud recupera los permisos delegados definidos por la entidad de servicio de Microsoft Graph en el inquilino.

GET https://graph.microsoft.com/v1.0/servicePrincipals?$filter=displayName eq 'Microsoft Graph'&$select=id,displayName,appId,oauth2PermissionScopes

Respuesta

En el ejemplo siguiente se muestra la 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/v1.0/$metadata#servicePrincipals(id,displayName,appId,oauth2PermissionScopes)",
    "value": [
        {
            "id": "7ea9e944-71ce-443d-811c-71e8047b557a",
            "displayName": "Microsoft Graph",
            "appId": "00000003-0000-0000-c000-000000000000",
            "oauth2PermissionScopes": [
                {
                    "adminConsentDescription": "Allows the app to read the full set of profile properties, reports, and managers of other users in your organization, on behalf of the signed-in user.",
                    "adminConsentDisplayName": "Read all users' full profiles",
                    "id": "a154be20-db9c-4678-8ab7-66f6cc099a59",
                    "isEnabled": true,
                    "type": "Admin",
                    "userConsentDescription": "Allows the app to read the full set of profile properties, reports, and managers of other users in your organization, on your behalf.",
                    "userConsentDisplayName": "Read all users' full profiles",
                    "value": "User.Read.All"
                },
                {
                    "adminConsentDescription": "Allows the app to list groups, and to read their properties and all group memberships on behalf of the signed-in user.  Also allows the app to read calendar, conversations, files, and other group content for all groups the signed-in user can access. ",
                    "adminConsentDisplayName": "Read all groups",
                    "id": "5f8c59db-677d-491f-a6b8-5f174b11ec1d",
                    "isEnabled": true,
                    "type": "Admin",
                    "userConsentDescription": "Allows the app to list groups, and to read their properties and all group memberships on your behalf.  Also allows the app to read calendar, conversations, files, and other group content for all groups you can access.  ",
                    "userConsentDisplayName": "Read all groups",
                    "value": "Group.Read.All"
                }                
            ]
        }
    ]
}

Paso 2: Concesión de un permiso delegado a la entidad de servicio de cliente en nombre de un usuario

Solicitud

En este paso, concederá a la aplicación, en nombre de un usuario, un permiso delegado expuesto por Microsoft Graph, lo que da lugar a una concesión de permisos delegados.

  • En el paso 1, el identificador de objeto de Microsoft Graph en el inquilino es 7ea9e944-71ce-443d-811c-71e8047b557a
  • Los permisos User.Read.All delegados y Group.Read.All se identifican mediante los identificadores únicos globales a154be20-db9c-4678-8ab7-66f6cc099a59 y 5f8c59db-677d-491f-a6b8-5f174b11ec1d respectivamente.
  • La entidad de seguridad es un usuario identificado por el identificador 3fbd929d-8c56-4462-851e-0eb9a7b3a2a5.
  • La entidad de servicio de cliente se identifica mediante el identificador b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94. Este es el identificador de objeto de la entidad de servicio y no su appId.
POST https://graph.microsoft.com/v1.0/oauth2PermissionGrants
Content-Type: application/json

{
    "clientId": "b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94",
    "consentType": "Principal",
    "resourceId": "7ea9e944-71ce-443d-811c-71e8047b557a",
    "principalId": "3fbd929d-8c56-4462-851e-0eb9a7b3a2a5",
    "scope": "User.Read.All Group.Read.All"
}

Aunque la solicitud anterior concede consentimiento en nombre de un único usuario, puede optar por conceder el consentimiento en nombre de todos los usuarios del inquilino. El cuerpo de la solicitud es similar al cuerpo de la solicitud anterior, excepto con los siguientes cambios:

  • ConsentType es AllPrincipals, lo que indica que da su consentimiento en nombre de todos los usuarios del inquilino.
  • La propiedad principalId no se proporciona o puede ser null.

Un cuerpo de solicitud de ejemplo para conceder consentimiento en nombre de todos los usuarios es el siguiente:

POST https://graph.microsoft.com/v1.0/oauth2PermissionGrants
Content-Type: application/json

{
    "clientId": "b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94",
    "consentType": "AllPrincipals",
    "resourceId": "7ea9e944-71ce-443d-811c-71e8047b557a",
    "scope": "User.Read.All Group.Read.All"
}

Respuesta

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#oauth2PermissionGrants/$entity",
    "clientId": "b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94",
    "consentType": "Principal",
    "id": "47nZsM8O_UuNq5Jz3QValETpqX7OcT1EgRxx6AR7VXqdkr0_VoxiRIUeDrmns6Kl",
    "principalId": "3fbd929d-8c56-4462-851e-0eb9a7b3a2a5",
    "resourceId": "7ea9e944-71ce-443d-811c-71e8047b557a",
    "scope": "User.Read.All Group.Read.All"
}

Si concediera el consentimiento para todos los usuarios del inquilino, consentType en el objeto de respuesta sería AllPrincipalsy el principalId sería null.

Confirmación de la concesión de permisos

Para comprobar los permisos delegados asignados a la entidad de servicio en nombre del usuario, ejecute la siguiente solicitud.

Solicitud

GET https://graph.microsoft.com/v1.0/oauth2PermissionGrants?$filter=clientId eq 'b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94' and principalId eq '3fbd929d-8c56-4462-851e-0eb9a7b3a2a5' and consentType eq 'Principal'

Respuesta

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#oauth2PermissionGrants",
    "value": [
        {
            "clientId": "b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94",
            "consentType": "Principal",
            "id": "47nZsM8O_UuNq5Jz3QValETpqX7OcT1EgRxx6AR7VXqdkr0_VoxiRIUeDrmns6Kl",
            "principalId": "3fbd929d-8c56-4462-851e-0eb9a7b3a2a5",
            "resourceId": "7ea9e944-71ce-443d-811c-71e8047b557a",
            "scope": "User.Read.All Group.Read.All"
        }
    ]
}

Paso 3: Revocar permisos delegados concedidos a una entidad de servicio en nombre de un usuario [Opcional]

Si a una entidad de servicio se le han concedido varias concesiones de permisos delegados en nombre de un usuario, puede optar por revocar concesiones específicas o todas las concesiones. Use este método para quitar y revocar el consentimiento para los permisos delegados que asignó a la entidad de servicio del cliente.

  • Para revocar una o algunas concesiones, ejecute una solicitud PATCH en el objeto oauth2PermissionGrant y especifique solo los permisos delegados que se conservarán en el parámetro scope .
  • Para revocar todas las concesiones, ejecute una solicitud DELETE en el objeto oauth2PermissionGrant.

Solicitud

La siguiente solicitud revoca todas las concesiones de permisos y solo conserva la concesión de User.Read.All permisos. Los permisos se quitan y se revoca el consentimiento concedido anteriormente.

PATCH https://graph.microsoft.com/v1.0/oauth2PermissionGrants/47nZsM8O_UuNq5Jz3QValETpqX7OcT1EgRxx6AR7VXqdkr0_VoxiRIUeDrmns6Kl
Content-Type: application/json

{
    "scope": "User.Read.All"
}

Respuesta

HTTP/1.1 204 No Content

Solicitud

La siguiente solicitud revoca todas las concesiones de permisos para una entidad de servicio en nombre de un usuario.

DELETE https://graph.microsoft.com/v1.0/oauth2PermissionGrants/47nZsM8O_UuNq5Jz3QValETpqX7OcT1EgRxx6AR7VXqdkr0_VoxiRIUeDrmns6Kl

Respuesta

HTTP/1.1 204 No Content

Conclusión

Ha concedido permisos delegados (o ámbitos) a una entidad de servicio. Este método de concesión de permisos mediante Microsoft Graph es una alternativa al consentimiento interactivo y se debe usar con precaución.