Nesta página vamos explicar como instalar um IDP Shibboleth 4.3.3 em Debian 12 integrado com uma Active Directory. Para esta instalação é utilizado um Playbook Ansible que automatiza a instalação e configuração do Apache2, Java 11, Tomcat 9, PostgreSQL e Shibboleth IDP 4.3.3. Este playbook permite fazer vários tipos de configuração. Permite:

• Instalar e configurar um IDP para ser possível fazer uma autenticação com a AD.
• Configurar um layout de acordo com a instituição.
• Instalar ou remover o plugin de autenticaçãoGov e configurá-lo para um ambiente de testes.
• Atualizar um IDP existente para a versão 4.3.3.

Estes métodos de instalação do playbook serão explicados em melhor detalhe na secção 2.1.

Pré-Requisitos

Antes de executar o playbook é necessário instalar o pacote ansible e unzip:

shell> apt install ansible unzip

Depois ter extraído o playbook, entre na nova pasta shibboleth-4-3-3-debian12-org:

shell> cd shibboleth-4-3-3-debian12-org

Certificados Apache

Caso ainda não tenha certificados para o frontend execute os passos 1 e 2. Se já tiver os certificados e estes estão válidos, execute apenas o passo 3.

1. Criar o CSR para realizar o pedido de certificado:

   shell> openssl req -new -newkey rsa:2048 -nodes -out idp_fccn_pt.csr -keyout idp_fccn_pt.key -subj "/C=PT/ST=Lisboa/L=Lisboa/O=FCCN/CN=idp.fccn.pt"

2. Aceda ao Portal da Sectigo e realize o pedido do certificado (o link para o pedido do certificado deve ser fornecido pela sua instituição). Quando o pedido for aceite, o certificado será enviado para o mail que colocou ao fazer o pedido

Configuração do playbook

Adicione as informações sobre a instituição no seguinte ficheiro:

shell> vi group_vars/general_definitions

Neste ficheiro vão estar as variáveis utilizadas pelo playbook durante a sua execução. Estas variáveis vão definir quais as configurações a serem colocadas no IDP de acordo com cada instituição.

Descrição das variáveis

A instalação do Shibboleth IdP depende dos valores colocados no ficheiro general_definitions.

Os parâmetros seguintes dizem respeito ao plug-in autenticacaoGov. Preencha estes atributos se pretender instalar o plugin.

Exemplo do ficheiro de configuração

Apresentamos um exemplo de configuração do ficheiro general_definitions para a FCCN:

#
# Configurações Apache
######################
organization_name: FCCN
organization_domain: fccn.pt
server_name: idp.fccn.pt
server_admin: idp-admin@fccn.pt

#
# 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: idp_fccn_pt.key
ssl_cert_file_name: 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.38      #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-20200211
idp_metadata: 
  - rctsaai
  - engine-rctsaai-key-20200211         
# 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.2.1                                                      #Não alterar
source_directory: /usr/local/dist/shibboleth-identity-provider-4.2.1    #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.2.1
• 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 "Pré-requisitos Autenticacao.Gov "
• 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 "Pré-requisitos Autenticacao.Gov "
• 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 "Pré-requisitos Autenticacao.Gov "
• 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.

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

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.

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: substituia o ficheiro idp_logo.png na pasta roles/layout/files/FCCN/images/ pela nova imagem. Mantenha o nome do ficheiro como idp_logo.png.

• background: substituia o ficheiro bg_web.jpg na pasta roles/layout/files/FCCN/images/ pela nova imagem. Mantenha o nome do ficheiro como bg_web.jpg.

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

Este playbook permite a instalação do plugin autenticacaoGov e a configuração para testes. Mais informação sobre a instalação e configuração do plugin na secção 3.

Existe um conjunto de variáveis que devem ser preenchidos antes de se instalar o plug-in de Autenticacao.Gov:

1. Protocolo com a AMA.
2. Apenas para testes: 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 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 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 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 objetivo 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 europeia (também baseado no cartão do cidadão português e de outros países europeus).

Flow de autenticação com o plugin AutenticacaoGov

Nesta secção vamos explicar o flow de autenticação utilizando o plugin AutenticacaoGov.

• O utilizador começa por autenticar-se perante o IDP utilizando a sua chave móvel digital.
• Tendo se autenticado com sucesso, o plugin envia ao IDP o número de identificação fiscal (NIF) do utilizador.
• O IDP vai confirmar se existe algum utilizador na instituição cujo NIF corresponde ao recebido. Isto é feito acedendo a uma base de dados com esta informação.
• Se existir, a base de dados vai retornar ao IDP o nome do utilizador.
• O IDP utiliza esse nome para procurar na AD pelos atributos do utilizador.

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 noc@fccn.pt.

Funcionamento do plug-in

1.Após uma autenticação bem sucedida com o plugin Autenticação.Gov, este vai retornar ao IDP o valor do número do cartão do cidadão ou do passaporte. 2.O IDP vai validar se existe algum utilizador da instituição com algum desses dados. Para isso, durante a instalação do plugin, o playbook cria uma tabela na base de dados de PostgreSQL do IDP, que estabelece a ligação entre os nomes dos 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 configurar o plug-in da autenticacaoGov 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).

Executar o playbook para instalar e configurar plug-in

Para executar o plugin de forma a instalar e configurar o plugin utilize o seguinte comando:

ansible-playbook -i "localhost," --connection=local main.yml --tags=cc

Pode utilizar este playbook para apenas instalar o plugin:

ansible-playbook -i "localhost," --connection=local main.yml --tags=cc-install

Pode utilizar este playbook para apenas configurar o plugin. O plugin já tem de estar instalado para este comando correr com sucesso.

ansible-playbook -i "localhost," --connection=local main.yml --tags=cc-config

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