Skip to content

Latest commit

 

History

History
481 lines (308 loc) · 26.2 KB

README_FCCN.md

File metadata and controls

481 lines (308 loc) · 26.2 KB

Playbook para a instalação e configuração do Shibboleth IDP 4.3.0 com AD

Este projeto cria uma imagem docker em Debian Bullseye (11) onde depois é feita a instalação do Shibboleth IDP 4.3.0 com as configurações específicas da instituição utilizando uma Active Directory.

Em teoria, este playbook também pode ser executado diretamente numa VM com Debian 11, mas este cenário não foi testado.

Se apenas necessitar de instruções para a instalação do IDP com as configurações da FCCN siga para o capítulo TL;DR no final deste documento.

Índice

  1. Playbook
  2. Docker
  3. Pipeline
  4. TL;DR

Playbook

Este playbook foi construído utilizando ansible e permite a automatização da instalação e configuração do Shibboleth IDP e do software necessário. É este:

  • Apache2
  • Java
  • Tomcat
  • PostgreSQL
  • Shibboleth
  • Plugin AutenticacaoGov
  • Fail2Ban

A versão mais atualizada deste playbook pode ser transferida aqui ou acedendo ao repositório deste projeto, carregar no botão download e, por baixo de Previous Artifacts, carregar na entrada Shibboleth_IDP_4.3.0_ORG.zip. Dependendo das configurações da instituição, o playbook pode necessitar de alterações para além das explicadas neste documento.

Nas subsecções seguintes explicamos as funcionalidades do playbook, como está construído e como trabalhar com ele.

general_definitions

Este playbook vai configurar o IDP tendo em conta os valores dados às variáveis no ficheiro group_vars/general_definitions.

Clique aqui para ler a descrição de cada variável.

  • organization_name: nome da instituição.

  • organization_domain: domínio da instituição.

  • server_name: nome da máquina ou FQDN onde está a ser instalado o Shibboleth IdP.

  • server_admin: endereço de email de administração da instituição

  • bd_backup_file_name: nome do ficheiro de backup da base de dados postgresql.

  • old_postgresql_password: password de acesso à base de dados postgresql caso esteja a fazer um backup da bd.

  • path_ssl_cert_apache: Caminho os certificados usado pelo apache e a chave.

  • ssl_cert_key_file_name: Nome do ficheiro com a chave do certificado usado pelo apache.

  • ssl_cert_file_name: Nome do ficheiro com o certificado usado pelo apache.

  • ssl_cert_chain_file_name: Nome do ficheiro com os certificados da cadeia de confiança usada pelo apache.

  • path_ldap_cert_file: local onde o certificado das ADs será guardado no IDP.

  • ldap_cert_file_name: nome do certificado dos servidore LDAPS.

  • idp_cert_name: nome do certificado do IDP (necessário caso esteja a fazer uma atualização do IDP).

  • idp_key_name: nome da chave do certificado do IDP (necessário caso esteja a fazer uma atualização do IDP).

  • idp_metadata_name: nome do ficheiro de metadados do IDP (necessário caso esteja a fazer uma atualização do IDP).

  • postgresql_backup_dest: caminho para a pasta onde ficarão alojados os backups da base de dados. Os backups serão lançados automaticamente todos dias durante a madrugada.

  • tomcat_version: versão do tomcat a utilizar. Não alterar

  • tomcat_xms: tamanho de heap size inicial em memória no arranque do Tomcat.

  • tomcat_xmx: tamanho de heap size máximo em memória do Tomcat.

  • user_test: O nome do utilizador de testes utilizado para monitorização feita pela FCCN.

  • attribute_scope: scope da organização.

  • choose_ldap: escolher entre ldaps e ldap.

  • ip_range_access_control: rede e o domínio em que é permitido visualizar o estado do IdP. É obrigatório a rede estar entre plicas.

  • idp_metadata: nome dos metadados das federações a configurar no IDP.

  • ldap_url: endereço do servidor da AD ou LDAP da instituição. É obrigatório a rede estar entre plicas.

  • ldap_dn_format: objetos a consultar na AD da instituição.

  • ldap_port: porto de comunicação com o AD ou LDAP.

  • ldap_username: nome de utilizador que efetuará a ligação à AD ou LDAP da instituição.

  • ldap_password: password de acesso à AD utilizada pelo o utilizador definido para ldap_bind_dn.

  • ldap_type: atributo de AD ou LDAP a utilizar:

    • quando AD: sAMAccountName
    • quando LDAP: uid

  • pgsql_username: nome do utilizador da base de dados PostgreSQL. Por defeito: shibboleth.

  • salt: se for atualizar o idp a partir de uma versão antiga, coloque o valor antigo do salt. Caso contrário pode manter este campo vazio.

  • idp_version: versão do Fornecedor de Identidade. Não alterar

  • source_directory: directoria onde são colocados os ficheiros de instalação do Fornecedor de Identidade Shibboleth. Por defeito: /usr/local/dist/shibboleth-identity-provider-4.3.0. Não alterar

  • installation_directory: diretoria de instalação do Fornecedor de Identidade Shibboleth. Por defeito: /opt/shibboleth-idp Não alterar

  • link_suporte: URL para uma página de suporte da organização.

  • link_rctsaai: URL para a página com informação sobre a RCTSaai.

  • link_seguranca: URL para uma página com informação sobre segurança relevante para o utilizador.

  • link_ajuda: URL para uma página com informação que possa ajudar o utilizador. Por exemplo, uma FAQ.

  • link_esqueceu_palavra_chave: URL para uma página onde é possível redefinir a palavra-chave ou que tenha informação sobre o que é necessário fazer.

  • idp_logo_url: URL da página que o utilizador será redirecionado se carregar no logotipo da instituição.

  • org_layout: nome da pasta do layout da organização.

  • idp_logo_img_name: nome da imagem com o logotipo da instituição.

  • idp_bg_img_name: nome da imagem de fundo da instituição.

  • update_idp: flag que indica se pretende atualizar ou instalar o idp de raiz. Se for instalar de raiz, coloque qualquer valor. Para atualizar coloque true.

  • backup_bd_shib: flag que indica se pretende utilizar o backup da base de dados postgresql. Para atualizar coloque true.

Os seguintes parâmetros dizem respeito ao plug-in autenticacaoGov. Apenas é necessário preencher estes atributos se pretender instalar o plugin.

  • authGov_cmd_display: flag que ativa/inativa o botão do CC-CMD na página de login. Para ativar coloque 'true'.

  • authGov_assertionConsumerUrl: endpoint de receção da mensagem enviada pela AMA. Deverá ser a composição do url do IdP mais a terminação /Authn/AutenticacaoGov/LoginResponse.

  • authGov_providerName: nome do provider enviado na mensagem SAML. Valor enviado e acordado com a AMA

  • authGov_issuerId: issuer enviado na mensagem SAML. Valor enviado e acordado com a AMA

  • authGov_faaaLevel: nível de segurança do pedido de autenticação. Permite ativar ou desativar a opção de autenticação com chave móvel digital. Por defeito: 3

  • authGov_link_logout_success: endpoint após logout bem sucedido.

  • authGov_link_logout_error: endpoint após logout mal sucedido.

  • authGov_path_ssl_cert: local onde os certificados da AMA serão guardados no IDP.

  • authGov_govIdp_crt: nome do certificado para validação das respostas da AMA.

  • authGov_sign_crt: nome do certificado para cifrar pedidos enviados à AMA pelo IdP.

  • authGov_sign_privateKey: nome da chave para assinatura de pedidos enviados à AMA pelo IdP. A chave deverá estar no formarto PKCS8.

Funcionalidades

Para além da instalação e configuração de um novo IDP, este playbook permite automizar a configuração do apache, a atualização de IDPs, a adição de novas federações e a atualização do layout.

Certificados Apache

Pode utilizar este playbook para adicionar automaticamente os certificados utilizados pelo Apache2. Para isso, coloque os certificados em roles/apache2/files/certs. Os nomes dos certificados devem ser os mesmos que foram colocados no ficheiro general_definitions. Quando o role apache2 estiver a ser executado, estes ficheiros serão colocados no caminho colocado em path_ssl_cert_apache.

Atualizar o IDP a partir de uma configuração antiga

Sendo o IDP da FCCN, existe informação que deve ser migrada para o novo IDP. Esta informação é:

  • Ficheiro de metadados do IDP - este ficheiro tem informação que identifica o IDP nas federações como o entityID ou chave utilizada para a assinatura de mensagens durante o processo de autenticação.

  • Certificado do IDP - o par de chaves é utilizado para assinar e cifrar mensagens trocadas durante o processo de autenticação.

  • Certificado da AD

  • Ficheiro com backup da base de dados PostgreSQL - Nesta base de dados está guardado o consentimento de envio de dados dos utilizadores e a aceitação dos termos e condições. Sem este backup, o utilizador terá de aceitar tudo novamente.

  • Certificados autenticacaoGov - Estes certificados permitem ao IDP utilizar o plugin como um método de autenticacao alternativo.

Para que esta informação seja automaticamente colocada e configurada, siga os seguintes pontos:

  • Coloque os metadados e certificados utilizados pelo IDP Shibboleth antigo em roles/shibboleth/files/metadata. Estes devem ter os mesmos nomes que foram colocados no ficheiro general_definitions.

  • Coloque o certificado da AD em roles/shibboleth_config/files/AD. O nome do ficheiro com certificado deve ser o mesmo que foi colocado no ficheiro general_definitions.

  • Coloque o ficheiro com o backup da BD em roles/postgresql/files/backup. O nome do ficheiro com o backup deve ser o mesmo que foi colocado no ficheiro general_definitions.

  • Adicione a password da base de dados PostgreSQL em old_postgresql_password e coloque a variável backup_bd_shib com o valor true.

  • Adicione os certificados utilizados pelo plugin em roles/cc-cmd-install/files/certs.

  • Atualize as variáveis authGov_path_ssl_cert,authGov_govIdp_crt, authGov_sign_crt e authGov_sign_privateKey.

  • Confirme a informação do ficheiro general_definitions.

Adicionar novas federações

Esta subsecção explica como adicionar novas federações ao playbook.

Clique aqui para expandir.

Para adicionar novas federações siga as seguintes instruções:

  • No ficheiro general_definitions crie uma lista com o nome dos metadados. Por exemplo:
idp_metadata:
  - rctsaai
  - engine-rctsaai-key-20250210
  - metadados-da-instituição
  • Crie um novo ficheiro na diretoria roles/shibboleth_config/files/blocks cujo nome terá o seguinte formato: metadata_value_NomeDosMetadados.xml. Seguindo o exemplo dado no ponto anterior, o nome do novo ficheiro seria: metadata_value_metadados-da-instituição.xml. Neste ficheiro adicionará a linha que será escrita no ficheiro services.xml. Para o ficheiro de metadados dado como exemplo será:
<value>#{ '%{idp.metadata}' matches '.*\bmetadados-da-instituição\b.*' ?
                      '%{idp.home}/conf/metadata-provider-metadados-da-instituição.xml' : '' }</value>

  • Na diretoria roles/shibboleth_config/files/metadata-providers adicione o ficheiro metadata-provider-metadados-da-instituição.xml onde terá as várias regras para o IDP interagir com os serviços dessa federação, o URL para transferir os metadados e um certificado (caso seja utilizado). Para o nome deste ficheiro siga o formato metadata-provider-NomeDosMetadados.xml.

  • Se os metadados estiverem assinados, adicione o certificado na diretoria roles/shibboleth_config/files/federation_certs com o nome utilizado no ficheiro do ponto anterior.

Atualizar o Layout

Se for necessário atualizar o logótipo ou a imagem de fundo do IDP, siga as seguintes instruções:

  • logótipo: adicione o ficheiro com o logotipo na pasta roles/layout/files/FCCN/images/ e adicione o seu nome na variável idp_logo_img_name no ficheiro general_definitions.

  • background: adicione o ficheiro com a imagem de fundo na pasta roles/layout/files/FCCN/images/ e adicione o seu nome na variável idp_bg_img_name no ficheiro general_definitions.

Também pode alterar o nome da pasta FCCN para qualquer outro nome que seja apropriado no contexto da instituição. O novo nome deve ser colocado na variável org_layout. A alteração do nome da pasta vai alterar o texto escrito no separador do browser quando estiver na página do IDP.

Roles

Este Ansible Playbook é constituído por um conjunto de roles. Cada role tem uma função específica, por exemplo, instalar e configurar o Apache2, instalar e configurar o Fail2Ban, etc.

Os roles podem estar divididos, no máximo, em 3 diretorias:

  • templates
  • tasks
  • files

Na diretoria templates estão ficheiros que vão funcionar como uma base do ficheiro final (um template). Quando estes ficheiros são copiados para a máquina, certos valores são substituídos pelos definidos no ficheiro general_definitions.

Na diretoria tasks colocamos os ficheiros com as operações a serem efetuadas pelo playbook.

Na diretoria files colocamos ficheiros que vão ser copiados para a máquina sem nenhuma alteração feita, ao contrário do que acontece com templates.

Nas subsecções seguintes explico como funciona cada role deste playbook. Os roles são:

check-system

No role check-system, verificamos se a máquina em que o playbook vai ser executado tens as características necessárias. Neste caso, apenas verificamos se é uma máquina Debian 11.

system

No role system, instalamos os pacotes necessários para executar o playbook e alguns necessários para o funcionamento do IDP.

apache2

No role apache2 instalamos e configuramos o apache2.

Este role começa por verificar se os certificados a utilizar no apache2 estão presentes. Estes têm de ser colocados em roles/apache2/files/certs. Se faltar algum, o playbook retorna um erro.

Feita a verificação, o playbook instala e configura o apache2 e copia os certificados a utilizar.

java

No role java instalamos e configuramos o Java 11.

tomcat

No role tomcat instalamos e configuramos o tomcat 9.0.68 utilizando o ficheiro transferido do repositório do tomcat.

Este role necessitou de algumas alterações para ser executado corretamente num container. Estas alterações serão explicadas na secção seguinte.

postgresql

No role postgresql instalamos e configuramos o postgresql. Neste role é possível utilizar um ficheiro de backup da base de dados do IDP antigo.

Este role começa por instalar os pacotes necessários para utilizar o postgresql, verifica se é para utilizar um ficheiro de backup da BD ou para criar uma nova, e, por fim, configura o postgresql.

shibboleth

No role shibboleth instalamos e configuramos o shibboleth. É possível utilizar os certificados e ficheiro de metadados do IDP antigo de forma a fazer uma atualização do mesmo.

  1. Este role começa por instalar o IDP, começamos por instalar o Shibboleth IDP através do ficheiro shibboleth-identity-provider-4.3.0.tar.gz que está na pasta files.

  2. Se for para fazer uma atualização do IDP, substituímos os certificados e o ficheiro de metadados criados durante a instalação pelos que estão na pasta files/metadata.

  3. Se não for utilizar o backup da BD postgresql, configuramos um novo utilizador na BD para o IDP. Se utilizar o backup criamos um utilizador com a password antiga.

  4. Instalamos o plugin rhino, utilizado na definição de alguns atributos.

  5. Por fim, criamos o ficheiro idp.war e colocamos na configuração do tomcat.

shibboleth_config

No role shibboleth_config configuramos o IDP.

  1. Começamos por configurar os metadados das federações em que o IDP vai estar inscrito. Carregue aqui para ver como adicionar novas federações ao IDP utilizando o playbook.

  2. Adicionamos os ficheiros utilizados que definem os atributos.

  3. Configurações gerais do IDP, como ativar os termos e condições.

  4. Configurar o acesso do IDP à AzureAD.

layout

No role layout configuramos o layout do IDP.

Executar playbook

Para efectuar diferentes tipos de instalações, podemos utilizar as tags seguintes:

  • idp: instalação apenas do Shibboleth IDP v4.3.0, incluindo layout de demonstração
  • layout: instalação apenas do layout para demonstração (requer que exista um IDP instalado)
  • cc: instalação e configuração de testes do plug-in CC-CMD (requer que exista um IDP instalado). Atenção: Deve primeiro verificar se cumpre todos pré-requisitos descritos na Secção 3
  • cc-install: instalação do plug-in CC-CMD (requer que exista um IDP instalado). Atenção: Deve primeiro verificar se cumpre todos pré-requisitos descritos na Secção 3
  • cc-config: configuração do plug-in CC-CMD (requer que exista um IDP instalado e que tenha já sido executado os roles da tag cc-config). Atenção: Deve primeiro verificar se cumpre todos pré-requisitos descritos na Secção 3
  • apache2: instalação ou atualização das configurações do apache2.
  • java: instalação ou atualização das configurações do java.
  • remove-cc: desinstalação do plug-in CC-CMD, repondo a configuração prévia à sua instalação
  • remove-cc-config: remoção das configurações de teste do plug-in CC-CMD.
  • remove-cc-install: desinstalação do plug-in CC-CMD.

Para executar localmente o playbook de instalação do Shibboleth, basta executar o seguinte comando:

[root@idp-server]# ansible-playbook -i "localhost," --connection=local main.yml --tags=<tag1>

Por exemplo, para executar uma instalação completa (IDP+Layout):

[root@idp-server]# ansible-playbook -i "localhost," --connection=local main.yml --tags=idp,layout

Uma vez terminada a execução do Ansible espera-se um resultado sem erros, por exemplo:

PLAY RECAP *********************************************************************
localhost                  : ok=190  changed=147  unreachable=0    failed=0    skipped=18   rescued=0    ignored=0

Nota: O playbook não está construído para utilizar múltiplas tags na mesma execução.

Docker

Este projeto utiliza o docker com o objetivo de permitir a execução do playbook num ambiente bem conhecido. Isto é útil para:

  • Desenvolver o projeto: quando é criado um novo container, o ambiente onde o playbook vai ser executado é bem conhecido e as alterações feitas por execuções antigas não vão estar presentes. Isto permite a todas as execuções e testes serem feitos no mesmo ambiente.

  • Manutenção: utilizando containers, passa a não ser necessário criar uma nova máquina para cada atualização da versão do IDP.

A ideia com a utilização do docker é utilizá-lo como uma VM mais leve que estará a correr numa VM real. Esta forma de trabalhar com o docker permite que utilizadores que não estão habituados a esta ferramenta continuem a gerir o IDP como era feito anteriormente.

Instalar o docker

O docker é a única ferramenta que tem de estar instalada na própria máquina. Atualmente, os IDPs da FCCN utilizam Debian, por isso as instruções seguintes serão focadas nesse SO.

Para instalar o docker execute os seguintes comandos:

sudo apt-get update
sudo apt-get install ca-certificates curl gnupg lsb-release -y

sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-compose-plugin -y

Pode encontrar mais informação sobre a instalação do docker em Debian e noutros Sistemas Operativos aqui.

Instalação do IDP num container

O primeiro passo para a instalação do IDP num container é a criação da Docker Image. Uma imagem é um conjunto de instruções utilizadas para a construção do container.

Para criar a imagem execute o comando seguinte na diretoria do ficheiro Dockerfile.* :

* A primeira etapa não é executada neste projeto. A imagem é criada no projeto do IDP da FCCN. Deixo esta etapa para entender de onde vem a imagem idp_fccn_image. Caso seja necessário criar uma imagem com este projeto, copie o ficheiro Dockerfile do projeto do IDP da FCCN.

docker build -t idp_fccn_image .

Este comando cria uma imagem com o nome idp_fccn_image. Pode confirmar a sua criação com o comando

docker images

Depois da imagem estar criado tem de lançar um Docker Container. Como um IDP comunica com o exterior através do porto 443, precisamos de mapear o porto 443 do container ao porto 443 da máquina. O comando completo é o seguinte:

docker run -dit -p 443:443 --name idp_fccn_org idp_fccn_image

Para confirmar que o container foi criado e está a correr, pode executar o comando seguinte:

docker ps

Este comando mostra todos os containers que estão a correr na máquina.

Por fim, precisa de adicionar o playbook no container. Este playbook não é diretamente adicionado na imagem para termos maior flexibilidade na sua edição. Isto também permite-nos utilizar a mesma imagem para várias versões do playbook, poupando tempo e facilitando a gestão das imagens.

Para copiar o playbook para o container, execute o seguinte comando na diretoria do playbook:

docker cp playbook idp_fccn_org:/root

Este comando copia a pasta playbook e todo o seu conteúdo da VM para a diretoria /root do container.

Para executar o playbook, utilize o comando:

docker exec -t idp_fccn_org sh -c 'cd /root/playbook; ansible-playbook -i "localhost," --connection=local main.yml --tags=idp,layout'

Tomcat

Para conseguir utilizar o tomcat, visto que não é possível utilizar o systemd dentro de um container com configurações padrão, foi necessário fazer alterações à forma como se faz start, stop e restart.

Clique aqui para ler a explicação.

Instalei o pacote systemctl, que permite simular o comportamento do systemctl dentro do container sem a necessidade do systemd. Este pacote permitiu fazer start, stop e restart do tomcat utilizando as suas configurações do systemd.

Terminados os processos podemos relançar o tomcat. Ao executar o playbook, o comando para iniciar o tomcat pode não funcionar à primeira, porque os processos antigos podem ainda estar a ser terminados. Por essa razão, tentamos executar o comando 3 vezes, no máximo.

Pipeline

Clique aqui para obter informação sobre o pipeline deste projeto

O pipeline permite automatizar o processo de testagem deste projeto. Neste momento, o pipeline é constiuído por 3 stages (no playbook estão mais, mas não estão a ser utilizados), são estes:

  • build - onde verificamos se o playbook tem a sintaxe correta, fazemos deploy numa máquina de testes do IDP sem o plugin autenticacaoGov.
  • test - onde são feitos testes ao IDP sem o plugin autenticacaoGov.
  • package - onde é criado um .zip com o playbook mais recente.

Dentro de cada stage existe um conjunto de jobs. No stage build temos os seguintes jobs:

  • check_syntax: verifica se a sintaxe do playbook está correta. Este job só é executado se forem feitas alterações nos ficheiros dentro da diretoria playbook.

  • rm-old-container: para possíveis containers ativos a executar IDPs. Remove o container com a instalacao antiga do IDP da FCCN com AzureAD. Este job só é executado se forem feitas alterações nos ficheiros dentro da diretoria playbook.

  • executar-playbook: lança o container com a nova imagem e executa o playbook. Este job só é executado se forem feitas alterações nos ficheiros dentro da diretoria playbook ou no ficheiro Dockerfile.

  • verificar-estado-idp: executa o um teste para confirmar se o IDP já está acessível para poder começar os testes. Este teste foi feito utilizando um programa em python com a ferramenta selenium. O teste tenta chegar à janela de autenticação do IDP durante um máximo de 2 minutos. Depois desse tempo retorna um erro.

No stage test temos os seguintes jobs:

  • profile: executa um teste para confirmar se é possível fazer uma autenticação no profile. Este teste nao esta ativo porque é necessario fazer alteracoes no manage. Para o ativar tem de o descomentar.

  • authmonit: executa um teste para confirmar se é possível fazer uma autenticação no authmonit.

No stage package temos o seguinte job:

  • Shibboleth_IDP_4.2.1_ORG.zip: cria um zip com o novo playbook.

TL;DR

Para criar um novo IDP necessita de:

  1. Lançar o container e fazer o mapeamento entre o porto 443 da VM com o porto 443 do container:
docker run -dit -p 443:443 --name idp_fccn_org idp_fccn_image
  1. Na diretoria onde está o playbook, executar o comando seguinte para o colcoar no container:
docker cp playbook idp_fccn_org:/root
  1. Executar o playbook:
docker exec -t idp_fccn_org sh -c 'cd /root/playbook; ansible-playbook -i "localhost," --connection=local main.yml --tags=idp,layout'