Table of contents
TOC
Collapse the table of content
Expand the table of content
Última actualización: 20/06/2018

Compilar aplicaciones de servicio y demonio en Office 365

Se aplica a: Office 365

Las aplicaciones de servidor web y dispositivo generalmente requieren que el usuario inicie sesión y consienta que la aplicación tenga acceso y trabaje con su información en Office 365. El protocolo subyacente para obtener acceso se basa en el Flujo de concesión del código de autorización de OAuth2. Como parte de este flujo de OAuth2, la aplicación obtiene un token de acceso/token de actualización que representa una delegación otorgada a la aplicación por un usuario individual para un conjunto de permisos. Básicamente, antes de que la aplicación pueda acceder a los datos de un usuario, debe obtener un token acceso/token de actualización para cada usuario, y para obtenerlos, el usuario debe iniciar sesión en la aplicación al menos una vez.

Esto no es posible para las aplicaciones que se ejecutan en segundo plano, como un demonio o una aplicación de servicio. Estas aplicaciones necesitan acceso sin que el usuario tenga que iniciar sesión. OAuth2 proporciona el flujo de concesión de credenciales del cliente para este tipo de aplicaciones, y Office 365 admite el uso de este flujo.

Al usar este flujo, la aplicación presenta sus credenciales de cliente al extremo que emite el token OAuth2 y, a cambio, obtiene un token de acceso que representa la aplicación en sí sin información del usuario. El token en este escenario se conoce como un token de acceso de solo aplicación.

No es necesario que la aplicación obtenga un token de actualización, ya que cuando el token de acceso caduca, simplemente vuelve al extremo emisor del token OAuth2 para obtener uno nuevo. Además, dado que no hay información del usuario en el token de solo aplicación, la aplicación debe especificar el usuario dentro de la llamada API al usar este token.

Definición de permisos

Para configurar su aplicación para tokens de solo aplicación, primero debe especificar qué permisos requiere su aplicación. Especifique estos permisos en el registro de la aplicación para su aplicación en el portal de administración de Azure para Microsoft Azure Active Directory (Azure AD). Seleccione el tipo de permisos de la aplicación, ya que estos se asignan directamente a la aplicación. Consulte la figura 1 para obtener una captura de pantalla de la sección de permisos de registro de la aplicación Azure AD.

Figura 1. Configuración de permisos de aplicaciones en Azure ADUna captura de pantalla que muestra los permisos de la aplicación en la consola de administración de Azure.

Nota Al registrar la aplicación en Azure AD, debe seleccionar el tipo Aplicación web o API web, ya que los permisos de solo aplicación no están disponibles para las aplicaciones cliente nativas.

Una vez que se especifican los permisos en el registro de la aplicación, la aplicación puede solicitar que el consentimiento esté disponible en otra organización de Office 365. El administrador de inquilinos de Office 365 debe dar su consentimiento a los permisos de la aplicación. Esto se debe a que estas aplicaciones son bastante potentes en términos de los datos a los que pueden acceder dentro de una organización de Office 365. Por ejemplo, una aplicación de servicio con el permiso Mail.Read que adquiere tokens de acceso a través del flujo de credenciales del cliente puede leer el correo en cualquier buzón dentro de la organización de Office 365.

Debido al amplio acceso disponible para estas aplicaciones, para obtener con éxito un token de acceso las aplicaciones también deben usar un certificado X.509 con un par de claves pública/privada. No se permite el uso de claves simétricas simples, y aunque la aplicación podría obtener un token de acceso utilizando una clave simétrica, la API devolverá un error de acceso denegado para estos tokens de acceso. Se aceptan certificados autoexpedidos X.509, pero la aplicación debe registrar el certificado público X.509 con la definición de la aplicación en Azure AD. La aplicación mantiene entonces la clave privada y la usa para indicar su identidad al extremo emisor del token.

Usted implementa el flujo de consentimiento de forma similar al flujo de concesión de código de autorización enviando una solicitud al extremo de autorización OAuth2. Sin embargo, una vez que el extremo autorizado redirige de vuelta con un código de autorización a la aplicación, se puede ignorar el código restante; para obtener tokens, solo son necesarias las credenciales del cliente. Puede crear una experiencia como "Registrarse mi organización" en su aplicación para lograr el consentimiento inicial de una sola vez. El punto clave aquí es que debe hacer que el consentimiento de una sola vez sea parte de la configuración de su aplicación de servicio o demonio. Una vez que se otorga el consentimiento, la aplicación puede obtener tokens de acceso y comenzar a llamar a las API de Office 365.

Puede revocar el consentimiento para las aplicaciones de servicio igual que con cualquier otra aplicación instalada por un administrador de inquilinos de Office 365. El administrador puede ir al portal de administración de Azure, encontrar la aplicación en la Vista de aplicación, seleccionarla y eliminarla o, alternativamente, el administrador puede usar el cmdlet Remove-MSOLServicePrincipal desde el módulo Azure AD para Windows PowerShell.

Adquirir un token de acceso con el flujo de credenciales del cliente

Al solicitar tokens de solo aplicación, debe usar un extremo emisor de tokens específico de la cuenta empresarial. Si usa el extremo común (independiente de la cuenta empresarial), se devuelve un error.

Durante el proceso de consentimiento, cuando se alcanza el extremo y se entrega un código en el redireccionamiento a la aplicación, su aplicación puede solicitar un token de id. junto con el código. Este token es un token web JSON que contiene el id. de la cuenta empresarial como tipo de notificación tid, por lo que solo necesita analizar esto para obtener el id. para el extremo específico de la cuenta empresarial.

El siguiente es un ejemplo de cómo desencadenar el consentimiento usando una solicitud de Flujo híbrido de OpenID Connect:

GET https://login.microsoftonline.com/common/oauth2/authorize?state=e82ea723-7112-472c-94d4-6e66c0ca52b6&response_type=code+id_token&scope=openid&nonce=c328d2df-43d1-4e4d-a884-7cfb492beadc&client_id=0308CDD9-874D-4F87-85E0-A0DA7E05F999&redirect_uri=https:%2f%2flocalhost:44304%2fHome%2f&resource=https:%2f%2fgraph.windows.net%2f&prompt=admin_consent&response_mode=form_post HTTP/1.1

Esta solicitud proporciona a su aplicación el flujo de consentimiento y redirige de vuelta con el código y el token de id. en una solicitud POST. Su aplicación puede ignorar el código y obtener el token de id. de los datos del formulario recibido. Para obtener más información sobre el modo de respuesta de publicación de formulario, consulte la Especificación de OpenID.

En ASP.Net puede recuperar el token de id. a través de Request.Form ["id_token"] en la página de redireccionamiento, encontrando el id. de la cuenta empresarial en la notificación tid dentro del id_token.

Obtener un token de solo aplicación

El siguiente fragmento de código muestra el uso de la biblioteca cliente de Azure AD para adquirir un token de solo aplicación a través del flujo de credenciales del cliente:

//need to address the tenant specific authority/token issuing endpoint
//https://login.microsoftonline.com/<tenant-id>/oauth2/authorize
//retrieved tenantID from ID token for the app during consent flow (authorize flow)
string authority = appConfig.AuthorizationUri.Replace("common", tenantId);
AuthenticationContext authenticationContext = new AuthenticationContext(authority,false);
string certfile = Server.MapPath(appConfig.ClientCertificatePfx);
X509Certificate2 cert = new X509Certificate(certfile,appConfig.ClientCertificatePfxPassword, X509KeyStorageFlags.MachineKeySet);
ClientAssertionCertificate cac = new ClientAssertionCertificate(appConfig.ClientId, cert);
var authenticationResult = await authenticationContext.AcquireTokenAsync(resource, cac);
return authenticationResult.AccessToken;

La aplicación para este ejemplo mantiene la clave privada en un directorio bien protegido en el servidor web en forma de archivo PFX. Sin embargo, es mejor mantener la clave privada en un almacenamiento más seguro, como el almacenamiento de certificados de Windows de la cuenta del equipo.. Para obtener una muestra completa de una aplicación web que utiliza el flujo de credenciales del cliente, consulte la muestra o365api-as-apponly-webapp.

Configurar un certificado público X.509 para su aplicación

La última parte es cómo configurar un certificado público X.509 para su aplicación. Como esto no está expuesto en la interfaz de usuario del portal de administración de Azure, debe configurarlo editando manualmente el manifiesto de la aplicación. Para ello, deberá:

  • Crear un certificado autoemitido si no tiene ya un certificado X.509.

  • Recuperar el valor del certificado codificado en base64 y la huella digital de un archivo de certificado público .cer X509 con Windows PowerShell.

  • Subir el certificado a través del archivo de manifiesto de la aplicación. Puede usar la herramienta makecert.exe, incluida con las herramientas de .NET Framework, para generar un certificado autoemitido.

Para generar un certificado autoemitido utilizando la herramienta makecert.exe:

  1. En la línea de comandos, escriba y ejecute

    makecert -r -pe -n "CN=MyCompanyName MyAppName Cert" -b 12/15/2014 -e 12/15/2016 -ss my -len 2048

  2. Abra el complemento de consola de administración de Certificados y conéctese a su cuenta de usuario.

  3. Encuentre el nuevo certificado en la carpeta Personal y expórtelo a un archivo CER codificado en base64.

    Nota Asegúrese de que la longitud de la clave sea de al menos 2048 al generar el certificado X.509. Longitudes de clave más cortas no se aceptan como claves válidas.

Obtener el valor de certificado codificado en base64 y la huella digital de un archivo de certificado público .cer X509

  1. Desde la línea de comandos de Windows PowerShell, escriba y ejecute los siguientes cmdlets:

    $cer = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2
    $cer.Import("mycer.cer")
    $bin = $cer.GetRawCertData()
    $base64Value = [System.Convert]::ToBase64String($bin)
    $bin = $cer.GetCertHash()
    $base64Thumbprint = [System.Convert]::ToBase64String($bin)
    $keyid = [System.Guid]::NewGuid().ToString()
    

    Nota Este paso muestra cómo usar Windows PowerShell para obtener las propiedades de un certificado x.509. Otras plataformas proporcionan herramientas similares para recuperar propiedades de certificados.

  2. Almacene los valores de $base64Thumbprint, $base64Value y $keyid, ya que los necesitará cuando suba el certificado en el siguiente conjunto de pasos.

Subir el certificado a través del archivo de manifiesto de la aplicación

  1. Inicie sesión en el portal de administración de Azure.

  2. Haga clic en Active Directory en el menú de la izquierda, y luego haga clic en el directorio deseado.

  3. En el menú superior, haga clic en Aplicaciones y luego haga clic en la aplicación que desea configurar. La página de Inicio rápido aparecerá con el inicio de sesión único, así como otra información de configuración.

  4. Haga clic en Administrar manifiesto en la barra de comandos, y seleccione Descargar manifiesto.

  5. Abra el archivo descargado para editar y reemplazar la propiedad vacía KeyCredentials con el siguiente JSON:

    "keyCredentials": [
    {
      "customKeyIdentifier": "$base64Thumbprint_from_above",
      "keyId": "$keyid_from_above",
      "type": "AsymmetricX509Cert",
      "usage": "Verify",
      "value":  "$base64Value_from_above"
     }
    ], 
    

    por ejemplo:

    "keyCredentials": [
     {
       "customKeyIdentifier": "ieF43L8nkyw/PEHjWvj+PkWebXk=",
       "keyId": "2d6d849e-3e9e-46cd-b5ed-0f9e30d078cc",
       "type": "AsymmetricX509Cert",
       "usage": "Verify",
       "value": "MIICWjCCAgSgAwIBA***omitted for brevity***qoD4dmgJqZmXDfFyQ"
     }
    ],
    

    La propiedad KeyCredentials es una colección, que permite subir múltiples certificados X.509 para escenarios donde haya que revertirlos, o eliminar certificados en escenarios en que se hayan visto comprometidos.

  6. Guarde los cambios y suba el archivo de manifiesto de la aplicación actualizado haciendo clic en Administrar manifiesto en la barra de comandos, seleccionando Subir manifiesto, navegando a su archivo de manifiesto actualizado y luego seleccionándolo.

© 2018 Microsoft