Resumo

Este artigo demostra como criar um aplicativo no portal AZURE para clientes que utilizam a pesquisa de XML na plataforma MICROSOFT OFFICE 365.

Configuração no Portal da Azure

Por muitos anos, os aplicativos usaram a autenticação básica para se conectar a servidores, serviços e pontos de extremidade de API. A autenticação básica simplesmente significa que o aplicativo envia um nome de usuário e uma senha a cada solicitação. Tradicionalmente, a autenticação básica é habilitada por padrão na maioria dos servidores ou serviços e é simples de configurar.

A Microsoft, em seu serviço OFFICE 365, esta removendo a capacidade de usar a autenticação básica no Exchange Online para Exchange ActiveSync (EAS), POP, IMAP, Remote PowerShell, Exchange Web Services (EWS), OAB (Catálogo de Endereços Offline), Autodiscover, Outlook para Windows e Outlook para Mac e estão passando a trabalhar com a autenticação moderna. 

A autenticação moderna (autorização baseada em token OAuth 2.0) tem muitos benefícios e melhorias que ajudam a atenuar os problemas na autenticação básica. Por exemplo, os tokens de acesso OAuth têm um tempo de vida útil limitado e são específicos para os aplicativos e recursos para os quais são emitidos, portanto, não podem ser reutilizados.

Mas o que é que oAuth 2.0 ?

OAuth 2 é um protocolo de autorização que permite que uma aplicação se autentique em outra. Para que isso aconteça, uma aplicação pede permissão de acesso para um usuário, sem que para isso ela tenha acesso a alguma senha dele. O usuário pode conceder ou não o acesso à aplicação. Depois da permissão ser aceita, caso o usuário precise alterar a senha de acesso, a permissão continuará válida para a aplicação e, caso necessário, a permissão dada à aplicação pode ser revogada a qualquer momento também.

Provavelmente você já clicou em algum botão escrito “Logar com sua conta do Google” ou “Logar com sua conta do Facebook” quando você está em alguma outra aplicação, para evitar de ter que fazer na mão algum cadastro. Neste caso, você está dando a autorização de uma aplicação terceira a usar os recursos da sua aplicação, neste caso o Google ou o Facebook. Essas aplicações têm acesso limitado às informações de usuários através do protocolo HTTP. OAuth 2 é utilizado nos mais diversos tipos de autenticação, como em telas de login e na autenticação de API.

A implementação desta forma de autenticação moderna, foi projetada pensado no ambiente WEB para ser desenvolvida. 

Na imagem acima, podemos ver como geralmente funciona o fluxo de autorização:

1 - Solicitação de autorização: Nessa primeira etapa o cliente (aplicação) solicita a autorização para acessar os recursos do servidor do usuário

2 - Concessão de autorização: Se o usuário autorizar a solicitação, a aplicação recebe uma concessão de autorização.

3 - Concessão de autorização: O cliente solicita um token de acesso ao servidor de autorização (API) através da autenticação da própria identidade e da concessão de autorização.

4 - Token de acesso: Se a identidade da aplicação está autenticada e a concessão de autorização for válida, o servidor de autorização (API) emite um token de acesso para a aplicação. O cliente já vai ter um token de acesso para gerenciar e a autorização nessa etapa já está completa.

5 - Token de acesso: Quando o cliente precisar solicitar um recurso ao servidor de recursos, basta apresentar o token de acesso.

6 - Recurso protegido: O servidor de recursos fornece o recurso para o cliente, caso o token de acesso dele for válido.

O servidor de autorização é responsável pelo SSO (Single Sign On), que centraliza as credenciais dos acessos dos usuários e faz a autenticação, gerencia as permissões dos usuários e emite os tokens de acesso.

Para começar a trabalhar com este tipo de autenticação, primeiramente é necessário criar um aplicativo no portal da azure.

Após logar na conta de adminstrador do portal, acesse o recurso de "AZURE ACTIVE DIRECTORY":

Em seguida, opção "Registro de Aplicativo":

E adicione um novo registro de aplicativo:

Em seguida, teremos que configurar as permissões para API e EWS API para o novo aplicativo. Isto pode ser feito através da opção "Ver Permissões de API" e depois "Adicionar Permissão":

As permissões devem ser selecionadas conforme as opções abaixo:

Logo em seguida, iremos criar a autenticação para o aplicativo:

As linhas abaixo devem ser informadas manualmente:

Para finalizar, é necessário criar a palavra secreta, usando a opção "Certificados e Segredos" e depois adicionando um novo secredo do cliente:

Depois que o segredo do cliente for criado, armazene o valor do segredo do cliente em algum lugar, pois não será possível ver o valor inteiro depois de sair desta rotina.

Logo em seguida, é necessário obter o ID do Aplicativo (cliente) ou "client-id" conforme abaixo:

Para registrar o aplicativo acima, nos baseamos no artigo abaixo que pode ser uma fonte de consulta também.

https://www.emailarchitect.net/eagetmail/ex/c/23.aspx#create-your-application-in-azure-portal

Configuração no WSGE

Tendo estas duas informações, valor do segredo do cliente e o ID do aplicativo, é necessário acessar a rotina NEM001 e configurar conforme abaixo:

1 - Endereço do servidor Office 365 e deve ser especificado conforme acima;

2 - Usuário que será utilizado para recuperar os e-mails;

3 - Não será necessário informar a senha;

4 - Marcar conexão SSL/TLS;

5 - Porta que será usada para a conexão e deve ser configurado conforme acima;

6 - Para efeito de testes, desmarcar esta opção, pois caso esteja marcado, irá eliminar todo o contéudo da caixa de e-mail depois que recuperar os anexos;

7 - Informar aqui o ID do aplicativo obtido no portal da Azure no cadastro do aplicativo;

8 - Informar aqui o segredo ou palavra secreta obtido no portal da Azure no cadastro do aplicativo; 

9 - Informar o endereço de redirecionamento: Este endereço será usado para que depois da autenticação, a rotina de Auth do portal do Office 365, envie os dados de token através desta URL. Para testes considerar: http://localhost/OAuth2/OAuth2/Callback.html (Para este item, veja uma explicação adicional no final desta artigo).

10 - Este será o endereço que fara a conexão entre o SGE e a rotina de autenticação do Office 365 e para efeito de testes deve ser o endereço interno onde esta o site do webapp. Normalmente é http://localhost/SGE/Run.html?View=Auth2SGE&psTheme=Df_Flat_Desktop&sModulo=MEN (Para este item, veja uma explicação adicional no final desta artigo).

11 - Este botão usará o token acesso gerado e usará para fazer o login no Exchange Office 365 para efeito de validação do token.

12 - Este botão será o botão que irá chamar a rotina de geração do token acesso, abrindo o navegador e indo para o site especificado no item 10.

13 - Este botão irá copiar a informação de token de acesso que esta armazenada no banco de dados do SGE. Apenas para bater com o que esta no retorno da autenticação.

Abaixo demonstramos o processo para a primeira autenticação, iniciando pelo botão de "Autenticar":

O botão abrirá o navegador padrão com a tela acima e deve ser iniciado o processo clicando no botão "Iniciar Autenticação".

Como aqui já usamos a rotina antes, ela já identifica que já foi autenticado e não pede mais uma tela com usuário e senha da conta do Office 365. Caso esta situação não tenha acontecido ainda, será aberto uma outra janela solicitando o usuário e senha e depois será emitido a mensagem acima caso o acesso seja concedido.

O token de acesso gerado tem uma vida de utilização de em média 60-90 minutos. Depois disto é necessáro gerar novamente.  Veja: https://learn.microsoft.com/pt-br/azure/active-directory/develop/access-tokens#access-token-lifetime

1 - Código do token de acesso é uma string com mais de 2000 caracteres;

2 - É o tempo que ira expirar este token;

3 - Data e hora que a última autenticação foi concedida.

No retorno desta tela acima, os dados já serão gravados no SGE e poderão ser verificados no NEM001:

Em seguida, para efeito de testes somente, poderá ser clicado no botão "Token Acesso" (1) e teremos o conteúdo pronto para ser colado, por exemplo, no bloco de notas e comparado com o que foi retornado no navegador.

Em seguida, poderemos testar o token de acesso autenticando na conta Office 365, clicando no botão "Testar Configurações" (2):

Feito isto, a rotina NEP023 já pode ser usada. 

Nesta mesma rotina, também temos o mesmo botão de "Autenticar" (1) para fazer todo o procedimento que foi feito pelo mesmo botão mas pela rotina NEM001, abrindo o navegador também.

URL de Redirecionamento (URL_Redirect) e URL de LOGIN

No exemplo acima, estamos sempre usando o http://localhost e para efeito de testes, tudo tem que ser testado primeiramente no mesmo computador/ambiente onde esta instalado o WebApp. Este será o localhost tanto para chamar a URL de login como para a URL de redirecionameto.

Isto significa que o WSGE, as rotinas de NEM001 e NEP023 devem ser testadas na mesma máquina que o WebApp. Funcionando desta form, o primeiro passo para a configuração esta correto e podemos partir para a segunda fase que é liberar o acesso para que isto funcione no ambiente de rede da empresa.

No momento de registrar o aplicativo no portal da Azure, temos uma etapa onde informamos onde estará a URL de Redirecionamento (URL_REDIRECT) e para testes colocamos o http://localhost. Isto é feito na opção "Autenticação":

Acima podemos notar que o http://localhost/OAuth2/OAuth2/Callback.html é o endereço liberado pois estamos testando tudo na máquina onde esta instalado o WebApp e lá é o localhost.

Para o ambiente de produção, onde o usuário não estará no locahost, é necessário a configuração de um endereço que seja chamado de fora da empresa para dentro dos servidores: 

Em nosso ambiente de testes aqui, fizemos uma regra no firewall do servidor para que as requisições de navegação da porta 80/443 fossem desviadas para o nosso servidor onde esta instalado o WebApp e cadastramos o endereço acima na liberação de autenticação. Note que quem irá chamar este endereço será a rotina de autentiacação do Office 365 e ela conterá no corpo da URL vários parâmetros inclusive o token de acesso que é devolvido desta forma. Este mesmo endereço deve ser informado no NEM001, no campo de "URL de Redirecionamento"

Além do exposto acima, existem mais duas regras que devem ser observadas pela autenticação Auth:

1. A URL de redrecionamento somente irá funcionar se o endereço base de retorno for o mesmo endereço base de saída, ou seja, o URL de Login SGE no NEM001 tem que ter o mesmo início https://177.43.35.58:5460/SGE/Run.html?View=Auth2SGE&psTheme=Df_Flat_Desktop&sModulo=MEN.
2. Note que os endereços tem que possuir HTTPS e não HTTP, ou seja, um certificado é necessário.