Setup Sync via Microsoft Graph

La presente linea guida contiene le direttive e i parametri per l’invocazione da parte di Cyber Guru delle API MS-Graph del tenant Azure Active Directory del cliente.

Prerequisiti

Il tenant Azure Active directory del cliente deve essere nello stesso tenant del portale Azure
L’SSO deve essere stato configurato e testato
La app registrata per SSO deve essere autorizzata all’utilizzo delle rest API di MS-Graph
I seguenti attributi devono essere disponibili in lettura:
- givenName -> Il nome dell'utente;
- surname -> Il cognome dell'utente;
- mail -> L'indirizzo email dell'utente;
- userPrincipalName -> Lo user principal name (upn) dell’utente, è il campo che verrà mappato come username, e che l’utente usa anche per effettuare l’accesso tramite SSO, dovrà quindi avere il formato email, e potrà essere uguale o diverso dall’ indirizzo email dell’utente;
- officeLocation (optional) -> se presente andrà a valorizzare il campo department/team di awareness, se assente il campo team verrà valorizzato col team di default “Dummy”;

I passi da effettuare per la corretta esecuzione delle API sono stati rilevati dalla seguente guida Microsoft : https://learn.microsoft.com/en-us/graph/auth-v2-user?tabs=http

Per l’estrazione dei dati utente da Azure Active Directory viene utilizzata la rest API di MS-Graph:

https://graph.microsoft.com/v1.0/{resource}?[query_parameters]

Per il corretto utilizzo della api da parte della piattaforma Cyber Guru è necessario che il cliente fornisca i seguenti parametri :

Parameter	Condition	Description
tenant	Required	Il tenant della directory a cui vuoi richiedere l'autorizzazione. Il valore può essere in formato GUID o nome descrittivo.
client_id	Required	L'ID applicazione assegnato dal portale di registrazione delle app SSO di Azure al momento della registrazione dell'app.
scope	Required	Il valore passato per il parametro scope in questa richiesta deve essere l'identificatore (URI ID app) della risorsa desiderata, con suffisso .default. Ad esempio, l'URI dell'ID dell'app risorsa Microsoft Graph è https://graph.microsoft.com/. Per Microsoft Graph, il valore di scope è quindi https://graph.microsoft.com/.default . Questo valore indica all'endpoint della piattaforma Microsoft Identity di includere nel token di accesso tutte le autorizzazioni a livello di app a cui l'amministratore ha acconsentito.
client_secret	Required	Il segreto client che hai generato per la tua app nel portale di registrazione dell'app. Assicurati che sia codificato nell'URL.
grant_type	Required	Deve essere `client_credentials`.
Group ID	Required	E’ l’object ID del gruppo Azure Active Directory dichiarato nella app SSO

Il processo viene inizializzato mediante la chiamata alla login url del cliente, con cui viene richiesto un “Access Token” che autorizzerà le successive chiamate verso le API.

Nei prossimi capitoli segue la descrizione delle attività necessarie lato Cliente e lato Cyber Guru.

Attività Cliente

Garantire l’accesso alla piattaforma Azure Active Directory per l’utilizzo delle rest API di MS-Graph secondo i pre-requisiti espressi nei capitoli precedenti.

A solo titolo di esempio si riporta di seguito un esempio delle autorizzazioni necessarie da configurare nella app SSO affinché sia raggiungibile dalle api MS-Graph:

Fornire l’object id del gruppo dichiarato nella app SSO. A titolo di esempi viene riportato lo screen dove si può reperire l’informazione:

Attività Cyber Guru

Richiesta del token tramite :

POST https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token HTTP/1.1

Host: login.microsoftonline.com

Content-Type: application/x-www-form-urlencoded

client_id=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default

&client_secret=YYYYYYYYYYYYYYYYYYYY

&grant_type=client_credentials

Richiesta della lista utenti tramite :

GET https://graph.microsoft.com/v1.0/groups/{group object id}/members

Il risultato è la lista degli utenti appartenenti al gruppo:

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#directoryObjects",
    "value": [
        {
            "@odata.type": "#microsoft.graph.user",
            "id": "YYYYYYYYYYYYYYYYYYYYYYYYYY",
            "businessPhones": [],
            "displayName": "rossella",
            "givenName": "rossella",
            "jobTitle": null,
            "mail": null,
            "mobilePhone": null,
            "officeLocation": null,
            "preferredLanguage": null,
            "surname": "bianchi",
            "userPrincipalName": "rossella@XXXXXXXXXXXXXXX.onmicrosoft.com"
        },
        {
            "@odata.type": "#microsoft.graph.user",
            "id": " YYYYYYYYYYYYYYYYYYYYYYYYYY ",
            "businessPhones": [],
            "displayName": "giorgia",
            "givenName": "giorgia",
            "jobTitle": null,
            "mail": null,
            "mobilePhone": null,
            "officeLocation": null,
            "preferredLanguage": null,
            "surname": "verdi",
            "userPrincipalName": "giorgia@ XXXXXXXXXXXXXXX.onmicrosoft.com"
        },

A questo punto il plug-in di allineamento, all’interno della piattaforma, utilizzerà il file json ricevuto per allineare le utenze sulla piattaforma CGA.