Autenticação e permissões do OneNote
Aplica-se a: Blocos de anotações de consumidor no OneDrive | Blocos de anotações empresariais no Office 365
O OneNote usa a conta da Microsoft (anteriormente, Live Connect) e o Active Directory do Azure para fornecer acesso seguro aos blocos de anotações do OneNote. Antes de poder acessar os blocos de anotações, primeiro é necessário autenticar usando a conta da Microsoft ou o Azure AD e obter um token de acesso.
A conta da Microsoft é usada para acessar os blocos de anotações do consumidor no OneDrive, e o Azure AD é usado para acessar blocos de notas corporativos no Office 365.
Ambos os serviços de autorização implementam o protocolo OAuth 2.0 para fornecer os tokens de acesso necessários para interagir com o OneNote. Todas as solicitações para a API do OneNote devem incluir um token de acesso válido no cabeçalho Autorização.
Este artigo descreve os processos relacionados à autenticação pelos quais você é responsável: registrar seu aplicativo para obter um ID do cliente, especificar as permissões necessárias e chamar o serviço de autorização para conectar usuários e obter um token de acesso.
Dependendo da sua plataforma, você poderá usar um SDK para simplificar os fluxos de autenticação.
Observação
O OneNote eventualmente oferecerá suporte ao modelo de autenticação única e ao registro de aplicativo fornecido pelo modelo de aplicativo v2.0. Fique atento para as atualizações relacionadas no Blog do desenvolvedor do OneNote.
Experimente as APIs
Siga as etapas neste artigo para obter um token de acesso usando sua ferramenta de rede favorita, como o Fiddler.
Autenticar usando a conta da Microsoft (aplicativos do consumidor)
- Registrar o aplicativo e obter um ID do cliente e um segredo
- Escolha as permissões do OneNote
- Conecte usuários e obtenha um token de acesso
- Obter um novo token de acesso após expirar
Registrar o aplicativo e obter um ID do cliente e um segredo (aplicativos do consumidor)
Para começar, você precisa registrar um aplicativo na Microsoft. Esse processo cria uma entidade de serviço para a qual você cria um link do seu aplicativo e gera o ID e o segredo do cliente que você envia para o serviço de autorização.
Faça isso se seu aplicativo acessa apenas blocos de anotações de consumidores ou acessa blocos de anotações corporativos e de consumidores.
Entre na Central de desenvolvedores da conta da Microsoft com sua conta da Microsoft. (Se você estiver desenvolvendo um aplicativo da Windows Store, faça isso.)
Se não tiver uma conta da Microsoft, você precisará criar uma. Você deve usar um endereço de e-mail que verifique regularmente. Podemos tentar contatá-lo para destacar seu aplicativo em nossa página Aplicativos em destaque ou se notarmos um tráfego de rede inesperado vindo do seu aplicativo. Não enviaremos spam nem venderemos suas informações.
Escolha Criar aplicativo.
Insira o nome que você deseja que os usuários vejam quando receberem solicitação para conceder permissões ao seu aplicativo e escolha o idioma principal do seu aplicativo.
Se você aceitar os termos de uso e a política de Privacidade e Cookies, escolha Aceito para continuar com o registro.
Na página Configurações da API, escolha seu tipo de aplicativo e forneça informações sobre seu aplicativo:
Aplicativos Web (aplicativos do lado do servidor)
a. Escolha Não para Aplicativo cliente móvel ou de desktop.
b. Para o domínio de destino, insira a URL de serviço.
c. Insira a URL de redirecionamento para a qual você deseja que os usuários sejam direcionados depois que eles forem autenticados e tiverem concedido acesso ao seu aplicativo.
Aplicativos nativos (instalados em um dispositivo)
a. Escolha Sim para Aplicativo cliente móvel ou de desktop.
b. (Opcional) Para o domínio de destino, insira a URL de serviço móvel.
c. (Opcional) Para a URL de redirecionamento, insira uma URL válida. Isso funciona como um identificador para seu aplicativo e não precisa ser um ponto de extremidade físico.*
Salve o ID e o segredo do cliente mostrados na página Configurações do aplicativo e na URL de redirecionamento, caso tenha fornecido uma.
Aplicativos da Windows Store
Se estiver criando um aplicativo do Windows, você registrará seu aplicativo no Centro de Desenvolvimento do Windows. Isso fornecerá a identidade do pacote (SID do pacote) que você usará em vez do ID do cliente.
Entre no Centro de Desenvolvimento do Windows com sua conta da Microsoft.
No painel, escolha Crie um novo aplicativo e insira o nome do seu aplicativo.
No Visual Studio, clique com o botão direito do mouse no projeto de aplicativo da Windows Store e escolha Loja > Associar Aplicativo à Loja.
Na janela Associar seu aplicativo à Windows Store, entre com sua conta da Microsoft, escolha seu aplicativo e depois escolha Próximo > Associado. Isso adiciona as informações de registro necessárias da Windows Store ao manifesto do aplicativo.
Para um aplicativo universal do Windows, repita as duas etapas anteriores para o projeto do Windows Phone.
Escolher escopos de permissão do OneNote (aplicativos do consumidor)
Escopos de permissão representam os níveis de acesso ao conteúdo do OneNote. Você solicita as permissões de que seu aplicativo precisa e os usuários concedem ou negam acesso quando fazem login no seu aplicativo. Os usuários só podem conceder as permissões que possuem.
Escolha o nível mais baixo de permissões que seu aplicativo precisa para funcionar. Você pode solicitar vários escopos.
| Escopo (consumidor) | Descrição |
|---|---|
| office.onenote_create | Pode exibir uma lista dos blocos de anotações do OneNote do usuário e criar novas páginas, mas não pode exibir ou editar as páginas existentes. Pode enumerar a hierarquia dos blocos de anotações do usuário e criar páginas em qualquer local. |
| office.onenote_update_by_app | Pode criar, exibir e modificar todas as páginas criadas pelo aplicativo. |
| office.onenote_update | Pode criar, exibir e modificar qualquer conteúdo nos blocos de anotações e páginas do OneNote do usuário. |
| office.onenote | Pode exibir blocos de anotações e páginas do OneNote, porém não modificá-los. |
| wl.signin | Um escopo de permissão de conta da Microsoft. Permite que seu aplicativo aproveite os recursos de logon único. |
| wl.offline_access | Um escopo de permissão de conta da Microsoft. Permite que seu aplicativo receba um token de atualização para poder trabalhar offline mesmo quando o usuário não está ativo. Este escopo não está disponível para o fluxo de token. |
Para permissões usadas para acessar os blocos de anotações do Office 365, veja Escolha as permissões do OneNote (aplicativos corporativos).
Conectar os usuários e obter um token de acesso (aplicativos do consumidor)
Seu aplicativo inicia o processo de login entrando em contato com o serviço de autorização. Se os usuários ainda não estiverem conectados ou não tiverem consentido, o serviço solicitará credenciais e consentirá as permissões solicitadas pelo seu aplicativo. Se a autenticação e a autorização forem bem-sucedidas, você receberá um token de acesso incluído nas suas solicitações para a API do OneNote.
Importante
Trate os tokens de acesso e atualize os tokens com a mesma segurança de uma senha de usuário.
Observação
Dependendo da sua plataforma, você poderá usar um SDK para simplificar os fluxos de autenticação.
Escolha seu fluxo de autenticação. Ambos são fluxos padrão do OAuth 2.0.
| Fluxo | Descrição |
|---|---|
| Fluxo de tokens | Obtém um token de acesso em uma chamada. Útil para acesso rápido, mas não fornece um token de atualização para acesso a longo prazo. Também chamado de fluxo Implícito. |
| Fluxo de códigos | Obtém um código de autorização na primeira chamada e troca o código por um token de acesso na segunda chamada. Quando usado com o escopo de permissão wl.offline-access, seu aplicativo recebe um token de atualização que permite o acesso de longo prazo. Também chamado de fluxo do Código de autorização. |
Conectar usuários com o fluxo de tokens
Carregue a seguinte solicitação de URL em um navegador da Web ou em um controle de navegador da Web.
GET https://login.live.com/oauth20_authorize.srf
?response_type=token
&client_id={client_id}
&redirect_uri={redirect_uri}
&scope={scope}
| Parâmetro da cadeia de caracteres de consulta obrigatória | Descrição |
|---|---|
| response_type | O tipo de fluxo de autenticação que você está usando. Nesse caso, token. |
| client_id | A ID do cliente criada para o aplicativo. |
| redirect_uri | A URL de redirecionamento que você registrou para seu aplicativo. Aplicativos móveis e de desktop que não especificaram uma podem usar isso: https://login.live.com/oauth20_desktop.srf |
| scope | Os escopos que seu aplicativo requer. Exemplo: office.onenote% 20wl.sign-in |
Após a autenticação e autorização bem-sucedidas, o navegador da Web redireciona para sua URL de redirecionamento e acrescenta parâmetros de acesso à URL. Os parâmetros incluem o access_token e o token_type, conforme mostrado no exemplo a seguir. O token de acesso é válido somente para o número de segundos especificado na propriedade expires_in.
https://your-redirect-url
#access_token=EwB4Aq...%3d
&token_type=bearer
&expires_in=3600
&scope=office.onenote wl.signin
&user_id=c519ea026ece84de362cfa77dc0f2348
Conectar usuários com o fluxo de código
Obter um token de acesso é um processo de duas etapas com o fluxo de código:
- Conecte o usuário e obtenha um código de autorização.
- Troque o código por um token de acesso.
Etapa 1. Conecte o usuário e obtenha um código de autorização. Para iniciar o processo de login, carregue a seguinte solicitação de URL em um navegador da Web ou em um controle de navegador da Web.
https://login.live.com/oauth20_authorize.srf
?response_type=code
&client_id={client-id}
&redirect_uri={redirect-uri}
&scope={scope}
| Parâmetro da cadeia de caracteres de consulta obrigatória | Descrição |
|---|---|
| response_type | O tipo de fluxo de autenticação que você está usando. Nesse caso, código. |
| client_id | A ID do cliente criada para o aplicativo. |
| redirect_uri | A URL de redirecionamento que você registrou para seu aplicativo. Aplicativos móveis e de desktop que não especificaram uma podem usar isso: https://login.live.com/oauth20_desktop.srf |
| scope | Os escopos que seu aplicativo requer. Exemplo: office.onenote wl.signin wl.offline_access |
Após a autenticação e autorização bem-sucedidas, o navegador da Web redireciona para sua URL de redirecionamento com um parâmetro de código acrescentado à URL, conforme mostrado no exemplo a seguir. Copie o valor do código a ser usado na etapa 2. Esse código é válido por alguns minutos.
https://your-redirect-uri
?code=M57010781-9e8c-e31e-ca0d-46bc104236c4
Etapa 2. Troque o código de autorização por um token de acesso e um token de atualização. Envie a seguinte solicitação HTTP com uma sequência de caracteres da URL codificada adequadamente no corpo da mensagem.
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 obrigatório do corpo | Descrição |
|---|---|
| grant_type | O tipo de concessão da solicitação. Nesse caso, authorization_code. |
| client_id | A ID do cliente criada para o aplicativo. |
| client_secret | O segredo do cliente criado para o seu aplicativo. |
| código | O código que você recebeu como um parâmetro de URL na etapa anterior. |
| redirect_uri | A URL de redirecionamento para seu aplicativo. Isso deve corresponder ao redirect_uri na primeira solicitação. |
Se bem-sucedida, a resposta irá conter uma cadeia de caracteres JSON que inclui o access_token-- e o refresh_token se você solicitou o escopo wl.offline_access, conforme mostrado no exemplo a seguir. O token de acesso é válido somente para o número de segundos especificado na propriedade 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"
}
Inclua o token de acesso em sua solicitação à API do OneNote
Todas as suas solicitações para a API do OneNote devem enviar o token de acesso como um token de portador no cabeçalho de Autorização. Por exemplo, a solicitação a seguir obtém cinco de seus blocos de anotações, classificados em ordem alfabética por nome:
GET https://www.onenote.com/api/v1.0/me/notes/notebooks?top=5
Authorization: Bearer {access-token}
Os tokens de acesso são válidos apenas por uma hora, portanto, você precisará obter tokens novos quando eles expirarem. Você deve verificar a validade do token antes de usá-lo e obter um novo token de acesso, se necessário. Os usuários podem permanecer conectados e não precisam consentir as permissões novamente, a menos que saiam do sistema ou revoguem as permissões.
Obter um token de acesso novo após expirar (aplicativos corporativos)
Solicite um novo token de acesso usando o token de atualização ou repetindo o processo de autenticação desde o início.
Quando o token de acesso expira, as solicitações para a API retornam uma resposta 401 Unauthorized. O aplicativo deverá lidar com essa resposta e verificar a validade do token antes de enviar solicitações.
Envie a seguinte solicitação HTTP com uma sequência de caracteres da URL codificada adequadamente no corpo da mensagem.
Você recebeu um token de atualização se solicitou a permissão wl.offline_access e usou o fluxo de 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 obrigatório do corpo | Descrição |
|---|---|
| grant_type | O tipo de concessão da solicitação. Nesse caso, refresh_token. |
| client_id | A ID do cliente criada para o aplicativo. |
| client_secret | O segredo do cliente criado para o seu aplicativo. |
| redirect_uri | A URL de redirecionamento para seu aplicativo. Isso deve corresponder ao redirect_uri que você usou para obter os tokens. |
| refresh_token | O token de atualização recebido anteriormente. |
Se bem-sucedida, a resposta para a solicitação POST irá conter uma cadeia de caracteres JSON que inclui o access_token e o refresh_token, conforme mostrado no exemplo a seguir.
{
"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"
}
Atualize os tokens armazenados para que o aplicativo tenha tokens com uma vida útil mais longa.
Desconectar os usuários (aplicativos do consumidor)
Para cancelar a inscrição do usuário, execute as seguintes etapas:
Exclua os tokens de acesso em cache ou os tokens de atualização recebidos ou armazenados.
Execute qualquer ação de cancelamento de inscrição no seu aplicativo (por exemplo, limpeza de estado local, remoção de itens armazenados em cache etc.).
Faça uma chamada ao serviço de autorização usando esta URL:
https://login.live.com/oauth20_logout.srf
?client_id={client_id}
&redirect_uri={redirect_uri}
Essa chamada remove os cookies que ativam o logon único e garantem que o usuário será solicitado a fazer login.
| Parâmetro da cadeia de caracteres de consulta obrigatória | Descrição |
|---|---|
| client_id | O valor da ID do cliente criada para o aplicativo. |
| redirect_uri | A URL de redirecionamento para seu aplicativo. Isso deve corresponder ao redirect_uri que você usou para obter os tokens. |
Depois de remover os cookies, o navegador redireciona para sua URL de redirecionamento. A página de redirecionamento é carregada sem especificar nenhuma opção da sequência de caracteres de consulta de autenticação, o que significa que o usuário foi desconectado.
Revogar Acesso
Os usuários podem revogar o acesso de um aplicativo às suas contas ao acessar a página Gerenciar da conta da Microsoft.
Quando o consentimento para seu aplicativo é revogado, qualquer token de atualização fornecido anteriormente ao seu aplicativo deixa de ser válido. Você receberá a seguinte resposta se tentar atualizar o 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."
}
Você precisará repetir o fluxo de autorização para solicitar um novo acesso e atualizar o token desde o início.
Autenticar usando o Azure AD (aplicativos corporativos)
Se o seu aplicativo usar permissões de aplicativo (em vez de permissões de delegação), consulte Autenticação do OneNote e permissões de aplicativo do AD do Azure.
- Registrar o aplicativo e obter um ID do cliente e um segredo
- Escolha as permissões do OneNote
- Conecte usuários e obtenha um token de acesso
- Obter um novo token de acesso após expirar
Registrar o aplicativo e obter um ID do cliente e um segredo (aplicativos corporativos)
Para começar, você precisa registrar um aplicativo na Microsoft. Esse processo cria uma entidade de serviço para a qual você cria um link do seu aplicativo e gera o ID e o segredo do cliente que você envia para o serviço de autorização.
Faça isso se seu aplicativo acessa apenas blocos de anotações corporativos ou acessa blocos de anotações de consumidores e corporativos.
Para registrar seu aplicativo em um locatário do Azure AD associado a uma assinatura do Office 365, você precisará:
Obter uma conta do Office 365 com permissões de administrador global para um locatário do Office 365
Você pode experimentar ou comprar uma assinatura do Office 365 Developer, ou assinar um plano de qualificação.
Provisione o OneDrive for Business para seu locatário
Isso disponibiliza o aplicativo OneNote para que você possa especificar as permissões do OneNote. Para verificar se o OneDrive for Business está provisionado, faça login no OneNote Online com suas credenciais do Office 365 (uma conta de trabalho ou escola como
someone@example.comousomeone@example.onmicrosoft.com).Se você ver seus blocos de anotações, está tudo pronto. Se você ver "Desculpe, parece que não conseguimos pegar seus blocos de anotações...", escolha Vá para minha conta > Próximo. Quando a página do OneDrive for Business for carregada, volte e atualize o OneNote Online para concluir o provisionamento.
Observação
Os sites pessoais de seus usuários devem ser provisionados antes que você possa acessar seus blocos de anotações. A API do OneNote tentará provisionar automaticamente seus sites, se necessário.
Associar sua assinatura do Office 365 a uma assinatura do Azure
Isso permite que você registre e gerencie seu aplicativo no Azure AD. (saiba mais)
Se você não tiver uma assinatura do Azure, vá para a Opção 1 na próxima seção. Se você tiver uma, vá para a Opção 2.
Importante
Você e seus usuários devem ter uma conta do Office 365 com uma licença válida do Office 365. As contas de usuário sem licenças válidas não poderão ver nenhum bloco de anotações no OneNote Online e as chamadas de API para seus notebooks falharão. Os administradores do Office 365 podem verificar o status e atribuir licenças não atribuídas.
Observação
Assinantes do MSDN: vocês podem estar qualificados para uma assinatura gratuita do Office 365 Developer, assim como economias adicionais ao ativar seu benefício do Azure. Verifique seus benefícios na página de assinaturas do MSDN.
Associar sua assinatura do Azure à sua assinatura do Office 365
Opção 1: Inscreva-se para uma assinatura do Azure usando credenciais de administrador para sua assinatura do Office 365. Faça isso se você não tiver uma assinatura do Azure. Esse processo associa as assinaturas.
Entre no Portal de Gerenciamento do Azure com suas credenciais de administrador do Office 365 (uma conta de trabalho ou escola como
someone@example.comousomeone@example.onmicrosoft.com).Na página Nenhuma assinatura encontrada, escolha Criar conta no Microsoft Azure. A página Criar conta será carregada, mostrando algumas informações da sua assinatura do Office 365. Essa conta se tornará um administrador de serviços para a nova assinatura do Azure.
A experiência Criar conta depende se você tem uma assinatura de avaliação ou uma assinatura paga do Office 365:
Se você tiver uma assinatura de avaliação, insira suas informações de pagamento na página Avaliação gratuita. Você não será cobrado a menos que decida mudar para uma assinatura paga.
Se você concordar com o contrato de assinatura, os detalhes da oferta e a declaração de privacidade, marque a caixa e escolha Comprar. A página Assinaturas para sua nova conta do Azure é aberta. As assinaturas de avaliação recebem um crédito de $ 200,00 que podem ser usados no prazo de 30 dias. Você pode cancelar a assinatura desta página a qualquer momento.
Se você tiver uma assinatura paga, preencha suas informações de contato e escolha Criar conta. Depois que sua assinatura for criada, escolha Comece a gerenciar meu serviço para abrir o Portal de Gerenciamento do Azure.
Opção 2: Associe uma assinatura do Azure existente a uma assinatura do Office 365. Faça isso se você tem uma conta da Microsoft que é um administrador de serviços ou coadministrador para sua assinatura do Azure. Esse processo faz com que a conta da Microsoft seja um administrador global do locatário do Office 365.
Entre no Portal de gerenciamento do Azure com as credenciais da sua conta da Microsoft (como
someone@live.com).Na gaveta na parte inferior da página, escolha Novo > Serviços de aplicativos > Active Directory > Diretório > Criar personalizado.
Na janela Adicionar diretório, escolha Use o diretório existente para o diretório.
Escolha Estou pronto para sair agorae clique na marca de seleção. Isso faz com que você saia do portal.
Faça login novamente usando as credenciais globais de administrador do locatário do Office 365 que você deseja associar (uma conta de trabalho ou escola como
someone@example.comousomeone@example.onmicrosoft.com).Quando perguntado se deseja usar o diretório com o Azure, escolha continuar > Sair agora.
Feche o navegador e reabra o Portal de gerenciamento do Azure.
Faça login novamente com as credenciais da sua conta da Microsoft e escolha Active Directory no painel de navegação. Seu diretório do Office 365 deve estar listado na guia Diretório.
Registre seu aplicativo no Portal de gerenciamento do Azure
Entre no Portal de gerenciamento do Azure. Use as credenciais de administrador para sua assinatura do Azure.
No painel de navegação, escolha Active Directory.
Escolha o diretório no qual deseja registrar seu aplicativo e abra a guia Aplicativos.
Na gaveta na parte inferior da página, escolha Adicionar > Adicionar um aplicativo que minha organização está desenvolvendo.
Digite um nome amigável para o aplicativo e escolha o tipo de aplicativo:
Aplicativo Web ou API da Web (aplicativos baseados em navegador ou servidor)
a. Escolha Aplicativo Web e/ou API da Web.
b. Para a URL de login, insira a URL onde os usuários fazem login e usam seu aplicativo.
c. Para o URI do ID do aplicativo, insira um identificador exclusivo para seu aplicativo. Isso deve estar em um domínio personalizado verificado.
d. Para a URL de resposta, insira a URL para redirecionar em resposta a uma solicitação do OAuth 2.0. Isso não precisa ser um ponto de extremidade físico, mas deve ser uma URI válida.
e. Para disponibilizar o aplicativo para locatários externos do Azure, escolha Sim para O aplicativo é multilocatário.
Aplicativo cliente nativo (aplicativos instalados em um dispositivo)
a. Escolha Aplicativo cliente nativo.
b. Insira um URI de redirecionamento para redirecionar em resposta a uma solicitação do OAuth 2.0. Isso não precisa ser um ponto de extremidade físico, mas deve ser uma URI válida.
Para aplicativos Web, o Azure gera um ID de cliente e um segredo de aplicativo (ou chave). Para aplicativos cliente nativos, o Azure gera um ID do cliente. Salve esses valores.
Veja a Documentação do Office 365 para instruções detalhadas sobre o registro de aplicativos.
Escolher escopos de permissão do OneNote (aplicativos corporativos)
Escopos de permissão representam os níveis de acesso ao conteúdo do OneNote. Você solicita as permissões de que seu aplicativo precisa e os usuários concedem ou negam acesso quando fazem login no seu aplicativo. Os usuários só podem conceder as permissões que possuem.
No Portal de Gerenciamento do Azure, na seção Permissões para outros aplicativos da página de configuração do aplicativo, escolha Adicionar aplicativo.
Escolha o aplicativo OneNote e, em seguida, clique na marca de seleção no canto inferior direito. Se o OneNote não estiver listado, verifique se o OneDrive for Business foi provisionado para seu locatário.
Escolha o nível mais baixo de permissões de aplicativo que o seu aplicativo requer para executar o trabalho e salve as alterações. Você pode solicitar vários escopos.
Escopos para blocos de anotações pessoais pertencentes ao usuário atual
Se você estiver apenas trabalhando com blocos de anotações pessoais no OneDrive for Business, escolha dentre os seguintes escopos.
| Escopo (empresa) | Permissão no Portal do Azure | Descrição |
|---|---|---|
| Notes.Create | Criar páginas em blocos de anotações do OneNote | Pode exibir os títulos dos seus blocos de anotações e seções; criar novas páginas em qualquer local. O usuário não pode visualizar ou editar páginas existentes. |
| Notes.ReadWrite.CreatedByApp | Acesso ao bloco de anotações do OneNote somente para aplicativos | Pode exibir os títulos dos seus blocos de anotações e seções; criar novas páginas; renomear seções; visualizar e modificar as páginas criadas pelo app. Não é possível exibir ou modificar as páginas criadas por outros aplicativos ou em seções protegidas por senha. |
| Notes.Read | Exibir blocos de anotações do OneNote | Pode exibir o conteúdo de seus blocos de anotações e seções. O usuário não pode criar novas páginas; modificar páginas existentes; acessar seções protegidas por senha. |
| Notes.ReadWrite | Visualizar e modificar os blocos de anotações do OneNote | Pode exibir os títulos dos seus blocos de anotações e seções; visualizar e modificar todas as suas páginas; criar novas páginas; renomear seções. O usuário não pode acessar seções protegidas por senha. |
Escopos para blocos de anotações de sites e grupos que o usuário atual pode acessar
Se você estiver trabalhando com blocos de anotações de sites do SharePoint ou blocos de anotações de grupos unificados, escolha entre os seguintes escopos. Essas permissões também se aplicam aos blocos de anotações pessoais do usuário atual, mas não aos blocos de anotações pessoais compartilhados por outros usuários. O acesso ao conteúdo pessoal compartilhado não é suportado atualmente.
| Escopo (empresa) | Permissão no Portal do Azure | Descrição |
|---|---|---|
| Notes.Read.All | Exibir blocos de anotações do OneNote em sua organização | Pode visualizar o conteúdo de blocos de anotações e seções em todos os blocos de anotações aos quais o usuário conectado tem acesso. O usuário não pode criar novas páginas; modificar páginas existentes; acessar seções protegidas por senha. |
| Notes.ReadWrite.All | Exibir blocos de anotações do OneNote em sua organização | Pode ver os títulos de blocos de anotações e seções; visualizar e modificar todas as páginas; renomear todas as seções; criar novas páginas em todos os blocos de anotações aos quais o usuário conectado tenha acesso. O usuário não pode acessar seções protegidas por senha. |
Para permissões usadas para acessar blocos de anotações pessoais no OneDrive, veja Escolha as permissões do OneNote (aplicativos do consumidor).
Conectar os usuários e obter um token de acesso (aplicativos corporativos)
Seu aplicativo inicia o processo de login entrando em contato com o serviço de autorização. Se os usuários ainda não estiverem conectados ou não tiverem consentido, o serviço solicitará credenciais e consentirá as permissões solicitadas pelo seu aplicativo. Se a autenticação e a autorização forem bem-sucedidas, você receberá um token de acesso incluído nas suas solicitações para a API do OneNote.
Importante
Trate os tokens de acesso e atualize os tokens com a mesma segurança de uma senha de usuário.
Observação
Dependendo da sua plataforma, você poderá usar um SDK para simplificar os fluxos de autenticação.
Obter um token de acesso é um processo de duas etapas:
- Conecte o usuário e obtenha um código de autorização.
- Troque o código por um token de acesso.
Esse processo representa o Fluxo de Concessão do Código de Autorização. Se você quiser usar o fluxo implícito, precisará editar o arquivo de manifesto. Veja Configure seu aplicativo para permitir o fluxo de concessão implícita do OAuth 2.0 em Registre seu aplicativo Web baseado em navegador.
Etapa 1. Conecte o usuário e obtenha um código de autorização. Para iniciar o processo de login, carregue a seguinte solicitação de URL em um navegador da Web ou em um controle de navegador da Web.
A URL abaixo usa o ponto de extremidade do locatário common, que é válido para qualquer aplicativo.
https://login.microsoftonline.com/common/oauth2/authorize
?response_type=code
&client_id={client-id}
&redirect_uri={redirect-uri}
&resource=https://onenote.com/
| Parâmetro da cadeia de caracteres de consulta obrigatória | Descrição |
|---|---|
| response_type | O tipo de fluxo de autenticação que você está usando. Nesse caso, código. |
| client_id | A ID do cliente criada para o aplicativo. |
| redirect_uri | A URL de redirecionamento para seu aplicativo. |
| recurso | O recurso que você precisa acessar. Nesse caso, https://onenote.com/ |
Após a autenticação e autorização bem-sucedidas, o navegador da Web redireciona para sua URL de redirecionamento com um parâmetro de código acrescentado à URL, conforme mostrado no exemplo a seguir. Copie o valor do código a ser usado na etapa 2. Esse código é válido por alguns minutos.
https://your-redirect-uri/
?code=AAABAA...AA
&session_state=d56e3523-614e-4fbe-bf89-3ba0f065954b
Etapa 2. Troque o código de autorização por um token de acesso e um token de atualização. Envie a seguinte solicitação HTTP com uma sequência de caracteres da URL codificada adequadamente no corpo da mensagem.
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 obrigatório do corpo | Descrição |
|---|---|
| grant_type | O tipo de concessão da solicitação. Nesse caso, authorization_code. |
| client_id | A ID do cliente criada para o aplicativo. |
| client_secret | Apenas aplicativos Web e APIs da Web. O segredo do cliente criado para o seu aplicativo. |
| código | O código que você recebeu como um parâmetro de URL na etapa anterior. |
| redirect_uri | A URL de redirecionamento para seu aplicativo. Isso deve corresponder ao redirect_uri na primeira solicitação. |
| recurso | O recurso que você precisa acessar. Nesse caso, https://onenote.com/ |
Se bem-sucedida, a resposta irá conter uma sequência de caracteres JSON que inclui access_token e refresh_token, conforme mostrado no exemplo a seguir. O token de acesso é válido somente para o número de segundos especificado na propriedade 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."
}
Veja Fluxo de Concessão do Código de Autorização para saber mais sobre a implementação do fluxo de concessão de código do Azure AD, incluindo os parâmetros adicionais que você pode usar nas solicitações.
Inclua o token de acesso em sua solicitação à API do OneNote
Todas as suas solicitações para a API do OneNote devem enviar o token de acesso como um token de portador no cabeçalho de Autorização. Por exemplo, a solicitação a seguir obtém cinco de seus blocos de anotações, classificados em ordem alfabética por nome:
GET https://www.onenote.com/api/v1.0/me/notes/notebooks?top=5
Authorization: Bearer {access-token}
Os tokens de acesso são válidos apenas por uma hora, portanto, você precisará obter tokens novos quando eles expirarem. Você deve verificar a validade do token antes de usá-lo e obter um novo token de acesso, se necessário. Os usuários podem permanecer conectados e não precisam consentir as permissões novamente, a menos que saiam do sistema ou revoguem as permissões.
Obter um token de acesso novo após expirar (aplicativos corporativos)
Solicite um novo token de acesso usando o token de atualização ou repetindo o processo de autenticação desde o início.
Quando o token de acesso expira, as solicitações para a API retornam uma resposta 401 Unauthorized. O aplicativo deverá lidar com essa resposta e verificar a validade do token antes de enviar solicitações.
Envie a seguinte solicitação HTTP com uma sequência de caracteres da URL codificada adequadamente no corpo da mensagem.
A URL no exemplo a seguir usa o ponto de extremidade do locatário comum, que é válido para qualquer aplicativo.
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 obrigatório do corpo | Descrição |
|---|---|
| grant_type | O tipo de concessão da solicitação. Nesse caso, refresh_token. |
| client_id | A ID do cliente criada para o aplicativo. |
| client_secret | Apenas aplicativos Web e APIs da Web. O segredo do cliente criado para o seu aplicativo. |
| redirect_uri | A URL de redirecionamento para seu aplicativo. |
| refresh_token | O token de atualização recebido anteriormente. |
| recurso | O recurso que você precisa acessar. Nesse caso, https://onenote.com/ |
Se bem-sucedida, a resposta para a solicitação POST irá conter uma sequência de caracteres JSON que inclui access_token e refresh_token, conforme mostrado no exemplo a seguir.
{
"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"
}
Atualize os tokens armazenados para que o aplicativo tenha tokens com uma vida útil mais longa.
SDKs para o desenvolvimento do OneNote
Os aplicativos do OneNote podem usar o SDK da API do OneDrive para obter os tokens de acesso necessários para todas as solicitações à API do OneNote. O SDK torna a autenticação mais fácil para você. Basta fornecer os suas informações de identidade e integrar algumas chamadas que o SDK cuida de tudo, desde a entrada até consentimentos para obter, armazenar e atualizar tokens. Então, você pode fazer chamadas REST para a API do OneNote. O nosso tutorial para iOS mostra como você pode usar o SDK em um aplicativo do OneNote.
Todas as versões do SDK oferecem suporte à autenticação de conta da Microsoft (para blocos de anotações de consumidores) e algumas também oferecem suporte ao Active Directory do Azure (para blocos de aotações de empresas). Consulte a documentação do OneDrive para ver a lista atual de plataformas com suporte.
Observação
O SDK da API do OneDrive substitui o Live SDK. O Live SDK foi preterido, mas continuará oferecendo suporte aos aplicativos existentes do OneNote que o usam. Para novos desenvolvimentos, use o SDK da API do OneDrive.
Em algum momento, podemos fornecer bibliotecas que lidem com autenticação e ofereçam suporte a chamadas nativas para a API do OneNote, mas por enquanto você pode usar o SDK da API do OneDrive.
Como alternativa, os aplicativos corporativos podem usar a Biblioteca de Autenticação do Active Directory (ADAL) para acessar blocos de anotações hospedados no Office 365 e no SharePoint. Caso não haja nenhum SDK disponível para a sua plataforma ou se você quiser mais controle sobre o processo de autenticação, é possível usar a ADAL diretamente. O nosso tutorial do ASP.NET MVC mostra como você pode usar a ADAL em um aplicativo do OneNote.
Importante
Para interagir com conteúdos e recursos do OneNote, você deve sempre usar a API do OneNote. Não use a API do OneDrive.
Erros
Se houver erros com a autenticação, o navegador da Web será redirecionado para uma página de erro. A página de erro apresenta uma mensagem amigável ao usuário final, mas a URL da página inclui parâmetros adicionais que podem ajudar a depurar o que aconteceu. Os parâmetros de URL são incluídos como um marcador, por exemplo: #error={error_code}&error_description={message}
Se o usuário optar por não fornecer consentimento para seu aplicativo, o fluxo será redirecionado para sua URL de redirecionamento e incluirá os parâmetros de erro.
Para informações detalhadas sobre como tratar erros, veja Tratamento de erros no OAuth 2.0.