Инструкция по установке Shibboleth Identity Provider (IdP) 3

    В данной инструкции описывается процесс установки и настройки технологического компонента Shibboleth Identity Provider (IdP) для работы в контексте федеративной среды FEDURUS. Документ предназначен для системных администраторов, владеющих навыками работы с командной строкой в Unix окружении, знакомых с синтаксисом XML (конфигурация IdP большей частью содержится в файлах XML) и имеющих опыт развертывания Java Web приложений на стороне сервера.

    Для развертывания Shibboleth IdP версии 3 рекомендуется использование промышленных операционных систем Linux с длительным сроком сопровождения: Ubuntu Server LTS или Red Hat Enterprise Linux / CentOS. Инструкция предназначена для версий данных операционных систем, выпущенных в 2014 году. Данные дистрибутивы будут получать обновления безопасности от производителей до апреля 2019 и июня 2024, соответственно. Инструкции по установке IdP для данных дистрибутивов довольно похожи и, в зависимости от выбранной вами операционной системы (см. форму ниже), разделы инструкции будут автоматически обновлены надлежащей информацией.

    Данная инструкция не предназначена для Ubuntu Server 16.04 LTS поскольку этот дистрибутив содержит OpenJDK 8 (и даже 9) и Tomcat 8. Общее описание установки для этих двух платформ сделает инструкцию более сложной и трудной в изложении последовательности действий. Ubuntu Server 16.04 LTS более предпочтительная платформа для IdP,но на данный момент мы не предоставляем официальную инструкцию для этой платформы.

    При обновлении с версии 2 Shibboleth IdP: (постоянная ссылка)

    При обновлении с конкретной версии Shibboleth IdP, обратитесь к соответсвующему разделу

    Обновление с версии v2.x IdP

    При обновлении, не рекомендуется производить оперативную замену существующего Shibboleth 2.x IdP. Рекомендуемая процедура состоит из установки новой версии 3.x на абсолютно новой машине (виртуально или физической) и переноса/адаптации, где это может быть применимо, конфигурации 2.x. Полный переход к v3 возможен только после положительных тестов взаимодействия новой системы с используемыми поставщиками ресурсов (service providers).

    Отдельные инструкции по обновлению помещены в блоки синего цвета в конце каждого соответствующего раздела. Их нельзя считать всеобъемлющими и, главным образом, они предназначены для выделения вопросов, на которые необходимо обратить внимание при подготовке к обновлению. Проект FEDURUS приветствует обратную связь от администраторов IdP v2 с информацией о собственном опыте обновления до v3. Таким образом инструкции по обновлению могут быть улучшены и быть полезными для других участников сообщества FEDURUS.

    На основании данных введенных выше, в разделах инструкции будут использоваться следующие параметры настройки:

    • домен организации: university.ru
    • доменное имя IdP: idp.university.ru
    • идентификатор entityID: https://idp.university.ru/shibboleth/idp
    • источник метаданных: и http://www.fedurus.ru/entities/interfederation+sp

    Системные требования

    Для Shibboleth IdP 3 рекомендуется машина по крайней мере с 2 GB оперативной памяти (4 GB для Interfederation-enabled IdP). Убедитесь, что в системе так же установлены следующие утилиты:

    sudo
    Рекомендуется установить sudo для выполнения команд, которым требуются привилегии пользователя root.
    curl
    Для загрузки программного обеспечения и шаблонов файлов конфигурации в инструкции используется утилита curl.
    OpenSSL
    Пакет: openssl, утилита командной строки, будет использоваться для работы с сертификатами сервера.
    unzip
    Используется для распаковки ZIP архивов и просмотра содержимого файлов архивов .war/.jar.

    Последнее и немаловажное, пожалуйста, обратите внимание на важность синхронизации времени средствами NTP для функционирования IdP. SAML сообщения содержат временные метки, которые проверяются технологическими компонентами поставщиков ресурсов (service providers), и смещение времени более чем на 5 минут гарантированно приведет к проблемам (SAML сообщения будут отклонятся и доступ к ресурсу будет не возможен даже при успешной аутентификации). В зависимости от вашей среды, возможно, потребуется установка пакета ntpd, в частности, при развертывании IdP в не виртуализированной системе.

    Рекомендуемое программное обеспечение сервера

    Shibboleth IdP - веб приложение (Java-based Web application), требующее для работы сервер приложений (Servlet container). Проект рекомендует использование следующих компонентов:

    • Apache HTTP Server 2.4 внешний веб сервис (Web frontend)
    • Apache Tomcat 7 сервер приложений Java (Java Servlet container)
    • PostgreSQL 9 база данных для хранения постоянных идентификаторов пользователей (persistent IDs) и пользовательского согласия (user consent)
    В начале инструкции приводится описание установки и настройки перечисленных выше компонентов и, далее, инструкции по установке и настройке Shibboleth IdP.

    Установка Apache HTTP Server

    Before installing the Apache HTTP Server, get an SSL certificate for the service name of the IdP (idp.university.ru) from a publicly trusted CA. Store the private key under /etc/sslpki/tls/private/idp.university.ru.key and the certificate under /etc/sslpki/tls/certs/idp.university.ru.crt, and make sure that the certificate file includes both the server certificate and any intermediate CA certificate(s). If SELinux is enabled on your system, verify that the two files have the correct context: use restorecon -nv /etc/pki/tls/private/idp.university.ru.key /etc/pki/tls/certs/idp.university.ru.crt to check, and if there's output from this command, rerun without -n to fix the context(s).

    Then, install the Apache HTTP Server 2.4 with the following command:

    sudo apt-get install apache2
    sudo yum install httpd mod_ssl

    Next, add a VirtualHost configuration for the IdP by creating a file named /etc/apache2/sites-available/etc/httpd/conf.d/idp.university.ru.conf and populating it with the following contents:

    <VirtualHost *:443>
  ServerName idp.university.ru
  ServerAdmin idp-admin@university.ru
  CustomLog /var/log/apache2/idp.university.ru.access.log combined
  ErrorLog /var/log/apache2/idp.university.ru.error.log

  SSLEngine On
  SSLCipherSuite HIGH:MEDIUM:!aNULL:!kRSA:!MD5:!RC4
  SSLProtocol all -SSLv2 -SSLv3
  SSLCertificateKeyFile /etc/ssl/private/idp.university.ru.key
  SSLCertificateFile /etc/ssl/certs/idp.university.ru.crt
  SSLCertificateChainFile /etc/ssl/certs/idp.university.ru.crt

  <IfModule headers_module>
  Header set X-Frame-Options DENY
  Header set Strict-Transport-Security "max-age=31536000 ; includeSubDomains"
  </IfModule>

  ProxyPass /idp ajp://localhost:8009/idp retry=5
  <Proxy ajp://localhost:8009>
    Require all granted
  </Proxy>
</VirtualHost>
    <VirtualHost *:443>
  ServerName idp.university.ru
  ServerAdmin idp-admin@university.ru
  CustomLog /var/log/httpd/idp.university.ru.access.log combined
  ErrorLog /var/log/httpd/idp.university.ru.error.log

  SSLEngine On
  SSLCipherSuite HIGH:MEDIUM:!aNULL:!kRSA:!MD5:!RC4
  SSLProtocol all -SSLv2 -SSLv3
  SSLCertificateKeyFile /etc/pki/tls/private/idp.university.ru.key
  SSLCertificateFile /etc/pki/tls/certs/idp.university.ru.crt
  SSLCertificateChainFile /etc/pki/tls/certs/idp.university.ru.crt

  <IfModule headers_module>
  Header set X-Frame-Options DENY
  Header set Strict-Transport-Security "max-age=31536000 ; includeSubDomains"
  </IfModule>

  ProxyPass /idp ajp://localhost:8009/idp retry=5
  <Proxy ajp://localhost:8009>
    Require all granted
  </Proxy>
</VirtualHost>

    In addition to adding the above VirtualHost definition, we suggest setting ServerTokens Prod and ServerSignature off in /etc/apache2/conf-enabled/security.conf/etc/httpd/conf/httpd.conf to make the server not disclose/announce version number details etc. by default.

    Finally, enable the Apache HTTP server and check its configuration with the following commands:

    sudo a2enmod ssl proxy_ajp
sudo a2ensite idp.university.ru
sudo apachectl configtest
    sudo systemctl enable httpd.service
sudo apachectl configtest

    If the output of the last command states Syntax OK, then proceed with restarting the Apache HTTP server:

    sudo apachectl restart
    sudo systemctl restart httpd.service

    Обновление с версии v2.x IdP

    If you keep the service name of your v2 IdP – which is highly preferred unless you have really good reasons for changing the name –, you can use the publicly-trusted certificate from your existing IdP. For v2 deployments which were set up according to the previous FEDURUS deployment guide, the certificate and private key can be found in the /etc/ssl/certs and /etc/ssl/private directories.

    Установка контейнера Java Servlet

    Среда выполнения приложений Java: OpenJDK 7

    Both Linux distributions supported in this guide provide OpenJDK 7 as their default Java runtime environment. To install, execute the following command:

    sudo apt-get install openjdk-7-jdk
    sudo yum install java-1.7.0-openjdk

    Контейнер приложений: Apache Tomcat 7

    The default supported version of the Tomcat Servlet container shipped with the recommended operating systems is version 7. While newer versions of Tomcat – as well as alternative Servlet containers such as Jetty – are available, they have the disadvantage of requiring manual security updates. For this reason, FEDURUS recommends relying on the Servlet container which is provided in the form of a vendor-supported package.

    To install the Apache Tomcat Servlet container, execute:

    sudo apt-get install tomcat7
    sudo yum install tomcat

    As a next step, adapt the following configuration defaults in /etc/tomcat/server.xml:

    • Disable the HTTP/1.1 connector on port 8080 by commenting out the <Connector port="8080" ...>element
    • Add an AJP connector on port 8009, by inserting the following lineadapting the <Connector port="8009" ...> line: 
      <Connector port="8009" address="127.0.0.1" protocol="AJP/1.3" />
    • Disable automatic application deployment by changing autoDeploy="true" to autoDeploy="false" on the <Host name="localhost" ...> element

    And configure JAVA_OPTS in /etc/default/tomcat7/etc/sysconfig/tomcat as follows:

    JAVA_OPTS="-server -Xmx1024m -Djava.security.egd=file:/dev/./urandom"

    -Xmx1024m - this is the maximum amount of heap memory that Tomcat may use.

    If your system is not short of “true” entropy (cf. cat /proc/sys/kernel/random/entropy_avail), you can leave out the -Djava.security.egd setting (for further background, see the FasterStartUp page in the Tomcat Wiki).

    If you need to install Tomcat 8 for some reason, please refer to the ShibWiki.

    База данных SQL: PostgreSQL 9

    A Shibboleth IdP in the FEDURUS federation relies on database-backed storage for two categories of information: persistent identifiers and user consent data. For the IdP version 3, FEDURUS recommends deploying PostgreSQL as the database backend; other relational databases may be used for this purpose as well, as long as they can be made available to the IdP through Hibernate ORM. If you prefer using a different RDBMS, then we assume that you – or your DBA – is able to adapt the steps in this section to your environment as needed.

    Установка

    For simplicity's sake, we recommend and show instructions to install the version of PostgreSQL provided by your Linux distribution, which may not be the most recent. If you prefer running the latest stable version, PostgreSQL developers provide packages repositories for all major distributions. Additionally, Red Hat Enterprise Linux subscribers can use Red Hat Software Collections to obtain recent PostgreSQL packages from Red Hat.

    To prepare PostgreSQL for use with the IdP, install the package as follows:

    sudo apt-get install postgresql libpostgresql-jdbc-java
    sudo yum install postgresql-server postgresql-jdbc
sudo postgresql-setup initdb
sudo systemctl enable postgresql.service
sudo systemctl start postgresql.service

    Создание и настройка базы данных

    Then, create a shibboleth database account, the shibboleth database and the shibpid and storagerecords tables with the following command sequence:

    sudo -iu postgres psql <<EOF
CREATE ROLE shibboleth WITH LOGIN;
CREATE DATABASE shibboleth WITH OWNER shibboleth ENCODING 'UTF8' TEMPLATE template0;
\c shibboleth
SET ROLE shibboleth;
CREATE TABLE shibpid (
    localEntity VARCHAR(1024) NOT NULL,
    peerEntity VARCHAR(1024) NOT NULL,
    principalName VARCHAR(255) NOT NULL,
    localId VARCHAR(255) NOT NULL,
    persistentId VARCHAR(36) NOT NULL,
    peerProvidedId VARCHAR(255) NULL,
    creationDate TIMESTAMP NOT NULL DEFAULT LOCALTIMESTAMP,
    deactivationDate TIMESTAMP NULL DEFAULT NULL,
    PRIMARY KEY (localEntity, peerEntity, persistentId)
);
CREATE INDEX shibpid_getbysourcevalue_index ON shibpid(localEntity, peerEntity, localId, deactivationDate);
CREATE TABLE storagerecords (
    context VARCHAR(255) NOT NULL,
    id VARCHAR(255) NOT NULL,
    expires BIGINT DEFAULT NULL,
    value TEXT NOT NULL,
    version BIGINT NOT NULL,
    PRIMARY KEY (context, id)
);
CREATE INDEX storagerecords_expires_index ON storagerecords(expires);
EOF

    On Red Hat Enterprise Linux / CentOS, you need to modify the default authentication settings: in /var/lib/pgsql/data/pg_hba.conf, change the METHOD for local connections from ident to md5, so that the lines read as follows:

    # IPv4 local connections:
host    all             all             127.0.0.1/32            md5
# IPv6 local connections:
host    all             all             ::1/128                 md5

    Execute

    sudo systemctl reload postgresql.service

    afterwards to make PostgreSQL re-read the changes to pg_hba.conf.

    Enable autovacuum and autoanalyze to make sure that data gets cleaned out and indexes are updated correctly. The default thresholds are set rather high (at least 20%/10% of a table needs to change before triggering autovacuum/autoanalyze) so we recommend lowering them to 0.2% and 0.1%, respectively. Edit PostgreSQL's configuration in /etc/postgresql/9.3/main/postgresql.conf /var/lib/pgsql/data/postgresql.conf so that the two lines are uncommented and the numbers changed like below:

    autovacuum_vacuum_scale_factor = 0.002  # fraction of table size before vacuum
autovacuum_analyze_scale_factor = 0.001 # fraction of table size before analyze

    Reload the configuration to apply changes:

    sudo service postgresql reload
    sudo systemctl reload postgresql.service

    Don't use large objects!

    Out-of-the box, the IdP version 3 will use “large objects” with the storagerecords.value column without enabling PostgreSQL's large object management (see issue OSJ-135 for further details). This results in orphaned large objects and guaranteed data loss if the vacuumlo command is ever run. In order to prevent such an accident, we urge administrators to apply the workaround described later before starting their IdP for the first time.

    Резервное копирование базы данных

    Finally, it is highly recommended to create backups (dumps) of the database at least on a daily basis, so that the database can be restored from a known good state in case of an emergency. A lightweight solution can be implemented by an /etc/cron.d/postgres-backup file with a pg_dumpall command which dumps all databases:

    40 4 * * * postgres pg_dumpall | gzip > /var/backups/postgresqllib/pgsql/backups/dumpall-`date +\%a`.sql.gz
20 * * * * postgres pg_dumpall | gzip > /var/backups/postgresql/dumpall-latest.sql.gz

    This cron entry creates a daily dump of all PostgreSQL databases at 4:40 in the morning and writes them in compressed format to the backup directory (with file names such as dumpall-Mon.sql.gz, dumpall-Tue.sql.gz etc). On Ubuntu, you also need to create the directory with the appropriate ownership and permissions first:

    sudo mkdir /var/backups/postgresql
sudo chown postgres:postgres /var/backups/postgresql
sudo chmod 700 /var/backups/postgresql

    Обновление с версии v2.x IdP

    An important step when upgrading from an existing IdP is to make sure that the persistent IDs are retained. To populate the newly created PostgreSQL database with the existing shibpid records, perform these steps (under the assumption that your v2 IdP has been set up with a MySQL database backend, as suggested in previous versions of this guide):

    1. On the current IdP, dump the persistent IDs stored from the MySQL database to a file: 
      sudo mysqldump --compatible postgres --compact --no-create-info --result-file shibpid.sql shibboleth shibpid
    2. Copy the shibpid.sql file to your new IdP
    3. Import the persistent IDs into the PostgreSQL database: 
      sudo -iu postgres psql shibboleth --file /path/to/shibpid.sql

    Be sure to only execute the import with psql once, otherwise the shibpid table will end up with duplicate records. To start the import from scratch, the table can be emptied first with sudo -u postgres psql shibboleth -c "truncate shibpid".

    Shibboleth IdP

    Deployment of the Shibboleth IdP is a two-part procedure: first, the distribution is unpacked and its installer is run, and second, the default configuration needs to be customized for an IdP in the FEDURUS (or AAI Test) federation. The next subsection is about the first part, while the remaining ones cover various aspects of the configuration in more detail. Generally speaking, this section is focusing on the specifics for an IdP in the FEDURUS federation, it should not be considered a systematic description of the vast number of configuration options provided by the Shibboleth IdP version 3.

    Readers interested in a comprehensive documentation of the IdP configuration settings are referred to the Configuration page in the Shibboleth Wiki, and might find the ConfigurationFileSummary page useful to get an overview of the fairly complex configuration file structure. Making oneself familiar with some SpringConfiguration basics is also helpful when trying to get a better understanding of the syntax used in the IdP configuration files.

    Обновление с версии v2.x IdP

    Depending on the customization of your v2.x IdP, migrating its configuration to a v3-based setup can be a fairly time-consuming task. In the upgrade instructions in this guide, we put the focus on the steps required for a typical v2 IdP which was set up according to the previous version of this guide. If you have further customized your IdP configuration (e.g. by supporting additional login methods or similar), then we strongly recommend diffing your configuration against the default versions of the files as shipped in the respective distribution from https://shibboleth.net/downloads/identity-provider/, to get a better understanding of what configuration changes might also have to be taken into account.

    Установка IdP

    Download the distribution archive in the tar.gz format from the Shibboleth site. We recommend creating a /usr/local/dist directory for storing the downloads:

    [ -d /usr/local/dist ] || sudo mkdir /usr/local/dist
cd /usr/local/dist
sudo curl -O https://shibboleth.net/downloads/identity-provider/3.x.y/shibboleth-identity-provider-3.x.y.tar.gz
sudo tar -zxf shibboleth-identity-provider-3.x.y.tar.gz

    Running the install.sh script included in the IdP distribution without any parameters would create a default configuration which is not very suitable for an IdP in the FEDURUS federation. We therefore recommend using a simple idp-install.sh wrapper script which ensures that the basic configuration parameters are set to FEDURUS compatible defaults. To run the custom installer, execute

    sudo curl -O http://www.fedurus.ru/guides/idp/installation/idp-install.sh
sudo bash idp-install.sh shibboleth-identity-provider-3.x.y

    The custom installer script will first prompt for two parameters and ask for confirmation, and then install the IdP to /opt/shibboleth-idp:

    Please enter the name of your home organization [university.ru]: university.ru
Please specify the service name for your IdP [idp.university.ru]: idp.university.ru

Proceed with the installation using the following parameters?

Service name:             idp.university.ru
Home organization name:   university.ru
Installation directory:   /opt/shibboleth-idp

Enter 'yes' to continue: yes

Warning: /opt/shibboleth-idp/bin does not exist.
Warning: /opt/shibboleth-idp/dist does not exist.
Warning: /opt/shibboleth-idp/doc does not exist.
Warning: /opt/shibboleth-idp/system does not exist.
Warning: /opt/shibboleth-idp/webapp does not exist.
Creating cookie encryption key files...
...done
Rebuilding /opt/shibboleth-idp/war/idp.war ...
...done

BUILD SUCCESSFUL
Total time: 4 seconds

Creating self-signed certificate...
...done

    The idp-install.sh script will also adjust the ownership of some files and directories, which you should verify with the following command:

    ls -ld /opt/shibboleth-idp/{conf/credentials.properties,credentials/{*.key,sealer.*},logs,metadata}

    The output should look similar to:

    -rw------- 1 tomcat root 1675 Mar 25 13:05 /opt/shibboleth-idp/conf/credentials.properties
-rw------- 1 tomcat root 1675 Mar 25 13:05 /opt/shibboleth-idp/credentials/idp.key
-rw-r--r-- 1 tomcat root  500 Mar 25 13:05 /opt/shibboleth-idp/credentials/sealer.jks
-rw-r--r-- 1 tomcat root   47 Mar 25 13:05 /opt/shibboleth-idp/credentials/sealer.kver
drwxr-xr-x 2 tomcat root 4096 Mar 25 13:05 /opt/shibboleth-idp/logs
drwxr-xr-x 2 tomcat root 4096 Mar 25 13:05 /opt/shibboleth-idp/metadata

    Обновление с версии v2.x IdP

    FEDURUS recommends leaving the entity ID of the v2 IdP unchanged, in particular when taking into account that modifying this ID would break continuity of existing persistent IDs. In this case, it's also easiest to retain the certificate and private key from the v2 IdP, as this makes a key rollover unnecessary. Copy /opt/shibboleth-idp/credentials/idp.crt and /opt/shibboleth-idp/credentials/idp.key from the existing IdP and make sure that they have the proper ownership and permissions (see above for the idp.key).

    Основные настройки IdP: services.xml и global.xml

    In /opt/shibboleth-idp/conf/services.xml there are two settings which need adjustment: a), the shibboleth.MetadataResolverResources list needs to be substituted by the following definition (allows metadata selection via settings in /opt/shibboleth-idp/conf/idp.properties):

        <util:list id="shibboleth.MetadataResolverResources">
        <value>#{ '%{idp.metadata}' matches '.*\bfedurus\b.*' ?
                  '%{idp.home}/conf/metadata-provider-fedurus.xml' : '' }</value>
        <value>#{ '%{idp.metadata}' matches '.*\baaitest\b.*' ?
                  '%{idp.home}/conf/metadata-provider-aaitest.xml' : '' }</value>
        <value>#{ '%{idp.metadata}' matches '.*\binterfederation\b.*' ?
                  '%{idp.home}/conf/metadata-provider-interfederation.xml' : '' }</value>
        <value>%{idp.home}/system/conf/metadata-providers-system.xml</value>
    </util:list>

    и b), 

    cd /opt/shibboleth-idp/conf
sudo curl -O http://www.fedurus.ru/guides/idp/installation/attribute-filter.xml

    Finally, there are a couple of configuration elements related to the database and HTTP client configuration which need to be added to global.xml. Instead of listing them verbatim here, the complete file can be downloaded as follows:

    cd /opt/shibboleth-idp/conf
sudo curl -O http://www.fedurus.ru/guides/idp/installation/global.xml

    Настройка метаданных федерации

    Download the configuration file(s) with the respective <MetadataProvider> element:

    cd /opt/shibboleth-idp/conf
sudo curl -O http://www.fedurus.ru/guides/idp/installation/metadata-provider-fedurus.xml
sudo curl -O http://www.fedurus.ru/guides/idp/installation/metadata-provider-interfederation.xml

    Second, download the trust anchor / “root certificate” which is needed for verifying the signature of FEDURUS metadata:

    cd /opt/shibboleth-idp/credentials
sudo curl -O http://metadata.fedurus.ru/arlicon-fedurus.pem

    And verify that the fingerprint shown from the following OpenSSL command output matches exactly:

    openssl x509 -in /opt/shibboleth-idp/credentials/arlicon-fedurus.pem -noout -fingerprint -sha256
SHA256 Fingerprint=51:40:82:42:74:FF:EA:FA:4C:E8:2F:D3:65:5C:2E:E5:8B:45:CC:3F:C8:41:E0:05:E8:6B:7B:3D:1F:10:A6:65

    Third, in /opt/shibboleth-idp/conf/idp.properties, insert the following line:

    idp.metadata = FEDURUS, interfederation

    Proxy settings for outgoing HTTP connections: for normal operations, the IdP needs to retrieve settings from both the metadata download site, http://www.fedurus.ru, and the Реестр федерации, https://manager.fedurus.ru/federationregistry/. If your network policy does not allow outgoing connections on ports 80 and 443 by default, then it is recommended to rely on an HTTP proxy for this purpose (the IP addresses for these DNS names are subject to change without notice, so it is strongly discouraged to add IP-based rules to the firewall configuration). To enable the use of an HTTP proxy server, add the following two parameters to the /opt/shibboleth-idp/conf/idp.properties file:

    idp.http.proxyhost = proxy.university.ru
idp.http.proxyport = 8080

    These settings are taken into account for both metadata downloads (HTTP) and attribute filter downloads (HTTPS). Omitting these two parameters from idp.properties – the default setting – will make the IdP open direct connections for HTTP(S) requests.

    Relying party configuration

    Download an adapted relying-party.xml configuration file which includes overrides for the special-purpose http://www.fedurus.ru/SAML1/Attribute-Push relying party group (see SAML 1 Attribute Push Relying Party for further information):

    cd /opt/shibboleth-idp/conf
sudo curl -O http://www.fedurus.ru/guides/idp/installation/relying-party.xml
    If necessary, configure in the relying-party.xml the “trusted” SPs for which the user consent dialog should be suppressed. In general, FEDURUS recommends using the new IdP v3 default settings, i.e. enabling user consent for all SPs.

    Обновление с версии v2.x IdP

    To determine if your v2 IdP includes custom modifications which might have to be recreated in the new configuration, we recommend comparing your current v2 configuration file against the default version FEDURUS provided in the v2.4 deployment guide. To do so, execute on your existing v2 IdP: 

    curl -o rp-v2-default.xml http://www.fedurus.ru/docs/shibboleth/FEDURUS/2.4/idp/deployment/relying-party.xml
diff -bu rp-v2-default.xml /opt/shibboleth-idp/conf/relying-party.xml
    Only changes to the Relying Party Configurations part are relevant (metadata providers are configured separately in v3, see above), and only if they relate to something other than the provider value. If you see additional differences in the relying-party.xml file of your existing IdP compared to rp-v2-default.xml, then have a look at Upgrade Tasks for relying-party.xml in the Shibboleth Wiki for further information.

    The relying-party.xml file is also the place where user consent for attribute release is configured (formerly known as uApprove, now included in the standard release of the Shibboleth IdP). The attribute release page is enabled for all SPs by default, through the postAuthenticationFlows setting for the default relying party. To disable user consent for specific SPs, follow the instructions in the relying-party.xml file itself, by enabling and configuring the shibboleth.NoUserConsentRelyingParty bean as needed. Generic user consent settings are documented on the ConsentConfiguration page in the Shibboleth Wiki and are specified through the idp.consent.* parameters in the idp.properties file, or via configuration in /opt/shibboleth-idp/conf/intercept/consent-intercept-config.xml. For most of the uApprove settings previously specified in /opt/shibboleth-idp/conf/uApprove.properties, equivalent options for the IdP v3 exist.

    Аутентификация пользователей

    The user authentication component in the Shibboleth IdP has undergone major rework for version 3. While JAAS (Java Authentication and Authorization Service) continues to be available for a flexible configuration of authentication methods, the IdP now ships with a native LDAP-based authentication component, which is configured in /opt/shibboleth-idp/conf/ldap.properties.

    We assume that a typical IdP deployment in the FEDURUS federation relies on authentication against an LDAP directory which is accessed through an LDAPS connection, with the LDAP server requiring a service account for binding to the directory and being configured with a server certificate chaining to a root which is present in the Java cacerts trust store (i.e., either use an SSL certificate from a publicly-trusted certification authority, or manually add your root certificate to the cacerts trust store). For this case, the settings in /opt/shibboleth-idp/conf/ldap.properties need to be adjusted as follows:

    idp.authn.LDAP.authenticator                    = bindSearchAuthenticator
idp.authn.LDAP.ldapURL                          = ldaps://ldap.university.ru
idp.authn.LDAP.useStartTLS                      = false
idp.authn.LDAP.useSSL                           = true
idp.authn.LDAP.sslConfig                        = jvmTrust
idp.authn.LDAP.baseDN                           = ou=people,dc=university,dc=ru
idp.authn.LDAP.bindDN                           = cn=idp,dc=university,dc=ru

    The LDAP bind password should be added to /opt/shibboleth-idp/conf/credentials.properties, by inserting the following line (and the respective line being removed from ldap.properties at the same time, for the sake of consistency):

    idp.authn.LDAP.bindDNCredential = secret

    For additional LDAP authentication options supported by version 3 of the Shibboleth IdP, see the LDAPAuthnConfiguration page in the Shibboleth Wiki. The full list of available login flows is covered on the AuthenticationConfiguration page in the Shibboleth Wiki.

    The default settings shipping with IdP version 3 do not log the success or failure of an LDAP authentication. If you're interested in seeing this information recorded in the idp-process.log file, (Authentication (succeeded|failed) for dn: ... lines), add the following element to /opt/shibboleth-idp/conf/logback.xml (after the line which sets org.ldaptive to WARN, for reasons of consistency):

        <logger name="org.ldaptive.auth.Authenticator" level="INFO" />

    Обновление с версии v2.x IdP

    The relevant settings for the ldap.properties file can be found in the /opt/shibboleth-idp/conf/login.config file of an existing v2 IdP. For setups which go beyond authenticating against a single LDAP directory, see PasswordAuthnConfiguration in the Shibboleth Wiki. In particular, note that JAAS continues to be supported with v3, so it should also be possible to carry over a configuration from a v2 IdP. To switch to JAAS, adjust the setting at the beginning of the /opt/shibboleth-idp/conf/authn/password-authn-config.xml file; by default, the JAAS configuration is now loaded from /opt/shibboleth-idp/conf/authn/jaas.config.

    Настройка выпуска атрибутов

    The configuration of the attribute resolution component is the most complex, but also the most important part of the IdP configuration – the primary task of an IdP is to make statements about its users and their attributes. There isn't a one-size-fits-all approach to configuring attribute resolution on an IdP in the FEDURUS federation, as it very much depends on what attributes are available within the organization, and what sources they are retrieved from.

    Make sure that the attributes configured in this section are aligned with the supported attributes you configured/will configure in the Реестр федерации.

    While the configuration files provided in this section can be used as templates for setting up attribute resolution, they will need further customization in almost all cases. The Shibboleth IdP is very flexible in terms of configuring retrieval of attributes from other sources; the reference documentation can be found in the Shibboleth Wiki under AttributeResolverConfiguration and the respective subpages, in particular the description of the various AttributeDefinitionConfiguration options.

    To get started, configure the shibboleth.AttributeResolverResources list in /opt/shibboleth-idp/conf/services.xml as follows:

        <util:list id="shibboleth.AttributeResolverResources">
        <value>%{idp.home}/conf/attribute-resolver-connectors.xml</value>
        <value>%{idp.home}/conf/attribute-resolver-interfederation-core.xml</value>
        <value>%{idp.home}/conf/attribute-resolver-fedurus-core.xml</value>
        <value>%{idp.home}/conf/attribute-resolver-other.xml</value>
    </util:list>

    and download the files with

    cd /opt/shibboleth-idp/conf
sudo curl -O http://www.fedurus.ru/guides/idp/installation/attribute-resolver-fedurus-core.xml
sudo curl -O http://www.fedurus.ru/guides/idp/installation/attribute-resolver-interfederation-core.xml
sudo curl -O http://www.fedurus.ru/guides/idp/installation/attribute-resolver-connectors.xml
sudo curl -O http://www.fedurus.ru/guides/idp/installation/attribute-resolver-other.xml

    Enabling attribute-resolver-fedurus-core.xml and attribute-resolver-connectors.xml will add support for the FEDURUS Core attributes: Affiliation, E-mail, Given name, Surname, Organization, SCHAC home organisation, SCHAC home organisation type, Scoped affiliation, Targeted ID/Persistent ID, and Unique ID. The two files assume that the user-specific attributes are retrieved from the LDAP directory (as defined via ldap.properties), and two static values are configured: at least the proper values for Organization and schacHomeOrganizationType must be added in attribute-resolver-connectors.xml

    The attribute-resolver-interfederation.xml file includes definitions for the five Interfederation core attributes: Common name, Display name, Principal name, SCHAC home organisation, and SCHAC home organisation type. The default definitions in this file are based on existing FEDURUS core attributes (Common Name and Display name e.g. are assembled from Given name and surname), but you should check each AttributeDefinition block in any case – in particular if “genuine” values are available from your LDAP directory, you should switch to retrieving the values from the directory.

    If your organization supports the common-lib-terms entitlement, you find its definition inside the attribute-resolver-other.xml. The attribute-resolver-other.xml file includes definitions for (most of) the attributes listed under Other attributes on the AAI attributes page. All attributes (except common-lib-terms entitlement) are commented out by default and should only be enabled after having carefully checked each AttributeDefinition (it assumes that most of these values are available from the LDAP directory, and all definitions which do not apply to your organization should be removed).

    Обновление с версии v2.x IdP

    In theory, it should be possible to reuse an attribute-resolver.xml configuration file from a v2 IdP as is, but FEDURUS strongly encourages administrators to carefully check / clean up existing v2 configuration files on the occasion of upgrading to the IdP version 3. As a first step, it is helpful to know what modifications your current v2 configuration includes compared to the default template we provided in the previous version of this guide. On your existing v2 IdP, execute 

    curl -o ar-v2-default.xml https://www.fedurus.ru/docs/shibboleth/FEDURUS/2.4/idp/deployment/attribute-resolver.xml
diff -bu ar-v2-default.xml /opt/shibboleth-idp/conf/attribute-resolver.xml
    to examine them. Then, migrate your customizations to the new versions of attribute-resolver-fedurus-core.xml, attribute-resolver-connectors.xml etc. For script-based attribute definitions, check in particular the ScriptedAttributeDefinition page and its V2 Compatibility section in the Shibboleth Wiki and where feasible, consider replacing a scripted attribute with one of the “simpler” types, e.g. Mapped or Template).

    For local or bilaterally agreed attributes, we suggest creating separate configuration files (attribute-resolver-local.xml or similar), which can be loaded by adding them to the shibboleth.AttributeResolverResources list shown above.

    Consent intercept configuration

    Download an adapted consent-intercept-config.xml configuration file that contains a defined ordering for the attribute release consent dialog as well as an extended blacklist that covers also the usually cryptic unique identifiers (see 'Shibboleth IdPv3 User Consent Configuration Guide' for further information): 

    cd /opt/shibboleth-idp/conf/intercept
sudo curl -O http://www.fedurus.ru/guides/idp/installation/consent-intercept-config.xml

    Настройка создания уникальных идентификаторов (persistent IDs)

    Для настройки создания уникальных идентификаторов новым методом, рекомендованным для версии 3 Shibboleth IdP (см. секцию V2 Compatibility на соответствующей странице Shibboleth Wiki), необходимы следующие изменения конфигурации:

    1. в файле /opt/shibboleth-idp/conf/saml-nameid.properties, активируйте/настройте следующие параметры: 
      idp.persistentId.generator = shibboleth.StoredPersistentIdGenerator
idp.persistentId.dataSource = shibboleth.PostgreSQLDataSource
idp.persistentId.sourceAttribute = uid
    2. в файле /opt/shibboleth-idp/conf/saml-nameid.xml, активируйте (удалите комментарии) компонент shibboleth.SAML2PersistentGenerator, чтобы это выглядело следующим образом: 
          <util:list id="shibboleth.SAML2NameIDGenerators">

        <ref bean="shibboleth.SAML2TransientGenerator" />

        <ref bean="shibboleth.SAML2PersistentGenerator" />

        [...]
    3. в файле /opt/shibboleth-idp/conf/c14n/subject-c14n.xml, активируйте (удалите комментарии) компонент c14n/SAML2Persistent, чтобы это выглядело следующим образом: 
              <!-- Handle a SAML 2 persistent ID, provided a stored strategy is in use. -->
        <ref bean="c14n/SAML2Persistent" />
    4. в файл /opt/shibboleth-idp/conf/credentials.properties, добавьте строку, которая задает значение "соли", используемого при создании уникального идентификатора (persistent ID). Корректное значение "соли" необходимо создать командой openssl rand -base64 36. 
      idp.persistentId.salt = ...random value...

    Обновление с версии v2.x IdP

    Для параметра idp.persistentId.salt, необходимо задать значение salt, используемое в блоке коннектора myStoredId файла /opt/shibboleth-idp/conf/attribute-resolver.xml вашей конфигурации IdP v2. Процедура переноса уникальных идентификаторов (persistent IDs) из базы данных действующего IdP рассматривалась в разделе настройки сервера управления базой данных PostgreSQL. Перед вводом в промышленную эксплуатацию нового IdP v3, не забудьте повторить импорт данных таблицы shibpid из idP v2 (во избежание дублирования данных используйте команду sudo -u postgres psql shibboleth -c "truncate shibpid" для опустошения таблицы).

    Configuring periodic encryption key rotation

    When using the default setting for the idp.session.StorageService in the idp.properties file, the Shibboleth IdP stores session information on the client side, in a cookie with encrypted data. The (symmetric AES) key to encrypt the client-side information should be rotated regularly, so it's best to set up a cron for this purpose. We recommend creating a shell script with the following contents and store it under /opt/shibboleth-idp/credentials/rotate-sealer.sh:

    #!/bin/sh

IDP_HOME=/opt/shibboleth-idp

java -cp "$IDP_HOME/webapp/WEB-INF/lib/*" \
  net.shibboleth.utilities.java.support.security.BasicKeystoreKeyStrategyTool \
  --storefile $IDP_HOME/credentials/sealer.jks \
  --versionfile $IDP_HOME/credentials/sealer.kver \
  --alias secret \
  --storepass "$(grep '^idp.sealer.password' $IDP_HOME/conf/credentials.properties | cut -d = -f 2)"

    Set the execute permissions on the file with chmod +x and configure a corresponding entry under /etc/cron.d/idp-rotate-sealer:

    50 4 * * 0 tomcat /opt/shibboleth-idp/credentials/rotate-sealer.sh

    This will rotate the key each Monday morning at 4:50 - depending on your local needs, you might want to adapt the time and/or the interval for this cron entry.

    With the default logging settings, the IdP will log a message of type Default key version has not changed to the idp-process.log file every 15 minutes, printing the alias of the currently used key (such as secret65, with the number being increased whenever the key is rotated). If you consider this sort of logging too noisy, then these messages can be suppressed by adding

    <logger name="net.shibboleth.utilities.java.support.security.BasicKeystoreKeyStrategy" level="WARN" />

    to the /opt/shibboleth-idp/conf/logback.xml file.

    Limit Cookies to Secure Connections

    The default setting for idp.cookie.secure is false. To prevent browsers from sending IdP cookies via http instead of https, add the following line to the /opt/shibboleth-idp/conf/idp.properties file:

    idp.cookie.secure = true

    Messages Translation (supporting multiple languages)

    Translations of the messages properties files in different languages are collected in the Shibboleth Wiki.

    Download the properties files for the languages relevant for your user base and install the downloaded files into the directory /opt/shibboleth-idp/system/messages.

    By default, the IdP evaluates the Accept-Language header as provided by the browser to identify the appropriate locale (language) to use.

    Login form customization

    In version 3 of the Shibboleth IdP, the default mechanism for rendering the login and error pages has been changed from JSP to Velocity templates, with the benefit that modifications to the login page do no longer require a restart of the Servlet container (Tomcat), but become active immediately after the editing the respective .vm file in the /opt/shibboleth-idp/views directory.

    The default templates included in the IdP are provided as samples, but it is assumed that they are customized for local use. You are welcome to use your organization's own corporate design for the login form; alternatively, you may use the templates which reflect the recommendations from the AAI Design Guidelines page. To install these custom FEDURUS Velocity templates and CSS files, proceed as follows:

    cd /usr/local/dist
sudo curl -O http://www.fedurus.ru/guides/idp/installation/idpv3-fedurus-login-templates.zip
cd /opt/shibboleth-idp
sudo unzip -o /usr/local/dist/idpv3-fedurus-login-templates.zip

    The ZIP archive includes the following files which have been customized for FEDURUS use (and may be further adapted):

    • three Velocity template files (replacing the default files in the /opt/shibboleth-idp/views directory): login.vm, login-error.vm and error.vm. Changes to these files do not require a Servlet container restart (with the exception of strings which are configured via entries in .properties files and rendered through #springMessageText).
    • two CSS files in the /opt/shibboleth-idp/edit-webapp/css subdirectory: main.css for use by most of the Velocity templates in the views subdirectory, and consent.css for the attribute release consent page
    • a small FEDURUS logo (/opt/shibboleth-idp/edit-webapp/images/fedurus-logo.png) for use on the login and error pages
    • a replacement for the index.jsp file which is used when someone is trying to access the IdP's “root page” (https://idp.university.ru/idp/, does not happen under normal circumstances, and the page will only display No services are available at this location in reply to such requests).

    After unpacking the ZIP archive, make sure that at least the following strings are set to correct values:

    In /opt/shibboleth-idp/system/messages/messages.properties and all the /opt/shibboleth-idp/messages/messages_XX.properties files for other languages you installed
    • configure three logo related parameters:
      Insert the new parameter idp.logo.target.url since it is not included in the default configuration. 
      idp.logo = /images/university.ru.png
idp.logo.alt-text = Friendly name of your organization
idp.logo.target.url = http://www.university.ru
      You also need to place a suitable PNG image with your organization's logo under the location referenced by idp.logo, i.e. /opt/shibboleth-idp/edit-webapp/images/university.ru.png, with a maximum suggested size of 200 by 100 pixel.
    • configure three target link parameters:
      Add three lines which define the target for the Forgot your password?, Change your password and Need Help? links: 
      idp.login.forgotPassword.url = https://support.university.ru/password-assistance
idp.login.needHelp.url = https://support.university.ru/help
idp.login.changePassword.url = https://support.university.ru/password-assistance

    Note: If the above parameters are the same for all languages, you can keep them in messages.properties and remove them from all other files such that they have to be defined only in the default messages file.

    Provided you installed support for multiple languages as described in the chapter Messages Translations above, you might want to integrate an explicit choice of language into the login form. Consult the Shibboleth Wiki for detailed instructions: Switching locale on the login page.

    These steps should be sufficient as a starting point, though further modifications to the above mentioned files might be necessary at a later stage (in login.vm e.g., there's an element which can optionally be enabled for better support of logins from “public” systems, allowing the user to disable SSO and only have the IdP create a one-time session for a single SP). More information on what properties are available through VTL – Velocity Template Language – can be found on the VelocityProperties page in the Shibboleth Wiki.

    Rebuilding the idp.war file is essential after any changes to files in the edit-webapp subdirectory, but we will execute this step after the installation of the configuration of the status page in the next section.

    Обновление с версии v2.x IdP

    With v2 of the IdP, the login and error pages always had to be implemented in the form of JSP (Java Server Pages), and customization was done by modifying the relevant files in the src/main/webapp subdirectory of the distribution, followed by re-running install.sh and restarting Tomcat after every modification. The Shibboleth IdP v3 now relies on Spring Web Flow for handling the login, and the default rendering method has been changed to Velocity (with the corresponding templates living under /opt/shibboleth-idp/views). If you have customized the login.jsp, login.css, error.jspfiles etc. in the past and did not use the FEDURUS-provided templates, then we recommend porting your changes to the new-style .vm files, as they have the benefit of not requiring a Servlet container restart to take effect. Alternatively, you may continue to use existing JSP versions of these pages, in which case you need to remove the equivalent Velocity files in the views subdirectory, so that the IdP falls back to a JSP-based rendering (see also the User Interface section on the PasswordAuthnConfiguration Wiki page). Be aware that all customized JSP files must be placed under /opt/shibboleth-idp/edit-webapp subdirectory, not /opt/shibboleth-idp/webapp – the latter directory gets removed when doing an upgrade from 3.x to 3.y.

    Настройка URL отображения статуса IdP

    Для отображения страницы статуса IdP необходима библиотека JSP Standard Tag Library (JSTL), которая не входит в состав дистрибутива Shibboleth IdP. Страница статуса предоставляет полезную диагностическую информацию и настоятельно рекомендуется активировать эту опцию. Для этого загрузите файл jstl-1.2.jar в папку /opt/shibboleth-idp/edit-webapp/WEB-INF/lib и выполните пересборку файла idp.war:

    cd /opt/shibboleth-idp/edit-webapp/WEB-INF/lib
sudo curl -O https://repo1.maven.org/maven2/jstl/jstl/1.2/jstl-1.2.jar
sudo JAVACMD=/usr/bin/java /opt/shibboleth-idp/bin/build.sh -Didp.target.dir=/opt/shibboleth-idp

    Результат выполнения команды будет следующим:

    Warning: JAVA_HOME environment variable is not set.
  If build fails because sun.* classes could not be found
  you will need to set the JAVA_HOME environment variable
  to the installation directory of java.
Rebuilding /opt/shibboleth-idp/war/idp.war ...
...done

BUILD SUCCESSFUL
Total time: 3 seconds

    Второе, добавьте в настройках компонента shibboleth.IPRangeAccessControl файла /opt/shibboleth-idp/conf/access-control.xml диапазоны адресов проекта для возможности доступа к данной странице сервису Реестр федерации. Первые два диапазона IPv4/IPv6 адресов разрешают доступ к странице с localhost. Последние адреса используются в настоящее время или запланированы к использованию сервисом Реестр федерации:

                <bean parent="shibboleth.IPRangeAccessControl"
                p:allowedRanges="#{ {'127.0.0.1/32', '::1/128', '194.85.183.0/24'} }" />

    Возможно Вы захотите добавить IP адреса вашей локальной сети для возможности доступа к странице статуса с других машин. Однако, имейте ввиду, по умолчанию, этот же список IP адресов или сетей так же используется для контроля доступа к новым IdP v3 возможностям перезапуска (многоуровневое средство управления посредством перезапуска отдельных подсистем), поэтому добавляйте только определенные IP адреса или используйте отдельные настройки accessPolicy, как описано в документации проекта Shibboleth Wiki в разделе AccessControlConfiguration.

    Hibernate ORM для JPAStorageService

    Существует неудачное взаимодействие между данными столбца value таблицы storagerecords, объявляемыми как “large object” в исходном коде IdP, как Hibernate ORM интерпретирует их и как драйвер JDBC PostgreSQL обращается с BLOBs. Комбинация этих трех элементов приводит к тому, что хранение large object столбца value не дает возможности управления этим типом данных серверу PostgreSQL (детальное описание проблемы OSJ-135). Результатом является появление "осиротевших" large objects и гарантированная потеря данных при выполнении команды vacuumlo. Для предотвращения этой ситуации администраторам, до первого запуска IdP, необходимо совершить следующие действия.

    Чтобы предотвратить использование типа данных large objects библиотекой Hibernate ORM с PostgreSQL, загрузите файл orm.xml и поместите в архив приложения idp.war: 

    sudo mkdir -p /opt/shibboleth-idp/edit-webapp/WEB-INF/classes/META-INF
cd /opt/shibboleth-idp/edit-webapp/WEB-INF/classes/META-INF/
sudo curl -O http://www.fedurus.ru/guides/idp/installation/orm.xml
    Параметры файла orm.xml определяют использование столбца storagerecords.value для хранения объектов в виде текста, при этом достигается такое дополнительное преимущество, как удобочитаемый вид данных.

    Выполните пересборку файла архива приложения idp.war с внесенными изменениями:

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

    Активация приложения

    Для активации приложения IdP в Tomcat создайте файл конфигурации /etc/tomcat/Catalina/localhost/idp.xml следующего содержания:

    <Context docBase="/opt/shibboleth-idp/war/idp.war"
         unpackWAR="false"
         swallowOutput="true">
  <Manager pathname="" />
</Context>

    и (пере)запустите Tomcat:

    sudo service tomcat7 restart
    sudo systemctl enable tomcat.service
sudo systemctl start tomcat.service

    Страница проверки статуса IdP

    На данном этапе есть возможность проверить наличие ошибок при старте IdP. Выполните команду:

    curl --interface lo https://idp.university.ru/idp/status

    Результат выполнения команды должен быть следующим

    ### Operating Environment Information
operating_system: Linux
operating_system_version: 4.4.0-64-generic
operating_system_architecture: amd64
jdk_version: 1.7.0_121
available_cores: 2
used_memory: 137 MB
maximum_memory: 592 MB

### Identity Provider Information
idp_version: 3.3.3
start_time: 2017-03-16T07:59:55Z
current_time: 2017-03-16T08:01:26Z
uptime: 90332 ms

[...]

    Если страница статуса не отображается, необходимо проверить файлы регистрации приложения и сервера приложений на наличие предупреждений и сообщений об ошибках в следующем порядке:

    • /opt/shibboleth-idp/logs/idp-warn.log: сообщения уровня WARN или ERROR в отдельном файле, т.е. часть сообщений файла idp-process.log, которая может быть полезной в получении быстрого обзора потенциальных проблем.
    • /opt/shibboleth-idp/logs/idp-process.log: основной файл регистрации IdP. Если при запуске приложения файлы в папке /opt/shibboleth-idp/logs отсутсвуют, проверьте разрешения данной папки и файлов (убедитесь, что они доступны для записи пользователю владельцу процессаtomcat).
    • /var/log/tomcat/localhost.YYYY-MM-DD.log: сообщения сервера приложений Tomcat (дополнительная информация Logging in Tomcat).
    • /var/log/tomcat/catalina.out: вывод сообщений консоли сервера приложений Tomcat.

    В случае, если после анализа файлов регистрации решение проблем не становится очевидным, первый шаг, который мы рекомендуем, обратиться к странице Troubleshooting Tips Shibboleth Wiki, или произвести поиск на сайте документации Identity Provider 3 проекта. Или воспользуйтесь каким-либо поисковым сервисом, используя ограничения результатов поискового запроса термином +site:shibboleth.net/pipermail/users (или подобным), возможно проблема уже обсуждалась в списке рассылки и была решена сообществом пользователей Shibboleth.

    Наконец, не менее важно обратить внимание, что синтаксические ошибки в файлах XML являются источником (иногда довольно загадочным) сообщений об ошибках. Чтобы убедиться, что файлы конфигурации - правильно оформленные XML документы, мы рекомендуем использовать команду xmllint --noout somefile.xml, которая выводит ошибки синтаксиса в дружественном для человека виде. Используйте команду apt-get install libxml2-utilsyum install libxml2 для установки данной утилиты в случае ее отсутствия в вашей системе. Как альтернатива, для проверки синтаксиса файлов XML возможно использование команды xmlwf somefile.xml.

    Registering the IdP in the federation

    TODO

    Обслуживание и обновление

    Функционирование технологического компонента в федеративной среде требует поддержки в актуальном состоянии программного обеспечения как самого компонента, так и операционной системы. Администраторам IdP рекомендуется подписаться на список рассылки Shibboleth Announce, который используется рабочей группой проекта Shibboleth для анонса выпуска новых версий и уведомлений об устранении проблем безопасности.

    Дополнительно, для своевременного получения оповещений об устранении проблем безопасности для компонентов операционной системы, настоятельно рекомендуется подписка на список рассылки разработчика используемой операционной системы (ubuntu-security-announce, enterprise-watch-list).

    Инструкция по обновлению для определенных версий

    Обновление с версии 3.1.x до 3.2.x

    Версия 3.2 содержит ряд исправлений ошибок и изменений, которые требуют внесения изменений в конфигурацию, добавленную в версии 3.1. Рекомендуется создать резервную копию вашей папки /opt/shibboleth-idp/conf, и далее, внести изменения в конфигурацию в следующей последовательности. Шаги с 1 по 6 (настройка конфигурации) могут быть произведены без остановки IdP.

    1. До вступления в силу изменений удалите файл/opt/shibboleth-idp/edit-webapp/WEB-INF/web.xml,т.к. будет использоваться версия данного файла из дистрибутива. Добавьте в файл /opt/shibboleth-idp/conf/idp.properties строку, отключающую автоматическое создание метаданных для URL с уникальным идентификатором entityID: 

      idp.entityID.metadataFile =

    2. В файле /opt/shibboleth-idp/conf/services.xml для компонента FileBackedFEDURUSAttributeFilter, строка 

      c:resource="file://%{idp.home}/conf/attribute-filter.fedurus.xml"
      должна быть изменена на 
      c:backingFile="%{idp.home}/conf/attribute-filter.fedurus.xml"

    3. Для создания persistentID больше не нужно задавать дополнительное определение атрибута EduPersonUniqueID.withoutAttributeEncoder. В файле /opt/shibboleth-idp/conf/attribute-resolver-fedurus-core.xml удалите элемент <resolver:AttributeDefinition> : 

      <resolver:AttributeDefinition id="%{idp.persistentId.sourceAttribute}" xsi:type="ad:Simple" sourceAttributeID="EduPersonUniqueID">
<resolver:Dependency ref="EduPersonUniqueID"/>
</resolver:AttributeDefinition>

      В файле /opt/shibboleth-idp/conf/saml-nameid.properties замените значение параметра: 
      idp.persistentId.sourceAttribute = EduPersonUniqueID.withoutAttributeEncoder
      значением 
      idp.persistentId.sourceAttribute = EduPersonUniqueID

    4. Так же, для параметра хранилища persistentID используется новое значение. Старое значение остается рабочим, но в файлах регистрации будет выдаваться предупреждение: net.shibboleth.idp.saml.nameid.impl.StoredPersistentIdGenerationStrategy: Transferring settings from deprecated JDBCPersistentStore, please update configuration. Чтобы избавиться от предупреждения, необходимо в файле /opt/shibboleth-idp/conf/saml-nameid.properties заменить значение: 

      idp.persistentId.store = PersistentIdStore
      на: 
      idp.persistentId.dataSource = shibboleth.PostgreSQLDataSource
      Значение параметра shibboleth.PostgreSQLDataSource ссылается на компонент в файле /opt/shibboleth-idp/conf/global.xml. Поэтому, в файле /opt/shibboleth-idp/conf/global.xml старое определение компонента для PersistentIdStore использоваться не будет и может быть удалено:
          <!-- Bean for accessing the "shibpid" table -->
    <bean id="PersistentIdStore"
          class="net.shibboleth.idp.saml.nameid.impl.JDBCPersistentIdStore"
          p:dataSource-ref="shibboleth.PostgreSQLDataSource" />

      “Старый” параметр idp.persistentId.store теперь используется для изменения настроек, связанных с запросами к базе данных, таких как timeout, SQL и column names. Подробное описание настройки данных параметров представлены на сайте проекта Shibboleth wiki в разделе PersistentNameIDGenerationConfiguration.

    5. Отмените временное использование (с 2015-07-17) явного значения salt, замените в файле /opt/shibboleth-idp/conf/attribute-resolver-connectors.xml 

          <resolver:DataConnector id="myStoredId"
        ...
        salt="...random value..."
        queryTimeout="0">
      обратно на 
          <resolver:DataConnector id="myStoredId"
        ...
        salt="%{idp.persistentId.salt}"
        queryTimeout="0">

    6. Подготовлен новый шаблон файла (обновлен для 3.2.1) /opt/shibboleth-idp/conf/intercept/consent-intercept-config.xml. Рекомендуется загрузить новый файл consent-intercept-config.xml и выполнить слияние с вашими существующими изменениями. При использовании существующиго файла consent-intercept-config.xml, необходимо заменить строку: 

      <value>EduPersonUniqueID.withoutAttributeEncoder</value>
      на 
      <value>EduPersonUniqueID</value>

    7. В данный момент пользовательское согласие с условиями использования хранится в виде больших объектов (large objects) реляционной базы данных PostgreSQL. Поскольку это приводит к потере данных при использовании утилиты vacuumlo, рекомендуется внести изменения в структуру базы данных. Для миграции необходимо выполнить следующие шаги:
      • Перейдите в /opt/shibboleth-idp/ и создайте новую папку: 
        cd /opt/shibboleth-idp/
mkdir -p edit-webapp/WEB-INF/classes/META-INF
      • Загрузите файл orm.xml в новую папку /opt/shibboleth-idp/edit-webapp/WEB-INF/classes/META-INF/ 
        cd /opt/shibboleth-idp/edit-webapp/WEB-INF/classes/META-INF/
sudo curl -O http://www.fedurus.ru/guides/idp/installation/orm.xml
        Файл содержит инструкции IdP использовать данные столбца storagerecords.value как text, а не как large object.
      • Создайте резервную копию существующей базы PostgreSQL командой:
        sudo -iu postgres pg_dumpall > dumpall-`date +\%Y-\%m-\%d-\%H\%M\%S`.sql
      • Остановите Tomcat, чтобы избежать потерь данных в процессе миграции базы данных. 
        sudo service tomcat7 stop
        Создайте новую таблицу storagerecords с типом данных text вместо oid следующими запросами: 
        sudo -iu postgres psql shibboleth

DROP RULE valuedeletecleanup on storagerecords;
DROP RULE valueupdatecleanup on storagerecords;

DROP TABLE IF EXISTS storagerecords_new;
DROP TABLE IF EXISTS storagerecords_old;

CREATE TABLE storagerecords_new (LIKE storagerecords INCLUDING ALL);
INSERT INTO storagerecords_new
    SELECT a.context as context,
        a.id as id,
        a.expires as expires,
        convert_from(b.data, 'UTF8') as value,
        a.version as version
    FROM storagerecords a, pg_largeobject b
        WHERE a.value::oid=b.loid;
      • Замените старую таблицу storagerecords новой: 
        ALTER TABLE storagerecords RENAME TO storagerecords_old;
ALTER INDEX storagerecords_pkey RENAME TO storagerecords_old_pkey;
ALTER TABLE storagerecords_new RENAME TO storagerecords;
ALTER INDEX storagerecords_new_pkey RENAME TO storagerecords_pkey;
ALTER TABLE storagerecords OWNER TO shibboleth;
      • Создайте новый индекс для данных столбца storagerecords.expires. Это значительно ускорит процесс обнаружения и очистки записей с истекшим сроком, выполняемый каждые 10 минут, для таблицы storagerecords в несколько тысяч строк. 
        CREATE INDEX storagerecords_expires_index ON storagerecords(expires);
      • Другое новое требование в версии 3.2.1, таблица shibpid должна иметь первичный ключ, создаваемый по значениям столбцов localEntity, peerEntity, persistentId. Добавьте ключ следующим запросом: 
        ALTER TABLE shibpid ADD PRIMARY KEY (localEntity, peerEntity, persistentId);
        По результатам тестов оставшиеся индексы больше не используются при запросах и, для устранения расхода ресурсов на их обслуживание при каждом изменении таблицы, могут быть удалены. Последний остающийся индекс переименован для ясности. 
        DROP INDEX persistentId;
DROP INDEX persistentId_2;
DROP INDEX localentity;
ALTER INDEX localentity_2 RENAME TO shibpid_getbysourcevalue_index;
        Выполните выход из интерфейса PostgreSQL: 
        \q

    Далее выполните действия раздела Общие инструкции по обновлению Shibboleth IdP 3 (patch или minor versions).

    Обновление с версии 3.2.x до 3.3.x

    Версия 3.3.x содержит ряд исправлений и изменений, которые могут потребовать внесение изменений в файлы конфигурации. Большинство из них не важны для стандартного типа развертывания федеративной среде FEDURUS. Однако, рекомендуется внести изменения, касающиеся поддержки многоязычного пользовательского интерфейса.

    XML Namespace Cleanup in Attribute Resolution Configuration

    Cleaning up the XML namespaces in the attribute resolution configuration is highly recommended to keep the configuration forward compatible. Although the current configuration using namespace prefixes is still supported by version 3.3.x, some new features, like the trustFile attribute of the LDAPDirectory Data Connector won't be available without this cleanup.

    The cleanup process is as simple as updating the header of the attribute resolution XML files and removing any occurences of the resolver:, dc:, ad: and enc: namespace prefixes from any XML element and type identifier in the attribute resolution configuration files.

    The following instructions describe in detail how to cleanup the XML namespaces.

    For each of the following files, process the steps below:

    • /opt/shibboleth-idp/conf/attribute-resolver-connectors.xml
    • /opt/shibboleth-idp/conf/attribute-resolver-fedurus-core.xml
    • /opt/shibboleth-idp/conf/attribute-resolver-interfederation-core.xml
    • /opt/shibboleth-idp/conf/attribute-resolver-other.xml
    • (possibly further files you added yourself)

    Steps:

    1. Locate the following <resolver:AttributeResolver ...> element at the beginning of the file (starting on the second line)
      <resolver:AttributeResolver
        xmlns:resolver="urn:mace:shibboleth:2.0:resolver"
        xmlns:pc="urn:mace:shibboleth:2.0:resolver:pc"
        xmlns:ad="urn:mace:shibboleth:2.0:resolver:ad"
        xmlns:dc="urn:mace:shibboleth:2.0:resolver:dc"
        xmlns:enc="urn:mace:shibboleth:2.0:attribute:encoder"
        xmlns:sec="urn:mace:shibboleth:2.0:security"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="urn:mace:shibboleth:2.0:resolver http://shibboleth.net/schema/idp/shibboleth-attribute-resolver.xsd
                      urn:mace:shibboleth:2.0:resolver:pc http://shibboleth.net/schema/idp/shibboleth-attribute-resolver-pc.xsd
                      urn:mace:shibboleth:2.0:resolver:ad http://shibboleth.net/schema/idp/shibboleth-attribute-resolver-ad.xsd
                      urn:mace:shibboleth:2.0:resolver:dc http://shibboleth.net/schema/idp/shibboleth-attribute-resolver-dc.xsd
                    urn:mace:shibboleth:2.0:attribute:encoder http://shibboleth.net/schema/idp/shibboleth-attribute-encoder.xsd
                    urn:mace:shibboleth:2.0:security http://shibboleth.net/schema/idp/shibboleth-security.xsd">
      and replace it with the following (much simpler) contents:
      <AttributeResolver
        xmlns="urn:mace:shibboleth:2.0:resolver"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="urn:mace:shibboleth:2.0:resolver http://shibboleth.net/schema/idp/shibboleth-attribute-resolver.xsd">
    2. At the end of the file, replace </resolver:AttributeResolver> by </AttributeResolver>.
    3. Remove all namespace prefixes resolver:, dc:, ad: and enc: from XML elements and XML type identifiers. You may do this be searching and replacing in your editor.
      • Remove the namespace prefix resolver: from XML elements.
        Examples:
        • Change <resolver:DataConnector ...> to <DataConnector ...> and
          change </resolver:DataConnector> to </DataConnector>.
        • Change <resolver:AttributeDefinition ...> to <AttributeDefinition ...> and
          change </resolver:AttributeDefinition> to </AttributeDefinition>.
        • etc.
      • Remove the namespace prefix dc: from XML elements and XML type identifiers.
        Examples:
        • Change <dc:FilterTemplate ...> to <FilterTemplate ...> and
          change </dc:FilterTemaplte> to </FilterTemplate>.
        • Change xsi:type="dc:LDAPDirectory" to xsi:type="LDAPDirectory".
        • etc.
      • Remove the namespace prefix ad: from XML elements and XML type identifiers.
        Examples:
        • Change <ad:Script> to <Script> and
          change </ad:Script> to </Script>.
        • Change <ad:ValueMap ...> to <ValueMap ...> and
          change </ad:ValueMap> to </ValueMap>.
        • Change xsi:type="ad:Simple" to xsi:type="Simple".
        • Change xsi:type="ad:Script" to xsi:type="ScriptedAttribute"
          Note: In the type definition you need to change the value 'Script' to 'ScriptedAttribute'!
        • etc.
      • Remove the namespace prefix enc: from XML elements and XML type identifiers.
        Examples:
        • Change xsi:type="enc:SAML2String" to xsi:type="SAML2String".
        • etc.
    4. The pc: prefix refers to the Principal Connector deprecated in IdPv3.
      Replace any configuration with a pc: prefix with the new mechanism.
    Limit Cookies to Secure Connections

    The default setting for idp.cookie.secure is false. To prevent browsers from sending IdP cookies via http instead of https, add the following line to the /opt/shibboleth-idp/conf/idp.properties file:

    idp.cookie.secure = true
    Update the messages.properties configuration
    1. Перейдите на страницу Shibboleth Message Translation
    2. Загрузите необходимые файлы messages_[de_CH|fr|it].properties
    3. Переместите загруженные файлы в папку /opt/shibboleth-idp/messages/:
      mv messages_*.properties /opt/shibboleth-idp/messages/
    4. Адаптируйте файлы для вашего случая использования. Т.е. измените текст "Условий использования" (terms of use), если в организации применяется подход получения согласия пользователя при первом использовании сервиса. При последующих обновлениях программного обеспечения данные файлы не будут изменяться, но при появлении новых необходимо будет произвести их замену самостоятельно.
    5. Replace in /opt/shibboleth-idp/conf/services.xml the following lines
      <util:list id="shibboleth.MessageSourceResources">
    <value>%{idp.home}/messages/authn-messages</value>
    <value>%{idp.home}/messages/consent-messages</value>
    <value>%{idp.home}/messages/error-messages</value>
</util:list>
      with these lines to load the new messages.properties files:
      <util:list id="shibboleth.MessageSourceResources">
    <value>%{idp.home}/messages/messages</value>
</util:list>
    6. Optional step: If you want to store local changes to messages.properties and messages_[de_CH|fr|it].properties files into separate files, e.g. local.properties and local_[de_CH|fr|it].properties in the directory /opt/shibboleth-idp/messages, you can add a separate bundle of files by the following configuration in /opt/shibboleth-idp/conf/services.xml:
      <util:list id="shibboleth.MessageSourceResources">
    <value>%{idp.home}/messages/local</value>
    <value>%{idp.home}/messages/messages</value>
</util:list>
    Software Upgrade

    Далее выполните действия раздела Общие инструкции по обновлению Shibboleth IdP 3 (patch или minor versions), расположенные ниже и вернитесь для сюда для выполнения остающихся шагов постмодернизации.

    1. Вы можете удалить предыдущие файлы сообщений из папки /opt/shibboleth-idp/messages, если использовались старые файлы переводов. Они могли включать authn-messages_[de_CH|fr|it].properties, consent-messages_[de_CH|fr|it].properties, error-messages_[de_CH|fr|it].properties.
    2. Только для случая использования функциональности IdP logout: необходимо самостоятельно перенести последнюю версию файла logout.vm из дистрибутива /usr/local/dist/shibboleth-identity-provider-3.3.3/views/logout.vm. Данный шаблон содержит исправления. Повторите собственные изменения, если необходимо. В процессе обновления, существующие в папке /opt/shibboleth-idp/views файлы не изменяются.

    Общие инструкции по обновлению Shibboleth IdP 3 (patch или minor versions)

    Процедура обновления с версии 3.x.y до более новой patch или minor version (3.x.z) Shibboleth IdP 3 достаточно проста, в отличие от довольно замысловатой процедуры, которая была необходима с IdP v2. Полный список изменений представлен на сайте проекта Shibboleth Wiki в разделе ReleaseNotes. В основном, нет необходимости изменения существующей конфигурации при обновлении до последней версии 3.x.y (если не появляются новые возможности, требующие явного внесения изменений).

    Примечание: Обновление с версии 3.1 до 3.2 и с 3.2 до 3.3 содержит ряд изменений параметров конфигурации (специально для PostgreSQL). При обновлении с одной из этих версий измените конфигурацию, как описано в соответствующих разделах выше и, далее, выполните следующие шаги: 

    cd /usr/local/dist
sudo curl -O https://shibboleth.net/downloads/identity-provider/3.x.y/shibboleth-identity-provider-3.x.y.tar.gz
sudo tar -zxf shibboleth-identity-provider-3.x.y.tar.gz
sudo JAVACMD=/usr/bin/java /usr/local/dist/shibboleth-identity-provider-3.x.y/bin/install.sh -Didp.conf.filemode=644

    Убедитесь, что используется параметр -Didp.conf.filemode=644 командной строки и подтвердите использование параметров по умолчанию нажатием клавиши enter, для Source (Distribution) Directory и Installation Directory. Это должно привести к выводу на экран следующей информации:

    Warning: JAVA_HOME environment variable is not set.
  If build fails because sun.* classes could not be found
  you will need to set the JAVA_HOME environment variable
  to the installation directory of java.
Source (Distribution) Directory: [/usr/local/dist/shibboleth-identity-provider-3.x.y]

Installation Directory: [/opt/shibboleth-idp]

Rebuilding /opt/shibboleth-idp/war/idp.war ...
...done

BUILD SUCCESSFUL
Total time: 5 seconds

    Обратите внимание на важность задания надлежащего параметра idp.conf.filemode – в противном случает полномочия (permissions) файлов конфигурации будут изменены к значениям, не подходящим для варианта установки, рекомендуемой данной инструкцией (см. инструкция по установке и настройке). Если Вы непреднамеренно забыли определять этот параметр, повторно запустите сценарий install.sh с заданным idp.conf.filemode. Завершите обновление настройкой разрешений для файла credentials.properties и перезапуском сервера приложений:

    sudo chmod 600 /opt/shibboleth-idp/conf/credentials.properties
sudo service tomcat7 restart
    sudo chmod 600 /opt/shibboleth-idp/conf/credentials.properties
sudo systemctl restart tomcat.service

    Финальные тесты

    После завершения установки и обновления необходимо провести проверку настройки Identity Provider:

    1. Проверьте страницу статуса для просмотра параметров работы модулей Identity Provider.
    2. Проверьте работу стандартной SAML аутентификации используя Сервис Проверки Атрибутов. Убедитесь в отсутствии предупреждений и сообщений об ошибках. Проверьте и убедитесь, что после обновления значение persistentID осталось тем же самым.

    Дополнительная информация

    Данные ссылки могут служить отправными точками для получения более детальной информации о широком спектре возможностей программного обеспечения Shibboleth Identity Provider:

    Информация о версии документа

    Copyright:  FEDURUS
Автор:      support@fedurus.ru
Дата:       2017-10-13
            журнал изменений
    Последние изменения страницы [an error occurred while processing the directive]