Autenticación de OneNote y permisos de aplicación en Azure AD
Se aplica a: blocs de notas empresariales en Office 365
Autenticar con Azure AD (aplicaciones de empresa):
- Registrar su aplicación y obtener un id. de cliente y secreto
- Elegir los ámbitos de permiso de aplicaciones de OneNote
- Obtener el consentimiento del administrador
- Obtener un token de acceso
- Obtener un nuevo token de acceso una vez que caduque
Registre su aplicación y obtenger una id. de cliente y secreto (aplicaciones empresariales)
Vea Registrar su aplicación y obtener un 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:
En elPortal de administración de Azure, en la sección Permisos para otras aplicaciones de la página de configuración de la aplicación, elija Agregar aplicación.
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.
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 Portal | Descripción |
|---|---|---|
| Notes.Read.All | Ver notas para todos los usuarios | Permite 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.All | Ver y modificar notas para todos los usuarios | Permita 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. |
Obtener el consentimiento del administrador
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 Azure AD assigned application id
GET https://login.microsoftonline.com/{tenant}/adminconsent?
client_id={app_id}
&state=12345
&redirect_uri=https://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 una dirección URL válida siguiendo las instrucciones a continuación).
// Replace {tenant} with the tenant (GUID or name) you need admin consent for
// Replace {app_id} with your Azure AD assigned application id
https://login.microsoftonline.com/{tenant}/adminconsent?client_id={app_id}&state=12345&redirect_uri=https://localhost/myapp/permissions
En esta tabla se describen los parámetros utilizados en la solicitud anterior:
| Parámetro | Condición | Descripción |
|---|---|---|
| inquilino | Obligatorio | La cuenta empresarial del directorio de la 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_id | Obligatorio | Identificador de aplicación que el portal de registro de aplicaciones ha asignado a la aplicación. |
| redirect_uri | Obligatorio | URI 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. |
| state | Recomendado | Valor 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
En esta tabla se describen los valores devueltos en la respuesta anterior:
| Parámetro | Descripción |
|---|---|
| inquilino | Cuenta empresarial de directorio que ha concedido a la aplicación los permisos que ha solicitado, 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.
En esta tabla se describen los valores devueltos en la respuesta anterior:
| Parámetro | Descripción |
|---|---|
| inquilino | Cuenta empresarial de directorio que ha concedido a la aplicación los permisos que ha solicitado, 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.
Nota
- Una cuenta empresarial específica tiene que obtener el permiso del administrador solo una vez.
- Si desea que la aplicación se ejecute en otras cuentas empresariales, se debe configurar como una aplicación de varias cuentas empresariales en Azure AD.
- Tanto si la aplicación está ejecutando en su propia cuenta empresarial como si lo hace en otra cuenta empresarial, el consentimiento del administrador es un paso requerido
- 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 Azure AD assigned application id
// Replace {app_secret} with an Azure AD 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
En esta tabla se describen los parámetros utilizados en la solicitud anterior:
| Parámetro | Condición | Descripción |
|---|---|---|
| grant_type | Obligatorio | Debe ser client_credentials. |
| client_id | Obligatorio | Identificador de aplicación que el portal de registro de aplicaciones ha asignado a la aplicación. |
| client_secret | Obligatorio | Secreto 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 |
| resource | Necesario | El 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..."
}
En esta tabla se describen los valores utilizados en la solicitud anterior:
| Parámetro | Descripción |
|---|---|
| token_type | Indica el valor de tipo del token. El único tipo que Azure AD admite es bearer. |
| expires_in | Período de validez del token de acceso (en segundos). |
| resource | El identificador de recurso (URI de ID de aplicación) del recurso con el que se puede usar este token. |
| access_token | El 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"
}
En esta tabla se describen los valores utilizados en la solicitud anterior:
| Parámetro | Descripción |
|---|---|
| error | Una 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_description | Un mensaje de error específico que podría ayudarlo a identificar la causa raíz de un error de autenticación. |
| error_codes | Una lista de códigos de error específicos de STS que pueden ayudar con el diagnóstico. |
| timestamp | La hora en que ocurrió el error. |
| trace_id | Un identificador exclusivo para la solicitud que podría ayudar con el diagnóstico. |
| correlation_id | Un identificador exclusivo para la solicitud que podría ayudar con el diagnóstico en todos los componentes. |
Incluir 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 encabezado Authorization. Por ejemplo, la siguiente solicitud obtiene cinco de sus blocs 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á 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 respuesta 401 Unauthorized. 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 depurar los problemas que hayan 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 control de errores, consulte Control de errores en OAuth 2.0.