Use o OAuth com compartilhamento de recursos entre origens para conectar um aplicativo de página única ao Microsoft Dynamics 365

Publicado: janeiro de 2017

Aplicável a: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Com Atualização do Microsoft Dynamics CRM Online 2016 e Microsoft Dynamics 365 locais com Implantação para a Internet (IFD), é possível criar aplicativos de página única (Single Page Apps, SPAs) que usam JavaScript para trabalhar com dados do Microsoft Dynamics 365. Para tal, o compartilhamento de recursos entre origens (Cross-Origin Resource Sharing, CORS) é habilitado para que seus SPAs possam ignorar restrições de navegador que normalmente evitam solicitações que cruzam limites de domínio.

Neste tópico

Os SPAs e política de mesma origem

Use o CORS com Microsoft Dynamics 365 (online)

Como a adal.js funciona

Preparando-se para usar a ADAL.js com um SPA

Os SPAs e política de mesma origem

Os SPAs dependem do uso extensivo do JavaScript do cliente para criar uma única página dinâmica que não precisa carregar novas páginas. Em vez disso, eles usam XMLHTTPRequests para recuperar dados e outros recursos do servidor. Os SPAs funcionam bem quando os dados e recursos existem no mesmo domínio que o aplicativo. No entanto, para proteger o acesso a dados e recursos em outros domínios, todos os navegadores modernos impõem uma política de mesma origem para evitar que sites usem dados e recursos de sites em um domínio diferente. O CORS permite obter acesso a recursos em outro domínio. Criar um SPA para acessar dados do Microsoft Dynamics 365 sem CORS não é uma opção viável.

Use o CORS com Microsoft Dynamics 365 (online)

A especificação de compartilhamento de recursos entre origens fornece uma descrição detalhada de como implementar e usar o CORS. Ela explica tudo sobre vários cabeçalhos e pedidos de comprovação que você precisa aplicar para fazer com que o CORS funcione. A boa notícia é que você não precisa se tornar um especialista em CORS para usá-lo com Microsoft Dynamics 365. A parte do servidor foi criada para você, sendo necessário apenas saber como utilizá-la. Não é preciso entender todos os mecanismos internos do CORS para usá-lo com Microsoft Dynamics 365. Em vez disso, você pode usar a Biblioteca de Autenticação do Azure Active Directory para JavaScript (adal.js), que cuidará de boa parte da complexidade do CORS para você. Como os usuários do Dynamics 365 (online) e da Implantação para a Internet (IFD) são autenticados por meio do Azure Active Directory, a ADAL.js é a forma compatível para autenticação de usuários do SPA.

Como a adal.js funciona

A biblioteca central é a adal.js. Você pode acessar a versão minimizada dessa biblioteca em https://secure.aadcdn.microsoftonline-p.com/lib/1.0.0/js/adal.min.js. O projeto e a documentação do Github estão em https://github.com/AzureAD/azure-activedirectory-library-for-js.

A biblioteca adal.js library contém os recursos de baixo nível para autenticação por meio do OAuth2. A Adal.js foi criada para ser usada com outras estruturas; por exemplo, há uma biblioteca adal-angular.js que foi criada para ser usada com a estrutura Angular. A forma como você trabalha com essa biblioteca é para definir determinadas propriedades de configuração. Daí em diante, a biblioteca aguardará até que ocorram eventos que acionam o fluxo de interação. Ela poderia simplesmente chamar a função login ou, se seu aplicativo tem comportamentos de roteamento, a autenticação pode ser iniciada pela forma como o controlador dessa rota é configurado.

Quando a autenticação é necessária, o usuário é levado à página de entrada na qual ele pode autenticar suas credenciais. Após a autenticação bem-sucedida, ele é redirecionado à página de chamada com as informações do token anexadas como um fragmento (usando Nº) à URL. Isso permite que o SPA adquira o token e armazene-o em cache no local ou no armazenamento de sessão. Ou seja, toda a página é recarregada após a autenticação, mas, dessa vez, as informações sobre o usuário autorizado estão disponíveis e o aplicativo pode continuar a chamar a API da Web do Dynamics 365 ou outros recursos.

Ao chamar a API da Web do Dynamics 365, você deve incluir o valor do token em um cabeçalho Authorization com sua XMLHTPPRequest. Porém, como os tokens têm uma expiração, o intuito é se certificar de que eles não expirarão enquanto as pessoas estiverem usando seu SPA. Lembre-se: inserir novas credenciais requer que todo o conteúdo da sua página do SPA seja transferido para a página de entrada. Se isso ocorresse enquanto as pessoas estivessem fazendo algo, seria uma experiência de usuário muito ruim. Para garantir que isso não ocorra, você coloca suas chamadas de API da Web em uma função acquireToken para que a validade do token possa ser verificada e atualizada, se necessário, sem levar o usuário a uma página de entrada.

Preparando-se para usar a ADAL.js com um SPA

Para configurar seu SPA para funcionar com a adal.js, você precisará:

1. Registrar seu aplicativo com o locatário do Azure Active Directory

2. Exportar seu manifesto de aplicativo registrado e editá-lo para permitir o fluxo implícito do OAuth2 e, depois, exportar o arquivo JSON de volta ao seu registro de aplicativo.

3. Definir variáveis de configuração em seu SPA com informações desse registro.

   Você precisará incluir o seguinte:

   • A URL para sua organização do Microsoft Dynamics 365

   • O nome do locatário do Active Directory que sua organização usa para autenticação

   • A ID do cliente que você obtém ao registrar o aplicativo

   • A URL para o local onde o SPA será implantado ou depurado durante o desenvolvimento

O conjunto de etapas necessárias está descrito em Passo a passo: Registrando e configurando o aplicativo SimpleSPA com adal.js.

Confira Também

Autenticar usuários no Microsoft Dynamics 365
Conecte-se ao serviços da Web de Microsoft Dynamics 365 usando OAuth
Ativar diretório e autenticação com base em declarações

Microsoft Dynamics 365

© 2017 Microsoft. Todos os direitos reservados. Direitos autorais