cs:tech:idp:uapprove

uApprove

Tento návod je pro Shibboleth IdP verze 2.4.x. Nová major verze Shibboleth 3.0 má uApprove již integrováno a bližší informace k této verzi budou dostupné společně s vydáním instalačního manuálu pro Shibboleth 3.0.

Návod vychází z manuálu od SWITCH na adrese https://www.switch.ch/aai/downloads/uApprove-manual/.


Instalace

Nejprve nastavíme proměnné prostředí pro instalaci a konfiguraci. UAPPROVE_INSTALL je adresář s rozbalenou instalací uApprove, IDP_INSTALL je adresář s rozbalenou instalací IdP a IDP_HOME je adresář, kde je nainstalované IdP.

Hodnoty níže je potřeba změnit podle aktuálních verzí a lokací v OS.

export UAPPROVE_INSTALL=/opt/src/uApprove-2.6.0/
export IDP_INSTALL=/opt/src/shibboleth-identityprovider-2.4.4/
export IDP_HOME=/opt/shibboleth-idp-2.4.4/

Stáhneme a rozbalíme uApprove.

cd /opt/src
wget https://forge.switch.ch/redmine/attachments/download/1823/uApprove-2.6.0.zip
unzip uApprove-2.6.0.zip

Zkopírujeme potřebné knihovny do instalačního adresáře IdP.

cp $UAPPROVE_INSTALL/lib/*.jar $IDP_INSTALL/lib
cp $UAPPROVE_INSTALL/lib/jdbc/*.jar $IDP_INSTALL/lib

Zkopírujeme standardní konfigurační soubory do adresáře s konfigurací IdP.

cp $UAPPROVE_INSTALL/manual/configuration/uApprove.properties $IDP_HOME/conf
cp $UAPPROVE_INSTALL/manual/configuration/uApprove.xml $IDP_HOME/conf

Zkopírujeme soubory webové aplikace (jsp, css, …) do instalačního adresáře IdP.

mkdir $IDP_INSTALL/src/main/webapp/uApprove
cp $UAPPROVE_INSTALL/webapp/* $IDP_INSTALL/src/main/webapp/uApprove

MySQL

V této podsekci zkopírujeme knihovnu pro MySQL, což je databáze, kterou v návodu budeme používat. Pokud už tuto knihovnu v instalačním adresáři máme, nebo nechceme použít MySQL databázi, můžeme celou tuto podsekci vynechat a pokračovat sekcí Konfigurace.

cp $UAPPROVE_INSTALL/lib/jdbc/optional/mysql-connector-java-5.1.34.jar $IDP_INSTALL/lib

Následující sekvence příkazů slouží k vytvoření a nastavení databáze. Je potřeba změnit heslo (v textu secret) a poznamenat si ho pro pozdější konfiguraci.

mysql -u root -p
SET NAMES 'utf8';
SET CHARACTER SET utf8;
CHARSET utf8;
 
CREATE DATABASE IF NOT EXISTS uApprove CHARACTER SET=utf8;
USE uApprove;
 
CREATE USER 'uApprove'@'localhost' IDENTIFIED BY 'secret';
 
GRANT INSERT, SELECT, UPDATE, DELETE ON uApprove.* TO 'uApprove'@'localhost';
FLUSH PRIVILEGES;
 
CREATE TABLE ToUAcceptance (
 userId         VARCHAR(104)                           NOT NULL,
 version        VARCHAR(104)                           NOT NULL,
 fingerprint    VARCHAR(256)                           NOT NULL,
 acceptanceDate TIMESTAMP   DEFAULT CURRENT_TIMESTAMP NOT NULL,
 
 PRIMARY KEY (userId, version)
);
 
CREATE TABLE AttributeReleaseConsent (
 userId         VARCHAR(104)                           NOT NULL,
 relyingPartyId VARCHAR(104)                           NOT NULL,
 attributeId    VARCHAR(104)                           NOT NULL,
 valuesHash     VARCHAR(256)                           NOT NULL,
 consentDate    TIMESTAMP   DEFAULT CURRENT_TIMESTAMP NOT NULL,
 
 PRIMARY KEY (userId, relyingPartyId, attributeId)
);

Konfigurace

Nyní upravíme soubor $IDP_INSTALL$/src/main/webapp/WEB-INF/web.xml následujícím způsobem. Změníme hodnotu v elementu context-param z

<param-value>$IDP_HOME$/conf/internal.xml; $IDP_HOME$/conf/service.xml;</param-value>

na

<param-value>$IDP_HOME$/conf/internal.xml; $IDP_HOME$/conf/service.xml; $IDP_HOME$/conf/uApprove.xml</param-value>

Přidáme následující filtry a servlety:

    <!-- uApprove Filter and Servlets -->
 
    <filter>
        <filter-name>uApprove</filter-name>
        <filter-class>ch.SWITCH.aai.uApprove.Intercepter</filter-class>
    </filter>
 
    <filter-mapping>
        <filter-name>uApprove</filter-name>
        <url-pattern>/profile/Shibboleth/SSO</url-pattern>
        <url-pattern>/profile/SAML1/SOAP/AttributeQuery</url-pattern>
        <url-pattern>/profile/SAML1/SOAP/ArtifactResolution</url-pattern>
        <url-pattern>/profile/SAML2/POST/SSO</url-pattern>
        <url-pattern>/profile/SAML2/POST-SimpleSign/SSO</url-pattern>
        <url-pattern>/profile/SAML2/Redirect/SSO</url-pattern>
        <url-pattern>/profile/SAML2/Unsolicited/SSO</url-pattern>
        <url-pattern>/Authn/UserPassword</url-pattern>
    </filter-mapping>
 
    <servlet>
        <servlet-name>uApprove - Terms Of Use</servlet-name>
        <servlet-class>ch.SWITCH.aai.uApprove.tou.ToUServlet</servlet-class>
    </servlet>
 
    <servlet-mapping>
        <servlet-name>uApprove - Terms Of Use</servlet-name>
        <url-pattern>/uApprove/TermsOfUse</url-pattern>
    </servlet-mapping>
 
    <servlet>
        <servlet-name>uApprove - Attribute Release</servlet-name>
        <servlet-class>ch.SWITCH.aai.uApprove.ar.AttributeReleaseServlet</servlet-class>
    </servlet>
 
    <servlet-mapping>
        <servlet-name>uApprove - Attribute Release</servlet-name>
        <url-pattern>/uApprove/AttributeRelease</url-pattern>
    </servlet-mapping>

V souboru $IDP_HOME/conf/uApprove.xml nahradíme řádek z

<context:property-placeholder location="classpath:/configuration/uApprove.properties" />

na

<context:property-placeholder location="file:$IDP_HOME/conf/uApprove.properties" />

(Proměnnou $IdP_HOME je nutné nahradit absolutní cestou!)

Nyní provedeme konfiguraci uApprove v souboru $IDP_HOME/conf/uApprove.properties.

Nejprve nadefinujeme seznam služeb, pro které se nebude uApprove zobrazovat. Lze použít jak celý název entityID, tak i část doplněnou o hvězdičku (přesněji je možné používat regulární výrazy pro definování entityID), reprezentující libovolnou hodnotu. Pokud chceme uApprove zobrazovat pro všechny služby, tak tuto sekci přeskočíme. Nastavením volby services.blacklist na hodnotu false docílíme toho, že se uApprove bude zobrazovat pouze na stránkách s entityID definovaným v proměnné services.

services                    = ^*\.example\.org/.*$ \
		              https://hostname\.example2\.org/shibboleth/sp
services.blacklist          = true

Dále nastavíme spojení s databází. Níže uvedené heslo secret nahradíme za heslo, které jsem nastavili při vytváření databáze.

database.driver             = com.mysql.jdbc.Driver
database.url                = jdbc:mysql://localhost:3306/uApprove?autoReconnect=true
database.username           = uApprove
database.password           = secret

Pokud nechceme zobrazovat stránku s Podmínkami použití služby, tak vytvoříme prázdný soubor $IDP_HOME/conf/terms-of-use.html a nastavíme konfiguraci viz. níže. V opačném případě vytvoříme patřičný soubor $IDP_HOME/conf/terms-of-use.html a konfigurační volbu tou.enabled nastavíme na hodnotu true.

tou.enabled                 = false
tou.resource                = file:$IDP_HOME/conf/terms-of-use.html

Pomocí volby ar.attributes.order definujeme pořadí zobrazení atributů, například:

ar.attributes.order         = tcsUnstructuredName \
                              eduPersonPrincipalName \
                              givenName \
                              sn \
                              cn \
                              displayName \
                              email \
                              eduPersonAffiliation \
                              eduPersonScopedAffiliation \
                              o \
                              ou \
                              eduPersonEntitlement

A pomocí volby ar.attributes.blacklist definujeme atributy, které se nemají nikdy ve výpisu zobrazovat, například:

ar.attributes.blacklist     = transientId \
                              persistentId \
                              eduPersonTargetedID

V souboru $IDP_HOME/conf/uApprove.xml změníme konfiguraci, aby uApprove nezobrazoval exception při nedostupné databázi (změníme parametr p:graceful na hodnotu true u elementů <bean> s hodnotou id='uApprove.ToUModule' a id='uApprove.AttributeReleaseModule') – v případě nedostupné databáze se uApprove zobrazí i uživatelům, kteří potvrdili, že se jim již nemá zobrazovat.

    <bean class="ch.SWITCH.aai.uApprove.tou.ToUModule" ... >
        <!-- ... -->
        <property name="storage">
            <bean class="ch.SWITCH.aai.uApprove.tou.storage.JDBCStorage" ...
                p:graceful="true" ... />
        </property>
    </bean>
 
    <!-- ... -->
 
    <bean id="uApprove.attributeReleaseModule" class="ch.SWITCH.aai.uApprove.ar.AttributeReleaseModule" ...>
        <!-- ... -->
        <property name="storage">
            <bean class="ch.SWITCH.aai.uApprove.ar.storage.JDBCStorage" ...
               p:graceful="true" ... />
        </property>
    </bean>

Lokalizace

Pokud nechceme uApprove lokalizovat, tak lze následující sekci přeskočit. V souboru $IDP_HOME/conf/attribute-resolver.xml, lze definovat popisy a jména atributů v různých jazykových mutacích. Následuje příklad pro e-mail.

<resolver:AttributeDefinition xsi:type="ad:Simple" id="email" sourceAttributeID="mail">
  <resolver:Dependency ref="myLDAP" />
  <resolver:DisplayName xml:lang="en">E-mail</resolver:DisplayName>
  <resolver:DisplayName xml:lang="cs">E-mail</resolver:DisplayName>
  <resolver:DisplayDescription xml:lang="en">E-mail address</resolver:DisplayDescription>
  <resolver:DisplayDescription xml:lang="cs">E-mailová adresa</resolver:DisplayDescription>
  <resolver:AttributeEncoder xsi:type="enc:SAML1String" name="urn:mace:dir:attribute-def:mail" />
  <resolver:AttributeEncoder xsi:type="enc:SAML2String" name="urn:oid:0.9.2342.19200300.100.1.3" friendlyName="mail" />
</resolver:AttributeDefinition>

Pro překlad webového rozhraní uApprove je potřeba zkopírovat $UAPPROVE_INSTALL/manual/examples/messages do $IDP_INSTALL/src/main/webapp/WEB-INF/classes/uApprove/messages a upravit příslušný jazyk. Dále je potřeba v $IDP_HOME/conf/uApprove.xml změnit následující část konfigurace

<bean class="ch.SWITCH.aai.uApprove.ViewHelper" ...
      p:messagesBase="messages" />

na

<bean class="ch.SWITCH.aai.uApprove.ViewHelper" ...
      p:messagesBase="uApprove.messages" />

Změna loga

Logo na úvodní obrazovce můžeme změnit překopírováním souboru logo.png přes $IDP_INSTALL/src/main/webapp/uApprove/logo.png.

Aktivace

Nyní by mělo být již vše nachystáno, tak provedeme instalaci IdP a restart Tomcat:

$IDP_INSTALL/install.sh
/etc/init.d/tomcat6 restart

Restart kontejneru Tomcat způsobí ztrátu všech sezení a uživatelé se budou muset znovu přihlásit. Proto zvažte, zda neprovést restart v době, kdy je přihlášeno minimum uživatelů. Zejména v případě nutnosti ladění a s tím souvisejících vícenásobných restartů Tomcatu nebudou uživatelé spokojeni.

Právní ujednání

Právnické texty pro uApprove připravili právníci z Masarykovy univerizty.

V češtině:

Souhlas se zpracováním osobních údajů

Souhlasím se shromažďováním, uchováním a zpracováním osobních údajů obsažených v tomto formuláři správcem provozujícím službu, ke které se přihlašuji, (příp. jeho zaměstnanci) pro účel stanovený níže. Tento souhlas uděluji pro všechny údaje obsažené v tomto formuláři. Zároveň jsem si vědom/a svých práv podle § 12 a 21 zákona č. 101/2000 Sb., o ochraně osobních údajů. Se všemi vyplněnými částmi tohoto formuláře jsem byl/a seznámen/a, všechny údaje jsou přesné a pravdivé a jsou poskytovány dobrovolně.

Účel zpracování osobních údajů

V souladu s § 5 zákona č. 101/2000 Sb. o ochraně osobních údajů jsou všechny údaje uvedené v tomto formuláři shromažďovány a zpracovávány výhradně pro statistické účely a pro vnitřní potřebu správce prostřednictvím elektronických prostředků podle zákona č. 480/2004 Sb., o některých službách informační společnosti, a to do doby, kdy subjekt údajů přímo a účinně zašle správci informaci o tom, že si nepřeje aby byly jeho údaje dále uchovávány a zpracovávány.

V angličtině:

Consent to personal data processing

I hereby certify that I grant express consent to maintain and process my personal data contained in this form. My personal data will be processed by administrator of the service to which I'm hereby subscribing, for the purposes specified below. This consent applies to all data contained in this form. I hereby certify that pursuant to Section 11 and Section 21 of the Act No. 101/2000 Coll., I have been informed about my rights related to the processing of personal data and about other conditions related to the processing of personal data and to the method of its processing. Furthermore, I hereby certify that I'm familiar with all the data in this form and that the data is true, accurate and provided voluntarily.

Purpose of personal data processing

In accordance with Section 5 of the Act No. 101/2000 Sb. all data provided in this form is maintained and processed exclusively for internal use of the controller and for statistical purposes. The data is processed both manually and automatically through electronic means according to Act No. 480/2004 Coll. The consent is voluntary and you may withdraw your consent any time.


Návod připravil Tomáš Sapák, upravil Jan Oppolzer.

Last modified:: 2018/07/13 12:58