Difference: AtualizacaoShibboleth3 (r3 vs. r2)

Atualização do Shibboleth para versão 3.2.1

1 Objetivo

Este documento descreve os passos necessários para atualizar, manualmente, o Shibboleth (software usado para Provedor de Identidade da CAFe) para a versão 3.2.1, última versão estável homologada pela RNP.

A RNP disponibiliza uma máquina virtual para realizar o processo de atualização de forma mais simplificada, porém caso você deseje aplicar a atualização manualmente, mantendo o servidor no perfil de instalação e configuração da sua instituição, poderá seguir esse procedimento.

2 Definições

Shibboleth: software desenvolvido pela Internet2 (rede acadêmica dos Estados Unidos) que funciona como framework para implementar um Provedor de Identidade (IdP) através do protocolo SAML.
IdP: Ou Provedor de Identidade, é responsável por associar uma identidade a um usuário, após um processo de autenticação. O usuário então recebe uma credencial, chamada de identidade.

3 Pré-requisitos

Tomcat 7 ou superior
Java 7 ou superior (pode ser o Java OpenJDK)

4 Descrição das etapas

Baixar o tarball de instalação do código do Shibboleth na versão 3.2.1 com as customizações da RNP (metadados das federações, configuração de filtro e resolução de atributos etc.):

cd /root wget https://nuvem.ufba.br/index.php/s/YEmrldVlNBOX3wA https://wiki-sti.ufba.br/foswiki/pub/Wiki/AtualizacaoShibboleth3/shibboleth-identity-provider-3.2.1-rnp.tgz -O shibboleth-identity-provider-3.2.1-rnp.tgz tar -xzf shibboleth-identity-provider-3.2.1-rnp.tgz

Em seguida, será necessário configurar alguns parâmetros referentes ao seu IDP e ao LDAP/AD da sua instituição. Em particular, você precisará das seguintes informações:

LDAP_SERVIDOR, URL do servidor LDAP/AD, exemplo: ldap://localhost:389
LDAP_BASE, raiz da base LDAP/AD, exemplo: dc=foobar,dc=br
LDAP_USER, usuário que fará login (bind) na base LDAP/AD para buscar os usuários (busca não anônima), exemplo: cn=leitor-shib,ou=apps,dc=foobar,dc=br
LDAP_PASS, senha do usuário de bind do LDAP/AD, exemplo: XXXXXXXXX
LDAP_USERSDN, sub-árvore de usuários onde o shibboleth irá buscar, exemplo: ou=people,dc=foobar,dc=br
Caso esteja utilizando autenicação no AD, você precisará alterar os atributos de busca (uid para sAMAccountName) e formato do DN de usuário. Os comentários ajudam a entender as mudanças necessárias.

Abaixo vamos mostrar a criação do arquivo de parâmetros do LDAP considerando as variáveis acima e seus respectivos valores ilustrados:

cat >  /root/shibboleth-identity-provider-3.2.1-rnp/dist/conf/ldap.properties.dist <<-EOF
# LDAP authentication configuration, see authn/ldap-authn-config.xml
## Authenticator strategy, either anonSearchAuthenticator, bindSearchAuthenticator, directAuthenticator, adAuthenticator
#idp.authn.LDAP.authenticator                   = anonSearchAuthenticator
idp.authn.LDAP.authenticator                   = bindSearchAuthenticator
## Connection properties ##
idp.authn.LDAP.ldapURL                         = ldap://localhost:389
idp.authn.LDAP.useStartTLS                     = false
idp.authn.LDAP.useSSL                          = false
idp.authn.LDAP.connectTimeout                  = 30000
## SSL configuration, either jvmTrust, certificateTrust, or keyStoreTrust
#idp.authn.LDAP.sslConfig                       = certificateTrust
## If using certificateTrust above, set to the trusted certificate's path
#idp.authn.LDAP.trustCertificates                = %{idp.home}/credentials/ldap-server.crt
## If using keyStoreTrust above, set to the truststore path
#idp.authn.LDAP.trustStore                       = %{idp.home}/credentials/ldap-server.truststore
## Return attributes during authentication
## NOTE: this is not used during attribute resolution; configure that directly in the
## attribute-resolver.xml configuration via a DataConnector's  element
idp.authn.LDAP.returnAttributes                 = uid
## DN resolution properties ##
# Search DN resolution, used by anonSearchAuthenticator, bindSearchAuthenticator
# for AD: CN=Users,DC=example,DC=org
idp.authn.LDAP.baseDN                           = dc=foobar,dc=br
idp.authn.LDAP.subtreeSearch                    = true
idp.authn.LDAP.userFilter                       = (uid={user})
# bind search configuration
# for AD: idp.authn.LDAP.bindDN=adminuser@domain.com
idp.authn.LDAP.bindDN                           = cn=leitor-shib,ou=apps,dc=foobar,dc=br
idp.authn.LDAP.bindDNCredential                 = XXXXXXXX
# Format DN resolution, used by directAuthenticator, adAuthenticator
# for AD use idp.authn.LDAP.dnFormat=%s@domain.com
idp.authn.LDAP.dnFormat                         = uid=%s,ou=people,dc=foobar,dc=br
# LDAP attribute configuration, see attribute-resolver.xml
idp.attribute.resolver.LDAP.ldapURL             = %{idp.authn.LDAP.ldapURL}
idp.attribute.resolver.LDAP.baseDN              = %{idp.authn.LDAP.baseDN}
idp.attribute.resolver.LDAP.bindDN              = %{idp.authn.LDAP.bindDN}
idp.attribute.resolver.LDAP.bindDNCredential    = %{idp.authn.LDAP.bindDNCredential}
idp.attribute.resolver.LDAP.useStartTLS         = %{idp.authn.LDAP.useStartTLS:true}
idp.attribute.resolver.LDAP.trustCertificates   = %{idp.authn.LDAP.trustCertificates}
idp.attribute.resolver.LDAP.searchFilter        = (uid=\$requestContext.principalName)
# LDAP pool configuration, used for both authn and DN resolution
#idp.pool.LDAP.minSize                          = 3
#idp.pool.LDAP.maxSize                          = 10
#idp.pool.LDAP.validateOnCheckout               = false
#idp.pool.LDAP.validatePeriodically             = true
#idp.pool.LDAP.validatePeriod                   = 300
#idp.pool.LDAP.prunePeriod                      = 300
#idp.pool.LDAP.idleTime                         = 600
#idp.pool.LDAP.blockWaitTime                    = 3000
#idp.pool.LDAP.failFastInitialize               = false
EOF

Em seguida, será necessário configurar alguns parâmetros referentes ao seu IDP, a saber:

IDP_DOMINIO, domínio da instituição, exemplo: foobar.br
IDP_HOSTNAME, nome do servidor que será disponibilizado para acesso ao IDP, exemplo: idp-cafe.foobar.br

Abaixo vamos mostrar a criação do arquivo de parâmetros do IDP considerando as variáveis acima e seus respectivos valores ilustrados:

cat >  /root/shibboleth-identity-provider-3.2.1-rnp/dist/conf/idp.properties.dist <<-EOF
idp.additionalProperties= /conf/ldap.properties, /conf/saml-nameid.properties, /conf/services.properties
 
idp.entityID= https://idp-cafe.foobar.br/idp/shibboleth
 
idp.scope= foobar.br
 
idp.sealer.storeResource= %{idp.home}/credentials/sealer.jks
idp.sealer.versionResource= %{idp.home}/credentials/sealer.kver
idp.sealer.storePassword= changeit
idp.sealer.keyPassword= changeit
 
idp.signing.key= %{idp.home}/credentials/idp.key
idp.signing.cert= %{idp.home}/credentials/idp.crt
idp.encryption.key= %{idp.home}/credentials/idp.key
idp.encryption.cert= %{idp.home}/credentials/idp.crt
 
idp.authn.flows= Password
 
idp.status.accessPolicy= AccessByIPAddress
idp.resolvertest.accessPolicy= AccessByIPAddress
idp.reload.accessPolicy= AccessByIPAddress
 
idp.ui.fallbackLanguages= pt-br,en

idp.cafe.computedIDsalt = `openssl rand -base64 32`
EOF

Abaixo vamos mostrar a criação do arquivo de outros parâmetros do IDP. Aqui você precisará se atentar ao parâmetro sourceAttribute, pois ele será diferente se usar AD. Abaixo exemplo conforme valores ilustrativos anteriores:

cat > /root/shibboleth-identity-provider-3.2.1-rnp/dist/conf/saml-nameid.properties.dist <<-EOF
# Properties involving SAML NameIdentifier/NameID generation/consumption

# For the most part these settings only deal with "transient" and "persistent"
# identifiers. See saml-nameid.xml and c14n/subject-c14n.xml for advanced
# settings

# Comment out to disable legacy NameID generation via Attribute Resolver
#idp.nameid.saml2.legacyGenerator = shibboleth.LegacySAML2NameIDGenerator
#idp.nameid.saml1.legacyGenerator = shibboleth.LegacySAML1NameIdentifierGenerator

# Default NameID Formats to use when nothing else is called for.
# Don't change these just to change the Format used for a single SP!
#idp.nameid.saml2.default = urn:oasis:names:tc:SAML:2.0:nameid-format:transient
#idp.nameid.saml1.default = urn:mace:shibboleth:1.0:nameIdentifier

# Set to shibboleth.StoredTransientIdGenerator for server-side transient ID storage
#idp.transientId.generator = shibboleth.CryptoTransientIdGenerator

# Persistent IDs can be computed on the fly with a hash, or managed in a database

# For computed IDs, set a source attribute and a secret salt:
idp.persistentId.sourceAttribute = uid
#idp.persistentId.useUnfilteredAttributes = true
# Do *NOT* share the salt with other people, it's like divulging your private key.
#idp.persistentId.algorithm = SHA
idp.persistentId.salt = `openssl rand -base64 32`

# To use a database, use shibboleth.StoredPersistentIdGenerator
#idp.persistentId.generator = shibboleth.ComputedPersistentIdGenerator
# For basic use, set this to a JDBC DataSource bean name:
#idp.persistentId.dataSource = PersistentIdDataSource
# For advanced use, set to a bean inherited from shibboleth.JDBCPersistentIdStore
#idp.persistentId.store = MyPersistentIdStore
# Set to an empty property to skip hash-based generation of first stored ID
#idp.persistentId.computed = shibboleth.ComputedPersistentIdGenerator
EOF

O próximo passo é executar o script de instalação do shibboleth, conforme ilustrado abaixo. Atente-se, pois, ao executar esse script de instalação ele irá processar os parâmetros e em seguida ficará aguardando um ENTER para continuar a instalação. Observe, ainda, que a instalação será feita no diretório /opt/shibboleth-idp-3 para não entrar em conflito com a instalação existente do shibboleth.

# variavel de ambiente do java, altere segundo a sua instalacao (ex: oracle java, java8 etc)
export JAVA_HOME="/usr/lib/jvm/java-7-openjdk-amd64"

# Executa a instalacao
/root/shibboleth-identity-provider-3.2.1-rnp/bin/install.sh \
   -Didp.src.dir=/root/shibboleth-identity-provider-3.2.1-rnp \
   -Didp.target.dir=/opt/shibboleth-idp-3 \
   -Didp.sealer.password=changeit \
   -Didp.keystore.password=changeit \
   -Didp.conf.filemode=644 \
   -Didp.host.name=idp-cafe.foobar.br \
   -Didp.scope=ufba.br \
   -Didp.entityID=https://idp-cafe.foobar.br/idp/shibboleth

Agora precisaremos copiar os Certificados Digitais do IDP Shibboleth na versão anterior para a nova instalação (caso seja uma instalação nova, veja CertificadoIDPShib):

cd /opt/shibboleth-idp-3/credentials/
rm -f idp*
cp /opt/shibboleth-idp/credentials/{idp.crt,idp.key} ./

Ainda na pasta de certificados, vamos gerar o pacote de certificados para ser usado pelo TOMCAT, caso opte pelo proxy com SSL (não é obrigatório):

# forneca a senha: changeit (igual a /etc/tomcat7/server.xml)
openssl pkcs12 -export -in idp.crt -inkey idp.key -out idp.p12 -name idp -caname selfsigned

Metadados da CAFe / RNP

Junto com o pacote do shibboleth-idp-3.2.1-rnp foi disponibilizado também o arquivo de metadados da federação CAFe. Precisaremos fazer alguns ajustes nesse arquivo e copiá-lo para a pasta do shibboleth-3.

O primeiro passo é copiá-lo para a pasta do shibboleth-idp-3:

cp /root/idp-metadata.cafe.xml.dist /opt/shibboleth-idp-3/metadata/idp-metadata.xml

Em seguida, alterar alguns parâmetros específicos da sua instituição, a saber:

DOMINIO, domínio da instituição, exemplo: foobar.br
HOSTNAME, nome do servidor que será disponibilizado para acesso ao IDP, exemplo: idp-cafe.foobar.br
SIGLA, sigla da sua instituição, exemplo: FOOBAR
NOME, nome completo da sua instituição, exemplo: Foo Bar University
CONTATO, nome do contato técnico da sua instituição, exemplo: Setor de Tecnologia da Informacao
EMAIL, e-mail do contato técnico da sua instituição, exemplo: setorti@foobar.br

Abaixo vamos mostrar a criação do arquivo de parâmetros da instituição considerando as variáveis acima e seus respectivos valores ilustrados:

sed -i -e "s/SUBSTITUIR_URL/idp-cafe.foobar.br/g" -e "s/SUBSTITUIR_HOSTNAME/idp-cafe.foobar.br/g" \
   -e "s/SUBSTITUIR_DOMINIO_INSTITUICAO/foobar.br/g" -e "s/SUBSTITUIR_SIGLA/FOOBAR/g" \
   -e "s/SUBSTITUIR_INSTITUICAO/Foo Bar University/g" -e "s/SUBSTITUIR_NOME_CONTATO_TECNICO/Setor de Tecnologia da Informacao/g" \
   -e "s/SUBSTITUIR_EMAIL_CONTATO_TECNICO/setorti@foobar.br/g" \
      /opt/shibboleth-idp-3/metadata/idp-metadata.xml

Agora precisamos inserir o certificado digital do seu IDP no arquivo de metadados. Para isso, execute os seguintes passos:

sed -e '1d' -e '$d' /opt/shibboleth-idp-3/credentials/idp.crt > /tmp/idp.crt.tmp
      
awk '/SUBSTITUIR_CONTEUDO_DO_ARQUIVO_DO_CERTIFICADO/ { system ("cat /tmp/idp.crt.tmp") } \
   !/SUBSTITUIR_CONTEUDO_DO_ARQUIVO_DO_CERTIFICADO/{ print; }' /opt/shibboleth-idp-3/metadata/idp-metadata.xml > /opt/shibboleth-idp-3/metadata/idp-metadata.tmp
   
mv /opt/shibboleth-idp-3/metadata/idp-metadata.tmp /opt/shibboleth-idp-3/metadata/idp-metadata.xml

sed -i "s/\r//g" /opt/shibboleth-idp-3/metadata/idp-metadata.xml

Feito esse processo, será necessário corrigir a configuração do attribute-resolver para aumentar a quantidade de entradas retornadas na busca, permitindo usuários que possuem múltiplos vínculos a terem todos os seus vínculos mapeados, e aumentando o tempo máximo da busca, a fim de evitar que sobrecargas no servidor LDAP retornem erro no IDP. Para isso, edite o arquivo /opt/shibboleth-idp-3/conf/attribute-resolver.xml e adicione o seguinte:

diff --git a/attribute-resolver.xml b/attribute-resolver.xml
index 02ffef5..932f190 100644
--- a/attribute-resolver.xml
+++ b/attribute-resolver.xml
@@ -132,6 +132,7 @@ rev 5 - Sanitização do arquivo e adequação ao Shibboleth 3
        
  
        
  
        

 Configuração Shibboleth / Tomcat 

 É preciso corrigir as permissões do Shibboleth para o usuário e grupo do tomcat: 

USER=$(grep tomcat /etc/passwd | cut -d: -f1)
GROUP=$(grep tomcat /etc/group | cut -d: -f1)
chown -R $USER:$GROUP /opt/shibboleth-idp-3/{credentials,logs,metadata}

 Editar o arquivo de deploy do IDP no tomcat (/etc/tomcat7/Catalina/localhost/idp.xml), para deixá-lo da seguinte forma:    

 Editar a configuração do tomcat e alterar o Connector da porta 8009 para aceitar conexões para as webapps (IDP) invés de redirecionar para a porta com SSL (8443). Para isso, edite o arquivo /etc/tomcat7/server.xml para comentar a conexão anterior ao Shibboleth, retirar o redirecionamento e habilitar a nova conexão via protocolo AJP, conforme abaixo: 

diff --git a/tomcat7/server.xml b/tomcat7/server.xml
index 33165a6..c54dced 100644
--- a/tomcat7/server.xml
+++ b/tomcat7/server.xml
@@ -92,6 +92,8 @@
     -->
 
     
+    
+    
 
 
     
+       
+               
+               
+               
+       
+
+       
+       
+               
+               
+               
+       
+
+       
+       
+               
+               
+               
+       
+
+       
+       
+               
+               
+               
+       
+
+       
+       
+               
+               
+               
+       
  
        
        
        
+
+       
+               
+                       %{idp.scope}
+               
+               
+                       urn:schac:homeOrganizationType:int:university
+               
+       

 Reiniciar o tomcat: 

/etc/init.d/tomcat7 restart

 Acompanhar nos logs: 

tail -n 1000 -f /opt/shibboleth-idp/logs/idp-process.log /var/log/tomcat7/catalina.out

 Para testar se o acesso ao Edugain está funcionando corretamente, acesse https://attribute-viewer.aai.switch.ch/interfederation-test/ e execute o processo de autenticação. Caso os atributos estejam resolvendo corretamente no seu IDP, você deveria visualizar as seguintes telas de sucesso: 





 Customização da página de Login 

 Na versão 3 do shibboleth o mecanismo padrão para renderização das páginas de login, erro e consentimento mudou de JSP para templates Velocity, eliminando a necessidade de reiniciar o Container Servlet (tomcat) a cada modificação. Em particular, com os templates no formato Velocity, basta modificar os arquivos .vm no diretório /opt/shibboleth-idp/views que imediatamente as mudanças serão refletidas no IDP. 

 No caso da UFBA, modificamos os templates para deixá-los com a identidade visual da Universidade, de acordo com os passos adotados pela federação SWITCHaai. Para aplicar os templates da UFBA, execute os seguintes passos: 

cd /root wget https://nuvem.ufba.br/index.php/s/MeqSQrPOMjJxkTG https://wiki-sti.ufba.br/foswiki/pub/Wiki/AtualizacaoShibboleth3/custom-login-page-v3.tgz -O custom-login-page-v3.tgz tar -xzf custom-login-page-v3.tgz -C /opt/shibboleth-idp-3/ 

 O tarball acima inclui os seguintes arquivos, customizados para o ambiente da UFBA: 

 Três arquivos de template Velocity (substituindo os arquivos padrões em /opt/shibboleth-idp-3/views): login.vm, login-error.vm e error.vm. Mudanças nesses arquivos não necessitam de reinicialização do Tomcat. 
 Um outro arquivo de template velocity do Termo de uso, substituindo o arquivo /opt/shibboleth-idp-3/views/intercept/terms-of-use.vm
 Arquivos de CSS no diretório /opt/shibboleth-idp-3/edit-webapp/css: bootstrap.min.css e style.css, foi preferido criar esses arquivos novos invés de utilizar os antigos main.css e content.css 
 Arquivos de imagens no diretório /opt/shibboleth-idp-3/edit-webapp/images, com logo da UFBA, favicon, fontes etc. 
 Uma página alternativa para o index.jsp padrão do IDP, para o caso de alguém tentando acessar a página raiz do IDP (ex: https://cafe.ufba.br/idp/), o que não deve ocorrer em circunstâncias normais, e que retorna a mensagem padrão "Nenhum serviço disponível aqui" 

 Após essas alterações, é necessário reconstruir o WAR do IDP, pois fizemos alterações no diretório edit-wabapp. Para isso, execute os passos abaixo: 

JAVACMD=/usr/bin/java /opt/shibboleth-idp-3/bin/build.sh -Didp.target.dir=/opt/shibboleth-idp-3

 Página de Consentimento e Termo de Uso 

 Para alterar a página de consentimento e termo de uso, será necessário editar alguns arquivos e modificar algumas propriedades do Shibboleth. Em particular, no caso da UFBA, decidimos por omitir a página de consentimento do usuário e por ativar a página do termo de uso, que já versa sobre os atributos disponibilizados aos Provedores de Serviço. Dessa forma, os passos abaixo mostrarão como desativar a página de consentimento e ativar a página de termo de uso, utilizando como base a documentação Federação SWITCHaai. 

 O primeiro passo é alterar o relying-party para remover a obrigatoriedade do consentimento e adicionar do termo de uso. Para isso, edite o arquivo /opt/shibboleth-idp-3/conf/relying-party.xml e altere as seguintes definições: 

-
+
...
-
+
...
-
+

 Em seguida, no arquivo /opt/shibboleth-idp/conf/intercept/consent-intercept-config.xml desativar o alias para shibboleth.consent.terms-of-use.Key, comentando-o: 



 Ainda naquele mesmo arquivo, insira logo abaixo do comentário anterior uma nova definição do alias e do bean para o termo de uso: 






    


 Em seguida, no arquivo /opt/shibboleth-idp-3/messages/consent-messages.properties vamos definir a chave my-terms-of-use usada anteriormente. Para isso, comente as seguintes propriedades: 

#https\://sp.example.org = example-tou-1
#example-tou-1.title = Example Terms of Use
#example-tou-1.text  =  _ This is an example ToU - tailor due to your needs _  \
#                      ...
#                


 E adicione as seguintes propriedades do nosso Termo de Uso (atente-se para alterar para a URL do termo de uso da sua instituição): 

my-terms-of-use = my-tou
my-tou.title = Termo de uso do serviço CAFe IDP FOOBAR
my-tou.text = Termo de uso do serviço CAFe Provedor de Identidade FOOBAR \
              Veja o documento completo \
              aqui. \
              

 Ainda nesse arquivo, altere as seguintes propriedades: 

idp.terms-of-use.accept     = Eu li os termos de uso
idp.terms-of-use.submit     = Aceitar
idp.terms-of-use.reject     = Rejeitar
idp.terms-of-use.required   = Por favor marque essa opção se deseja continuar.

 Por fim, o arquivo /opt/shibboleth-idp-3/views/intercept/terms-of-use.vm possui o template Velocity que é exibido na tela do termo de uso, porém seu conteúdo já foi alterado na customização anterior. 

 Agora é necessário fazer um reload do Tomcat e testar seu funcionamento: 

/etc/init.d/tomcat7 restart
tail -n 300 -f /var/log/tomcat7/catalina.out /opt/shibboleth-idp/logs/idp-process.log

 Para testar se o termo de uso foi configurado com sucesso, acesse a página de teste da CAFe/RNP (https://sp.rnp.br/cafe) e verifique que após fazer o login, você precisa aceitar o termo de uso. No lado do servidor, aceitar o termo de uso gera a seguinte mensagem: 

prompt# grep Shibboleth-Consent-Audit.SSO /opt/shibboleth-idp-3/logs/idp-process.log
2016-07-07 14:10:31,774 - INFO [Shibboleth-Consent-Audit.SSO:241] - 20160707T171031Z|https://sp.rnp.br/cafe|TermsAccepted|fulano.tal@foobar.br|my-tou||true
2016-07-07 14:11:23,826 - INFO [Shibboleth-Consent-Audit.SSO:241] - 20160707T171123Z|https://sp.rnp.br/cafe|TermsRejected|fulano.tal@foobar.br|my-tou||false

 5 Plano de Testes 

 Realizar acesso ao portal de testes da RNP https://sp.rnp.br/cafe
 Escolher o provedor de identidade FOOBAR 
 Fornecer suas credenciais da sua organização e aceitar o termo de uso 
 Verificar se o retorno ao portal de teste da RNP inclui as informações do seu perfil na sua organização. Por exemplo: 



 6 Plano de Retorno 

 Corrigir o link simbólico do shibboleth: 

cd /opt
unlink shibboleth-idp
ln -s /opt/shibboleth-idp-2 shibboleth-idp

 Corrigir o xml de deploy do IDP, alterando o arquivo /opt/shibboleth-idp/war/idp.war



 Corrigir as configurações das portas do Tomcat para voltar ao padrão anterior: 

index c54dced..33165a6 100644
--- a/tomcat7/server.xml
+++ b/tomcat7/server.xml
@@ -92,8 +92,6 @@
     -->
 
     
-    
-