Web Service di Identity Management

Esse3 espone un Web Service SOAP, denominato IDMUserService, pensato per l’integrazione con il sistema di Identity Management di ateneo.

In particolare tale Web Service mette a disposizione le operazioni descritte nella tabella seguente.

Operazione	Parametri di input	Descrizione
trovaUtenza	codiceFiscale tipoUtenza	Ricerca e ritorna, se presente, l’utenza Esse3 del tipo indicato per il codice fiscale richiesto. Il tipo di utenza può essere: - STU (studente) - DOC (docente) - SOG (soggetto esterno). Entrambi i parametri di input sono obbligatori, viene ritornata sempre al più una sola utenza: in presenza di più utenze del medesimo tipo per lo stesso codice fiscale viene presa l’unica abilitata (o, se non presente, la più recente).
trovaUtenze	codiceFiscale tipoUtenza	Ricerca simile alla precedente, con la differenza che vengono ritornate tutte le utenze definite in Esse3 per il codice fiscale richiesto (del tipo eventualmente indicato), sia abilitate che non. Il parametro di input tipoUtenza è facoltativo.
cambiaUserName	codiceFiscale tipoUtenza userName	Cambia il nome account (UserName) in uso in Esse3 per l’utenza individuata dal codice fiscale ed il tipo indicati (disabilitando l’account esistente e creandone uno nuovo copia del vecchio a meno dello UserName). Tutti i parametri di input sono obbligatori.
assegnaEmail	codiceFiscale tipoUtenza email	Imposta l’indirizzo email di anagrafica per l’utenza Esse3 individuata dal codice fiscale ed il tipo indicati. In particolare nel caso di studente (tipoUtenza = ‘STU’) si tratta dell’indirizzo email di ateneo. Tutti i parametri di input sono obbligatori.

Si allega qui di seguito, a titolo esemplificativo, il WSDL del servizio.

IDMUserService.wsdl

1.1 Accesso al Web Service

Il Web Service è esposto al seguente URL:

https://unipg.esse3.cineca.it/services/IDMUserService

L’accesso è protetto tramite WS-Security, ovvero per invocare le varie operazioni è necessario passare un apposito token (che segue lo standard WS-Security Username Token).

Gli estremi di tale token (username e password) sono configurabili su Esse3 e vanno quindi concordati in fase di avviamento.

1.2 Informazioni ritornate

In risposta a tutte le operazioni descritte in precedenza il Web Service ritorna una serie di dati riconducibili sempre alla medesima struttura, descritta nella tabella seguente.

Campo	Descrizione
success	Indica se l’operazione richiesta ha avuto successo (true) oppure no (false).
message	Messaggio descrittivo che fornisce maggiori indicazioni sull’esito dell’operazione richiesta.
data	Contiene i dati della/e utenza/e oggetto dell’operazione richiesta. Nel caso di interrogazione (operazioni trovaUtenza e trovaUtenze) conterrà i dati della/e utenza/e reperita/e. Nel caso di cambio dello UserName o assegnazione dell’indirizzo email (operazioni cambiaUserName e cambiaUserName) conterrà i dati dell’utenza come risulta dopo avere eseguito l’operazione richiesta, nel caso questa sia terminata con successo.

I dati di ogni singola utenza che vengono ritornati (precedente campo data) sono descritti nella tabella seguente.

Campo	Descrizione
id	Identificativo univoco dell’utenza su Esse3
userName	UserName dell’utenza su Esse3 (univoco)
tipoUtente	Tipo di utenza: - STU (studente) - DOC (docente) - SOG (soggetto esterno)
codiceFiscale	Codice fiscale
nome	Nome
cognome	Cognome
email	Indirizzo email
idAnag	Identificativo di anagrafica (univoco a parità di tipo utenza)
utenzaAbilitata	Indica se l’utenza è abilitata (true) oppure no (false)

1.3 Esempio di richiesta e risposta

Riportiamo qui di seguito un esempio di invocazione del Web Service, nello specifico per l’operazione trovaUtenza.

La richiesta sarà del tipo:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:idm="http://IdentityManagement.integrazioni.esse3.kion.it">
   <soapenv:Body>
      <idm:trovaUtenza>
         <idm:codiceFiscale>RSSMRA83B01H501W</idm:codiceFiscale>
         <idm:tipoUtenza>STU</idm:tipoUtenza>
      </idm:trovaUtenza>
</soapenv:Body>
</soapenv:Envelope>

Nel caso in cui esista un’utenza per il codice fiscale ed il tipo indicato si otterrà una risposta del tipo:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Body>
      <idm:trovaUtenzaResponse xmlns:idm="http://IdentityManagement.integrazioni.esse3.kion.it">
         <idm:return type="it.kion.esse3.integrazioni.IdentityManagement.IDMUserResult1">
            <idm:data type="it.kion.esse3.integrazioni.IdentityManagement.IDMUserData">
               <idm:codiceFiscale>RSSMRA83B01H501W</idm:codiceFiscale>
               <idm:cognome>ROSSI</idm:cognome>
               <idm:email>m.rossi@studenti.unipg.it</idm:email>
               <idm:id>376761</idm:id>
               <idm:idAnag>91855</idm:idAnag>
               <idm:nome>MARIO</idm:nome>
               <idm:tipoUtente>STU</idm:tipoUtente>
               <idm:userName>m.rossi</idm:userName>
               <idm:utenzaAbilitata>true</idm:utenzaAbilitata>
            </idm:data>
            <idm:message>Trovata una utenza</idm:message>
            <idm:success>true</idm:success>
         </idm:return>
      </idm:trovaUtenzaResponse>
   </soapenv:Body>
</soapenv:Envelope>

Nel caso in cui non esista alcuna utenza per il codice fiscale ed il tipo indicato si otterrà una risposta del tipo:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Body>
      <idm:trovaUtenzaResponse xmlns:idm="http://IdentityManagement.integrazioni.esse3.kion.it">
         <idm:return type="it.kion.esse3.integrazioni.IdentityManagement.IDMUserResult1">
            <idm:data xsi:nil="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
            <idm:message>Nessun dato trovato</idm:message>
            <idm:success>false</idm:success>
         </idm:return>
      </idm:trovaUtenzaResponse>
   </soapenv:Body>
</soapenv:Envelope>

Space shortcuts

Page tree

1.1 Accesso al Web Service

1.2 Informazioni ritornate

1.3 Esempio di richiesta e risposta