Provedores de identidade

Os provedores de identidade são serviços externos ao sistema que fornecem e autenticam a identidade dos usuários. Eles podem ser utilizados em conjunto com a autenticação padrão do sistema, onde o usuário continua tendo um senha válida no sistema, mas com a alternativa de também poder se autenticar via provedor de identidade externo, de forma similar ao conceito de Login Social. Eles também podem ser configurados para substituir a autenticação padrão do sistema, garantindo que os usuários não autenticados pelo provedor de identidade fiquem impedidos de utilizar o sistema.

Uma vez configurado um provedor de identidade, as interfaces e scripts devem fazer uso das APIs do sistema para realizar a autenticação dos usuários. O uso dos provedores normalmente não é transparante e as interfaces devem ser compatíveis com essa funcionalidade. Atualmente, apenas a tela de login padrão do sistema, a tela de login da IDE embarcada do Engine e a tela de autenticação de conexões da extensão do VS Code são totalmente compatíveis com essa forma de autenticação. Outras interfaces do sistema podem não ser compatíveis com esse recurso, entre elas:

Formulário de autenticação do Web Framework.
Processos que realizam autenticação remota, entre eles os de atualização do sistema.

Com a evolução do sistema, essas interfaces devem ser revistas para suportar os provedores de identidade. No entanto, processos customizados que coletem senhas de usuários, por padrão não serão compatíveis com os provedores de identidade, exceto se o provedor de identidade suportar o tipo de concessão “Credenciais do proprietário do recurso”, o qual permite que o sistema colete a senha do usuário. Esse tipo de concessão pode ser habilitado em ferramentas de Single Sign-On corporativas, mas não é suportado por nenhum provedor de identidade de rede social ou serviços de ferramentas empresariais baseados em nuvem, como Google ou Facebook.

Ao utilizar o provedor de identidade em conjunto com a autenticação padrão do sistema, o usuário continua tendo sua senha controlada pelo sistema, podendo ser trocada sempre que desejar. Nesse modelo de utilização as interfaces do sistema que realizam coleta de senha continuam funcionando normalmente. No momento do login o usuário tem a opção de informar suas credenciais de acesso do sistema ou realizar o login por meio do provedor de identidade configurado, conceito conhecido como login social. Ao utilizar o sistema sem uma conexão ativa com a internet, o login via provedor de identidade não poderá ser utilizado, sendo necessário informar as credenciais de acesso.

Para disponibilizar um provedor de identidade para login, basta realizar o cadastro no processo Provedores de identidade, verificando que os campos “Habilitado” e “Visível no login” estão marcados.

Os provedores de identidade podem ainda ser utilizados como substitutos ao processo de autenticação padrão do sistema. Nesse modelo de utilização, a senha do usuário não é controlada pelo sistema e não pode ser trocada ou utilizada na tela de login padrão. Todo o controle de acesso fica centralizado no provedor de identidade, conceito também conhecido como single sign-on. As interfaces que realizam a coleta de senha do usuário não irão funcionar, exceto se o provedor de identidade aceitar o tipo de concessão “Credenciais do proprietário do recurso”. Ao utilizar esse modelo, não será possível realizar a autenticação sem uma conexão ativa com a internet, pois ela é necessária para a comunicação com o provedor.

Para utilizar um provedor de identidade como substituto ao processo de autenticação padrão do sistema, é necessário que os grupos dos usuários sejam associados a uma política de segurança que tenha uma política de autenticação OpenID Connect vinculada a um provedor de identidade habilitado.

Processo Provedores de identidade

Caminho: Admin > Segurança > Provedores de identidade.

Neste processo é possível cadastrar os provedores de identidade que serão aceitos pelo sistema e que serão exibidos na tela de login.

Antes de cadastrar um provedor de identidade é necessário realizar o cadastro do sistema junto a esse provedor para obter as informações de preenchimento dos campos “Id do cliente” (Client Id) e “Segredo do cliente” (Client Secret). Para detalhes de como realizar essa configuração, consulte a seção de configuração do Keycloak, Google ou Microsoft. Também é necessário que os endereços de acesso ao sistema estejam corretamente configurados.

Após cadastro do cliente junto ao provedor de identidade, acesse o processo “Provedores de identidade”. Será exibida uma grade com os provedores cadastrados. Ao clicar no botão de inserir da grade, será exibida uma lista para seleção do tipo de provedor que se deseja cadastrar e em seguida será exibida a grade para preenchimento dos dados do provedor.

Campos importantes:

URL do provedor: URL principal do provedor de identidade. Deve ser obtida na página de configuração do provedor ou na sua documentação.
Id do cliente: identificação do cliente gerado ou cadastrado no provedor de identidade.
Segredo do cliente: chave secreta gerada pelo provedor de identidade para que o cliente se identifique junto ao provedor de identidade.
Habilitado: indica se o provedor cadastrado está disponível para utilização. Se um provedor estiver desabilitado, o sistema apresentará um erro caso se tente utilizar este provedor.
Visível no login: indica se o provedor deve aparecer na lista de provedores exibida na interface de login.

Se o provedor cadastrado é do tipo “Google”, há disponível ainda o campo Domínio hospedado. Esse campo permite simplificar o processo de login para contas hospedadas no Google Workspace. Ao incluir o domínio do usuário do Google Workspace (por exemplo, minhaempresa.com.br), será exibida uma seleção de contas exclusivas para este domínio na tela de seleção de contas de usuário. Se este campo não estiver preenchido e o usuário possuir uma conta @gmail.com e uma conta @minhaempresa.com.br, ambas as contas estarão disponíveis para escolha na tela de seleção de contas de usuário.

Após o cadastro realizado, é possível alterar as configurações de um provedor selecionando o registro do provedor na grade da tela principal e clicando no botão “Alterar configurações”.

Operações comuns

Desativando temporariamente um provedor de identidade

Em alguns casos pode ser necessário desativar temporariamente o uso de um provedor de identidade cadastrado, como em uma manutenção programada, por exemplo. Para realizar essa operação, acesse o processo “Provedores de identidade”, selecione o registro do provedor, desmarque o campo “Habilitado” e efetive as alterações da grade. O provedor não será mais exibido na interface de login após ser desativado e, se alguma API interna tentar utilizá-lo, ocorrerá um erro.

Ativar ou desativar um tipo de concessão

Caso seja necessário alterar o suporte a um tipo de concessão, acesse o processo “Provedores de identidade”, selecione o registro do provedor e clique no botão “Alterar configurações”. Na tela seguinte, na seção “Tipos de concessões habilitados”, ajuste a concessão desejada. Se a alteração for de ativação, o sistema irá consultar a configuração do provedor para confirmar se aquele tipo de concessão é atualmente aceito e exibirá um erro caso não seja.

Logando na IDE embarcada do Engine

Após o cadastro dos provedores de identidade suportados, os que estiverem habilitados e suportarem o tipo de concessão “Código de dispositivo”, aparecerão também na janela de login da IDE embarcada do Engine. Abaixo dos campos usuário e senha são apresentados botões, um para cada provedor cadastrado seguindo a ordem determinada no cadastro. Se mais de dois provedores estiverem disponíveis para o login na IDE, o primeiro botão será o do provedor de menor ordem e o segundo botão será o “Outros provedores” que ao ser clicado faz com que seja exibida a lista completa dos provedores disponíveis.

Ao selecionar um dos botões, dependendo do provedor, pode ser exibida uma mensagem com um código, informando que esse código será colocado na área de transferência e que ele deve ser informado na página que será aberta no navegador em seguida.

Após clicar em um dos botões o navegador será aberto na página de autenticação do provedor de identidade. Após a realização da autenticação a janela de login da IDE detectará que o login foi feito e a janela principal da IDE será exibida.

Para disponibilizar um provedor de identidade complementar é preciso cadastrá-lo, como descrito anteriormente, e se certificar de que os campos “Habilitado” e “Visível no login” estejam marcados. Este provedor passará então a aparecer na lista de provedores na interface de login padrão do sistema.

Criando um provedor de identidade para fins de Single sign-on

Para implementar o modelo de Single sign-on utilizando um provedor de identidade, devem ser realizados os seguintes procedimentos:

Deve ser configurado o provedor de identidade como descrito anteriormente.
Deve ser criada uma política de autenticação associada a esse provedor de identidade, conforme descrito na documentação.
A política de segurança dos usuários deve ser alterada para utilizar essa nova política de autenticação. Mais detalhes no manual Políticas de segurança.

Para conferir a política de autenticação em vigor para os usuários, garantindo que a autenticação deles foi delegada para o provedor de identidade, deve ser utilizado o relatório “Admin > Segurança > Políticas de segurança > Políticas associadas aos usuários”.

Importante: o “administrator” é um usuário especial do sistema e sua política de autenticação sempre é a padrão, independentemente da política de segurança atribuída a ele. Esse comportamento permite que esse usuário possa ser utilizado para corrigir uma eventual falha na configuração do provedor de identidade que impeça os usuários de entrarem no sistema.

Processos e relatórios auxiliares

Políticas associadas aos usuários

Caminho: Admin > Segurança > Políticas de segurança > Políticas associadas aos usuários.

Quando utilizado um provedor de identidade em uma solução de Single Sign-On, este relatório deve ser utilizado para validar que todos os usuários estão corretamente associados a uma política de autenticação externa.

Configuração do cliente no Keycloak

Para realizar a configuração do cliente no Keycloak é preciso uma conta com acesso ao console de administração. Ao acessar o console, no menu apresentado na lateral esquerda, selecionar a opção “Clients”. Será apresentada uma tabela com a listagem dos clientes cadastrados. Clique no botão “Create” no lado superior direito da tabela.

Na tela apresentada, preencher os campos:

Client ID: identificador do cliente, por exemplo, o nome da base que autenticará seus usuários nessa instância do Keycloak.
Client Protocol: selecione a opção “openid-connect” pois esse será o protocolo utilizado na comunicação com o Engine.
Root URL: preencha com a URL principal do sistema, que pode ser consultada no processo endereços de acesso ao sistema.

Após salvar será apresentada a tela de cadastro completa do cliente criado. Campos de destaque:

Access Type: selecione a opção “confidential” para que seja gerado um “client ID”.
Standard Flow Enabled: esse é o fluxo padrão baseado em redirecionamento do usuário. É o fluxo utilizado pela tela de login padrão do sistema.
Direct Access Grants Enabled: esse é o fluxo que permite ao cliente coletar as credenciais do usuário.
Service Accounts Enabled: esse fluxo permite que o Engine obtenha tokens de acesso utilizando suas próprias credenciais de cliente (Client ID e Client Secret), portanto sem utilizar credenciais de usuário. Esse fluxo pode ser utilizado em rotinas automatizadas do sistema, onde não ocorre a interação com um humano.
OAuth 2.0 Device Authorization Grant Enabled: esse fluxo pode ser utilizado em cenários em que o redirecionamento do usuário via interface web não é possível, como em aplicações nativas. Para poder realizar login na IDE embarcada do Engine e no VSCode esse fluxo precisa estar habilitado.
Valid Redirect URIs: utilize o botão “+” do lado direito desse campo para adicionar as URLs de redirecionamento que devem ser consideradas válidas pelo Keycloak. Devem ser cadastradas todas as URLs indicadas no cadastro “Admin > Segurança > Provedores de identidade”, exibidas no campo “URIs de redirecionamento” ao inserir um novo registro ou ao clicar no botão “Alterar configurações” em um registro existente.

Salve as alterações e depois mude para a aba “Credentials”. Confirme que o campo “Client Authenticator” está preenchido com a opção “Client Id and Secret”.

É obrigatório que todos os usuários cadastrados no Keycloak também estejam cadastrados no sistema, com mesmo username e email. Essa restrição é necessária porque vários controles internos do Engine estão atrelados a uma chave de usuário, como o controle de permissões por exemplo. Para cadastrar os usuários, no menu lateral esquerdo, selecione a opção “Users”. Na tela apresentada selecione a opção “View all users” para visualizar os usuários cadastrados ou “Add user” para adicionar novos usuários.

Para maiores detalhes sobre a configuração do Keycloak, consulte a documentação oficial.

Configuração do cliente no Google

Para configurar o cliente do protocolo OpenID Connect no Google é preciso uma conta com acesso ao Google Cloud Console.

Configuração da tela de permissão OAuth

No Google Console, acesse “APIs e Serviços > Tela de permissão OAuth”. Selecione o tipo de usuário “Interno” e em seguida clique no botão “Criar” para iniciar a configuração.

A configuração da tela de permissão é composta por 3 etapas. Na primeira etapa são informados alguns detalhes sobre a empresa como nome, logomarca, endereço principal etc. Escolha o tipo de usuário “interno”. Ao selecionar o tipo interno, os usuários que podem acessar a aplicação ficam restritos aos usuários da organização do Google Workspace.

Na segunda etapa podem ser definidos escopos utilizados pela aplicação. A princípio nenhum escopo precisa ser definido. Na terceira etapa é apresentado um resumo das configurações. Confirme que os dados estão corretos e clique em “Voltar para o painel”.

Criação das credenciais do cliente

Acesse a opção “APIs e Serviços > Credenciais”. A tela exibida apresenta 3 seções: “Chaves de API”, “IDs do cliente OAuth 2.0” e “Contas de serviço”. Clique no botão “+ Criar credenciais” e selecione a opção “ID do cliente OAuth”. Informe o tipo de aplicativo “Aplicativo da Web” e em seguida informe um nome para o cliente. O nome escolhido nessa etapa é apenas para identificação cadastral e não corresponde ao “Client ID”. Pode ser utilizado o nome da base de dados por exemplo.

No campo “Origens JavaScript autorizadas”, cadastrar a URL principal de acesso ao sistema. No campo “URIs de redirecionamento autorizados”, devem ser cadastradas todas as URLs indicadas no cadastro “Admin > Segurança > Provedores de identidade”, exibidas no campo “URIs de redirecionamento” ao inserir um novo registro ou ao clicar no botão “Alterar configurações” em um registro existente.

Clique em “Criar” para confirmar a criação do registro. Será exibido um diálogo modal com o título “Cliente OAuth criado” e informando o ID do cliente e a chave secreta. Essas informações devem ser utilizadas no cadastro de provedores de identidade.

Num cenário em que várias bases poderão autenticar seus usuários no Google, poderão ser criadas várias credenciais de cliente OAuth, uma para cada base de dados.

Conforme descrito acima, no momento da criação de uma credencial é necessário informar o tipo de cliente. Entre os tipos disponíveis estão “Aplicativo da Web”, “App para computador”, “TV e dispositivos de entrada limitados”, “Android”, “iOS” entre outros. Durante a realização de um fluxo de autenticação no Google, o tipo da credencial é validada de modo que uma credencial do tipo “Aplicativo da Web” não pode ser utilizada em um fluxo do tipo “Código de dispositivo”, por exemplo.

O sistema possui cenários de login tanto em navegadores web quanto em ambientes mais restritos que não permitem a exibição da página de login da Google. Por esse motivo, é necessário criar credenciais para esses dois cenários de uso, sendo necessária uma credencial do tipo “Aplicativo da Web” para a página de login principal do sistema, e uma outra do tipo “TV e dispositivos de entrada limitados”, para a extensão do VS Code e a IDE embarcada do Engine.

No cadastro dos provedores de identidade do tipo “Google” existem os campos “Id do cliente” e “Segredo do cliente”, que devem ser utilizados para informar tanto as credenciais de cliente para o login em ambiente web, no grupo de campos “Configurações provedor”, quanto as credenciais de cliente para o login em ambientes que não suportam a exibição da página de login do Google, no grupo de campos “Configurações do cliente para TV e dispositivos de entrada limitados”.

Configuração do cliente na Microsoft

Para configurar o cliente do protocolo OpenID Connect para autenticação junto à plataforma de identidade da Microsoft, é preciso acesso de administrador ao portal do Azure.

Registro da aplicação cliente

Para registrar o sistema como um cliente OpenID Connect acesse opção “Azure Active Directory” e em seguida “App registrations”. Realize o cadastro da aplicação conforme descrito na documentação oficial. Após confirmar o cadastro da aplicação será apresentado o ID do cliente no campo “Application (client) ID”.

Adicione um segredo de cliente clicando na opção “Add a certificate or secret” do campo “Client credentials”. Será exibida a tela “Certificates & secrets”. Na aba “Client secrets” selecione a opção “New client secret”. Informe uma descrição e um prazo de validade para o segredo e em seguida clique em “Add”. Antes de fechar a tela “Certificates & secrets” copie o valor da coluna “Value” do segredo criado. O segredo e o ID do cliente serão utilizados no cadastro do provedor de identidade no sistema.

Após o cadastro, acesse a opção “Authentication” no painel lateral. Na tela de configuração da autenticação, em “Platform configurations”, selecione a opção “Add a platform”. Escolha a opção de plataforma “Web”. No campo “Redirect URIs” deve ser cadastrada a URL indicada no cadastro “Admin > Segurança > Provedores de identidade”, exibida no campo “URIs de redirecionamento” ao inserir um novo registro ou ao clicar no botão “Alterar configurações” em um registro existente. No caso de haver múltiplas URIs de redirecionamento, informe a principal e as demais podem ser acrescentadas após a finalização do cadastro da plataforma, utilizando a opção “Add URI”.

Na seção “Supported account types” é possível definir os tipos de acesso permitidos, se apenas usuários da organização ou se contas pessoais também poderão ser utilizadas na autenticação.

Importante: A implementação atual da Microsoft só é inteiramente compatível com a especificação do protocolo OpenID Connect quando utilizado o tipo de acesso “Accounts in this organizational directory only (Single tenant)”. Por esse motivo, o uso de contas Microsoft pessoais atualmente não são suportadas diretamente pelo sistema. Essa limitação pode ser contornada utilizando um provedor de identidade intermediário que implemente corretamente o protocolo OpenID Connect e se conecte com o provedor da Microsoft, como o Auth0.

Ainda na tela de configuração de autenticação da aplicação, para habilitar o login por meio da extensão do VS Code e da IDE embarcada do Engine, em “Advanced settings” habilite a opção “Enable the following mobile and desktop flows” e em seguida salve as alterações.

Última atualização em 16 Sep 2023