====== Research & Scholarship ======

Kategorie //Research & Scholarship// (R&S) má svou [[https://refeds.org/category/research-and-scholarship|oficiální dokumentaci]] na webu [[https://refeds.org|REFEDS]]. Níže uvedené informace jsou překladem oficiální dokumentace a nemusí být vždy aktuální.

**//Zde uvedený překlad je přeložen v dobré víře a s maximální snahou o přesnost a pochopitelnost. Originální dokumenty, které jsou odkazovány, však mají vždy přednost.//**

Historie:\\
[[https://refeds.org/wp-content/uploads/2016/09/ENTCAT-RANDS-v1.3.pdf|v1.3]] publikováno 20. února 2017. (aktuální verze)

Dále je možné na stránkách REFEDS nalézt [[https://wiki.refeds.org/display/ENT/Research+and+Scholarship|další užitečné dokumenty]] jako:

  *[[https://wiki.refeds.org/display/ENT/Research+and+Scholarship+FAQ|Research and Scholarship FAQ]],
  *[[https://wiki.refeds.org/display/ENT/Research+and+Scholarship+IdP+Config|Research and Scholarship IdP Config]] a
  *[[https://wiki.refeds.org/display/ENT/Research+and+Scholarship+Review+2016|Research and Scholarship Review 2016]].

===== Přehled =====

Výzkumné a vzdělávací federace jsou vyzvány, aby používaly skupinou REFEDS definou kategorii entit //Research & Scholarship// pomocí níž zajistí snadné uvolňování atributů pro poskytovatele služeb splňující požadavky uvedené níže.

Klíčová slova "MUSÍ" (//MUST//), "NESMÍ" (//MUST NOT//), "POŽADOVANÝ" (//REQUIRED//), "MUSÍ" (//SHALL//), "NESMÍ" (//SHALL NOT//), "MĚL BY" (//SHOULD//), "NEMĚL BY" (//SHOULD NOT//), "DOPORUČENÝ" (//RECOMENDED//), "SMÍ" (//MAY//) a "VOLITELNÝ" (//OPTIONAL//) v tomto dokumentu by měla být interpretována jak je popsáno v RFC 2119 [[https://tools.ietf.org/html/rfc2119|[RFC2119]]].

Tato definice je sepsána v souladu se specifikací [[https://tools.ietf.org/html/draft-young-entity-category|Entity Category SAML Entity Metadata Attribute Types]] [EntityCatTypes]. Tato specifikace může být rozšířena o doporučení na další formulace specifické pro tento protokol podle vyžadovaných okolností.

[[https://wiki.refeds.org/display/ENT/Research+and+Scholarship+FAQ|Sekce s otázkami a odpověďmi]] (FAQ) je k dispozici pro snazší implementaci [R&SFAQ].
===== 1. Definice =====

Žadatelé o členství v kategorii R&S jsou služby provozované alespoň z části pro účely podpory výzkumu a vzdělávání, spolupráce nebo řízení.

Jako příklady služeb je možné uvést např. nástroje pro spolupráci jako wiki stránky, blogy, nástroje pro projektové a grantové řízení vyžadující určité osobní informace o uživatelích pro efektivní činnost. Tato kategorie nesmí být použita pro přístup k licencovanému obsahu jako např. elektronické žurnály.

Poskytovatelé identit mohou označit podporu pro poskytovatele služeb v této kategorii pro usnadnění uživatelské zkušenosti na službě. Typicky podporu deklaruje správce entity, avšak není to jediná akceptovatelná metoda.

Následující sekce vyjmenovávají požadavky pro poskytovatele služeb a poskytovatele identit v této kategorii.

===== 2. Syntaxe =====

Následující URI se používá jako hodnota atributu pro kategorii entit:

<code>
http://refeds.org/category/research-and-scholarship
</code>

===== 3. Sémantika =====

Uplatněním členství na poskytovatele služby v této kategorii registrátor tvrdí, že:

  - Poskytovatel služby požádal o členství v kategorii R&S a splňuje registrační požadavky na členství v R&S.
  - Žádost o členství poskytovatele služby v kategorii R&S byla posouzena a schválena registrátorem.

Nabytím členství v R&S se poskytovatel služby zavazuje, že nepoužije získané uživatelské atributy pro účely, které nespadají do definice služby prezentované uživatelům v době registrace.

Nabytím členství v R&S se poskytovatel identity zavazuje, že uvolní atributy poskytovatelům služeb z kategorie R&S jak je uvedeno v sekci "[[#pozadavky_na_idp|Požadavky na IdP]]" níže.

===== 4. Registrační kritéria =====

Když registrátor poskytovatele služby (normálně domovská federace poskytovatele služby) registruje poskytovatele služby do kategorie R&S, musí (//MUST//) prověřit alespoň následující:

  - Služba obohacuje výzkumné a vzdělávací aktivity určité části uživatelské komunity.
  - Metadata služby byla odeslána registrátorovi k publikaci.
  - Služba splňuje následující technické požadavky:
    - Poskytovatel služby je produkční služba s podporou SAML V2.0 HTTP-POST vazbou.
    - Poskytovatel služby deklaruje, že aktualizuje federační metadata alespoň jednou denně.
    - Poskytovatel služby poskytuje v metadatech ''mdui:DisplayName'' a ''mdui:InformationURL'' (anglická verze ''xml:lang="en"'' je doporučená).
    - Poskytovatel služby v metadatech uvádí alespoň jeden technický kontakt.

Poskytovatelé služeb v kategorii R&S musí (//MUST//) vyřešit libovolné problémy během rozumného časového intervalu od doby, kdy se o problému dozvědí. Pokud tak neučiní, musí (//MUST//) být jejich členství v R&S kategorii zrušeno.

===== 5. Skupina atributů =====

Způsob, jakým tato kategorie entit uvolňuje atributy, je dán definicí skupiny obecně podporovaných a používaných atributů, které jsou typicky potřeba pro efektivní využívání služeb spojených s výzkumem a vzděláváním. Vybrané atributy reprezentují základní informace, jejichž další minimalizace nepřináší žádné další výhody. Je tak dodržen princip, že se uvolňuje pouze minimální potřebný set uživatelských informací.

Použití mechanismu ''<md:RequestedAttribute>'' podporovaného v SAML metadatech je mimo rozsah této kategorie, ale může být využit, je-li to žádoucí.

//Skupina atributů R&S// kategorie sestává z následujících elementů:

  * //identifikátor uživatele//,
  * //jméno uživatele//,
  * //e-mail uživatele//,

a jednoho volitelného elementu:

  * //afiliace//,

kde //identifikátor uživatele// je trvalý, nerecyklovatelný a jednoznačný identifikátor definovaný jako jedna z následujících možností:

  * ''eduPersonPrincipalName'' (pokud nedochází v rámci organizace k jeho recyklaci),
  * ''eduPersonPrincipalName'' + ''eduPersonTargetedID'',

kde //jméno uživatele// je definováno jako jedna z následujících možností:

  * ''displayName'',
  * ''givenName'' + ''sn'',

kde //e-mail uživatele// je definován jako atribut ''mail'',

a kde //afiliace// je definována jako atribut ''eduPersonScopedAffiliation''.

Všechny výše uvedené atributy jsou definovány ve specifikaci [[http://software.internet2.edu/eduperson/internet2-mace-dir-eduperson-201602.html|[eduPerson]]]. Konkrétní pojmenování a formát těchto atributů je řízený použitým protokolem. Pro SAML 2.0 musí (//MUST//) být použit profil [[http://macedir.org/docs/internet2-mace-dir-saml-attributes-200804a.pdf|[SAMLAttr]]]. Tato specifikace může být dle požadavků rozšířena o další na protokolu závislé formulace.

===== 6. Požadavky na SP =====

Poskytovatelé služeb by měli (//SHOULD//) omezit své požadavky na uživatelské údaje na skupinu atributů definovanou v sekci "[[#skupina_atributu|Skupina atributů]]", ale mohou si vyjednat dodatečné uživatelské údaje dle vlastních požadavků pomocí mechanismů spadajících mimo rozsah této specifikace.

Poskytovatelům služeb je silně doporučeno, aby podporovali všechny alternativy pro //identifikátor uživatele// a //jméno uživatele// popsané v sekci "[[#skupina_atributu|Skupina atributů]]" pro zajištění maximální kompatibility. Pokud tak neučiní, mohou se setkat s problémy i v případě, že budou výhradně používat poskytovatele identit z kategorie R&S. V případě atributu ''eduPersonTargetedID'' to znamená schopnost podporovat i persistentní NameID z protokolu SAML 2.0, což je doporučený moderní způsob vyjádření tohoto atributu.

Pokud poskytovatel identity v metadatech deklaruje podporu kategorie R&S a neposílá atribut ''eduPersonTargetedID'', je možné se v souvislosti s následující sekcí spolehnout na skutečnost, že atribut ''eduPersonPrincipalName'' se na dané organizaci nerecykluje.

V opačném případě může poskytovatel služby získat nerecyklovatelný //identifikátor uživatele// kombinací (např. zřetězením) hodnot atributů ''eduPersonPrincipalName'' a ''eduPersonTargetedID''. Pokud se někdy kombinace těchto dvou hodnot změní, může poskytovatel služby předpokládat, že došlo k recyklaci hodnoty eduPersonPrincipalName a nyní reprezentuje jiného uživatele.

**Poskytovatel služby splňující kritéria kategorie R&S má v metadatech uvedený následující entity atribut:**

<code xml>
<mdattr:EntityAttributes xmlns:mdattr="urn:oasis:names:tc:SAML:metadata:attribute">
  <saml:Attribute
      xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
      NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"
      Name="http://macedir.org/entity-category">
    <saml:AttributeValue>http://refeds.org/category/research-and-scholarship</saml:AttributeValue>
  </saml:Attribute>
</mdattr:EntityAttributes>
</code>

===== 7. Požadavky na IdP =====

Poskytovatel identity deklaruje podporu R&S kategorie v metadatech uvedením entity atributu. Takový poskytovatel identity musí (//MUST//) pro značnou část svých uživatelů uvolňovat všechny požadované atributy ze "[[#skupina_atributu|Skupiny atributů]]" a to všem poskytovatelům služeb z R&S kategorie. Uvolňování atributů musí být buď plně automatické nebo dosaženo pomocí uživatelského souhlasu [např. "uApprove"], případně oznámení uživateli, avšak bez jakéhokoliv administrativního zásahu kteroukoli stranou.

Poskytovatel identity, který z libovolného důvodu neuvolňuje všechny požadované uživatelské údaje ze [[#skupina_atributů|skupiny atributů]] pro kategorii R&S, nesmí (//SHALL NOT//) deklarovat podporu pro kategorii R&S v metadatech. Výjimky, limitující uvolňování atributů konkrétnímu poskytovateli služeb z kategorie R&S, mohou být dovoleny v případě bezpečnostní události nebo dalších osamocených okolností.

Trvalý, nerecyklovatelný a necílený identifikátor je vyžadovaný (//REQUIRED//). Pokud konfigurace poskytovatele identity zajišťuje nerecyklovatelnost atributu ''eduPersonPrincipalName'' a organizace v dobré víře věří, že to tak zůstane, je atribut ''eduPersonPrincipalName'' dostatečný. V ostatních případech musí (//MUST//) poskytovatel identity uvolňovat atribut ''eduPersonTargetedID'' (který je z definice nerecyklovatelný) společně s atributem ''eduPersonPrincipalName''. V každém případě se doporučuje uvolňovat oba dva atributy.

Buď ''displayName'' nebo kombinace ''givenName'' + ''sn'' je vyžadován. Uvolňování všech tří atributů obsahující jméno uživatele (''displayName'', ''givenName'', ''sn'') je doporučené (//RECOMENDED//).

Poskytovatelé identit jsou nabádáni k uvolňování celé skupiny (tedy vyžadovaných i volitelných) R&S atributů všem poskytovatelům služeb z kategorie R&S. Maximalizuje se tím interoperabilita a rozsah podporovaných služeb. Jediným volitelným atributem je //afiliace//, který je sice povahou odlišný od zbývajících atributů, ale je důležitý pro mnoho služeb z kategorie R&S a je také důležitou odlišností u akademických organizací.

**Poskytovatel identity podporující kategorii R&S má v metadatech uvedený následující entity atribut:**

<code xml>
<mdattr:EntityAttributes xmlns:mdattr="urn:oasis:names:tc:SAML:metadata:attribute">
  <saml:Attribute
      xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
      NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"
      Name="http://macedir.org/entity-category-support">
    <saml:AttributeValue>http://refeds.org/category/research-and-scholarship</saml:AttributeValue>
  </saml:Attribute>
</mdattr:EntityAttributes>
</code>

===== 8. Odkazy =====

[[http://software.internet2.edu/eduperson/internet2-mace-dir-eduperson-201602.html|[eduPerson]]] Internet2 MACE Directory Working Group, “eduPerson Object Class Specification (201602)”, February 2016.

[[https://tools.ietf.org/html/draft-young-entity-category|[EntityCatTypes]]] Young, I, Johansson, L, and Cantor, S Ed., “The Entity Category SAML Attribute Types”, July 2014.

[[https://wiki.refeds.org/display/ENT/Research+and+Scholarship+FAQ|[R&SFAQ]]] Harris, N., “Research and Scholarship FAQ”, November 2014.

[[https://www.ietf.org/rfc/rfc2119.txt|[RFC2119]]] Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels”, BCP 14, RFC 2119, March 1997.

[[http://macedir.org/docs/internet2-mace-dir-saml-attributes-200804a.pdf|[SAMLAttr]]] Internet2 MACE Directory Working Group, “MACE-Dir SAML Attribute Profiles”, April 2008.

----

====== Konfigurace SP ======

V konfiguračním souboru ''shibboleth2.xml'' je ideální přidat k metadatům externí šablonu (''template="metadata-template.xml"'') umístěnou do adresáře ''/etc/shibboleth/'' následujícím způsobem.

<code xml>
<Handler type="MetadataGenerator" Location="/Metadata" signing="false" template="metadata-template.xml"/>
</code>

Tato externí šablona (''metadata-template.xml'') musí obsahovat následující (hodnoty upravte dle svých potřeb).

<code xml>
<?xml version="1.0" encoding="utf-8" ?>
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata">

    <md:SPSSODescriptor>

        <md:Extensions>
            <!-- UIInfo -->
            <mdui:UIInfo xmlns:mdui="urn:oasis:names:tc:SAML:metadata:ui">
                <mdui:DisplayName xml:lang="en">Software Database</mdui:DisplayName>
                <mdui:DisplayName xml:lang="cs">Databáze software</mdui:DisplayName>
                <mdui:Description xml:lang="en">Software available for download.</mdui:Description>
                <mdui:Description xml:lang="cs">Seznam software ke stažení.</mdui:Description>
                <mdui:InformationURL xml:lang="en">https://www.example.org/en/info.html</mdui:InformationURL>
                <mdui:InformationURL xml:lang="cs">https://www.example.org/cs/info.html</mdui:InformationURL>
                <mdui:Logo height="128" width="128">https://www.example.org/logo.png</mdui:Logo>
            </mdui:UIInfo>
        </md:Extensions>

        <!-- Requested Attributes -->
        <md:AttributeConsumingService index="0">
            <md:ServiceName xml:lang="en">Software Database</md:ServiceName>
            <md:ServiceName xml:lang="cs">Databáze software</md:ServiceName>
            <md:ServiceDescription xml:lang="en">Software available for download.</md:ServiceDescription>
            <md:ServiceDescription xml:lang="cs">Seznam software ke stažení.</md:ServiceDescription>
            <md:RequestedAttribute FriendlyName="displayName" Name="urn:oid:1.3.6.1.4.1.5923.1.1.1.6" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" isRequired="true"/>
            <md:RequestedAttribute FriendlyName="eduPersonPrincipalName" Name="urn:oid:1.3.6.1.4.1.5923.1.1.1.6" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" isRequired="true"/>
            <md:RequestedAttribute FriendlyName="eduPersonScopedAffiliation" Name="urn:oid:1.3.6.1.4.1.5923.1.1.1.9" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" isRequired="true"/>
            <md:RequestedAttribute FriendlyName="eduPersonTargetedID" Name="urn:oid:1.3.6.1.4.1.5923.1.1.1.10" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" isRequired="true"/>
            <md:RequestedAttribute FriendlyName="givenName" Name="urn:oid:2.5.4.42" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" isRequired="true"/>
            <md:RequestedAttribute FriendlyName="mail" Name="urn:oid:0.9.2342.19200300.100.1.3" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" isRequired="true"/>
            <md:RequestedAttribute FriendlyName="sn" Name="urn:oid:2.5.4.4" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" isRequired="true"/>
        </md:AttributeConsumingService>

    </md:SPSSODescriptor>

    <md:Organization>
        <md:OrganizationName xml:lang="en">Example, a. l. e.</md:OrganizationName>
        <md:OrganizationName xml:lang="cs">Example, z. s. p. o.</md:OrganizationName>
        <md:OrganizationDisplayName xml:lang="en">Example</md:OrganizationDisplayName>
        <md:OrganizationDisplayName xml:lang="cs">Example</md:OrganizationDisplayName>
        <md:OrganizationURL xml:lang="en">https://www.example.org/en</md:OrganizationURL>
        <md:OrganizationURL xml:lang="cs">https://www.example.org/cs</md:OrganizationURL>
    </md:Organization>

    <md:ContactPerson contactType="technical">
        <md:GivenName>Kryštof</md:GivenName>
        <md:SurName>Šáteček</md:SurName>
        <md:EmailAddress>mailto:krystof.satecek@example.org</md:EmailAddress>
    </md:ContactPerson>

</md:EntityDescriptor>
</code>

----
====== Konfigurace IdP ======

Následující konfigurace (je vyžadován Shibboleth IdP 3.3.0+) je doporučený způsob uvolňování atributů poskytovatelům služeb z kategorie R&S.

Pravidla pro konfigurační soubor ''attribute-filter.xml'' uvolní R&S atributy všem poskytovatelům služeb z kategorie R&S. Všechny služby z kategorie R&S budou pomocí následujícího filtru tedy fungovat, pokud si vystačí s R&S atributy. **Toto je povinný způsob uvolňování atributů pro služby z kategorie R&S.**

<code xml>
<?xml version="1.0" encoding="UTF-8"?>

<AttributeFilterPolicyGroup id="ShibbolethFilterPolicy"
    xmlns="urn:mace:shibboleth:2.0:afp"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="urn:mace:shibboleth:2.0:afp http://shibboleth.net/schema/idp/shibboleth-afp.xsd">

    <!-- Research and Scholarship -->
    <AttributeFilterPolicy id="RS">
 
        <PolicyRequirementRule
            xsi:type="EntityAttributeExactMatch"
            attributeName="http://macedir.org/entity-category"
            attributeValue="http://refeds.org/category/research-and-scholarship" />
 
        <!-- displayName -->
        <AttributeRule attributeID="displayName">
            <PermitValueRule xsi:type="ANY"/>
        </AttributeRule>
 
        <!-- eduPersonPrincipalName -->
        <AttributeRule attributeID="eduPersonPrincipalName">
            <PermitValueRule xsi:type="ANY"/>
        </AttributeRule>
 
        <!-- eduPersonScopedAffiliation -->
        <AttributeRule attributeID="eduPersonScopedAffiliation">
            <PermitValueRule xsi:type="ANY"/>
        </AttributeRule>

        <!-- eduPersonTargetedID -->
        <AttributeRule attributeID="eduPersonTargetedID">
            <PermitValueRule xsi:type="ANY"/>
        </AttributeRule>
 
        <!-- givenName -->
        <AttributeRule attributeID="givenName">
            <PermitValueRule xsi:type="ANY"/>
        </AttributeRule>
 
        <!-- mail -->
        <AttributeRule attributeID="mail">
            <PermitValueRule xsi:type="ANY"/>
        </AttributeRule>
 
        <!-- sn -->
        <AttributeRule attributeID="sn">
            <PermitValueRule xsi:type="ANY"/>
        </AttributeRule>
   
    </AttributeFilterPolicy>

</AttributeFilterPolicyGroup>
</code>