====== Filtrování uživatelů na straně Shibboleth SP ======

Chcete-li omezit přístup uživatelů ke zdrojům pomocí Shibboleth SP, máte možnost to udělat prostřednictvím logiky implementované ve vaší aplikaci, anebo pomocí filtru přímo v Shibboleth SP. První cesta nabízí větší flexibilitu a také komfort pro uživatele, kterého můžete přesně informovat, proč mu byl přístup odepřen. Druhá cesta je podstatně jednodušší k implementaci a v řadě případů jediná možná s ohledem na nemožnost zásahů do provozované aplikace. V obou případech se vám může hodit mít k dispozici **entity atributy**.

===== Definice entity atributů =====

Entity atributy jsou uvedeny v metadatech. V případě eduID.cz se jedná o [[:cs:tech:categories|kategorie IdP a několik dalších]]. Tyto atributy lze v Shibboleth SP mapovat stejně jako uživatelské atributy (ty o uživateli vydává IdP). K jejich použití je potřeba v ''shibboleth2.xml'' nastavit prefix pro atributy z metadat u elementu ''ApplicationDefaults'' (nebo případně ''ApplicationOverride'') takto:

<code xml>
<ApplicationDefaults entityID="https://example.org/shibboleth/"
    metadataAttributePrefix="md_">
</code>

Řekněme, že v metadatech máme u dané entity definován následující atribut:
<code xml>
<mdattr:EntityAttributes>
    <saml:Attribute Name="http://macedir.org/entity-category" 
                    NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
        <saml:AttributeValue>http://eduid.cz/uri/idp-group/library</saml:AttributeValue>
    </saml:Attribute>
</mdattr:EntityAttributes>
</code>

Pak můžeme v ''attribute-map.xml'' definovat mapování atributů, bude vypadat takto:

<code xml>
<Attribute name="http://macedir.org/entity-category" id="entityCategory" />
</code>

Ve výsledku se nám hodnota výše uvedeného atributu uloží do proměnné ''md_entityCategory''. Pokud máme zdrojové kódy aplikace SP ve svých rukou, je implementace potřebné logiky pro řízení přistupu také na nás. V opačném případě je možné využít funkcionalitu Shibboleth SP.

Jak je hodnota proměnné předána aplikaci, si můžete prohlédnout na testovacím SP [[https://attributes.eduid.cz/]].

==== Kontrola přístupu pomocí Shibboleth SP ====

Pravidla pro řízení přístupu mohou být komplexní a jsou detailně popsána v [[https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPXMLAccessControl|dokumentaci]].

Základem je v Apache definovat, ke kterému místu (''/limit/access'') chceme omezit přistup a kde jsou pravidla definující oprávnění k onomu místu (''/path/to/ac.xml'').

Pro Apache řady 2.2.x je konfigurace následující:

<code apache>
<Directory /limit/access>
    AuthType              shibboleth
    ShibRequestSetting    requireSession 1
    ShibAccessControl     /path/to/ac.xml 
</Directory>
</code>

Pokud používáte Apache řady 2.4.x, ''ShibAccessControl </cesta/k/pravidlum.xml>'' je nutné změnit na ''Require shib-plugin </cesta/k/pravidlum.xml>'':

<code apache>
<Directory /limit/access>
    AuthType               shibboleth
    ShibRequestSetting     requireSession 1
    require shib-plugin    /path/to/ac.xml 
</Directory>
</code>

=== Include filtr ===

V dokumentu popisujícím [[cs:tech:categories#kategorie_idp|kategorie entit v eduID.cz]] je uveden příklad include filtru, který výčtem uvádí, jaké typy uživatelů a z kterých kategorií IdP akceptujeme jako členy Research & Education komunity. **Důrazně doporučujeme při potřebě filtrování uživatelů použít tento typ filtru.** Filtr je v pseudojazyce popsán takto:

{{page>cs:tech:include-filter&nofooter}}

Implementace pro Shibboleth SP vypadá takto (obsah souboru ''/path/to/ac.xml''):

<code xml>
<AccessControl type="edu.internet2.middleware.shibboleth.sp.provider.XMLAccessControl">
  <OR>
    <AND>
       <Rule require="md_entityCategory">http://eduid.cz/uri/idp-group/university</Rule>
       <OR>
	 <RuleRegex require="affiliation">^employee@.+\.cz$</RuleRegex>
	 <RuleRegex require="affiliation">^faculty@.+\.cz$</RuleRegex>
	 <RuleRegex require="affiliation">^member@.+\.cz$</RuleRegex>
	 <RuleRegex require="affiliation">^student@.+\.cz$</RuleRegex>
	 <RuleRegex require="affiliation">^staff@.+\.cz$</RuleRegex>
       </OR>
    </AND>
    <AND>
       <Rule require="md_entityCategory">http://eduid.cz/uri/idp-group/avcr</Rule>
       <RuleRegex require="affiliation">^member@.+\.cz$</RuleRegex>    
    </AND>
    <AND>
       <Rule require="md_entityCategory">http://eduid.cz/uri/idp-group/library</Rule>
       <RuleRegex require="affiliation">^employee@.+\.cz$</RuleRegex>
    </AND>
    <AND>
       <Rule require="md_entityCategory">http://eduid.cz/uri/idp-group/hospital</Rule>
       <RuleRegex require="affiliation">^employee@.+\.cz$</RuleRegex>    
    </AND>
    <AND>
       <Rule require="md_entityCategory">http://eduid.cz/uri/idp-group/other</Rule>
       <OR>
	 <RuleRegex require="affiliation">^employee@.+\.cz$</RuleRegex>    
	 <RuleRegex require="affiliation">^member@.+\.cz$</RuleRegex>    
       </OR>
    </AND>
  </OR>
</AccessControl>
</code>

Pokud potřebujete jakýkoliv jiný filtr, neměl by pro Vás být problém si filtr s pomocí [[https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPXMLAccessControl|dokumentace]] sestavit. Nebudete-li si vědět rady, můžete se na nás s konkrétním dotazem obrátit -- připojíte-li nějakou část kódu, bude Vám to přičteno k dobru. :-)

=== Exclude filtr ===

Alternativou k include je exclude filtr, který není prostou inverzí include filtru. Neřeší uživatele, kteří mají současně typ affiliate a employee, a dále neřeší vznik nové kategorie IdP. V takovém případě mají přistup všichni uživatelé z nově vzniklé kategorie. **Proto nedoporučujeme použít tento typ filtrování, pokud si nejste jisti všemi vedlejšími účinky jeho nasazení.**

{{page>cs:tech:exclude-filter&nofooter}}

Implementace pro Shibboleth SP vypadá takto (obsah souboru ''/path/to/ac.xml''):

<code xml>
<AccessControl type="edu.internet2.middleware.shibboleth.sp.provider.XMLAccessControl">
  <NOT>
    <OR>
      <RuleRegex require="affiliation">^alumn@.+\.cz$</RuleRegex>
      <AND>      
        <Rule require="md_entityCategory">http://eduid.cz/uri/idp-group/library</Rule>
        <NOT>
          <RuleRegex require="affiliation">^employee@.+\.cz$</RuleRegex>    
        </NOT>
      </AND>      
    </OR>
  </NOT> 
</AccessControl>
</code>
==== Zpracování odmítnutí přístupu ====

V základní konfiguraci Shibboleth SP je uživatel informován pomocí klasického chybového hlášení 403 - přístup odepřen.

{{:cs:tech:403-shibb.png|}}

Administrátor má malé možnosti ladění bez spolupráce s uživatelem. Shibboleth SP neloguje hodnoty atributů ani v nejvyšším debug režimu. Apache do logu zaznamená pouze informaci o odepření přístupu k dokumentu:

<code apache>
2001:718:1:6::1:1 - uid@cesnet.cz [29/Sep/2014:16:19:46 +0200] "GET /ac2/ HTTP/1.1" 403 235
</code>

Připravili jsme jednoduchou stránku pro uživatelsky přívětivější informování o odmítnutí přístupu. K dispozici je také jednoduchý skript, který administrátorům pomůže s laděním přístupových práv. Tyto materiály jsou včetně podrobnějších informací k dispozici v [[https://github.com/CESNET/shibboleth-sp-access-control/tree/master/access_errors|repozitáři CESNETu]] na GitHubu.

Nejprve je nutno výše uvedený repozitář naklonovat, případně si stáhnout odpovídající stránky ''accessError.html'' a ''accessError.php''. Pak je potřeba říci Shibbolethu, jakou stránku má zobrazit, pokud při přístupu k nějakému zdroji dojde k odmítnutí uživatele z důvodu nedostatečných práv. To se nastavuje pomocí atributu ''access'' elementu ''<Errors>'' v konfiguračním souboru ''shibboleth2.xml'' následujícím způsobem:

<code xml>
<Errors supportContact="admin@example.cz"
   logoLocation="/shibboleth-sp/logo.jpg"
   styleSheet="//maxcdn.bootstrapcdn.com/bootstrap/3.2.0/css/bootstrap.min.css"
   access="/path/to/accessError.html"
   ...
/>
</code>

Ve stránce ''accessError.html'' je potřeba se odkázat na skript, který provádí diagnostiku problému. V našem uvedeném případě je to adresa ''/my-app/diagnose'', kterou nakonfigurujeme v Apachi následovně:

<code apache>
<Location /my-app/diagnose>
    AuthType              shibboleth
    ShibRequestSetting    requireSession 1
    require               valid-user
</Location>
</code>

Je-li uživateli zamítnut přístup ke zdroji z důvodu nedostatečného oprávnění, je mu zobrazena stránka ''accessError.html''.

{{:cs:tech:auth-failed.png|}}

Z té se může po kliknutí na tlačítko "Diagnose" dostat na stránku (skript), který zaloguje proměnné prostředí (''$_SERVER'') do definovaného souboru (ve výchozím nastavení ''/tmp/shib-access-error.log''). Danému problému je také vygenerováno identifikační číslo, které se zobrazí uživateli.

{{:cs:tech:auth-diag.png|}}

Pomocí tohoto identifikátoru se správce dané aplikace může podívat na zalogované proměnné prostředí. Porovnáním atributů z logu a těch, které jsou vyžadovány aplikací (''ac.xml'' viz výše) lze určit, kde je problém.

Diagnostická stránka a skript jsou pouze jakýsi návod, jak postupovat. Rozhodně nedoporučujeme, aby byly nasazeny bez bližšího prozkoumání, jelikož je potřeba provést ruční nastavení některých proměnných jako např. umístění logu s proměnnými prostředí nebo e-mailové adresy správce!