Instalação do GrantID em Windows Server

observação

A documentação deste sistema encontra-se em construção. Pedimos desculpas pela inconveniência. Por favor, contate-nos caso precise de alguma informação que ainda não está documentada.

Setup do IIS

1. Abra o Gerenciador do Servidor e selecione a opção Adicionar Funções e Recursos:
2. Na seção Funções de Servidor, selecione Servidor Web (IIS):
3. Na seção Serviços de Função, selecione os serviços desejados ou aceite as opções padrão:
4. Abra o Gerenciador do IIS (Serviços de Informações da Internet) e remova o Default Web Site:

Setup do .NET Core

1. Baixe e instale o Microsoft Visual C++ 2015 Redistributable package
2. Baixe e instale o NET 8.0 Hosting Bundle. Se a opção de instalação não for exibida, escolha a opção de reparo.
3. (Somente para Windows Server 2012 ou anterior) Baixe e instale o Windows Management Framework (WMF) 5.1

aviso

Depois que a instalação for concluída, o servidor precisa ser reiniciado.

Visão geral do pacote de instalação

Um pacote de instalação chamado grantid-<version_number>.zip será disponibilizado sempre que você precisar instalar ou atualizar o GrantID.

O GrantID é composto de 3 componentes:

1. IdentityService: serviço REST que precisa ter acesso a um banco de dados SQL Server.
2. AuthServer: servidor de autorização OAuth 2.0 e OpenID Connect.
3. Console: interface de console para configurar as aplicações.

Os componentes podem ser instalados em servidores diferentes ou no mesmo servidor, conforme a sua necessidade, desde que os seguintes requisitos sejam atendidos:

• O AuthServer precisa ter acesso de rede ao IdentityService.
• O Console precisa ter acesso de rede ao IdentityService. Ele não precisa de acesso de rede explícito ao AuthServer, mas pode redirecionar um usuário para ele, já que todos os logins e cadastros são tratados pelo AuthServer.
• O IdentityService precisa ser atualizado antes dos outros dois componentes, já que eles dependem das APIs dele.

Estrutura de pastas do pacote:

• Tools: contém binários que podem ser usados para gerar certificados e chaves. Requer o NET Framework 4.5.2 para ser executado.
• Keys: contém o certificado e a chave de desenvolvimento.
• Config: contém os arquivos de configuração usados para configurar os componentes.
• Components: contém os binários de todos os componentes.

Instruções de instalação

Comece criando um diretório de trabalho, por exemplo: C:\GrantId-Install.

Descompacte o pacote de instalação na raiz do diretório de trabalho (ele já contém uma pasta chamada grantid). Se já houver arquivos de instalações anteriores, sobrescreva-os (veja as Instruções de atualização).

Ao instalar em um ambiente de produção pela primeira vez, você precisa gerar um certificado e uma chave para o seu ambiente.

Gerando os arquivos de certificado e de chave

O certificado GrantID.pfx será usado para assinar os tokens de aplicação emitidos pelo GrantID. Para gerar um novo certificado:

$cert = New-SelfSignedCertificate -Type Custom -Subject "CN=<certificate_name>" -TextExtension @("2.5.29.37={text}1.3.6.1.5.5.7.3.2,1.3.6.1.5.5.7.3.1") -KeyUsage DigitalSignature, KeyEncipherment -KeyAlgorithm RSA -KeyLength 4096 -CertStoreLocation "Cert:\CurrentUser\My" -NotAfter (Get-Date).AddYears(100).AddHours(-5)
$pass = ConvertTo-SecureString -String "pass" -Force -AsPlainText
Export-PfxCertificate -Cert ("Cert:\CurrentUser\My\" + $cert.Thumbprint) -Password $pass -FilePath .\GrantId.pfx
Get-ChildItem ("Cert:\CurrentUser\My\" + $cert.Thumbprint) | Remove-Item

Exemplo:

$cert = New-SelfSignedCertificate -Type Custom -Subject "CN=GrantID" -TextExtension @("2.5.29.37={text}1.3.6.1.5.5.7.3.2,1.3.6.1.5.5.7.3.1") -KeyUsage DigitalSignature, KeyEncipherment -KeyAlgorithm RSA -KeyLength 4096 -CertStoreLocation "Cert:\CurrentUser\My" -NotAfter (Get-Date).AddYears(100).AddHours(-5)
$pass = ConvertTo-SecureString -String "pass" -Force -AsPlainText
Export-PfxCertificate -Cert ("Cert:\CurrentUser\My\" + $cert.Thumbprint) -Password $pass -FilePath .\GrantId.pfx
Get-ChildItem ("Cert:\CurrentUser\My\" + $cert.Thumbprint) | Remove-Item

Mova o arquivo gerado para o diretório Keys.

O key.xml é usado para proteger os cookies e os secrets gerados pelo GrantID. Navegue até o diretório Tools usando o PowerShell como administrador e execute o comando:

.\grantid.exe genkey [output_directory]

Exemplo:

.\grantid.exe genkey

Mova o arquivo gerado para o diretório Keys.

Configurando os componentes

Antes de publicar de fato os componentes, revise e configure cada um deles.

Navegue até o diretório Config. Se você estiver instalando pela primeira vez, todos os arquivos terão o sufixo -Sample.

Para cada componente (e para os arquivos comuns):

observação

Se você já tem arquivos XML e JSON sem o sufixo -Sample para aquele componente, basta revisar ou atualizar as configurações nesses arquivos e pular os dois passos seguintes.

1. Remova o sufixo -Sample do arquivo XML do componente. Esse arquivo contém configurações relativas ao site do IIS que será criado para a aplicação. Edite o arquivo de acordo com as suas preferências.
2. Remova o sufixo -Sample do arquivo JSON do componente. Esse arquivo contém as configurações do componente, como o caminho do arquivo de log, connection strings etc. (veja o guia do arquivo de configuração). Edite o arquivo de acordo com as suas preferências.

Publicando os componentes

Antes de publicar os componentes, pode ser necessário permitir a execução de scripts do PowerShell com o seguinte comando:

Set-ExecutionPolicy Bypass -Scope LocalMachine

Depois que os arquivos de configuração de todos os componentes estiverem prontos, você pode publicar um componente executando o script de instalação dele no PowerShell como administrador:

.\Install-<component>.ps1 

• O script mostra as configurações definidas na pasta Config e pergunta ao usuário se ele quer continuar. Você pode pular essa verificação com o argumento NoPrompt, assim:

.\Install-<component>.ps1 NoPrompt

Sempre comece publicando o IdentityService, depois o AuthServer e, por fim, o Console:

.\Install-IdentityService.ps1 
.\Install-AuthServer.ps1 
.\Install-Console.ps1 

Depois que todos os componentes estiverem instalados, configure os bindings de SSL de cada aplicação do IIS (se necessário).

Depois que o AuthServer estiver instalado e os bindings configurados, pode ser necessário dar ao pool de aplicativos do AuthServer acesso total ao certificado do GrantID:

1. Abra Gerenciar certificados do computador.
2. Clique com o botão direito no certificado e selecione Todas as Tarefas → Gerenciar Chaves Privadas….
3. Digite IIS AppPool\AuthServer_App e clique em OK.
4. Certifique-se de que Controle total esteja selecionado e clique em Aplicar e depois em OK.

Instruções de atualização

Descompacte o novo pacote de instalação na raiz do diretório de trabalho e sobrescreva todos os arquivos.

Suas configurações permanecerão inalteradas, porque o novo pacote de instalação não contém arquivos sem o sufixo -Sample.

Verifique os arquivos de configuração de todos os componentes na pasta Config. Você pode consultar os arquivos com o sufixo -Sample para identificar configurações adicionadas ou removidas.

Execute o script de instalação de cada componente, como mostrado na seção Publicando os componentes.

Resolução de problemas

Se você encontrar um erro de acesso negado a uma chave do registro, como o mostrado abaixo:

System.UnauthorizedAccessException: Access to the registry key 'HKEY_LOCAL_MACHINE\SOFTWARE\GrantID\Keys' is denied.

Verifique se as identidades dos pools de aplicativos do IIS de todos os módulos receberam a permissão Controle total na chave do registro:

1. Abra o Editor do Registro.
2. Navegue até a pasta Computer\HKEY_LOCAL_MACHINE\SOFTWARE\GrantID\Keys e clique na opção Permissões....
3. Verifique se todas as identidades dos pools de aplicativos do IIS (IIS AppPool\AuthServer_App, IIS AppPool\IdentityService_App e IIS AppPool\Console_App) têm a permissão Controle total. Se faltar alguma, adicione-a.
4. Reinicie os sites do IIS correspondentes, se alguma identidade estava faltando.