Configurar o Microsoft Entra ID com a API do Microsoft Graph

O Microsoft Entra ID (anteriormente conhecido como Azure Active Directory, Azure AD) é uma solução de gerenciamento de identidade e acesso baseada em nuvem. Este artigo explica como integrar o Microsoft Entra ID ao MyQ para fornecer autenticação de usuários e outros serviços.

Crie uma conexão com o Microsoft Entra ID

Acesse MyQ > Configurações > Conexões.
Clique em Adicionar e selecione Microsoft Entra ID na lista.
Insira um Título para sua conexão e selecione o Modo de sua preferência:
- Criar automaticamente: o MyQ X configura o aplicativo do Azure necessário para acessar as informações do usuário do Entra ID.
- Configurar manualmente: configure o aplicativo do Azure manualmente. Selecione esta opção se desejar gerenciar todos os aspectos da configuração da integração.
Passe para a seção correspondente abaixo.

Criar automaticamente

Este modo permite que o administrador faça com que o MyQ crie o Aplicativo Corporativo (Entidade de Serviço) em seu locatário e conceda a esse aplicativo permissões para acessar usuários do Entra ID.

Considerações

Se você hesitar em conceder acesso administrativo, mesmo que temporário, para a criação de um segredo do cliente, o procedimento de conexão automática com o ODB não estará disponível para uso. Nesses casos, é recomendável criar manualmente um aplicativo no ambiente do Azure da sua organização e configurar você mesmo a conexão com o MyQ X (modo “Configuração manual”). Essa abordagem garante que você mantenha controle total sobre as permissões do aplicativo e os aspectos de segurança da conexão, alinhando-se às políticas de segurança específicas e aos requisitos de conformidade da sua organização.

Pré-requisitos

Para criar a entidade de serviço no tenant do cliente, são necessárias as funções de Administrador de Aplicativos ou Administrador de Aplicativos em Nuvem.
Para conceder consentimento de administrador à entidade de serviço, é necessária a função de Administrador Global.
Para o acabamento de todas as etapas da configuração automática, é necessária a função de Administrador Global.

Etapas para configurar automaticamente o aplicativo Microsoft Entra ID

O administrador faz login com sua conta de Administrador do Azure. A entidade de serviço do MyQ X Entra ID Connector é criada no locatário.
O administrador concede a permissão delegada para gerenciar aplicativos do Azure.
1. Permissões solicitadas nesta etapa:
  Application.ReadWrite.All (para recuperar uma chave de segurança)
  Directory.Read.All (para ler o nome de domínio padrão no locatário conectado, para que ele possa ser exibido no MyQ).
O administrador concede ao aplicativo corporativo MyQ X Entra ID Connector permissões para ler Usuários e Grupos e concede o consentimento de administrador.
- Permissões solicitadas nesta etapa:
  Group.Read.All
  User.Read.All
Assim que o processo for concluído, o conector do Microsoft Entra ID é salvo, e os detalhes da conexão são armazenados com segurança no MyQ.

Autorização da conexão com o Entra ID

A conexão automática com o Entra ID pode ser alterada ou mudada para manual após ter sido criada. Ao clicar com o botão direito do mouse na conexão, a opção “Autorizar novamente” ficará disponível no menu de contexto.

Gerenciamento de aplicativos

A validade do segredo é de 2 anos. Certifique-se de trocar a chave quando estiver prestes a expirar. Você pode fazer isso com a opção “Autorizar” no MyQ. Quando faltarem 30 dias para o vencimento do segredo, o MyQ enviará um aviso de verificação de integridade.
As credenciais para entidades de serviço não são visíveis no portal do Azure. Elas podem ser gerenciadas por meio do PowerShell ou da API do Microsoft Graph.
Caso precise revogar o acesso do aplicativo ou o Segredo usado atualmente, basta excluir todo o aplicativo corporativo MyQ X Entra ID Connector no Azure e criar um novo com a opção “Reautorizar” no MyQ.

Informações adicionais

Se a configuração automática for concluída novamente, ela não criará uma nova instância do aplicativo no locatário, mas o aplicativo atual será atualizado (por exemplo, um novo segredo será criado na entidade de serviço no locatário). Se o aplicativo MyQ X Entra ID Connector tiver sido removido do Azure, ele será criado novamente.
A entidade de serviço (aplicativo corporativo) é criada no locatário após a Etapa 1 (sem as permissões necessárias, que são concedidas na Etapa 2). A Etapa 2 pode ser concluída posteriormente (clicando com o botão direito do mouse no MyQ X Entra ID Connector e selecionando “Reautorizar”).
Para entender melhor o que o MyQ está fazendo neste modo, a Microsoft explica esse método em sua documentação para desenvolvedores – Entenda o consentimento do usuário e do administrador da perspectiva do desenvolvedor de aplicativos

Configuração manual

Configuração do aplicativo Microsoft Entra ID

Faça login no portal do Microsoft Azure e acesse “Registros de aplicativos”.
Clique em “Novo registro” para criar um novo aplicativo ou selecione um aplicativo existente.
Se estiver criando um novo aplicativo, defina o Nome e, em “Tipos de conta suportados”, selecione a opção “Apenas contas neste diretório organizacional (somente {nome do locatário} – locatário único)” se todos os seus usuários forem membros do seu locatário. Um aplicativo multilocatário também pode ser usado, se necessário, dependendo do público-alvo do aplicativo.
Você pode ignorar as configurações de URI de redirecionamento por enquanto (descritas na etapa 7). Clique em “Registrar” para criar o aplicativo.
Na tela Visão geral do aplicativo, acesse Permissões de API e selecione API do Microsoft Graph e o tipo de permissão necessário (Delegada ou de aplicativo), conforme ilustrado abaixo.
- As seguintes permissões são necessárias:
  - Microsoft Graph \ Group.Read.All
  - Microsoft Graph \ User.Read
  - Microsoft Graph \ User.Read.All
- Observe que o sistema também solicitará automaticamente os seguintes escopos do OpenID Connect durante a autenticação do usuário para permitir uma verificação de identidade aprimorada.
  - openid (permite o login e a leitura do perfil básico do usuário)
  - email (acesso ao endereço de e-mail do usuário)
  - profile (acesso às informações básicas do perfil do usuário)
O status “Concedido para o diretório padrão” precisa ser definido em todas as permissões. Você pode conceder o consentimento de administrador ao aplicativo usando os botões na parte superior da lista de permissões.

Use “Adicionar uma permissão” para adicionar uma nova permissão.
Use “Conceder consentimento de administrador para o diretório padrão” para definir o status da permissão como “Concedido para o diretório padrão”.
Vá para Autenticação e, em Configurações da plataforma, clique em Adicionar uma plataforma.
- Selecione Web e liste todas as URLs de redirecionamento para seu aplicativo MS Entra ID. Para as URLs reais, use o nome do host (e a porta) do seu servidor no seguinte formato:
  https://{hostname:port}/auth
- Além disso, clique em “Adicionar uma plataforma” e selecione “Aplicativo de página única”. Adicione a seguinte URL de redirecionamento, certificando-se de incluir a barra final:
  https://helper.myq.cz/openid/
  Todos os servidores que usam o logon do Entra ID devem ter um redirecionamento definido no aplicativo do Azure. Certifique-se de executar esta etapa para cada servidor de impressão e servidor central em sua implantação.
- Clique em “Configurar” para cada configuração de plataforma.
Na página de visão geral do aplicativo, salve o ID do cliente e o ID do diretório (locatário), pois eles são necessários para a configuração do MyQ.
Clique em “Adicionar um certificado ou segredo” ao lado de “Credenciais do cliente” e conclua as seguintes etapas:
1. Clique em Novo segredo do cliente.
2. Adicione uma Descrição.
3. Defina a validade da chave.
4. Clique em “Adicionar”.
5. Salve o valor da chave do segredo do cliente, pois você precisará dele para a configuração no MyQ e não poderá recuperá-lo posteriormente.

Configuração no MyQ

Acesse MyQ > Configurações > Conexões para conectar o MyQ ao Microsoft Entra ID. Clique em “Adicionar” e selecione “Microsoft Entra ID” na lista. Na janela pop-up, preencha as informações necessárias:

Título: Adicione um título para a conexão.
ID do locatário: insira o ID do diretório (locatário) que você salvou do Microsoft Entra.
ID do cliente: insira o ID do aplicativo (cliente) que você salvou do Microsoft Entra.
Chave de segurança: insira o valor (secreto) que você salvou do Microsoft Entra.

Clique em “Salvar”. Sua conexão com o Microsoft Entra ID está concluída.

Login único da Microsoft

Para usar o logon único da Microsoft:

Habilite a opção “Usar como servidor de autenticação” na fonte de sincronização do Microsoft Entra ID — guia “Usuários” antes de sincronizar usuários ou habilite o Microsoft Entra ID como servidor de autenticação manualmente para usuários selecionados em seus detalhes na página principal “Usuários”.
Nas configurações do servidor de autenticação do Microsoft Entra ID, habilite a exibição do método de login “Entrar com a Microsoft”.

Quando o login único da Microsoft está ativado, o botão “Entrar com a Microsoft” é sempre exibido na página de login da interface do usuário da MyQ Web, mas somente os usuários que utilizam o Microsoft Entra ID como servidor de autenticação podem usá-lo para fazer login. Qualquer tentativa de usar o login único da Microsoft por um usuário que não utilize o sistema de autenticação do Microsoft Entra ID resultará em um erro.

O que acontece quando um usuário tenta fazer login com a Microsoft na interface do usuário da Web do MyQ:

O usuário clica no botão de login único.
- Se o usuário não estiver conectado à Microsoft no navegador, ele será redirecionado para a página de login da Microsoft para fazer o login e, em seguida, será conectado ao MyQ com a conta fornecida.
- Se o usuário estiver conectado a duas contas da Microsoft, ele será redirecionado para a página de login da Microsoft e poderá escolher a conta com a qual deseja continuar.
O logout na interface do usuário da Web do MyQ desconecta o usuário apenas localmente, não da Microsoft.
Nos casos em que vários servidores de autenticação Microsoft Entra ID estiverem configurados, a página de login exibirá vários botões “Continuar com a Microsoft”.

Limitações

Usuários que utilizam o servidor de autenticação Microsoft Entra ID não podem fazer login na MyQ Web User Interface com um PIN. No entanto, eles podem usar seu PIN nos terminais embarcados do MyQ e no MyQ Desktop Client.

A sincronização e a autenticação por meio do Microsoft Entra ID com o Microsoft Graph agora podem ser realizadas seguindo estas etapas:

Adicionar um servidor de autenticação do Microsoft Entra ID em MyQ > Configurações > Servidores de autenticação.
Adicionar uma fonte de sincronização do Microsoft Entra ID em MyQ > Configurações > Sincronização de usuários.

Sincronização e autenticação multilocatária do Entra ID (Azure)

Agora é possível usar vários locatários do Entra ID em ambientes MyQ para sincronizar e realizar a autenticação de usuários. Isso é particularmente útil em configurações de infraestrutura de impressão compartilhada, como as encontradas no setor público, onde várias organizações gerenciam impressoras a partir de um único local, enquanto cada uma usa seu próprio Entra ID.

Siga um dos processos descritos acima, mas repita-o para configurar várias instâncias. Certifique-se de atribuir nomes claros e exclusivos a cada locatário, o que permitirá que os usuários identifiquem qual é o relevante para seu uso.