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

Autenticación de OneNote y permisos de aplicación en Azure AD

Aplica a: Bloc de notas empresarial en Office 365

Autenticar con Azure AD (aplicaciones empresariales)

  1. Registre su aplicación y obtenga una ID de cliente y secreto
  2. Elija los ámbitos de permiso de aplicaciones de OneNote
  3. Obtener el consentimiento del administrador
  4. Obtener un token de acceso
  5. Obtenga un nuevo token de acceso una vez que caduque

Registre su aplicación y obtenga una ID de cliente y secreto (aplicaciones empresariales)

Ver Registre su aplicación y obtenga una ID de cliente y secreto.

Elija los ámbitos de permisos de aplicaciones de OneNote (aplicaciones empresariales)

Los ámbitos de permiso representan los niveles de acceso al contenido de OneNote. El administrador de una organización otorga un permiso de aplicación a una aplicación y solo se puede usar para acceder a los datos que pertenecen a esa organización y a sus empleados. Por ejemplo, la API de OneNote expone varios permisos de aplicaciones para hacer lo siguiente:

  • Ver notas para todos los usuarios
  • Ver y modificar notas para todos los usuarios

Siga los pasos a continuación para asignar permisos de aplicación de OneNote a su aplicación:

  1. En elPortal de administración de Azure, en la secciónPermisos a otras aplicacionesde la página de configuración de la aplicación, elijaAgregar aplicación.

  2. Elija la aplicación OneNote y luego haga clic en la marca de verificación en la esquina inferior derecha. Si OneNote no aparece en la lista, asegúrese de haber dispuesto OneDrive para negocios para su inquilino.

  3. Elija el nivel más bajo de permisos de aplicaciones que su aplicación necesita para hacer su trabajo, y guarde los cambios. Puede solicitar múltiples ámbitos.


Ámbitos de permisos de aplicaciones

Si está accediendo a computadoras portátiles con permisos de aplicaciones, elija entre los siguientes ámbitos.

Ámbito (empresa)Permiso en Azure PortalDescripción
Notes.Read.AllVer notas para todos los usuariosPermite que la aplicación vea las notas de OneNote de todos los usuarios de su organización sin un usuario registrado. La aplicación no puede crear notas nuevas, modificar notas existentes ni ver notas en secciones protegidas por contraseña.
Notes.ReadWrite.AllVer y modificar notas para todos los usuariosPermita que la aplicación vea las notas de OneNote de todos los usuarios de su organización sin que ningún usuario haya iniciado sesión. La aplicación no puede acceder a las notas en secciones protegidas por contraseña.

Recomendado: inicie sesión del usuario en su aplicación

Por lo general, cuando creas una aplicación que usa permisos de aplicaciones, la aplicación requiere una página o vista en la que el administrador aprueba los permisos de la aplicación. Esta página puede ser parte del flujo de inicio de sesión de la aplicación, parte de la configuración de la aplicación, o puede ser un flujo dedicado de "conexión". En muchos casos, tiene sentido que la aplicación muestre esta vista de "conexión" solo después de que un usuario haya iniciado sesión con una cuenta Microsoft de trabajo o escuela.

Si inicia sesión del usuario en su aplicación, puede identificar la organización a la que pertenece el usuario antes de solicitarle al usuario que apruebe los permisos de la aplicación. Aunque no es estrictamente necesario, puede ayudarlo a crear una experiencia más intuitiva para sus usuarios. Para iniciar la sesión del usuario, siga nuestros tutoriales de protocolo v2.0.

Solicite los permisos de un administrador de directorio

Cuando esté listo para solicitar permisos del administrador de la organización, puede redirigir al usuario al punto de conexión de consentimiento del administrador. Puede hacer la llamada API de la siguiente forma:

// Line breaks are for legibility only.

// Replace {tenant} with the tenant (GUID or name) you need admin consent for
// Replace {app_id} with your AAD assigned application id

GET https://login.microsoftonline.com/{tenant}/adminconsent?
client_id={app_id}
&state=12345
&redirect_uri=http://localhost/myapp/permissions

También puede probar la solicitud anterior en un navegador, escriba el siguiente URL en la barra de dirección de su navegador (haga un URL válido siguiendo las instrucciones a continuación).

// Replace {tenant} with the tenant (GUID or name) you need admin consent for
// Replace {app_id} with your AAD assigned application id

https://login.microsoftonline.com/{tenant}/adminconsent?client_id={app_id}&state=12345&redirect_uri=http://localhost/myapp/permissions

La siguiente tabla describe los parámetros utilizados en la solicitud anterior:

ParámetroCondiciónDescripción
inquilinoObligatorioEl inquilino del directorio del que desea solicitar permiso. Esto puede ser en formato GUID o un nombre fácil de usar. Si no sabe a qué inquilino pertenece el usuario y quiere permitirle que inicie sesión con cualquier inquilino, utilice el campo común.
client_idObligatorioIdentificador de aplicación que el portal de registro de aplicaciones ha asignado a la aplicación.
redirect_uriObligatorioURI de redireccionamiento adonde quiere que se envíe la respuesta para que la aplicación la controle. Debe coincidir exactamente con uno de los URI de redireccionamiento que ha registrado en el portal, pero con codificación URL, y puede tener segmentos de ruta de acceso adicionales.
estadoRecomendadoValor incluido en la solicitud que también se devuelve en la respuesta de token. Puede ser una cadena con cualquier contenido que quiera. El estado se usa para codificar la información sobre el estado del usuario en la aplicación antes de que se produjese la solicitud de autenticación, como la página o la visualización en la que estaba.

Se le presentará un cuadro de diálogo de consentimiento de administrador que puede aprobar sin problema.

Respuesta correcta

Si el administrador aprueba los permisos de la aplicación, la respuesta correcta se ve así:

GET https://login.microsoftonline.com/{tenant}/Consent/Grant

La siguiente tabla describe los valores devueltos en la respuesta anterior:

ParámetroDescripción
inquilinoInquilino de directorio que concedió a su aplicación los permisos que solicitó, en formato GUID.

Respuesta de error

Si el administrador no aprueba los permisos para su aplicación, la respuesta de error es la siguiente:

GET https://login.microsoftonline.com/{tenant}/login

Additional technical information: 
Correlation ID: f3817dd1-8476-46c2-a81b-fdefd209f988 
Timestamp: 2017-01-18 05:36:57Z 
AADSTS90093: This operation can only be performed by an administrator. Sign out and sign in as an administrator or contact one of your organization's administrators. 

La siguiente tabla describe los valores devueltos en la respuesta anterior:

ParámetroDescripción
inquilinoInquilino de directorio que concedió a su aplicación los permisos que solicitó, en formato GUID.

Una vez que haya recibido una respuesta exitosa del punto de conexión de la aplicación proveedora, su aplicación habrá obtenido los permisos de aplicación directa que solicitó. Ahora puede solicitar un token para el recurso que desea.

Notas:

  1. Un inquilino específico tiene que obtener el permiso del administrador solo una vez
  2. Si desea que su aplicación funcione en otros inquilinos, debe configurarla como una aplicación multiinquilino en AAD
  3. Tanto si la aplicación está ejecutando en su propio inquilino como si lo hace en otro inquilino, el consentimiento del administrador es un paso requerido
  4. Su aplicación puede elegir permisos de delegado además de los permisos de la aplicación (pero todavía se requiere el consentimiento del administrador)

Obtener un token de acceso (aplicaciones empresariales)

Después de que haya adquirido la autorización necesaria para su aplicación, proceda con la adquisición de tokens de acceso para las API. Para obtener un token utilizando la concesión de credenciales del cliente, envíe una solicitud POST como la siguiente:

// Replace {tenant} with the tenant (GUID or name) you need admin consent for
// Replace {app_id} with your AAD assigned application id
// Replace {app_secret} with an AAD generated key for your application

POST https://login.microsoftonline.com/{tenant}/oauth2/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id={app_id}&client_secret={app_secret}&resource=https%3A%2F%2Fonenote.com%2F

La siguiente tabla describe los parámetros utilizados en la solicitud anterior:

ParámetroCondiciónDescripción
grant_typeObligatorioDebe ser client_credentials.
client_idObligatorioIdentificador de aplicación que el portal de registro de aplicaciones ha asignado a la aplicación.
client_secretObligatorioSecreto de la aplicación generado para la aplicación en el portal de registro de aplicaciones. Es muy importante que este sea un URL codificado
recursoObligatorioEl valor pasado para el resource El parámetro en esta solicitud debe ser el identificador de recursos (URI de ID de aplicación) del recurso que desea. Para la API de OneNote, el valor es https://onenote.com/. Este valor informa al punto de conexión del token de todos los permisos de aplicación directa que ha configurado para su aplicación, debe emitir un token para los asociados con el recurso que desea usar.

Respuesta correcta

Una respuesta correcta tiene un aspecto similar al siguiente:

{
  "token_type": "Bearer",
  "expires_in": "3600",
  "resource": "https:\/\/onenote.com\/",
  "access_token": "eyJ0eXAiOiJKV1Qi..."
}

La siguiente tabla describe los valores devueltos en la respuesta anterior:

ParámetroDescripción
token_typeIndica el valor de tipo del token. El único tipo que Azure AD admite es bearer.
expires_inPeríodo de validez del token de acceso (en segundos).
recursoEl identificador de recurso (URI de ID de aplicación) del recurso con el que se puede usar este token.
access_tokenEl token de acceso solicitado. La aplicación puede usar este token para autenticarse con el recurso seguro, como en una API web.

Respuesta de error

Una respuesta de error se ve así (en este ejemplo, se proporciona un valor no válido para client_secret en la solicitud):

{
  "error": "invalid_client",
  "error_description": "AADSTS70002: Error validating credentials. AADSTS50012: Invalid client secret is provided.\r\nTrace ID: b6e89947-f005-469e-92ad-18aed399b140\r\nCorrelation ID: c2d1c230-bee9-41f1-9d4d-a5687e01b7bc\r\nTimestamp: 2017-01-19 20:34:11Z",
  "error_codes": [
    70002,
    50012
  ],
  "timestamp": "2017-01-19 20:34:11Z",
  "trace_id": "b6e89947-f005-469e-92ad-18aed399b140",
  "correlation_id": "c2d1c230-bee9-41f1-9d4d-a5687e01b7bc"
}

La siguiente tabla describe los valores devueltos en la respuesta anterior:

ParámetroDescripción
errorUna cadena de código de error que puede usar para clasificar los tipos de errores que se producen y para reaccionar ante los errores.
error_descriptionUn mensaje de error específico que podría ayudarlo a identificar la causa raíz de un error de autenticación.
error_codesUna lista de códigos de error específicos de STS que pueden ayudar con el diagnóstico.
marca de horaLa hora en que ocurrió el error.
trace_idUn identificador exclusivo para la solicitud que podría ayudar con el diagnóstico.
correlation_idUn identificador exclusivo para la solicitud que podría ayudar con el diagnóstico en todos los componentes.

Incluya el token de acceso en su solicitud a la API de OneNote

Todas sus solicitudes a la API de OneNote deben enviar el token de acceso como un token de portador en el encabezamiento deAutorización. Por ejemplo, la siguiente solicitud obtiene cinco de sus bloc de notas, ordenados alfabéticamente por nombre:

GET https://www.onenote.com/api/v1.0/users/foo@example.com/notes/notebooks?top=5
Authorization: Bearer {access-token}

Los tokens de acceso solo son válidos por una hora, por lo que necesitarás obtener tokens nuevos cuando caduquen. Debe verificar el vencimiento del token antes de usarlo y obtener un nuevo token de acceso si es necesario. Los administradores no tienen que dar su consentimiento a los permisos nuevamente a menos que revoquen los permisos.

Obtenga un nuevo token de acceso una vez que caduque (aplicaciones empresariales)

Si el token de acceso expira, las solicitudes a la API devolverán una 401 Unauthorizedrespuesta. Su aplicación debe manejar esta respuesta y verificar la caducidad del token antes de enviar las solicitudes.

Puede solicitar un nuevo token de acceso repitiendo el proceso descrito en la sección Obtener un token de acceso anteriormente en este tema.

Actualiza tus tokens almacenados para asegurarte de que tu aplicación tenga tokens con la mayor vida útil.

Errores

Si existen errores con la autenticación, el explorador web se redirige a una página de error. Aunque la página de error siempre muestra un mensaje fácil de usar por el usuario, la dirección URL de la página de error incluye información adicional que puede ayudarle a resolver los problemas que han sucedido. Los parámetros de URL se incluyen como un marcador, por ejemplo: #error={error_code}&error_description={message}

Si el administrador decide no dar su consentimiento a su aplicación, el flujo redirigirá a su URL de redirección e incluirá los parámetros de error.

Para obtener información detallada sobre el manejo de errores, consulte Control de errores en OAuth 2.0.

Recursos adicionales

© 2018 Microsoft