======= Service Provider: HowTo Shibboleth =======

\\

====== Protocollo SAML2 ======

Le informazioni seguenti sono ad uso e consumo del referente tecnico che amministra il Service Provider Shibboleth

===== Informazioni =====

  * EntityID dell’IdP: https://shibidp.unipr.it/idp/shibboleth
  * Metadata dell‘IdP: https://shibidp.unipr.it/idp/shibboleth


  * L’elenco degli attributi veicolati attraverso le asserzioni SAML sono

    * **Per tutti gli entityID**
      * attributeID="transientId"
      * attributeID="eduPersonTargetedID"
      * attributeID="eduPersonAffiliation"
      * attributeID="eduPersonScopedAffiliation"\\

    * **Per gli entityID del tipo *.unipr.it**
      * attributeID="uniprID"
      * attributeID="uid"
      * attributeID="sn"
      * attributeID="givenName"
      * attributeID="mail"
      * attributeID="locality"
      * attributeID="server"
      * attributeID="principal"
      * attributeID="matricola"
      * attributeID="categoria"
      * attributeID="corsolaurea"
      * attributeID="uniprStudDip"
      * attributeID="codSISA"
      * attributeID="eduPersonPrimaryAffiliation"
      * attributeID="codicefiscale"
      * attributeID="uniprId"
      * attributeID="organizationalUnit"

Lato Service Provider configurare opportunamente l'attribute-map.xml per recepire gli attributi rilasciati:\\

  * transientID viene codificato lato Idp nel seguente modo: nameFormat="urn:oasis:names:tc:SAML:2.0:nameid-format:transient"
  * eduPersonTargetedID -> <Attribute name="urn:oid:1.3.6.1.4.1.5923.1.1.1.10" id="eduPersonTargetedID"/>
  * eduPersonAffiliation -> <Attribute name="urn:oid:1.3.6.1.4.1.5923.1.1.1.1" id="eduPersonAffiliation"/>
  * eduPersonScopedAffiliation -> <Attribute name="urn:oid:1.3.6.1.4.1.5923.1.1.1.9" id="eduPersonScopedAffiliation"/>
  * uniprID -> <Attribute name="urn:oid:1.3.6.1.4.14657.1.1.3.42" id="uniprID"/>
  * uid -> <Attribute name="urn:oid:0.9.2342.19200300.100.1.1" id="uid"/>
  * sn -> <Attribute name="urn:oid:2.5.4.4" id="sn"/>
  * givenName -> <Attribute name="urn:oid:2.5.4.42" id="givenName"/>
  * mail -> <Attribute name="urn:oid:0.9.2342.19200300.100.1.3" id="mail"/>
  * locality -> <Attribute name="urn:oid:2.5.4.7" id="locality"/>
  * server -> <Attribute name="urn:oid:1.3.6.1.4.14657.1.1.3.1" id="server"/>
  * principal viene codificato nel seguente modo lato IdP: nameFormat="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"
  * matricola -> <Attribute name="urn:oid:1.3.6.1.4.14657.1.1.3.5" id="matricola"/>
  * categoria -> <Attribute name="urn:oid:1.3.6.1.4.14657.1.1.3.31" id="categoria"/>
  * corsolaurea -> <Attribute name="urn:oid:1.3.6.1.4.14657.1.1.3.7" id="corsolaurea"/> 
  * uniprStudDip -> <Attribute name="urn:oid:1.3.6.1.4.14657.1.1.3.49" id="uniprStudDip"/>
  * codSISA -> <Attribute name="urn:oid:1.3.6.1.4.14657.1.1.3.16" id="codSISA"/>
  * eduPersonPrimaryAffiliation -> <Attribute name="urn:oid:1.3.6.1.4.1.5923.1.1.1.8" id="eduPersonPrimaryAffiliation"/>
  * codicefiscale -> <Attribute name="urn:oid:1.3.6.1.4.14657.1.1.3.30" id="codicefiscale"/>
  * uniprID -> <Attribute name="urn:oid:1.3.6.1.4.14657.1.1.3.42" id="uniprID"/>
  * organizationalUnit -> <Attribute name="urn:oid:2.5.4.11" id="organizationalUnit"/>

Per tutti gli entityID non riferiti al dominio unipr.it occorre concordare il rilascio degli attributi, che saranno filtrati e rilasciati in maniera puntuale da parte del nostro IdP.



===== Istruzioni =====

  - Caricare il Metadata dell'IdP, reperibile al paragrafo precedente
  - Comunicare all'Area Sistemi Informativi il metadata dell'SP via email:
    - destinatario email: sistemitecnologici.infrastrutture@unipr.it
    - il metadata può essere comunicato in uno dei seguenti modi:
      - inserendolo come allegato in formato compresso
      - indicando l'URL per il download nel corpo del messaggio
  - Nel caso di entityID non riferito a dominio unipr.it, richiedere gli attributi necessari da rilasciare al vostro SP.

  - Requisiti:
    - **Le asserzioni devono essere firmate e cifrate**, pertanto includere in linea nel Metadata del proprio SP i certificati per la firma e la crittografia.



===== Riferimenti =====

  * https://shibboleth.atlassian.net/wiki/spaces/SP3/overview?homepageId=2058387896


====== Protocollo OpenID Connect (OIDC) ======

OpenID Connect Issuer: https://shibidp.unipr.it

OIDC Discovery (come da specifiche [[https://openid.net/specs/openid-connect-discovery-1_0.html]]):\\
[[https://shibidp.unipr.it/.well-known/openid-configuration
]]

default scope: openid email profile

===== Registrazione relying party (RP) =====
Il gestore del RP deve fornire il Metadata in formato JSON:

^  Nome chiave    ^  Tipo del valore  ^  Descrizione                                           ^
| client_id       | string            | Identificatore OIDC client per l'RP                    |
| response_types  | array of strings  | Tipologia risposte del client (obbligatorio id_token)  |
| scope           | string            | Lista degli scope che rilasciano i claim               |
| redirect_uris   | array of strings  | URL di redirezione per la response verso RP            |

Esempio:

  {
    "redirect_uris":["httpq://www.esempio.it/secure/redirect_uri"],
    "client_id":"lamiapp01",
    "client_secret":"stringaalfanumericasegreta",
    "response_types":["id_token"],
    "grant_types":["authorization_code"],
    "scope": "openid email profile spid"
  }

^ scope    ^ claims - OP identifier                                                                                                             ^ claims - oidc names                                                                                                                ^ transcoder            ^
| openid   | subject                                                                                                                            | sub                                                                                                                                | OIDCStringTranscoder  |
| profile  | displayName, sn, givenName, codiceFiscale                                                                                          | name, family_name. given_name, codicefiscale                                                                                       | OIDCStringTranscoder  |
| spid     | unipr_spid_email, spidName, spidFamilyName, spidCode, spidFiscalNumber, externalIDPLoA, externalIDPType, spid_shib_authnctx_class  | unipr_spid_email, spidName, spidFamilyName, spidCode, spidFiscalNumber, externalIDPLoA, externalIDPType, spid_shib_authnctx_class  | OIDCStringTranscoder  |
| email    | mail                                                                                                                               | email                                                                                                                              | OIDCStringTranscoder  |


Esempio:
<code>
["OIDC_CLAIM_email"]=>
  string(25) "riccardo.cappone@unipr.it"
  ["OIDC_CLAIM_spid_shib_authnctx_class"]=>
  string(30) "https://www.spid.gov.it/SpidL2"
  ["OIDC_CLAIM_externalIDPLoA"]=>
  string(4) "LoA3"
  ["OIDC_CLAIM_family_name"]=>
  string(7) "CAPPONE"
  ["OIDC_CLAIM_iat"]=>
  string(10) "1709631164"
  ["OIDC_CLAIM_exp"]=>
  string(10) "1709634764"
  ["OIDC_CLAIM_name"]=>
  string(16) "Riccardo CAPPONE"
  ["OIDC_CLAIM_auth_time"]=>
  string(10) "1709631164"
  ["OIDC_CLAIM_spidName"]=>
  string(8) "RICCARDO"
  ["OIDC_CLAIM_spidFamilyName"]=>
  string(7) "CAPPONE"
  ["OIDC_CLAIM_codicefiscale"]=>
  string(16) "CPPRCR74P19Z112J"
  ["OIDC_CLAIM_eduPersonScopedAffiliation"]=>
  string(44) "member@unipr.it staff@unipr.it alum@unipr.it"
  ["OIDC_CLAIM_aud"]=>
  string(11) "sptestunipr"
  ["OIDC_CLAIM_sid"]=>
  string(33) "_2be7419256300bfc12ae5386638b8287"
  ["OIDC_CLAIM_spidFiscalNumber"]=>
  string(16) "CPPRCR74P19Z112J"
  ["OIDC_CLAIM_nonce"]=>
  string(43) "I3nOHwGpLWh2whVI-7LBsoPWhxAHo7PEW-VYUuc7GXw"
  ["OIDC_CLAIM_unipr_spid_email"]=>
  string(25) "riccardocappone@gmail.com"
  ["OIDC_CLAIM_given_name"]=>
  string(8) "Riccardo"
  ["OIDC_CLAIM_externalIDPType"]=>
  string(4) "spid"
  ["OIDC_CLAIM_spidCode"]=>
  string(14) "NAMI0007649168"
  ["OIDC_CLAIM_iss"]=>
  string(24) "https://shibidp.unipr.it"
  ["OIDC_CLAIM_sub"]=>
  string(32) "TYFP4PMTLC2VKCSGOCS7QEEPN2I2F4OU"
</code>
  
  
===== Flusso autorizzativo adottato dal nostro OP =====
response_type => id_token
  
In questa modalità è attivo solamente l'Authorization Endpoint che dopo l'autenticazione rilascerà l'ID Token comprensivo dei claim sottoscritti dagli scope. La durata dell'ID Token è 1h.


{{:guide_pubbliche:howto:identity:response_type_id_token.png?600|}}


====== Protocollo OpenID Connect (OIDC) via reverse proxy riservato a Relying Party UNIPR ======

<WRAP center round info 85%>
Il servizio di autenticazione basato su protocollo OIDC (OpenID Connect via OAuth2) servito via reverse proxy è riservato esclusivamente ai Relying Party UNIPR (su dominio unipr.it).
In vista della disattivazione del protocollo CAS, questo middleware semplifica notevolmente l'autenticazione presso il nostro Identity Provider, mettendo a disposizione dei service provider l'intera filiera di autenticazione 'a costo zero', senza cioè il bisogno da parte degli sviluppatori dei servizi web, di gestire il processo di autenticazione.
</WRAP>

===== Modalità di richiesta =====
Inviare una richiesta a helpdesk.informatico@unipr.it richiedendo che il proprio servizio web possa avvalersi del middleware di autenticazione OIDC mediato dal reverse proxy UNIPR.
Nella richiesta è opportuno indicare se l'intera risorsa debba essere protetta da autenticazione ("/"), oppure solo una o più location specifiche ("/secure", "/percorso/specifico/")

Quando la richiesta verrà accolta e lavorata, il sito web sarà automaticamente sottoposto ad autenticazione e protetto da certificato TLS.


===== Architettura =====

{{:guide_pubbliche:howto:identity:architettura_reverse_oidc3.png?600 |}}


===== Attributi disponibili post autenticazione =====

==== Autenticazione con credenziali di Ateneo ====
<code>
Headers disponibili

    [X-Remote-Sub] => TYFP4PMTLC2VKCSGOCS7QEEPN2I2F4OU
    [X-Remote-Familyname] => ROSSI
    [X-Remote-Givenname] => Mario
    [X-Remote-Externalidploa] => LoA2
    [X-Remote-Codicefiscale] => RSSMAR74P19Z112J
    [X-Remote-Name] => Mario ROSSI
    [X-Remote-Email] => mario.rossi@unipr.it
</code>
<code>
In php -> $_SERVER

["HTTP_X_REMOTE_SUB"]=>
  string(32) "TYFP4PMTLC2VKCSGOCS7QEEPN2I2F4OU"
  ["HTTP_X_REMOTE_FAMILYNAME"]=>
  string(7) "ROSSI"
  ["HTTP_X_REMOTE_GIVENNAME"]=>
  string(8) "Mario"
  ["HTTP_X_REMOTE_EXTERNALIDPLOA"]=>
  string(4) "LoA2"
  ["HTTP_X_REMOTE_CODICEFISCALE"]=>
  string(16) "RSSMAR74P19Z112J"
  ["HTTP_X_REMOTE_NAME"]=>
  string(16) "Mario ROSSI"
  ["HTTP_X_REMOTE_EMAIL"]=>
  string(25) "mario.rossi@unipr.it"
</code>

==== Autenticazione con SPID ====
<code>
Headers disponibili

    [X-Remote-Sub] => TYFP4PMTLC2VKCSGOCS7QEEPN2I2F4OU
    [X-Remote-Familyname] => ROSSI
    [X-Remote-Givenname] => Mario
    [X-Remote-Externalidptype] => spid
    [X-Remote-Externalidploa] => LoA3
    [X-Remote-Codicefiscale] => RSSMAR74P19Z112J
    [X-Remote-Name] => Mario ROSSI
    [X-Remote-Email] => mario.rossi@unipr.it
</code>
<code>
In php -> $_SERVER

["HTTP_X_REMOTE_SUB"]=>
  string(32) "TYFP4PMTLC2VKCSGOCS7QEEPN2I2F4OU"
  ["HTTP_X_REMOTE_FAMILYNAME"]=>
  string(7) "ROSSI"
  ["HTTP_X_REMOTE_GIVENNAME"]=>
  string(8) "Mario"
  ["HTTP_X_REMOTE_EXTERNALIDPTYPE"]=>
  string(4) "spid"
  ["HTTP_X_REMOTE_EXTERNALIDPLOA"]=>
  string(4) "LoA3"
  ["HTTP_X_REMOTE_CODICEFISCALE"]=>
  string(16) "RSSMAR74P19Z112J"
  ["HTTP_X_REMOTE_NAME"]=>
  string(16) "Mario ROSSI"
  ["HTTP_X_REMOTE_EMAIL"]=>
  string(25) "mario.rossi@unipr.itt"
</code>