====== Implementace federativní autentizace u EZproxy ======

Aplikace EZproxy (dodává [[http://www.oclc.org/ezproxy/|OCLC Inc.]]) je dodávána s podporou autentizace v prostředí Shibboleth/SAML. U EZproxy je vlastní implementace Service Providera.

Parametry pro autentizaci se nastavují v konfiguračním souboru. Po aktivaci přihlašování a nastavení mapování skupin uživatelů jsou k dispozici tyto funkce:
  * Přihlášení uživatale v rámci jednotného přihlašování v prostředí Shibboleth/SAML
  * Personalizovaný výpis dostupných el. zdrojů v rámci EZproxy portálu
  * WAYFless odkazy na zpřístupňované el. zdroje

Implementace Shibboleth/SAML nepodporuje Single Logout.

Odkaz na konfiguraci Shibboleth na [[http://www.oclc.org/support/documentation/ezproxy/usr/shibboleth.htm|webu OCLC]].

Konfiguraci Shibboleth u EZproxy představuje Petr Novák na semináři //Shibboleth v praxi// v Národní technické knihovně - [[http://www.slideshare.net/pnovak99/ezproxy-a-shibboleth-seminar-v-ntk-201010|prezentace]], [[rtsp://xs.ruk.cuni.cz/~bojar/ntk5-264.mov|videozáznam]].


===== Před implementací =====

V EZproxy je nutno nakonfigurovat X.509 certifikát pro podepisování a šifrování komunikace s IdP.
Doporučené parametry:
<code>
 délka klíče 2048 bitů 
 CN=login.hostname.domain.tld
 Organizace=jméno organizace
</code>

Pro vygenerování certifikační žádosti je možno použít jak vestavěný generátor certifikátů EZproxy dostupný z webového admin rozhraní (http://login.hostname.domain.tld/ssl-new?shibboleth=on), tak např. nástroj openssl - [[http://www.oclc.org/support/documentation/ezproxy/cfg/ssl/default.htm|odkaz na návod OCLC]].

{{cs:tech:apps:ezproxy:ezp-spravacertifikatu.png|Správa certifikátů v EZproxy}}


Doporučuje se nasadit serverový certifikát CA TERENA (více viz. služby [[http://pki.cesnet.cz/cs/ch-server.html|CA CESNET]]).
Tento certifikát neslouží pro autentizaci meziserverového SSL spojení (EZproxy ↔ informační zdroj) – pro tento účel má být použit jiný, tzv. hvězdičkový certifikát, vystavený na CN=*.hostname.domain.tld 

===== Metadata =====

EZproxy obsahuje generátor metadat. 

Ukázka metadat -  polotovar metadat generovaný EZproxy (odkaz Certificate Metadata dostupný v EZproxy na URL http://domain.tld/shibboleth):

<code>

<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata">
  <md:SPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol http://schemas.xmlsoap.org/ws/2003/07/secext">
    <md:Extensions>
      <idpdisc:DiscoveryResponse Binding="urn:oasis:names:tc:SAML:profiles:SSO:idp-discovery-protocol" 
                                 Location="https://login.ezproxy.is.cuni.cz/Shibboleth.sso/DS" index="1" 
                                 xmlns:idpdisc="urn:oasis:names:tc:SAML:profiles:SSO:idp-discovery-protocol"/>
    </md:Extensions>
    <md:KeyDescriptor>
      <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <ds:X509Data>
          <ds:X509Certificate>MIIEhDCCA2ygAwIBAgIQA+Tm7A+sXd+JKGnXJsvwLTANBgkqhkiG9w0BAQUFADA2
MQswCQYDVQQGEwJOTDEPMA0GA1UEChMGVEVSRU5BMRYwFAYDVQQDEw1URVJFTkEg
U1NMIENBMB4XDTA5MTIyMjAwMDAwMFoXDTEyMTIyMTIzNTk1OVowVzELMAkGA1UE
BhMCQ1oxJTAjBgNVBAoTHENoYXJsZXMgVW5pdmVyc2l0eSBpbiBQcmFndWUxITAf
BgNVBAMTGGxvZ2luLmV6cHJveHkuaXMuY3VuaS5jejCCASIwDQYJKoZIhvcNAQEB
BQADggEPADCCAQoCggEBAKXw1e19JpiQeBt6S0NPMFiebt2XveiVoNPkJgfMdKbM
rD91zJxuLm7kxAUIp24iYlv5B/5avGUaIXNgfXXuL2uB7O74gom2fUQuZMIXbK+r
MTP0u/iXDVOdmDKfP2sxZcgDjBUwabVh0QxNERdj4AF8j/p9MyR2ifFs5ZA9Aybn
AceRs3iXutc0/qxdfEIPUKqxXh8DX5hfvpzLq1z/pqjZaDJ1kD9SroxRJkTt3MOW
Fv0TCu66dDpOmN5pNnpxtF5ELQHIO4nStgoktQoCi6xZ4Cw+eshyBdy/rzCuySDY
SrTBAG7UUUrQvfNNGr9MmEDdb8OxuQ4ojp5lMv5Z1CUCAwEAAaOCAWswggFnMB8G
A1UdIwQYMBaAFAy9k2gM896ro0lrKzdXR+qQ47ntMB0GA1UdDgQWBBQaQRwoYI9v
J01LmNiWQuBEAgQ9MTAOBgNVHQ8BAf8EBAMCBaAwDAYDVR0TAQH/BAIwADAdBgNV
HSUEFjAUBggrBgEFBQcDAQYIKwYBBQUHAwIwGAYDVR0gBBEwDzANBgsrBgEEAbIx
AQICHTA6BgNVHR8EMzAxMC+gLaArhilodHRwOi8vY3JsLnRjcy50ZXJlbmEub3Jn
L1RFUkVOQVNTTENBLmNybDBtBggrBgEFBQcBAQRhMF8wNQYIKwYBBQUHMAKGKWh0
dHA6Ly9jcnQudGNzLnRlcmVuYS5vcmcvVEVSRU5BU1NMQ0EuY3J0MCYGCCsGAQUF
BzABhhpodHRwOi8vb2NzcC50Y3MudGVyZW5hLm9yZzAjBgNVHREEHDAaghhsb2dp
bi5lenByb3h5LmlzLmN1bmkuY3owDQYJKoZIhvcNAQEFBQADggEBAJnUSqvJjiny
IYRggUFQP+o46sf8wf3WM7xDOncBwuS5y+RSiCvRfftIYrf9R7WnXEcnpIPmugrj
vgwoPyqQhcOu/alnp69ogjkS1b1mKKSKyUkhLIUsFsw+9Sh8iLEqboeWJVDhD3v3
OBAPbfWNZCXcTcXoIxk9PsiP0fGFO6EVw3tV9vGBTBYfUApiRDKOvO3xLPkSsmJh
Lyj3jXth52Fp/1wHmZ5q4pR4gw83C1fla3q5ylMvksmlr4tLaCR0NX5fZzD2fCnG
gbjp6yF2aheE4G+/ouASbZy6fijs58IAHczfB36XXBe7zcUS8VnW4y88WsDCH+Jv
2Dyuki1c8zY=
</ds:X509Certificate>
        </ds:X509Data>
      </ds:KeyInfo>
    </md:KeyDescriptor>
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" 
     Location="https://login.ezproxy.is.cuni.cz/Shibboleth.sso/SAML2/POST" index="1" 
     isDefault="true"/>
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact"
     Location="https://login.ezproxy.is.cuni.cz/Shibboleth.sso/SAML2/Artifact" index="2"/>
  </md:SPSSODescriptor>
</md:EntityDescriptor>

</code>

První tag je tzv. EntityDescriptor – je nutno doplnit entityID jako je v tomto příkladu:
<code>
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="https://login.domain.tld/sp/shibboleth">
</code>

EntityID je nutno zkonzultovat se správcem IdP v instituci.


{{cs:tech:apps:ezproxy:manageshibb.png|Manage Shibboleth – webové rozhraní EZproxy pro správu Shibbolethu}}


Webové rozhraní obsahuje Assertion Consumer Service URL, která se následně využije v metadatech EZproxy.


===== Provoz mimo federaci =====

Pro testovací účely není nutné zapojit EZproxy do federace.
Metadatový soubor v tomto případě umístíme do adresáře s binárním souborem ezproxy. 
Součástí tohoto metadatového souboru musí být metadata příslušného Identity Provideru.

===== Nastavení Shibbolethu v EZproxy =====

config.txt (ezproxy.cfg – v pre 5.x verzích)

Formát konfigurace:
<code>
ShibbolethMetadata \
-EntityID=EZproxyEntityID \
-File=MetadataFile \
-Cert=EZproxyCertNumber \
-URL=MetadataURL
</code>

Příklad EZproxy UK
<code>
ShibbolethMetadata \
-EntityID=https://login.ezproxy.is.cuni.cz/sp/shibboleth \
-File=MetadataFile \
-Cert=1 \ 			
-URL=http://www.eduid.cz/docs/eduid/metadata/eduid-metadata.xml 
</code>

===== Nastavení Shibbolethu jako autentizačního způsobu v EZproxy =====

Soubor ''user.txt'' udržuje informace o lokálních uživatelích EZproxy + definuje další autentizační mechanismy. 
<code>
::Shibboleth
If login:auth eq "shibboleth"; IDP20 https://cas.cuni.cz/idp/shibboleth
/Shibboleth
</code>

Popsaná konfigurace nedává možnost výběru IdP (vynechá WAYF). Pokud požadujeme WAYF, musíme upravit – doplnit URL Directory Service:
<code>
::Shibboleth
If login:auth eq "shibboleth"; DS20 https://ds.eduid.cz/wayf.php
/Shibboleth
</code>

===== Úprava přihlašovací stránky EZproxy =====

<code>
<a href="/login?auth=shibboleth&url=^U">Přihlaste k EZproxy se pomocí Shibboleth </a> 
</code>
                  
Podle nastavení user.txt se zobrazí přímo přihlášení k žádanému IdP nebo se zobrazí služba výběru IdP (WAYF / DS služba).


===== WAYFless linkování =====

WAYFless linkování na zdroj – odkaz si generuje EZproxy, příklad = SpringerLink:
<code>
https://login.domain.tld/login?auth=shibboleth&url=http://ebooks.springerlink.com
</code>


===== Skupiny v EZproxy =====

Používá se pro definování přístupu dle skupin, typicky: fakulty, základní součásti, pracoviště, čtenáři, zaměstnanci – s rozdílným portfoliem zpřístupněných předplacených zdrojů.

Definice příkazem Group FACULTY1 v ''config.txt'' předcházejícím vlastní konfiguraci zdroje.

Lze kombinovat Group FACULTY1+FACULTY2 ...

Na skupiny lze namapovat afiliace předané prostřednictvím Shibbolethu. U EZproxy k tomu slouží pravidla definovaná v souboru ''shibuser.txt''.


===== Shibuser.txt – konfigurace procesu přihlašování =====

Obsah shibuser.txt

<code>
MsgAuth
</code>
ukládá autentizační hlášky do messages.txt, po odladění možno vypnout

<code>
Set login:loguser=auth:eduPersonTargetedID
</code>
stanoví, že EZproxy definuje předané eduPersonTargetedID jako přihlašovací jméno

<code>
If !(auth:issuer eq "https://cas.cuni.cz/idp/shibboleth");   \
      Deny unaffiliated.html
</code>
test zda uživatel přichází od požadovaného IdP, pokud ne, je mu přístup odepřen

<code>
Group NULL
</code>
inicializace skupin

<code>
If Any(auth:eduPersonAffiliation, "staff"); Group +Staff
</code>
otestujeme základní skupiny uživatelů (staff, student, ...) a přiřadíme ke skupině

<code>
IfNoGroups {
  If auth:eduPersonAffiliation eq "interrupted-student"; 
  Deny deny_interrupted.html
  Deny deny_other.html
}
</code>
pokud příchozí uživatel nespadá do povolené skupiny, zamítneme přístup

<code>
Group +Default
</code>
definujeme skupinu Default všem, kdo prošli až sem

<code>
If Any(auth:eduPersonEntitlement, "urn:uni:affiliation:staff@domain.ltd");	
      Group +FACULTY1
</code>
testujeme a přiřazujeme skupiny dle fakult, číselníků kateder, studijních programů, oborů a dalších atributů (přístup lze definovat až na úroveň jedince)

===== Ladění =====

Průběh autentizační session je k dispozici ve webovém rozhraní:
<code>
http://domain.tld/messages?last=100
</code>

===== Konfigurace s SFX =====

Požadovaný scénář: Při připojení k elektronickému informačnímu zdroji přes EZproxy server z počítače, jenž je připojen k počítačové síti instituce (přímo či přes VPN) a jehož IP adresa spadá do definovaného rozsahu IP adres instituce, není požadována autentizace. Při připojení k elektronickému informačnímu zdroji přes EZproxy server z počítače, jenž není připojen k počítačové síti instituce a jehož IP adresa nespadá do definovaného rozsahu IP adres instituce, je požadována autentizace. 

Řešení:
Ke konfiguraci každého zdroje (většinou tvořenou příkazy TITLE, URL, DOMAIN, HOST aj) v souboru config.txt je nutno přidat rozsah IP adres instituce (nebo části instituce, např. fakulty). Tento rozsah se přidává 2x - před a za konfiguraci zdroje.

Příklad:
<code>
AutoLoginIP 192.168.0.1-192.168.0.254
Title Databáze XY
URL http://www.databaze.com
D databaze.com
IncludeIP 192.168.0.1-192.168.0.254
</code>

IP adresy mohou být jak privátní, tak veřejné. Rozsahy je možné sdružovat (zápis vždy na nový řádek), pokud má instituce více rozsahů. Páry příkazů AutoLoginIP a IncludeIP se musí nacházet vždy v rámci jedné skupiny a mohou definovat přístup k více zdrojům. V EZproxy logu se místo uživatelského jména (eduPersonTargetedID, pokud je nastaveno) zobrazí uživatelské jméno “auto” a jako skupina (skupiny) uživatele se použije skupina, v níž je umístěna konfigurace zdroje.

[[https://www.eduid.cz/wiki/eduid/admins/howto/deploy/sfx/index|Konfigurace na straně SFX serveru]].

===== Varování k certifikace rollover =====

Při certifikace rollover polovina přihlášení u EZproxy končí s chybou - EZproxy nepodporuje korektně certificate rollover.