Instalação do Shibboleth 4.3.0 por Ansible

Procedimento de utilização do pacote de Ansible para instalação do Shibboleth IdP 4.3.0

Pré-requisitos

O primeiro passo a efectuar é instalar o pacote ansible e unzip.

shell> apt install ansible unzip

Crie a pasta Shibboleth_IDP_4.3.0, entre na nova diretoria e descomprima o código para dentro da mesma:

shell> mv Shibboleth_IDP_4.3.0_ORG.zip Shibboleth_IDP_4.3.0
shell> cd Shibboleth_IDP_4.3.0
shell> unzip Shibboleth_IDP_4.3.0_ORG.zip

Configuração do playbook

Edite o ficheiro de definições gerais sobre a instituição e da instalação em curso no seguinte ficheiro:

shell> vi group_vars/general_definitions

Descrição dos parâmetros a definir

A instalação do Shibboleth IdP depende das parametrizações efectuadas no ficheiro general_definitions. Em baixo encontram-se descritas as parametrizações necessárias de preencher relativas à sua instituição, seguidas de um exemplo do ficheiro de configuração totalmente preenchido para o caso da FCCN:

• 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.

Para mais detalhes acerca da instalação do plug-in, por favor ver a Secção 3.

Exemplo do ficheiro de configuração

#
# Configurações Apache
######################
organization_name: FCCN
organization_domain: fccn.pt
server_name: idp.fccn.pt
server_admin: [email protected]

#
# Configurações PostgreSQL
######################
bd_backup_file_name: bd.sql
old_postgresql_password: XXXXX


#
# Certificados digitais
#######################
path_ssl_cert_apache: /etc/certs/
ssl_cert_key_file_name: /etc/pki/idp_fccn_pt.key
ssl_cert_file_name: /etc/pki/idp_fccn_pt_cert.cer
ssl_cert_chain_file_name: idp_fccn_pt_interm.cer
path_ldap_cert_file: /opt/shibboleth-idp/credentials
ldap_cert_file_name: ldap_cert.crt
idp_cert_name: idp.crt
idp_key_name: idp.key
idp_metadata_name: idp-metadata.xml

#
# Configurações de Base de Dados
################################
postgresql_backup_dest: /var/lib/postgresql/backups     #Não alterar

#
# Configurações Tomcat
######################
tomcat_version: 9.0.68      #Não alterar
tomcat_xms: 512M
tomcat_xmx: 3072M

#
# Configurações Shibboleth
##########################
user_test: authmonit                                      #utilizador de monitorização dado à FCCN. O nome de utilizador padrão é authmonit
attribute_scope:  fccn.pt
choose_ldap: ldaps                                        # escolher entre ldaps e ldap
ip_range_access_control: '0.0.0.0/0'                      # Tem de estar obrigatoriamente entre 'plicas'
# No caso de testes aaitest, caso de produção rctsaai,engine-rctsaai-key-20250210
idp_metadata: 
  - rctsaai
  - engine-rctsaai-key-20250210         
# Pode ser o endereco IP ou o FQDN do servidor da AD ou LDAP server
ldap_url: 
  - ad1.fccn.pt 
  - ad2.fccn.pt 
  - ad3.fccn.pt           
ldap_dn_format: dc=fccn,dc=pt
ldap_port: 636                                            # Porto de ligação à AD ou LDAP (standart 389)
ldap_username: XXXXXXX
ldap_password: XXXXXXX
ldap_type: sAMAccountName                                 # No caso de AD sAMAccountName, no caso de LDAP uid
pgsql_username: shibboleth
salt: XXXXXXXXXXXXXXX
idp_version: 4.3.0                                                      #Não alterar
source_directory: /usr/local/dist/shibboleth-identity-provider-4.3.0    #Não alterar
installation_directory: /opt/shibboleth-idp                             #Não alterar

#
# Links Shibboleth
##########################
link_suporte: https://confluence.fccn.pt/pages/viewpage.action?pageId=16810329
link_rctsaai: https://confluence.fccn.pt/display/RCTSAAI/RCTSaai
link_seguranca: https://confluence.fccn.pt/display/RCTSAAI/FAQ
link_ajuda: https://confluence.fccn.pt/display/RCTSAAI/Contactos+de+Suporte+RCTSaai
link_esqueceu_palavra_chave: https://www.fccn.pt
idp_logo_url: https://www.fccn.pt

#
# Configuração do Layout
########################
org_layout: FCCN
idp_logo_img_name: idp_logo.png
idp_bg_img_name: bg_web.jpg
#
# Atualizar IDP
########################
update_idp: true               # y para utilizar certificados e chaves antigas ou qualquer outro valor para nao utilizar
backup_bd_shib: true

#
# Configurações AutenticacaoGov
##########################
authGov_cmd_display: true       # Enable/ Disable CC/CMD na página de login - 'true' to enable - 'false' to disable (obrigatoriamente entre 'plicas')
authGov_assertionConsumerUrl: https://idp.fccn.pt/idp/Authn/AutenticacaoGov/LoginResponse          # 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. Por exemplo: https://idp.fccn.pt/idp/Authn/AutenticacaoGov/LoginResponse.
authGov_providerName: Fundaç para a Ciêia e a Tecnologia                  # Nome do provider enviado na mensagem SAML. Valor enviado e acordado com a AMA. Por exemplo: Fundaç para a Ciêia e a Tecnologia
authGov_issuerId: idp.fccn.pt                      # Issuer enviado na mensagem SAML. Valor enviado e acordado com a AMA. Por exemplo: fccn.pt
authGov_faaaLevel: 3                     # 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 exemplo: 3
authGov_link_logout_success: https://idp.fccn.pt/idp/profile/Logout           # Endpoint após logout bem sucedido. Por exemplo: https://idp.fccn.pt/idp/profile/Logout
authGov_link_logout_error: https://idp.fccn.pt/idp/profile/Logout             # Endpoint após logout mal sucedido. Por exemplo: https://idp.fccn.pt/idp/profile/Logout

authGov_path_ssl_cert: /opt/shibboleth-idp/credentials/
authGov_govIdp_crt: saml.autenticacao.gov.pt.crt                    # Caminho do certificado para validação das respostas da AMA. Exemplo: /opt/shibboleth-idp/credentials/saml.autenticacao.gov.pt.crt
authGov_sign_crt: idp-fa.fccn.pt.crt                      # Caminho do certificado para cifrar pedidos enviados à AMA pelo IdP.
authGov_sign_privateKey: idp-fa_fccn_pt_PKCS8.key               # Caminho da key para assinatura de pedidos enviados à AMA pelo IdP (a key deverá estar no formarto PKCS8).

Tipos de instalação

O playbook permite efectuar diferentes tipos de instalações, através do uso de tags:

• idp: instalação apenas do Shibboleth IDP v4.3.0
• 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.

---

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

Se estiver a atualizar o IDP, 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/NomeDaInstituicao/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/NomeDaInstituicao/images/ e adicione o seu nome na variável idp_bg_img_name no ficheiro general_definitions.

Altere o nome da pasta NomeDaInstituicao 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.

Atualizar o layout manualmente

Sempre que se fizer manualmente alterações aos layouts do IDP (em /opt/shibboleth-idp/edit-webapp/), é necessário reconstruir o idp.war e reiniciar o serviço tomcat, utilizando os seguintes comandos:

[root@idp-server]# sudo JAVACMD=/usr/bin/java /opt/shibboleth-idp/bin/build.sh -Didp.target.dir=/opt/shibboleth-idp
[root@idp-server]# service tomcat restart

Pré-requisitos Autenticacao.Gov

Existem um conjunto de requisitos que devem ser preenchidos antes de se instalar o plug-in de Autenticacao.Gov, nomeadamente. Para mais informações acerca dos procedimentos que deve seguir antes de instalar o plug-in Autenticacao.Gov, siga as instruções descritas na secção Plug-In AutenticacaoGov.

Este playbook permite a instalação do plugin AutenticacaoGov e a aplica uma configuração de testes. Este processo pode ser revertido utilizando as respetivas tags (para mais informação, veja a secção Tipos de Instalação). Para utilizar esta funcionalidade do playbook terá de:

1. Assinar o protocolo com a AMA.
2. Para efeitos de demonstração: Preencher o ficheiro db_data.csv na pasta roles/cc-cmd/files/db_stuff/.
3. Adicionar os certificados enviados pela AMA na diretoria cc-cmd-install/files/certs. O nome destes ficheiro deve ser o mesmo que foi colocado no ficheiro general_definitions.

Instalação com múltiplas ADs

No ficheiro general_attributes, coloque os IPs ou nomes das ADs entre pelicas e separados por espaços, por exemplo, 'AD1 AD2 AD3' em que AD1, AD2 e AD3 são os nomes das ADs.

Caso pretenda utilizar o protocolo LDAPS tem de construir um certificado com o seguinte formato:

• Certificado da cadeia de confiança
• Certificados dos ADs

Por exemplo:

-----BEGIN CERTIFICATE-----
Certificado da cadeia de confiança
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
Certificado da AD1
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
Certificado da AD2
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
Certificado da AD3
-----END CERTIFICATE-----

---

Instalação do Shibboleth

Após o preenchimento do ficheiro de configurações, o IDP pode ser instalado executando o playbook.

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

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

Por exemplo, para executar uma instalação do Shibboleth IDP, editar o layout e instalar e configurar o plugin autenticacaoGov, execute:

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

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

PLAY RECAP *********************************************************************
localhost                  : ok=181  changed=141  unreachable=0    failed=0    skipped=16   rescued=0    ignored=0   

Plug-In AutenticacaoGov

Este plug-in tem como objectivo permitir integrar no IDP Shibboleth V4 a autenticação com a Chave Móvel Digital, autenticação com o Cartão do Cidadão e autenticação com eid-stork2 (também baseado no cartão do cidadão português e de outros países europeus).

Pré-requisitos

Para que se possa proceder à correta configuração de um Fornecedor de Identidade junto do Autenticação.Gov, é necessário primeiro estabelecer um protocolo com a Agência para a Modernização Administrativa (AMA). Para esse efeito, devem ser seguidos os passos descritos na página Celebrar Protocolo com a AMA (Agência para a Modernização Administrativa). Para ter acesso a esta página deve enviar um e-mail para [email protected].

Funcionamento do plug-in

Após uma autenticação bem sucedida com o Autenticação.Gov, este irá retornar ao IDP o valor do número do cartão do cidadão ou do passaporte. Nesse caso, o IDP terá que validar internamente se existe algum utilizador da instituição com algum desses dados. Para esse fim, durante a instalação é criada uma tabela na base de dados de PostgreSQL do IDP, que estabelece a ligação entre os nomes de utilizadores da instituição e o nº do CC e do passaporte. Estes dados nunca são enviados para os serviços, sendo apenas utilizados para verificar se existe correspondência entre eles e o username de algum colaborador da instituição (para além disso, esta implementação armazena na base de dados apenas uma hash destes dados e não os valores em si).

Para efeitos de demonstração do funcionamento do plug-in, durante a instalação do mesmo, é criada uma tabela (rm_idp) na base de dados do Shibboleth IDP (ver o script roles/cc-cmd/templates/db_script.py). Durante a instalação, esta tabela é populada com os dados existentes no ficheiro roles/cc-cmd/files/db_stuff/db_data.csv.

Antes de instalar o plug-in da autenticacaoGov (com a flag do ansible --flag=full ou --flag=cc) deve primeiro colocar os dados válidos de pelo menos um utilizador no ficheiro roles/cc-cmd/files/db_stuff/db_data.csv. Este ficheiro .csv não necessita de headers, pelo que deve substituir a linha fornecida como exemplo (utilizador1,XXXXXXXX,AA000000) pelos dados de um utilizador válido, ou seja, nome do utilizador como está guardado na AD, Nº ID CIVIL e Passaporte (se desejar, pode testar com múltiplos utilizadores, colocando um por linha).

Adaptar o plug-in à instituição

Caso a instituição pretenda ficar com o plug-in da autenticacaoGov instalado, e adaptá-lo à totalidade dos utilizadores internos, pode ser utilizado como base o script db_script.py que fica instalado na pasta /opt/shibboleth-idp/bin/. Para tal, será necessário alterar o local onde os dados serão lidos (por exemplo, deixando de usar o ficheiro de demonstração .csv para se usar a base de dados de utilizadores da instituição).

Nota: Como forma de garantir que os utilizadores reconhecidos pelo IDP (após autenticacaoGov) estão atualizados com os utilizadores da instituição, este script deve ser executado com alguma frequência. Por exemplo, 1 vez por semana.

Desinstalar plug-in

O plug-in pode ser removido na totalidade sem ser necessário reinstalar a totalidade do IDP (incluindo a tabela rm_idp). Para tal, basta correr o seguinte comando:

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

Dependências

Esta instalação foi testado numa máquina Debian, com a seguinte configuração:

• Debian 11
• Ansible 2.10.8