Autenticação do OneNote e permissões de aplicativo do Azure AD
Aplica-se a: Blocos de anotações empresariais no Office 365
Autenticar usando o Azure AD (aplicativos empresariais):
- Registrar o aplicativo e obter um ID do cliente e um segredo
- Escolher escopos de permissão de aplicativo do OneNote
- Obter o consentimento do administrador
- Obter 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 empresariais)
Veja Registrar o aplicativo e obter um ID do cliente e um segredo.
Escolher escopos de permissão de aplicativo do OneNote (aplicativos empresariais)
Escopos de permissão representam níveis de acesso ao conteúdo do OneNote. Uma permissão de aplicativo é concedida ao aplicativo pelo administrador de uma organização e pode ser usada somente para acessar dados de propriedade dessa organização e de seus funcionários. Por exemplo, a API do OneNote apresenta várias permissões de aplicativo que proporcionam o seguinte:
- Exibir as anotações de todos os usuários
- Exibir e modificar anotações de todos os usuários
Siga estas etapas para atribuir as permissões de aplicativo do OneNote ao seu aplicativo:
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 for listado, verifique se o OneDrive for Business foi provisionado para seu locatário.
Escolha o menor nível de permissões de aplicativo que o aplicativo necessita para executar o seu trabalho e salve as alterações. Você pode solicitar vários escopos.
Escopos para permissões de aplicativo
Se você estiver acessando blocos de anotações usando permissões de aplicativo, escolha um dos seguintes escopos.
| Escopo (empresa) | Permissão no Portal do Azure | Descrição |
|---|---|---|
| Notes.Read.All | Exibir as anotações de todos os usuários | Permite que o aplicativo visualize as anotações do OneNote de todos os usuários na organização, sem um usuário conectado. O aplicativo não pode criar novas anotações, modificar anotações existentes ou visualizar anotações em seções protegidas por senha. |
| Notes.ReadWrite.All | Exibir e modificar anotações de todos os usuários | Permite que o aplicativo visualize e modifique as anotações do OneNote de todos os usuários na organização, sem um usuário conectado. O aplicativo não pode acessar anotações em seções protegidas por senha. |
Obter o consentimento do administrador
Recomendado: Faça logon do usuário no seu aplicativo
Normalmente, quando você cria um aplicativo que usa permissões de aplicativo, o aplicativo requer uma página ou exibição na qual o administrador aprova as permissões do aplicativo. Essa página pode fazer parte do fluxo de logon do aplicativo, parte das configurações do aplicativo ou pode ser um fluxo de "conexão" dedicado. Em muitos casos, faz mais sentido o aplicativo mostrar essa exibição de "conexão" somente após o usuário fazer logon com uma conta da Microsoft corporativa ou de estudante.
Ao fazer logon do usuário no seu aplicativo, você poderá identificar a organização à qual o usuário pertence antes de solicitar que o usuário aprove as permissões do aplicativo. Embora não seja estritamente necessário, isso pode ajudar você a criar uma experiência mais intuitiva para seus usuários. Para fazer logon do usuário, siga os nossos tutoriais do protocolo v2.0.
Solicitar as permissões de um administrador do diretório
Quando você estiver pronto para solicitar permissões do administrador da organização, poderá redirecionar o usuário para o ponto de extremidade de consentimento do administrador. Você pode fazer a chamada API conforme abaixo:
// 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
Você também pode testar a solicitação acima em um navegador; insira o seguinte URL na barra de endereços do seu navegador (crie um URL válido seguindo estas instruções).
// 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
Esta tabela descreve os parâmetros usados na solicitação anterior:
| Parâmetro | Condição | Descrição |
|---|---|---|
| locatário | Obrigatório | O locatário do diretório do qual você deseja solicitar permissão. Pode estar no formato de um nome amigável ou GUID. Se você não sabe a qual locatário o usuário pertence e deseja permitir que ele faça logon em qualquer locatário, use common. |
| client_id | Obrigatório | ID de Aplicativo que o Portal de Registro de Aplicativos atribuiu a seu aplicativo. |
| redirect_uri | Obrigatório | O URI de redirecionamento para onde você deseja que a resposta seja enviada para que o aplicativo trate da situação. Ele deve corresponder exatamente a um dos URIs de redirecionamento registrados no portal, exceto que ele deve ser codificado por URL e pode ter segmentos de caminho adicionais. |
| estado | Recomendado | Um valor incluído na solicitação e que também será retornado na resposta do token. Pode ser uma cadeia de caracteres de qualquer conteúdo que você desejar. O estado é usado para codificar as informações sobre o estado do usuário no aplicativo antes da solicitação de autenticação ter ocorrido, como a página ou o modo de exibição em que ele estava. |
Será exibida uma caixa de diálogo de consentimento do administrador que você deve aprovar.
Resposta bem-sucedida
Se o administrador aprovar as permissões do seu aplicativo, a resposta bem-sucedida será parecida com esta:
GET https://login.microsoftonline.com/{tenant}/Consent/Grant
Esta tabela descreve os valores retornados na resposta anterior:
| Parâmetro | Descrição |
|---|---|
| locatário | O locatário do diretório que concedeu ao seu aplicativo as permissões solicitadas, no formato GUID. |
Resposta de erro
Se o administrador não aprovar as permissões do aplicativo, a resposta com falha será parecida com esta:
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.
Esta tabela descreve os valores retornados na resposta anterior:
| Parâmetro | Descrição |
|---|---|
| locatário | O locatário do diretório que concedeu ao seu aplicativo as permissões solicitadas, no formato GUID. |
Após receber uma resposta bem sucedida do ponto de extremidade de configuração do aplicativo, o aplicativo receberá as permissões solicitadas. Agora você poderá solicitar um token para o recurso que deseja.
Observação
- O consentimento do administrador é uma etapa única para um locatário específico.
- Se deseja que seu aplicativo execute locatários .her, é necessário configurá-lo como um aplicativo multilocatário no Azure AD.
- O consentimento do administrador é uma etapa obrigatória, seja o aplicativo executado em seu próprio locatário, seja em outro locatário
- O aplicativo também poderá usar permissões delegadas, além das permissões do aplicativo (contudo, o consentimento do administrador ainda será necessário).
Obter um token de acesso (aplicativos empresariais)
Após adquirir a autorização necessária para o aplicativo, obtenha os tokens de acesso para as APIs.
Para obter um token usando as credenciais concedidas do cliente, envie uma solicitação POST conforme abaixo:
// 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
Esta tabela descreve os parâmetros usados na solicitação anterior:
| Parâmetro | Condição | Descrição |
|---|---|---|
| grant_type | Obrigatório | Deve ser client_credentials. |
| client_id | Obrigatório | A ID do aplicativo que o Portal de registro de aplicativos atribuiu ao seu aplicativo. |
| client_secret | Obrigatório | O segredo do aplicativo gerado para o seu aplicativo no portal de registro de aplicativos. É muito importante que seja em formato de URL codificada |
| recurso | Obrigatório | O valor passado para o parâmetro resource nessa solicitação deve ser o identificador de recurso (URI do ID do Aplicativo) do recurso desejado. Para a API do OneNote, o valor é https://onenote.com/. Esse valor informa ao ponto de extremidade do token que, de todas as permissões de aplicativo diretas configuradas para o aplicativo, ele deve emitir um token para aquelas associadas ao recurso desejado. |
Resposta bem-sucedida
Uma resposta bem-sucedida será parecida com esta:
{
"token_type": "Bearer",
"expires_in": "3600",
"resource": "https:\/\/onenote.com\/",
"access_token": "eyJ0eXAiOiJKV1Qi..."
}
Esta tabela descreve os valores usados na solicitação anterior:
| Parâmetro | Descrição |
|---|---|
| token_type | Indica o valor de tipo de token. O único tipo ao qual o Azure AD dá suporte é bearer. |
| expires_in | Por quanto tempo o token de acesso é válido (em segundos). |
| recurso | O identificador de recurso (URI do ID do Aplicativo) do recurso onde este token pode ser usado. |
| access_token | O token de acesso solicitado. O aplicativo pode usar esse token para se autenticar no recurso protegido, como uma API Web. |
Resposta de erro
Uma resposta de erro será parecida com esta (neste exemplo, um valor inválido para o client_secret foi fornecido na solicitação):
{
"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"
}
Esta tabela descreve os valores usados na solicitação anterior:
| Parâmetro | Descrição |
|---|---|
| erro | Uma string de código de erro que pode ser usada para classificar os tipos de erros ocorridos e lidar com eles. |
| error_description | Uma mensagem de erro específica que ajudará a identificar a causa raiz de um erro de autenticação. |
| error_codes | Uma lista de códigos de erro específicos do STS que podem ajudar com diagnósticos. |
| timestamp | A hora em que o erro ocorreu. |
| trace_id | Um identificador exclusivo para a solicitação que pode ajudar com diagnósticos. |
| correlation_id | Um identificador exclusivo para a solicitação que pode ajudar com diagnósticos entre componentes. |
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/users/foo@example.com/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 administradores não precisam conceder permissões novamente, a menos que revoguem as permissões.
Obter um token de acesso novo após expirar (aplicativos empresariais)
Quando o token de acesso expirar, as solicitações para a API retornarão uma resposta 401 Unauthorized. O aplicativo deverá lidar com essa resposta e verificar a validade do token antes de enviar as solicitações.
Você pode solicitar um novo token de acesso repetindo o processo descrito anteriormente neste tópico na seção Obter um token de acesso.
Atualize os tokens armazenados para que o aplicativo tenha tokens com uma vida útil mais longa.
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 apresentará uma mensagem amigável ao usuário final, porém, a URL da página de erro incluirá informações adicionais que poderão ajudar a depurar o problema. Os parâmetros de URL são incluídos como marcadores, por exemplo: #error={error_code}&error_description={message}
Se o administrador não fornecer o consentimento para o aplicativo, o fluxo será redirecionado para o URL de redirecionamento e incluirá os parâmetros de erro.
Para informações detalhadas sobre como lidar com erros, veja Manipulação de Erro no OAuth 2.0.