Shibboleth IdP 5.2.3 para Debian 13 - Integração com Active Directory

Nesta página vamos explicar como instalar um IDP Shibboleth 5.2.3 em Debian 13 integrado com uma Active Directory ou OpenLDAP. Para esta instalação é utilizado um Playbook Ansible que automatiza a instalação e configuração do Apache2, Java 17.0.18, Tomcat 11.0.6, PostgreSQL e Shibboleth IDP 5.2.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 ou OpenLDAP.
  • 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.

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

Playbook
Pode transferir o playbook através do link seguinte: Shibboleth IdP 5.2.3 para Debian 13 - Integração com AD.

1. Pré-requisitos

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

shell> apt install ansible unzip

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

shell> mv shibboleth-idp-5-2-3-debian-ORG.zip Shibboleth_IDP_5.2.3
shell> cd Shibboleth_IDP_5.2.3
shell> unzip shibboleth-idp-5-2-3-debian-ORG.zip

2. 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/all.yml

Descrição dos parâmetros a definir

A instalação do Shibboleth IdP depende das parametrizações efectuadas no ficheiro all.yml. Em baixo encontram-se descritas as parametrizações necessárias de preencher relativas à sua instituição:

2.1 Configurações Gerais do Apache

  • fqdn: hostname do idp a ser instalado (ex: idp.fccn.pt)
  • server_admin: contacto de admin do servidor (ex: idp-admin@fccn.pt)

2.2 Configuração SSL - Certificados

Tradicional ACME
configure_SSL_certificates: "Tradicional" configure_SSL_certificates: "ACME"

2.2.1 Configuração SSL Tradicional

  • configure_SSL_certificates: "Tradicional"
  • path_ssl_cert_apache: Localização dos certificados/chaves públicas usadas pelo apache (ex.: /etc/ssl/certs)
  • path_ssl_cert_apache_private: Localização dos certificados/chaves privadas usadas pelo apache (ex.: /etc/ssl/private)

Copiar ficheiros de certificados SSL do IdP para files/ORG/ssl-certs/

  • ssl_cert_key_file_name: Nome do ficheiro que contém o certificado privado usado pelo apache (ex.: idp_fccn_pt.key)
  • ssl_cert_file_name: Nome do ficheiro que contém o certificado público usado pelo apache (ex.: idp_fccn_pt_cert.cer)
  • ssl_cert_chain_file_name: Nome do ficheiro que contém os certificados da cadeia de confiança usada pelo apache (ex.: idp_fccn_pt_interm.cer)

2.2.2 Configuração SSL ACME

O cliente de ACME (certbot) necessita de credenciais de uma conta ACME (mac_id e mac_key), pelo que antes da execução Ansible, o Administrador da Instituição responsável pelos certificados SSL deve criar/configurar uma conta ACME no portal da HARICA associada aos domínios desejados.

  • configure_SSL_certificates: "ACME"
  • path_ssl_cert_apache: /etc/letsencrypt/live/{{ fqdn }} Não alterar
  • path_ssl_cert_apache_private: /etc/letsencrypt/live/{{ fqdn }} Não alterar
  • ssl_cert_key_file_name: Nome do ficheiro que contém o certificado privado usado pelo apache (ex.: privkey.pem)
  • ssl_cert_file_name: Nome do ficheiro que contém o certificado público e da cadeia de confiança usada pelo apache (ex.: fullchain.pem)
  • option_multi_domain: "single-domain" Não alterar
  • option_encryption_algorithm: ecdsa Não alterar
  • option_acme_account_name: IDP Não alterar
  • option_common_names_list: "{{ fqdn }}" Não alterar
  • contact_email: Contacto de email do responsável por esta configuração
  • acme_accounts:
    • name: IDP Não alterar
    • ca: acme-v02.harica.gr Não alterar
    • server: URL do diretório do servidor da HARICA associado à conta ACME (ex.: https://acme-v02.harica.gr/acme//directory)
    • mac_id: Adicionar a EAB Key ID da conta ACME previamente criada
    • mac_key: Adicionar o EAB HMAC Key da conta ACME previamente criada

2.3. Configurações Fail2Ban

  • destemail: endereço de e-mail para onde serão enviadas as notificações do Fail2Ban (ex.: admin@org.pt)
  • sender: endereço de e-mail que aparecerá como remetente nas notificações do Fail2Ban (ex.: admin@org.pt)

2.4. Configurações Tomcat

  • tomcat_major_version: 11 — versão do tomcat a utilizar. Não alterar
  • tomcat_version: 11.0.6 — versão do tomcat a utilizar. Não alterar
  • tomcat_xms: tamanho de heap size inicial em memória no arranque do Tomcat (ex.: 1024M)
  • tomcat_xmx: tamanho de heap size máximo em memória do Tomcat (ex.: 4096M)

2.5. Configurações Shibboleth

  • idp_version: versão do Fornecedor de Identidade. Não alterar
  • source_directory: diretoria onde são colocados os ficheiros de instalação do Shibboleth IdP. Por defeito: /usr/local/dist/shibboleth-identity-provider-5.2.3. Não alterar
  • installation_directory: diretoria de instalação do Shibboleth IdP. Por defeito: /opt/shibboleth-idp. Não alterar
  • update_idp: indica se pretende atualizar ou instalar o IdP de raiz. Para atualizar coloque true, para instalar de raiz coloque false
  • ip_range_access_control: Intervalo de IPs que podem aceder a endpoints sensíveis (ex.: https://HOSTNAME/idp/status). A rede deve estar obrigatoriamente entre plicas (ex.: "'133.16.11.0/24', '133.16.10.0/24'")
  • attribute_scope: Domínio da organização utilizado nos metadados e atributos (schacHomeOrganization, eduPersonScopedAffiliation) que identificam a organização (ex.: fccn.pt)
  • organization_name: nome da instituição (ex.: Fundação para a Computação Científica Nacional)
  • ou_organization_name: nome da unidade orgânica da instituição, caso se aplique (ex.: FCCN, Serviços Digitais FCT)
  • user_test: username da conta de monitorização fornecida à FCCN. O nome de utilizador padrão é monitidp

Configuração de Armazenamento de sessões do IdP

  • idp_session_storage: Define como deve ser armazenada a informação de sessão do utilizador. "Server-Side" armazena as sessões no servidor na BD PostgreSQL ou "Client-Side" armazena as sessões no cliente (Recomendado)

Configuração de Armazenamento de Termos e Condições e Consentimento

  • idp_consent_storage: Define como deve ser armazenada a informação de consentimento. "Server-Side" armazena os pedidos de consentimento e termos e condições no servidor na BD PostgreSQL ou "Client-Side" armazena os pedidos de consentimento e termos e condições no cliente.

Configuração de Identificadores Antigos (Transient + eduPersonTargetId)

  • idp_old_persistentId_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_old_persistentId_sourceAttribute: Identifique o atributo do LDAP que seja único para cada utilizador, que permaneça inalterado durante todo o ciclo de vida na instituição e que não seja reutilizado após a sua saída.
  • idp_old_persistenteId_generator: Define como deve ser armazenado o persistentId. "Stored" armazena o persistentId na base de dados PostgreSQL (recomendado) ou "Computed" calcula o persistentId dinamicamente sem armazenamento em BD.

Configuração de Identificadores Novos (samlPairwiseID + samlSubjectID)
Nota: É de extrema importância que o persistentId_sourceAttribute seja preenchido com um atributo único para cada utilizador, que permaneça inalterado durante todo o ciclo de vida na instituição e que não seja reutilizado após a sua saída. Se anteriormente não garantia estes requisitos para o Transient + eduPersonTargetId, esta é a oportunidade de identificar um novo atributo e cumprir os requisitos obrigatórios do protocolo RCTSaai.

  • idp_persistentId_salt: se for atualizar o IdP a partir de uma versão antiga e já tenha definido estes novos identificadores, coloque o valor antigo do salt. Caso contrário pode manter este campo vazio.
  • idp_persistentId_sourceAttribute: Identifique o atributo do LDAP que seja único para cada utilizador, que permaneça inalterado durante todo o ciclo de vida na instituição e que não seja reutilizado após a sua saída.
  • idp_persistenteId_generator: Define como deve ser armazenado o persistentId. "Stored" armazena o persistentId na base de dados PostgreSQL (recomendado) ou "Computed" calcula o persistentId dinamicamente sem armazenamento em BD.

Configuração da BD PostgreSQL

  • postgresql_version: versão do PostgreSQL a instalar. Não alterar
  • postgresql_host: endereço do servidor PostgreSQL. Por defeito: localhost. Não alterar
  • backup_bd_shib: Indica se deseja utilizar o backup do IdP de produção em caso de atualização (update_idp: true). Defina true para utilizar o backup ou false para não utilizar.

Comando a utilizar para realizar o PostgreSQL dump:

sudo pg_dump -U shibboleth -F c -f shibboleth

Copiar ficheiro para a seguinte localização files/ORG/idp-postgres-backup/

  • bd_backup_file_name: nome do ficheiro de backup da base de dados PostgreSQL (ex.: bd.sql)
  • postgresql_database: shibboleth Não alterar
  • postgresql_username: shibboleth Não alterar
  • postgresql_password: password de acesso à base de dados PostgreSQL — adicionar entre pelicas
  • 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 os dias durante a madrugada. /var/lib/postgresql/backups Não alterar

Configuração de Metadados do IdP

  • idp_entityID: Identificador único do IdP. Em caso de atualização (update_idp: true), mantenha o valor igual ao entityID do IdP atualmente em produção (ex.: https://idp.fccn.pt/idp/shibboleth)
  • idp_metadata_name: idp-metadata Não alterar

Nota: Em caso de atualização (update_idp: true) deve copiar os ficheiros dos certificados na pasta files/ORG/idp-metadata-certs/

  • idp_sign_cert_name: nome do ficheiro que contém o certificado utilizado para assinar asserções do IdP (ex.: idp-signing.crt)
  • idp_sign_key_name: nome do ficheiro que contém a chave privada utilizada para assinar asserções do IdP (ex.: idp-signing.key)
  • idp_encryption_cert_name: nome do ficheiro que contém o certificado utilizado para cifrar asserções do IdP (ex.: idp-encryption.crt)
  • idp_encryption_key_name: nome do ficheiro que contém a chave privada utilizada para cifrar asserções do IdP (ex.: idp-encryption.key)
  • idp_backchannel_cert_name: nome do ficheiro que contém o certificado utilizado para comunicação em backchannel com o IdP (ex.: idp-backchannel.crt)
  • idp_backchannel_key_name: nome do ficheiro que contém a chave privada utilizada para comunicação em backchannel (ex.: idp-backchannel.p12)

Configuração de Ligação ao LDAP / AD

  • type_of_idp: definir como ldap para integração com Active Directory ou OpenLDAP
  • choose_ldap: escolher entre ldaps (Recomendado) e ldap
  • ldap_cert_file_name: nome do ficheiro que contém os certificados do(s) servidor(es) LDAPS (ex.: ldap-server.crt)

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

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

Deve copiar os ficheiros dos certificados na pasta files/ORG/idp-ldaps-certs/

  • path_ldap_cert_file: /opt/shibboleth-idp/credentials Não alterar
  • ldap_url: endereço(s) do(s) servidor(s) da AD ou LDAP da instituição (ex.: dc01.org.pt, dc02.org.pt)
  • ldap_dn_format: Caminho da AD onde se encontram os utilizadores (ex.: dc=fccn,dc=pt)
  • ldap_port: Porto de ligação — ldap: 389, ldaps: 636
  • ldap_username: nome de utilizador que efetuará a ligação à AD ou LDAP da instituição (ex.: ldap_user@fccn.pt)
  • ldap_password: password de acesso à AD utilizada pelo utilizador definido para ldap_bind_dn
  • ldap_type: No caso de AD usar sAMAccountName, no caso de LDAP usar uid

Configuração do Sealer (sincronização de chaves)

O Sealer é responsável por cifrar tokens de sessão do IdP. Em ambientes com um único IdP não é necessário configurar esta secção. Em ambientes multi-IdP é obrigatório configurar as variáveis abaixo para garantir que as chaves ficam sincronizadas entre todos os nós.

  • idp_sealer_cron_host: hostname do IdP onde a cron será ativada — apenas um IdP deve executar o script de geração e sincronização de chaves (ex.: idp1.fccn.pt)
  • idp_sealer_sync_hosts: lista de hostnames de todos os IdPs separados por espaço, incluindo o que executa o script (ex.: idp1.fccn.pt idp2.fccn.pt)
  • idp_sealer_sync_user: utilizador com permissões SSH/SCP nos IdPs de destino. Por defeito: root

Pré-requisitos para ambientes multi-IdP:

  1. Gerar o par de chaves SSH no IdP que executa o script (se não existir):
ssh-keygen -t rsa -b 4096 -f /opt/tomcat/.ssh/id_rsa -N ""
  1. Copiar a chave pública para cada um dos IdPs de destino:
ssh-copy-id -i /opt/tomcat/.ssh/id_rsa.pub <idp_sealer_sync_user>@<hostname_idp_destino>

Configuração de Metadata Providers

  • idp_metadata_providers: Nesta secção podem ser adicionados vários "Metadata Providers". No ficheiro all.yml já se encontram os providers necessários (RCTSaai, RCTSaai Engine PRD, RCTSaai Engine QUA e Interfederação). Caso pretenda adicionar um novo provider é necessário preencher a seguinte secção:
    • id: Identificador do Provider (ex.: "RCTSaaiMD")
      file: Nome do ficheiro onde deve ser armazenado (ex.: "metadata.rctsaai.xml")
      url: URL onde se pode realizar o download (ex.: "https://registry.rctsaai.pt/rr/signedmetadata/federation/rctsaai/metadata.xml")
      maxValidInterval: "P7D" Não alterar
      disregardTLSCertificate: "false" Não alterar
      pubKey: adicionar o certificado de verificação de assinatura. Para obter a chave pública a partir de um certificado PEM executar: openssl x509 -pubkey -noout -in <certificado>.pem

Configuração de 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 na pasta /files/ORG/idp-layout/NomeDaInstituicao/images/ e indique o seu nome na variável idp_logo_img_name
  • Background: adicione o ficheiro na pasta /files/ORG/idp-layout/NomeDaInstituicao/images/ e indique o seu nome na variável idp_bg_img_name

Altere o nome da pasta NomeDaInstituicao para um nome apropriado no contexto da instituição e coloque-o na variável org_layout. Esta alteração vai também alterar o texto escrito no separador do browser na página do IdP.

  • org_layout: nome da pasta do layout da organização (ex.: FCCN)
  • organization_domain: domínio da organização (ex.: fccn.pt)
  • idp_logo_img_name: nome da imagem com o logotipo da instituição
  • idp_logo_url: URL para o qual o utilizador será redirecionado ao clicar no logotipo
  • idp_bg_img_name: nome da imagem de fundo da instituição
  • 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 (ex.: FAQ)
  • link_esqueceu_palavra_chave: URL para uma página onde é possível redefinir a palavra-chave

Configuração do plug-in autenticacaoGov

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', para desativar 'false'. O valor deve estar obrigatoriamente entre aspas simples.
  • 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 (ex.: https://idp.fccn.pt/idp/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 (ex.: https://idp.fccn.pt/idp/profile/Logout)
  • authGov_link_logout_error: endpoint após logout mal sucedido (ex.: https://idp.fccn.pt/idp/profile/Logout)
  • authGov_attributes_id: atributos de identificação solicitados à AMA, separados por ; (por defeito: NIC e Passaporte)
  • authGov_attributes_other: restantes atributos solicitados à AMA, separados por ;
  • authGov_path_ssl_cert: local onde os certificados da AMA serão guardados no IdP. Não alterar
  • authGov_ama_public_crt: nome do ficheiro com o certificado para validação das respostas da AMA (ex.: saml.autenticacao.gov.pt.crt). Copiar para files/ORG/idp-cc-cmd-certs/ama-certs/
  • authGov_idp_public_crt: nome do ficheiro com o certificado para cifrar pedidos enviados à AMA pelo IdP (ex.: idp-fa_pt.crt). Copiar para files/ORG/idp-cc-cmd-certs/idp-certs/
  • authGov_idp_private_key: nome do ficheiro com a chave privada para assinatura de pedidos enviados à AMA pelo IdP. A chave deverá estar no formato PKCS8 (ex.: idp-fa_pt_PKCS8.key). Copiar para files/ORG/idp-cc-cmd-certs/idp-certs/

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

3. Tipos de instalação

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

shell> ansible-playbook -i "localhost," --connection=local main.yml --tags=<tags>
  • 3.1 Instalação e Configuração Base do IdP --tags=base

Após o preenchimento do ficheiro de configurações (all.yml), o IdP pode ser instalado executando o playbook.

Para realizar a instalação base do Shibboleth IdP 5.2.3 utilize o seguinte comando:

shell> ansible-playbook -vv -i "localhost," --connection=local main.yml --tags=base

Caso pretenda realizar apenas a instalação ou apenas a configuração do role IdP pode executar os seguintes comandos:

shell> ansible-playbook -vv -i "localhost," --connection=local main.yml --tags=idp-install

shell> ansible-playbook -vv -i "localhost," --connection=local main.yml --tags=idp-config
  • 3.2 Configuração do Layout --tags=idp-layout

Realizar apenas a configuração do layout (requer que exista um IdP instalado):

shell> ansible-playbook -vv -i "localhost," --connection=local main.yml --tags=idp-layout

Caso pretenda actualizar o layout manualmente, é necessário realizar as alterações em /opt/shibboleth-idp/edit-webapp/, reconstruir o idp.war e reiniciar o serviço tomcat:

shell> sudo JAVACMD=/usr/bin/java /opt/shibboleth-idp/bin/build.sh -Didp.target.dir=/opt/shibboleth-idp
shell> service tomcat restart
  • 3.3 Plugin Autenticação.GOV --tags=idp-cc-cmd

Este plug-in tem como objectivo permitir integrar no IdP Shibboleth 5 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).

Atenção: Deve primeiro verificar se cumpre todos os pré-requisitos descritos na [Secção 4].

Instalação e configuração de testes do plug-in CC-CMD (requer que exista um IdP instalado):

shell> ansible-playbook -vv -i "localhost," --connection=local main.yml --tags=idp-cc-cmd

Caso pretenda realizar apenas a instalação do plugin:

shell> ansible-playbook -vv -i "localhost," --connection=local main.yml --tags=idp-cc-cmd-install

Caso pretenda realizar apenas a configuração de testes do plugin:

shell> ansible-playbook -vv -i "localhost," --connection=local main.yml --tags=idp-cc-cmd-config
  • 3.4 Outros Comandos

Caso pretenda remover o PostgreSQL:

shell> ansible-playbook -vv -i "localhost," --connection=local main.yml --tags=postgresql-remove

Caso pretenda remover o Apache2:

shell> ansible-playbook -vv -i "localhost," --connection=local main.yml --tags=apache2-remove

4. Plugin Autenticacao.Gov

Este playbook permite a instalação do plugin AutenticacaoGov e aplica uma configuração de testes. Para utilizar esta funcionalidade do playbook terá de:

  1. Assinar o protocolo com a AMA.
  2. Adicionar os certificados enviados pela AMA na diretoria files/ORG/idp-cc-cmd-certs/ama-certs/ e os certificados do IdP em files/ORG/idp-cc-cmd-certs/idp-certs/. O nome destes ficheiros deve ser o mesmo que foi colocado no ficheiro all.yml.

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

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, Nacionalidade e Tipo de Documento. 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 temporária (utilizada apenas para testes, não deve ser utilizada em produção) 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, Tipo de Doc. e Nacionalidade.

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 efeitos de demonstração do funcionamento do plug-in, durante a instalação do mesmo, é criada uma tabela (info_cc_cmd) na base de dados do Shibboleth IdP (ver o script roles/idp-postgres/templates/idp-cc-cmd.sql.j2).

Após a instalação, pode aceder à base de dados de PostgreSQL do IdP e registar utilizadores para efectuar testes com a Autenticação.GOV:

shell> sudo -u postgres psql
postgres=# \c shibboleth
postgres=# \dt
postgres=# INSERT INTO info_cc_cmd (windowsuser, num_doc, tipo_doc, nacionalidade) VALUES ('jpereira','11111111','CC','PT');

Nota: tipo_doc: CC, PS, NIF (respectivamente Cartão do Cidadão, Passaporte e Número de Identificação Fiscal) nacionalidade: ALPHA-2 Code (https://www.iban.com/country-codes) Ex.: PT, BR, etc.