Autenticación y permisos de OneNote
Se aplica a: Blocs de notas para consumidores de OneDrive | Blocs de notas empresariales de Office 365
OneNote utiliza una cuenta Microsoft (anteriormente, Live Connect) y Azure Active Directory para proporcionar acceso seguro a los blocs de notas de OneNote. Para poder acceder a los blocs de notas, primero debe autenticarse con una cuenta Microsoft o Azure AD y obtener un token de acceso.
La cuenta Microsoft se usa para acceder a los blocs de notas de consumidor en OneDrive y Azure AD se usa para acceder a los blocs de notas de empresa en Office 365.
Ambos servicios de autorización implementan el protocolo OAuth 2.0 para proporcionar los tokens de acceso necesarios para interactuar con OneNote. Todas las solicitudes a la API de OneNote deben incluir un token de acceso válido en el encabezado Authorization.
Este artículo describe los procesos relacionados con la autenticación de los que es responsable: registrar su aplicación para obtener un id. de cliente, especificar los permisos que necesita y llamar al servicio de autorización para que los usuarios inicien sesión y obtengan un token de acceso.
Dependiendo de su plataforma, es posible que pueda usar un SDK para simplificar los flujos de autenticación.
Nota
OneNote finalmente admitirá el modelo de autenticación única y el registro de la aplicación proporcionado por el modelo de aplicación versión 2.0. Esté atento a las actualizaciones relacionadas en el Blog del desarrollador de OneNote.
Pruebe las API
O puede seguir los pasos de este artículo para obtener un token de acceso con su herramienta de red favorita, como Fiddler.
Autenticar usando cuenta Microsoft (aplicaciones de consumidor)
- Registrar su aplicación y obtener un id. de cliente y secreto
- Elegir permisos de OneNote
- Hacer que los usuarios inicien sesión y obtener un token de acceso
- Obtener un nuevo token de acceso una vez que caduque
Registrar su aplicación y obtener un id. de cliente y secreto (aplicaciones de consumidor)
Para comenzar, debe registrar una aplicación con Microsoft. Este proceso crea una entidad de servicio a la que se vincula desde su aplicación, y genera el id. de cliente y el secreto que envía al servicio de autorización.
Haga esto si su aplicación accede solo a blocs de notas de consumidor, o si accede a blocs de notas de consumidor y de empresa.
Inicie sesión en el Centro de desarrolladores de cuenta Microsoft con su cuenta Microsoft (Si está desarrollando una aplicación de Tienda Windows, haga esto en su lugar).
Si no tiene una cuenta Microsoft, necesitará crear una. Debe usar una dirección de correo electrónico que verifique regularmente. Podríamos tratar de ponernos en contacto con usted para resaltar su aplicación en nuestra página de Aplicaciones destacadas, o si notamos que un tráfico de red inesperado proviene de su aplicación. No le enviaremos correo basura ni venderemos su información.
Haga clic en Crear aplicación.
Escriba el nombre que desea que los usuarios vean cuando se les solicite otorgar permisos a su aplicación y elija el idioma principal para su aplicación.
Si acepta las condiciones de uso y la directiva de privacidad y cookies, elija Acepto para continuar con el registro.
En la página Configuración de API, elija su tipo de aplicación y proporcione información sobre su aplicación:
Aplicaciones web (aplicaciones de lado servidor)
a. Escoja No para la Aplicación de cliente móvil o de escritorio.
b. Para el dominio destino, escriba la URL del servicio.
c. Escriba la URL de redirección a la que desea que se dirija a los usuarios después de que se hayan autenticado y que hayan otorgado acceso a su aplicación.
Aplicaciones nativas (instaladas en un dispositivo)
a. Escoja No para la Aplicación de cliente móvil o de escritorio.
b. (Opcional) Para el dominio de destino, escriba la URL del servicio móvil.
c. (Opcional) Para la URL de redirección, escriba una URL válida. Esto actúa como un identificador para su aplicación, y no necesita ser un extremo físico.*
Guarde el id. del cliente y el secreto del cliente que se muestran en la página Configuración de la aplicación y la URL de redirección si la proporcionó.
Aplicaciones de la Tienda Windows
Si está creando una aplicación de Windows, registrará su aplicación en Centro para desarrolladores de Windows en su lugar. Esto le proporcionará la identidad del paquete (SID del paquete) que usará en lugar del id. del cliente.
Inicie sesión en el Centro para desarrolladores de Windows con su cuenta Microsoft.
En el panel, elija Crear una nueva aplicación y escriba el nombre de su aplicación.
En Visual Studio, haga clic con el botón derecho en su proyecto de la aplicación de la Tienda Windows y elija Tienda > Asociar aplicación con la tienda.
En la ventana Asociar su aplicación con Tienda Windows, inicie sesión con su cuenta Microsoft, elija su aplicación y luego elija Siguiente > Asociar. Esto agrega la información de registro de la Tienda Windows requerida al manifiesto de la aplicación.
Para una aplicación Windows universal, repita los dos pasos anteriores para el proyecto de Windows Phone.
Elegir ámbitos de permisos de OneNote (aplicaciones de consumidor)
Los ámbitos de permiso representan los niveles de acceso al contenido de OneNote. Usted solicita los permisos que su aplicación necesita y los usuarios conceden o deniegan el acceso cuando inician sesión en su aplicación. Los usuarios solo pueden otorgar los permisos que tienen.
Seleccione el nivel inferior de permisos que necesita la aplicación para funcionar correctamente. Puede solicitar múltiples ámbitos.
| Ámbito (consumidor) | Descripción |
|---|---|
| office.onenote_create | Puede ver una lista de los blocs de notas de OneNote del usuario y crear páginas nuevas, pero no puede ver o editar páginas existentes. Puede enumerar la jerarquía del bloc de notas del usuario y crear páginas en cualquier ubicación. |
| office.onenote_update_by_app | Puede crear, ver y modificar todas las páginas creadas por la aplicación. |
| office.onenote_update | Puede crear, ver y modificar cualquier contenido en los blocs de notas y páginas de OneNote del usuario. |
| office.onenote | Puede ver blocs de notas y páginas de OneNote pero no modificarlos. |
| wl.signin | Un ámbito de permisos de cuenta Microsoft. Permite que su aplicación aproveche las capacidades de inicio de sesión único. |
| wl.offline_access | Un ámbito de permisos de cuenta Microsoft. Permite que su aplicación reciba un token de actualización para que pueda funcionar sin conexión incluso cuando el usuario no está activo. Este ámbito no está disponible para el flujo token. |
Para conocer los permisos utilizados para acceder a los blocs de notas de Office 365, consulte Elegir permisos de OneNote (aplicaciones de empresa).
Hacer que los usuarios inicien sesión y obtener un token de acceso (aplicaciones de consumidor)
Su aplicación inicia el proceso de inicio de sesión poniéndose en contacto con el servicio de autorización. Si los usuarios aún no han iniciado sesión o no han dado su consentimiento, el servicio les pedirá las credenciales y que acepten los permisos solicitados por su aplicación. Si la autenticación y la autorización tienen éxito, recibirá un token de acceso que incluirá en sus solicitudes a la API de OneNote.
Importante
Trate los tokens de acceso y los tokens de actualización de forma tan segura como lo haría con la contraseña de un usuario.
Nota
Dependiendo de su plataforma, es posible que pueda usar un SDK para simplificar los flujos de autenticación.
Elija su flujo de autenticación. Ambos son flujos estándar de OAuth 2.0.
| Flujo | Descripción |
|---|---|
| Flujo de tokens | Obtiene un token de acceso en una llamada. Útil para un acceso rápido, pero no proporciona un token de actualización para el acceso a largo plazo. También llamado flujo Implícito. |
| Flujo de códigos | Obtiene un código de autorización en la primera llamada e intercambia el código por un token de acceso en la segunda llamada. Cuando se usa con el ámbito de permisos wl.offline-access, su aplicación recibe un token de actualización que permite el acceso a largo plazo. También llamado flujo Código de autorización. |
Hacer que los usuarios inicien sesión con el flujo Token
Cargue la siguiente solicitud de URL en un explorador web o control de explorador web.
GET https://login.live.com/oauth20_authorize.srf
?response_type=token
&client_id={client_id}
&redirect_uri={redirect_uri}
&scope={scope}
| Parámetro de cadena de consulta requerido | Descripción |
|---|---|
| response_type | El tipo de flujo de autenticación que está utilizando. En este caso, token. |
| client_id | El identificador de cliente que se crea para su aplicación. |
| redirect_uri | La URL de redirección que ha registrado para su aplicación. Las aplicaciones móviles y de escritorio que no especificaron uno pueden usar esto: https://login.live.com/oauth20_desktop.srf |
| scope | Los ámbitos que requiere su aplicación. Ejemplo: office.onenote%20wl.sign-in |
Después de una autenticación y autorización con éxito, el explorador web redirige a su URL de redirección y agrega los parámetros de acceso a la URL. Los parámetros incluyen los access_token y token_type, tal como se muestra en el siguiente ejemplo. El token de acceso es válido durante el número de segundos que se especifique en la propiedad expires_in.
https://your-redirect-url
#access_token=EwB4Aq...%3d
&token_type=bearer
&expires_in=3600
&scope=office.onenote wl.signin
&user_id=c519ea026ece84de362cfa77dc0f2348
Hacer que los usuarios inicien sesión con el flujo Código
Obtener un token de acceso es un proceso de dos pasos con el flujo Código:
- Haga que el usuario inicie sesión y obtenga un token de autorización.
- Intercambie el código por un token de acceso.
Paso 1. Haga que el usuario inicie sesión y obtenga un token de autorización. Para iniciar el proceso de inicio de sesión, cargue la siguiente solicitud de URL en un explorador web o control de explorador web.
https://login.live.com/oauth20_authorize.srf
?response_type=code
&client_id={client-id}
&redirect_uri={redirect-uri}
&scope={scope}
| Parámetro de cadena de consulta requerido | Descripción |
|---|---|
| response_type | El tipo de flujo de autenticación que está utilizando. En este caso, code (código). |
| client_id | El identificador de cliente que se crea para su aplicación. |
| redirect_uri | La URL de redirección que ha registrado para su aplicación. Las aplicaciones móviles y de escritorio que no especificaron uno pueden usar esto: https://login.live.com/oauth20_desktop.srf |
| scope | Los ámbitos que requiere su aplicación. Ejemplo: office.onenote wl.signin wl.offline_access |
Después de una autenticación y autorización con éxito, el explorador web redirecciona a su URL de redirección con un parámetro code anexado a la URL, como se muestra en el siguiente ejemplo. Copie el valor código a usar en el paso 2. Este código es válido por unos minutos.
https://your-redirect-uri
?code=M57010781-9e8c-e31e-ca0d-46bc104236c4
Paso 2. Intercambie el código de autorización por un token de acceso y un token de actualización. Envíe la siguiente solicitud HTTP con una cadena URL codificada correctamente en el cuerpo del mensaje.
POST https://login.live.com/oauth20_token.srf
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code
&client_id={client-id}
&client_secret={client-secret}
&code={code}
&redirect_uri={redirect-uri}
| Parámetro de cuerpo obligatorio | Descripción |
|---|---|
| grant_type | El tipo de concesión de la solicitud. En este caso, authorization_code. |
| client_id | El identificador de cliente que se crea para su aplicación. |
| client_secret | El secreto de cliente que se crea para su aplicación. |
| code | El código que recibió como parámetro de URL en el paso anterior. |
| redirect_uri | La URL de redirección para su aplicación. Esto debe coincidir con el redirect_uri en la primera solicitud. |
Si tiene éxito, la respuesta contiene una cadena JSON que incluye el access_token y el refresh_token si solicitó el ámbito wl.offline_access, tal como se muestra en el siguiente ejemplo. El token de acceso es válido durante el número de segundos que se especifique en la propiedad expires_in.
{
"token_type":"bearer",
"expires_in":3600,
"scope":"office.onenote wl.sign-in wl.offline-access",
"access_token":"EwCAAq...wE=",
"refresh_token":"MCvePE...$$",
"user_id":"c519ea026ece84de362cfa77dc0f2348"
}
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/me/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 usuarios pueden permanecer conectados y no tienen que dar su consentimiento de nuevo a menos que cierren la sesión o revoquen los permisos.
Obtener un nuevo token de acceso una vez que caduque (aplicaciones de consumidor)
Puede solicitar un nuevo token de acceso usando el token de actualización, o repitiendo el proceso de autenticación desde el principio.
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 solicitudes.
Envíe la siguiente solicitud HTTP con una cadena URL codificada correctamente en el cuerpo del mensaje.
Recibió un token de actualización si solicitó el permiso wl.offline_access y usó el flujo Código.
POST https://login.live.com/oauth20_token.srf
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token
&client_id={client-id}
&client_secret={client-secret}
&redirect_uri={redirect-uri}
&refresh_token={refresh-token}
| Parámetro de cuerpo obligatorio | Descripción |
|---|---|
| grant_type | El tipo de concesión de la solicitud. En este caso, refresh_token. |
| client_id | El identificador de cliente que se crea para su aplicación. |
| client_secret | El secreto de cliente que se crea para su aplicación. |
| redirect_uri | La URL de redirección para su aplicación. Esto debe coincidir con el redirect_uri que usó para obtener los tokens. |
| refresh_token | El token de actualización que recibió antes. |
Si tiene éxito, la respuesta para la solicitud POST contiene una cadena JSON que incluye el access_token y refresh_token, como se muestra en el siguiente ejemplo.
{
"token_type":"bearer",
"expires_in": 3600,
"scope":"office.onenote wl.sign-in wl.offline-access",
"access_token":"EwB4Aq...wE=",
"refresh_token":"MCVw8k...$$",
"user_id":"c519ea026ece84de362cfa77dc0f2348"
}
Actualice sus tokens almacenados para asegurarse de que su aplicación tenga tokens con la mayor vida útil.
Cerrar sesión de usuarios (aplicaciones de consumidor)
Para cerrar la sesión de un usuario, realice los siguientes pasos:
Elimine los tokens de acceso o los tokens de actualización en caché que haya recibido o almacenado.
Realice cualquier acción de cierre de sesión en la aplicación (por ejemplo, limpiar el estado local, quitar cualquier elemento almacenado en caché, etc.).
Realice una llamada al servicio de autorización con esta dirección URL:
https://login.live.com/oauth20_logout.srf
?client_id={client_id}
&redirect_uri={redirect_uri}
Esta llamada elimina todas las cookies que permiten el inicio de sesión único y garantiza que se le solicitará al usuario que inicie sesión.
| Parámetro de cadena de consulta requerido | Descripción |
|---|---|
| client_id | El valor de id. de cliente que se ha creado para su aplicación. |
| redirect_uri | La URL de redirección para su aplicación. Esto debe coincidir con el redirect_uri que usó para obtener los tokens. |
Después de eliminar las cookies, el navegador redirige a su URL de redirección. La página de redirección se carga sin especificar ninguna opción de cadena de consulta de autenticación, lo que significa que el usuario ha cerrado la sesión.
Revocar el acceso
Los usuarios pueden revocar un acceso de la aplicación a su cuenta visitando la página Administrar de la cuenta Microsoft.
Cuando se revoca el consentimiento de su aplicación, cualquier token de actualización que se haya proporcionado anteriormente en su aplicación ya no será válido. Recibirá la siguiente respuesta si intenta actualizar el token:
{
"error":"invalid_grant",
"error_description":"The request was denied because one or more scopes requested are unauthorized or expired. The user must first sign in and grant the client application access to the requested scope."
}
Tendrá que repetir el flujo de autenticación para solicitar un nuevo token de acceso y actualización desde el principio.
Autenticar con Azure AD (aplicaciones de empresa)
Si su aplicación usa permisos de aplicaciones (en lugar de delegar permisos), consulte Autenticación OneNote y permisos de la aplicación Azure AD.
- Registrar su aplicación y obtener un id. de cliente y secreto
- Elegir permisos de OneNote
- Hacer que los usuarios inicien sesión y obtener un token de acceso
- Obtener un nuevo token de acceso una vez que caduque
Registre su aplicación y obtenga una id. de cliente y secreto (aplicaciones empresariales)
Para comenzar, debe registrar una aplicación con Microsoft. Este proceso crea una entidad de servicio a la que se vincula desde su aplicación, y genera el id. de cliente y el secreto que envía al servicio de autorización.
Haga esto si su aplicación accede solo a blocs de notas de empresa, o si accede a blocs de notas de consumidor y de empresa.
Para registrar su aplicación en una cuenta empresarial de Azure AD asociada a una suscripción de Office 365, deberá:
Obtener una cuenta de Office 365 con permisos de administrador global para una cuenta empresarial de Office 365
Puede probar o comprar una suscripción de Desarrollador de Office 365 o suscribirse al plan de aptitud.
Aprovisionar OneDrive for Business en su cuenta empresarial
Esto hace que la aplicación de OneNote esté disponible para que pueda especificar los permisos de OneNote. Para verificar si OneDrive for Business está aprovisionado, inicie sesión en OneNote Online con sus credenciales de Office 365 (una cuenta profesional o educativa como
someone@example.comosomeone@example.onmicrosoft.com)Si ve sus blocs de notas, ya está listo. Si ve "Lo sentimos, parece que no podemos obtener sus blocs de notas...", elija Ir a mi cuenta > Siguiente. Cuando se cargue su página de OneDrive for Business, vuelva atrás y actualice OneNote Online para completar el aprovisionamiento.
Nota
Nota: los sitios personales de los usuarios deben aprovisionarse antes de poder acceder a sus blocs de notas. La API de OneNote intentará aprovisionar automáticamente sus sitios si es necesario.
Asociar su suscripción de Office 365 con una suscripción de Azure
Esto le permite registrar y administrar su aplicación en Azure AD. (más información)
Si no tiene una suscripción de Azure, realice la Opción 1 en la siguiente sección. Si tiene una, realice la Opción 2.
Importante
Usted y sus usuarios deben tener una cuenta de Office 365 con una licencia válida de Office 365. Las cuentas de usuario sin licencias válidas no podrán ver ningún bloc de notas en OneNote Online, y fallarán las llamadas API a sus blocs de notas. Los administradores de Office 365 pueden verificar el estado y asignar/desasignar licencias.
Nota
Suscriptores de MSDN: puede ser elegible para una suscripción gratuita de Desarrollador de Office 365, así como ahorros adicionales cuando active su beneficio de Azure. Verifique sus beneficios en la página de suscripciones MSDN.
Asociar su suscripción de Azure con su suscripción de Office 365
Opción 1: regístrese para obtener una suscripción de Azure con credenciales de administrador para su suscripción a Office 365. Haga esto si no tiene una suscripción de Azure. Este proceso asocia las suscripciones.
Inicie sesión en el Portal de administración de Azure con sus credenciales administrativas de Office 365 (una cuenta profesional o educativa como
someone@example.comosomeone@example.onmicrosoft.com).En la página No se encontraron suscripciones, elija Regístrese en Microsoft Azure. La página de Registro se cargará, mostrando cierta información de su suscripción de Office 365. Esta cuenta se convertirá en un administrador de servicios para la nueva suscripción de Azure.
La experiencia de Registro depende de si tiene una versión de prueba o una suscripción de pago de Office 365:
Si tienes una suscripción de prueba, escriba su información de pago en la página Prueba gratuita. No se le cobrará a menos que decida cambiarse a una suscripción de pago.
Si acepta el acuerdo de suscripción, los detalles de la oferta y la declaración de privacidad, marque la casilla y elija Comprar. Se abre la página Suscripciones para su nueva cuenta de Azure. Las suscripciones de prueba reciben un crédito de 200,00 $ que se puede usar en 30 días. Puede cancelar la suscripción desde esta página en cualquier momento.
Si tiene una suscripción de pago, complete su información de contacto y luego elija Registrarse. Después de que se cree su suscripción, elija Comenzar a administrar mi servicio para abrir el Portal de administración de Azure.
Opcion 2: asocie una suscripción existente de Azure con una suscripción de Office 365. Haga esto si tiene una cuenta Microsoft que sea un administrador de servicios o coadministrador de su suscripción de Azure. Este proceso hace que la cuenta Microsoft sea un administrador global de la cuenta empresarial de Office 365.
Inicie sesión en el Portal de administración de Azure con sus credenciales de cuenta Microsoft (como
someone@live.com).En el cajón en la parte inferior de la página, elija Nuevo > Servicios de aplicaciones > Active Directory > Directorio > Crear personalizado.
En la ventana Agregar directorio, elija Usar el directorio existente para el directorio.
Elija Estoy listo para ser desconectado ahora y haga clic en la marca de verificación. Esto lo desconecta del portal.
Vuelva a iniciar sesión con las credenciales de administrador global para la cuenta empresarial de Office 365 que desea asociar (una cuenta profesional o educativa como
someone@example.comosomeone@example.onmicrosoft.com).Cuando se le pregunte si desea usar el directorio con Azure, elija continuar> Cerrar sesión ahora.
Cierre el navegador y luego vuelva a abrir el Portal de administración de Azure.
Inicie sesión de nuevo con sus credenciales de cuenta Microsoft y elija Active Directory en el panel de exploración. Su directorio de Office 365 debe aparecer en la lista en la pestaña Directorio.
Registrar su aplicación en el Portal de administración de Azure
Inicie sesión en el Portal de administración de Azure. Use las credenciales de administrador para su suscripción de Azure.
En el panel de exploración, elija Active Directory.
Elija el directorio donde desea registrar su aplicación y luego abra la pestaña Aplicaciones.
En el cajón en la parte inferior de la página, elija Agregar > Agregar una aplicación que mi organización está desarrollando.
Escriba un nombre fácil de usar para la aplicación y elija el tipo de aplicación:
Aplicación web o API web (aplicaciones basadas en navegador o servidor)
a. Elija Aplicación web o API web.
b. Para la URL de inicio de sesión, escriba la URL donde los usuarios inician sesión y usan su aplicación.
c. Para el URI de id. de aplicación, escriba un identificador exclusivo para su aplicación. Este debe estar en un dominio personalizado verificado.
d. Para la URL de respuesta, escriba la URL a la que se redirigirá en respuesta a una solicitud de OAuth 2.0. Esto no tiene por qué ser un extremo físico, pero debe ser un URI válido.
e. Para que la aplicación esté disponible para las cuentas empresariales externas de Azure, elija Sí en La aplicación es multicuenta.
Aplicación de cliente nativo (aplicaciones instaladas en un dispositivo)
a. Elija Aplicación de cliente nativo.
b. Escriba un URI de redirección al cual redireccionar en respuesta a una solicitud de OAuth 2.0. Esto no tiene por qué ser un extremo físico, pero debe ser un URI válido.
Para las aplicaciones web, Azure genera tanto un id. de cliente como un secreto (o clave) de aplicación. Para aplicaciones nativas, Azure genera un id. de cliente. Guarde estos valores.
Consulte la Documentación de Office 365 para obtener instrucciones detalladas sobre el registro de aplicaciones.
Elegir los ámbitos de permisos de aplicaciones de OneNote (aplicaciones de empresa)
Los ámbitos de permiso representan los niveles de acceso al contenido de OneNote. Usted solicita los permisos que su aplicación necesita y los usuarios conceden o deniegan el acceso cuando inician sesión en su aplicación. Los usuarios solo pueden otorgar los permisos que tienen.
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 aprovisionado OneDrive for Business en su cuenta empresarial.
Elija el nivel más bajo de permisos que su aplicación necesita para hacer su trabajo, y guarde los cambios. Puede solicitar múltiples ámbitos.
Ámbitos para blocs de notas personales que son propiedad del usuario actual
Si solamente está trabajando con blocs de notas personales en OneDrive for Business, elija entre los siguientes ámbitos.
| Ámbito (empresa) | Permiso en Azure Portal | Descripción |
|---|---|---|
| Notes.Create | Crear páginas en blocs de notas de OneNote | Puede ver los títulos de los blocs de notas y secciones; crear nuevas páginas en cualquier ubicación. No puede ver ni editar páginas existentes. |
| Notes.ReadWrite.CreatedByApp | Acceso de bloc de notas de OneNote de solo aplicación | Puede ver los títulos de los blocs de notas y secciones; crear nuevas páginas; cambiar el nombre de secciones; ver y modificar páginas creadas por la aplicación. No puede ver o modificar páginas creadas por otras aplicaciones o en secciones protegidas con contraseña. |
| Notes.Read | Ver los blocs de notas de OneNote | Puede ver el contenido de las secciones y blocs de notas. No puede crear nuevas páginas; modificar páginas existentes; acceder a secciones protegidas por contraseña. |
| Notes.ReadWrite | Permite ver y modificar los blocs de notas de OneNote | Puede ver los títulos de los blocs de notas y secciones; ver y modificar todas sus páginas; crear nuevas páginas; cambiar el nombre de las secciones. No puede acceder a las secciones protegidas por contraseña. |
Ámbitos para blocs de notas de sitios y grupos a los que el usuario actual puede acceder
Si está trabajando con blocs de notas de sitio de SharePoint o blocs de notas de grupo unificado de Office 365, elija entre los siguientes ámbitos. Estos permisos también se aplican a los blocs de notas personales del usuario actual, pero no a los blocs de notas personales que comparten otros usuarios. El acceso al contenido personal compartido actualmente no se admite.
| Ámbito (empresa) | Permiso en Azure Portal | Descripción |
|---|---|---|
| Notes.Read.All | Ver los blocs de notas de OneNote en su organización | Puede ver el contenido de las secciones y blocs de notas en todos los blocs de notas a los que el usuario que ha iniciado sesión tiene acceso. No puede crear nuevas páginas; modificar páginas existentes; acceder a secciones protegidas por contraseña. |
| Notes.ReadWrite.All | Ver y modificar los blocs de notas de OneNote en su organización | Puede ver los títulos de los blocs de notas y secciones; ver y modificar todas las páginas; cambiar el nombre de todas las secciones; crear nuevas páginas en todos los blocs de notas a los que el usuario que ha iniciado sesión tiene acceso. No puede acceder a las secciones protegidas por contraseña. |
Para conocer los permisos utilizados para acceder a los blocs de notas personales en OneDrive, consulte Elegir permisos de OneNote (aplicaciones de consumidor).
Hacer que los usuarios inicien sesión y obtener un token de acceso (aplicaciones de empresa)
Su aplicación inicia el proceso de inicio de sesión poniéndose en contacto con el servicio de autorización. Si los usuarios aún no han iniciado sesión o no han dado su consentimiento, el servicio les pedirá las credenciales y que acepten los permisos solicitados por su aplicación. Si la autenticación y la autorización tienen éxito, recibirá un token de acceso que incluirá en sus solicitudes a la API de OneNote.
Importante
Trate los tokens de acceso y los tokens de actualización de forma tan segura como lo haría con la contraseña de un usuario.
Nota
Dependiendo de su plataforma, es posible que pueda usar un SDK para simplificar los flujos de autenticación.
Obtener un token de acceso es un proceso de dos pasos:
- Haga que el usuario inicie sesión y obtenga un token de autorización.
- Intercambie el código por un token de acceso.
Este proceso representa el Flujo de concesión del Código de autorización. Si desea usar el flujo implícito, deberá editar el archivo de manifiesto. Consulte Configurar su aplicación para permitir el flujo de concesión implícito de OAuth 2.0 en Registrar su aplicación web basada en navegador.
Paso 1. Haga que el usuario inicie sesión y obtenga un token de autorización. Para iniciar el proceso de inicio de sesión, cargue la siguiente solicitud de URL en un explorador web o control de explorador web.
La URL a continuación usa el punto de conexión de la cuenta empresarial común, que es válido para cualquier aplicación.
https://login.microsoftonline.com/common/oauth2/authorize
?response_type=code
&client_id={client-id}
&redirect_uri={redirect-uri}
&resource=https://onenote.com/
| Parámetro de cadena de consulta requerido | Descripción |
|---|---|
| response_type | El tipo de flujo de autenticación que está utilizando. En este caso, code (código). |
| client_id | El identificador de cliente que se crea para su aplicación. |
| redirect_uri | La URL de redirección para su aplicación. |
| resource | El recurso al que necesita acceso. En este caso, https://onenote.com/ |
Después de una autenticación y autorización con éxito, el explorador web redirecciona a su URI de redirección con un parámetro code anexado a la URL, como se muestra en el siguiente ejemplo. Copie el valor código a usar en el paso 2. Este código es válido por unos minutos.
https://your-redirect-uri/
?code=AAABAA...AA
&session_state=d56e3523-614e-4fbe-bf89-3ba0f065954b
Paso 2. Intercambie el código de autorización por un token de acceso y un token de actualización. Envíe la siguiente solicitud HTTP con una cadena URL codificada correctamente en el cuerpo del mensaje.
POST https://login.microsoftonline.com/common/oauth2/token
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code
&client_id={client-id}
&client_secret={client-secret}
&redirect_uri={redirect-uri}
&code={code}
&resource=https://onenote.com/
| Parámetro de cuerpo obligatorio | Descripción |
|---|---|
| grant_type | El tipo de concesión de la solicitud. En este caso, authorization_code. |
| client_id | El identificador de cliente que se crea para su aplicación. |
| client_secret | Aplicaciones web y API web solamente. El secreto de cliente que se crea para su aplicación. |
| code | El código que recibió como parámetro de URL en el paso anterior. |
| redirect_uri | La URL de redirección para su aplicación. Esto debe coincidir con el redirect_uri en la primera solicitud. |
| resource | El recurso al que necesita acceso. En este caso, https://onenote.com/ |
Si tiene éxito, la respuesta contiene una cadena JSON que incluye el access_token y refresh_token, como se muestra en el siguiente ejemplo. El token de acceso es válido durante el número de segundos que se especifique en la propiedad expires_in.
{
"token_type":"Bearer",
"expires_in":"3600",
"scope":"Notes.ReadWrite",
"expires_on":"1446588136",
"not_before":"1446584236",
"resource":"https://onenote.com/",
"access_token":"eyJ0eX...2-w",
"refresh_token":"AAABAAA...IAA",
"id_token":"eyJ0eX...fQ."
}
Consulte Flujo de concesión del Código de autorización para obtener más información sobre la implementación de Azure AD del flujo de concesión de código, incluidos los parámetros adicionales que puede usar en las solicitudes.
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/me/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 usuarios pueden permanecer conectados y no tienen que dar su consentimiento de nuevo a menos que cierren la sesión o revoquen los permisos.
Obtener un nuevo token de acceso una vez que caduque (aplicaciones de empresa)
Puede solicitar un nuevo token de acceso usando el token de actualización, o repitiendo el proceso de autenticación desde el principio.
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 solicitudes.
Envíe la siguiente solicitud HTTP con una cadena URL codificada correctamente en el cuerpo del mensaje.
La URL en el siguiente ejemplo usa el extremo de la cuenta empresarial común, que es válido para cualquier aplicación.
POST https://login.microsoftonline.com/common/oauth2/token
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token
&client_id={client-id}
&client_secret={client-secret}
&redirect_uri={redirect-uri}
&refresh_token={refresh-token}
&resource={resource-id}
| Parámetro de cuerpo obligatorio | Descripción |
|---|---|
| grant_type | El tipo de concesión de la solicitud. En este caso, refresh_token. |
| client_id | El identificador de cliente que se crea para su aplicación. |
| client_secret | Aplicaciones web y API web solamente. El secreto de cliente que se crea para su aplicación. |
| redirect_uri | La URL de redirección para su aplicación. |
| refresh_token | El token de actualización que recibió antes. |
| resource | El recurso al que necesita acceso. En este caso, https://onenote.com/ |
Si tiene éxito, la respuesta para la solicitud POST contiene una cadena JSON que incluye el access_token y refresh_token, como se muestra en el siguiente ejemplo.
{
"token_type":"Bearer",
"expires_in":"3600",
"scope":"Group.Read.All Notes.ReadWrite",
"expires_on":"1447656020",
"not_before":"1447652120",
"resource":"https://onenote.com/",
"access_token":"eyJ0eX...Jww",
"refresh_token":"AAABAAA...IAA"
}
Actualice sus tokens almacenados para asegurarse de que su aplicación tenga tokens con la mayor vida útil.
SDK para el desarrollo en OneNote
Las aplicaciones de OneNote pueden usar el SDK de la API de OneDrive para obtener los tokens de acceso necesarios para todas las solicitudes a la API de OneNote. El SDK hace que la autenticación sea más fácil para usted. Solo tiene que proporcionar su información de identidad e integrar algunas llamadas, y el SDK se ocupará de todo, desde el inicio de sesión hasta el consentimiento para obtener, almacenar y actualizar tokens. A continuación, podrá realizar llamadas REST a la API de OneNote. Nuestro tutorial de iOS muestra cómo puede usar el SDK en una aplicación de OneNote.
Todas las versiones del SDK admiten la autenticación de cuentas de Microsoft (para blocs de notas de consumidor) y algunas también son compatibles con Azure Active Directory (para blocs de notas de empresa). Consulte la documentación de OneDrive para obtener la lista actual de plataformas compatibles.
Nota
El SDK de la API de OneDrive reemplaza al SDK de Live. El SDK de Live está obsoleto, pero seguirá siendo compatible con las aplicaciones de OneNote existentes que lo utilicen. Para un desarrollo nuevo, use el SDK de la API de OneDrive.
En el futuro puede que proporcionemos bibliotecas que a la vez gestionen la autenticación y admitan llamadas nativas a la API de OneNote, pero por ahora puede usar el SDK de la API de OneDrive.
Como alternativa, las aplicaciones empresariales pueden usar la Biblioteca de autenticación de Active Directory (ADAL) para acceder a Office 365 y a los blocs de notas alojados en SharePoint. Puede considerar el uso de ADAL directamente si no hay un SDK disponible para su plataforma o si desea tener más control sobre el proceso de autenticación. Nuestro tutorial de ASP.NET MVC muestra cómo puede usar ADAL en una aplicación de OneNote.
Importante
Para interactuar con el contenido y los recursos de OneNote, siempre debe usar la API de OneNote. No use la API de OneDrive.
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 usuario 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.