Controllo dell'accesso

Con IBM Cloud® App ID è possibile definire quali utenti e applicazioni possono accedere a determinate funzioni o eseguire determinate azioni nelle applicazioni. Per controllare l'accesso, puoi creare degli ambiti e raggrupparli in un ruolo. Quindi, assegnare il ruolo a uno o più utenti e applicazioni dell'app.

Un ambito è un'azione di runtime nella tua applicazione che registri con App ID per creare un'autorizzazione di accesso. Un ruolo è un insieme di ambiti che assegna autorizzazioni diverse a diversi tipi di utenti e applicazioni. Ad esempio, se la tua azienda assume degli sviluppatori, si potrebbe creare un ruolo che consenta loro di leggere e scrivere sul codice. Se assumi dei revisori, potresti avere un ruolo di sola visualizzazione, come mostrato nella seguente immagine.

Diagramma che mostra il flusso di lavoro del controllo degli accessi di App ID in quattro fasi: registrazione delle azioni di runtime come ambiti, compilazione degli ambiti in ruoli, assegnazione dei ruoli agli utenti o alle applicazioni e verifica degli ambiti nei token di accesso a runtime — Come funziona il controllo degli accessi di App ID

Registra le azioni di runtime che possono verificarsi nella tua applicazione con App ID.
Compila gli ambiti in gruppi per formare i ruoli.
Controllate le autorizzazioni di accesso assegnando ruoli agli utenti o alle applicazioni.
Configurare l'applicazione per verificare gli ambiti restituiti nel token di accesso degli utenti in fase di esecuzione (o nel token delle applicazioni se il flusso delle credenziali del client).

Per ulteriori informazioni sulle applicazioni, vedi Identità e autorizzazione dell'applicazione.

Prima di iniziare

Devi avere un'applicazione.
Assicuratevi di aver compreso l'impatto che ogni tipo di ruolo e ambito può avere sulla vostra candidatura. Poiché stai concedendo l'accesso, vuoi essere sicuro di concederlo solo alle persone che ne hanno bisogno.
Tieni presente i limiti stabiliti esistenti.

Creazione di ambiti nella console

Un ambito è un'azione di runtime nella tua applicazione che può essere eseguita dagli utenti a cui sono state concesse le autorizzazioni necessarie per completarla. Gli ambiti vengono creati quando registri la tua applicazione con App ID. Se la tua applicazione è già registrata, puoi modificarla per includere gli ambiti.

I valori dei nomi di ambito devono soddisfare i seguenti requisiti:

Essere alfanumerici
Essere in minuscolo
Non iniziare con appid o openid
Non contenere caratteri speciali diversi da punti (.) o caratteri di sottolineatura (_)
Contenere meno di 50 caratteri.

Per creare un ambito, è possibile utilizzare la UI App ID.

Vai alla scheda Applications del dashboard App ID.
Fai clic su Add application per aprire la schermata di configurazione. Se disponi già di credenziali che desideri utilizzare, fai clic su Edit dal menu Actions nella riga che vuoi aggiornare.
Fornisci un nome alla tua applicazione e seleziona il tipo di applicazione di cui disponi.
Inserire un valore per l'ambito personalizzato e fare clic sul simbolo più (+). Un valore di ambito di esempio potrebbe essere read o write.
Ripetere il passaggio precedente fino ad aggiungere tutti gli ambiti all'applicazione.
Fare clic su Salva.

Creazione di ambiti con l'API

I valori dei nomi di ambito devono soddisfare i seguenti requisiti:

Essere alfanumerici
Essere in minuscolo
Non iniziare con appid o openid
Non contenere caratteri speciali diversi da punti (.) o caratteri di sottolineatura (_)
Contenere meno di 50 caratteri.

Per creare un ambito, è possibile utilizzare la UI App ID.

Crea gli ambiti effettuando la seguente richiesta all'endpoint /scopes.

curl -X PUT "https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/applications/<clientID>/scopes"
-H "accept: application/json"
-H "Content-Type: application/json"
-d "{\ "scopes":\ [\ <scopesObject>}" ]}"

Variabile	Descrizione
`region`	La regione in cui viene eseguito il provisioning della tua istanza di App ID. Ulteriori informazioni sulle regioni disponibili.
`tenantID`	L'identificativo univoco per la tua istanza di App ID. Questo valore si trova nelle credenziali della vostra applicazione, elencate nella scheda Applicazioni della dashboard del servizio.
`clientID`	L'identificativo univoco per la tua applicazione. Questo valore si trova nelle credenziali della vostra applicazione, elencate nelle vostre Applicazioni nella dashboard del servizio.
`scopesObject`	Un oggetto JSON con tutti gli ambiti che si desidera creare per l'applicazione.
{: caption="Variabili necessarie per chiamare l'`/scopes` endpoint" caption-side="top"}

Facoltativo: conferma che gli ambiti siano stati creati.

curl -X GET "https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/applications/<clientID>/scopes"
-H "accept: application/json"
-H "Content-Type: application/json"

Creazione di ruoli nella console

Un ruolo è un gruppo di ambiti che si applicano allo stesso tipo di utente. Ad esempio, se crei un ruolo di amministratore, la sezione degli ambiti potrebbe consentire a quel ruolo di eseguire azioni di lettura, scrittura o creazione. Ma, se si crea un altro ruolo che si chiama viewer, gli utenti che vengono assegnati quel ruolo hanno letto solo l'accesso. Per creare un ruolo, è possibile utilizzare la UI App ID.

Vai a Profiles and roles > Roles nel dashboard App ID.
Fai clic su Create role per aprire la schermata di configurazione.
Fornisci un nome e una descrizione per il ruolo.
Utilizzando gli ambiti che hai creato nella sezione precedente, assegna gli ambiti a un ruolo utilizzando il seguente formato. Fai clic su + per aggiungere l'ambito.
```
<appName>/<scope>
```
Se hai una sola applicazione, non è necessario specificarne il nome. Puoi aggiungere soltanto l'ambito.
Ripeti il passo precedente per aggiungere più ambiti.
Fare clic su Salva.

Creazione di ruoli con l'API

Un ruolo è un gruppo di ambiti che si applicano allo stesso tipo di utente. Ad esempio, se crei un ruolo di amministratore, la sezione degli ambiti potrebbe consentire a quel ruolo di eseguire azioni di lettura, scrittura o creazione. Ma, se si crea un altro ruolo che si chiama viewer, gli utenti che vengono assegnati quel ruolo avrebbero letto solo l'accesso. Per creare un ruolo, è possibile utilizzare le API App ID.

Fare una richiesta all'endpoint /roles per creare il ruolo.

curl -X POST "https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/roles"
-H "accept: application/json"
-H "Content-Type: application/json"
-d { \"name\": \"<roleName>\", \"description\": \"<roleDescription>\", \"access\": [ { \"application_id\": \"<applicationID>\", \"scopes\": [ \"<scopes>" ] } ]}"

Variabile	Descrizione
`region`	La regione in cui viene eseguito il provisioning della tua istanza di App ID. Ulteriori informazioni sulle regioni disponibili.
`tenantID`	L'identificativo univoco per la tua istanza di App ID. Questo valore si trova nelle credenziali della vostra applicazione, elencate nella scheda Applicazioni della dashboard del servizio.
`clientID`	L'identificativo univoco per la tua applicazione. Questo valore si trova nelle credenziali dell'applicazione, elencate in Applicazioni.
`roleName`	Il nome che vuoi assegnare al ruolo.
`roleDescription`	Una breve frase che descrive le azioni destinate al tuo ruolo.
`applicationID`	L'identificativo univoco per la tua applicazione. Questo valore si trova nelle credenziali dell'applicazione, elencate in Applicazioni.
`scopes`	Un oggetto JSON con tutti gli ambiti che si desidera applicare a un ruolo.
{: caption="Variabili necessarie per chiamare l'`/scopes` endpoint" caption-side="top"}

Facoltativo: conferma che i ruoli siano stati creati.

curl -X GET "https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/roles -H "accept: application/json"

La risposta è simile al seguente esempio:

{
   "roles": [
   {
      "id": "12345678-1234-1234-1234-123456789012",
      "name": "admin",
      "description": "Can perform administrative tasks.",
      "access": [
         {
         "application_id": "de33d272-f8a7-4406-8fe8-ab28fd457be5",
         "scopes": [
            "create",
            "update",
            "write",
            "read"
         ]
         }
      ]
   }
   {
      "id": "123454231-1234-1234-3334-12345687012",
      "name": "developer",
      "description": "Can perform administrative tasks.",
      "access": [
         {
         "application_id": "de33d272-f8a7-4406-8fe8-ab28fd457be5",
         "scopes": [
            "write",
            "read"
         ]
         }
      ]
   }
   ]
}

Assegnazione di ruoli agli utenti nella console

Dopo aver creato i ruoli, puoi assegnarli al profilo dell'utente. Puoi anche assegnare i ruoli quando crei un utente futuro.

Vai a Profiles and roles > User profiles nel tuo dashboard App ID.
Dal menu Actions nella riga dell'utente specifico a cui stai assegnando un ruolo, fai clic su Assign role.
Seleziona uno o più ruoli che vuoi aggiungere dall'elenco dei ruoli disponibili.
Facoltativo: se non vedi il ruolo che stai cercando, fai clic su Create role e fornisci le informazioni per aggiungere un'altra opzione.
Fare clic su Salva.

Assegnazione dei ruoli agli utenti con le API

Dopo aver creato i ruoli, puoi assegnarli al profilo dell'utente. Puoi anche assegnare i ruoli quando crei un utente futuro.

Ottieni il tuo ID utente cercando gli utenti App ID con una query di identificazione, come ad esempio un indirizzo email.

curl -X GET "https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/Users?query=<identifyingSearchQuery>" \
-H "accept: application/json" \
-H "authorization: Bearer <token>"

Esempio:

curl -X GET https://us-south.appid.cloud.ibm.com/management/v4/e19a2778-3262-4986-8875-8khjafsdkhjsdafkjh/cloud_directory/Users?query=example@domain.com
-H "accept: application/json"
-H "authorization: Bearer eyJraWQiOiIyMDE3MTEyOSIsImFsZ...."

Facoltativo: ottieni l'ID e il nome del ruolo. Se già conosci il tuo ID o nome del ruolo, vai al passo successivo.

curl -X GET "https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/roles" \
-H "accept: application/json" \
-H "authorization: Bearer <token>"

Effettua una richiesta all'endpoint /roles che contenga un oggetto JSON dei ruoli che vuoi assegnare.

curl -X PUT "https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/users/<userID>/roles"
-H "accept: application/json"
-H "Content-Type: application/json"
-d "{ \"roles\": { \"ids\": [ \"<roleIDs>\" ] }}"
-H "authorization: Bearer <token>"

Per rimuovere un ruolo da un utente, effettua di nuovo la richiesta PUT, ma rimuovi l'ID ruolo.

Aggiunta di ruoli utente ai token

Per impostazione predefinita, i ruoli non vengono restituiti in un token degli utenti. Ti consigliamo di configurare le tue decisioni di runtime in base agli ambiti. Se però vuoi utilizzare i ruoli, puoi associarli ai tuoi token utilizzando la tua associazione delle attestazioni personalizzate.

Quando si autentica, assicurarsi di utilizzare username : client ID e password : secret per l'applicazione e l'utente che ha configurato i controlli per.

Assegnazione dei ruoli ad un'applicazione

Dopo aver creato ruoli, è possibile assegnarli alle proprie applicazioni utilizzando le API App ID.

I ruoli applicativi sono validi solo nel flusso delle credenziali del client.

Ottenere il tuo ID client di applicazione interrogando l'elenco delle applicazioni. È inoltre possibile ottenere questo valore dalla scheda Applicazioni del App ID UI.

curl -X GET "https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/applications" \
-H "accept: application/json" \
-H "authorization: Bearer <token>"

Esempio:

curl -X GET https://us-south.appid.cloud.ibm.com/management/v4/e19a2778-3262-4986-8875-8khjafsdkhjsdafkjh/applications
-H "accept: application/json"
-H "authorization: Bearer eyJraWQiOiIyMDE3MTEyOSIsImFsZ...."

Ottenere il ruolo ID.

curl -X GET "https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/roles" \
-H "accept: application/json" \
-H "authorization: Bearer <token>"

Effettua una richiesta all'endpoint /roles che contenga un oggetto JSON dei ruoli che vuoi assegnare. Questa richiesta sostituisce i ruoli correnti con gli ID ruolo forniti. Assicurati di assegnare i ruoli corretti.

curl -X PUT "https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/applications/<clientID>/roles"
-H "accept: application/json"
-H "Content-Type: application/json"
-d "{ \"roles\": { \"ids\": [ \"<roleIDs>\" ] }}"
-H "authorization: Bearer <token>"

Per rimuovere un ruolo da un utente, effettua di nuovo la richiesta PUT, ma rimuovi l'ID ruolo.

Controllo dell'accesso in fase di esecuzione

Quando un utente o un'applicazione tenta di accedere a una delle risorse protette, i token vengono creati e restituiti da App ID. Gli ambiti assegnati a un utente o a un'applicazione vengono restituiti nel token di accesso. È possibile utilizzare il token di accesso per prendere decisioni in fase di esecuzione. A seconda della strategia utilizzata per proteggere le applicazioni, le modalità di verifica degli ambiti possono variare.

Quando utilizzi la strategia dell'applicazione web

Puoi utilizzare la strategia dell'applicazione web per verificare se una richiesta contiene degli ambiti utilizzando il metodo hasScope. Quando un utente con un ruolo assegnato accede, gli viene concesso l'accesso tramite un token App ID che contiene tutti gli ambiti definiti nel ruolo.Ad esempio, se stai lavorando con l'SDK Node.js, il tuo frammento di codice sarà simile al seguente:

app.get("/protected", passport.authenticate(WebAppStrategy.STRATEGY_NAME), function(req, res){
    if(WebAppStrategy.hasScope(req, "read write")){
              res.json(req.user);
    }
    else {
        res.send("insufficient scopes");
    }
});

Quando utilizzi la strategia API

Puoi definire gli ambiti richiesti per accedere a un endpoint specifico aggiungendo una variabile di ambito al tuo codice della strategia API. Ad esempio, se hai un'applicazione scritta in Node.js e stai lavorando con l'SDK Node.js, il tuo frammento di codice potrebbe essere simile al seguente.

app.get("/api/protected",
        passport.authenticate(APIStrategy.STRATEGY_NAME, {
                audience: "myApp",
                scope: "read write update"
        }),
        function(req, res) {
                res.send("Hello from protected resource");
        }
);

Comprendere le variabili utilizzate con la strategia API
Variabile	Descrizione
`scope`	Gli ambiti richiesti, che sono separati da uno spazio.
`audience`	L'ID client dell'applicazione.

Rimozione dell'accesso

Puoi eliminare qualsiasi ambito o ruolo non più necessario.

Eliminazione degli ambiti nella console

Se non hai più bisogno di un ambito, puoi eliminarlo utilizzando la UI App ID.

Quando si elimina un ambito, questo viene rimosso da tutti i ruoli a cui è associato.

Puoi utilizzare il dashboard del servizio App ID per eliminare gli ambiti.

Vai alla scheda Applications del dashboard App ID.
Dal menu Actions nella riga dell'applicazione per la quale vuoi modificare gli ambiti, fai clic su Edit.
Fai clic sulla X nella casella relativa all'ambito che vuoi rimuovere.
Fare clic su Salva.

Eliminazione degli ambiti con l'API

Se non hai più bisogno di un ambito, puoi eliminarlo utilizzando la API App ID. Per eliminare un ambito, rimuoverlo dall'oggetto JSON e fare una nuova richiesta PUT all'endpoint /scopes.

Quando si elimina un ambito, questo viene rimosso da tutti i ruoli a cui è associato.

Modifica o elimina un ambito effettuando la seguente richiesta all'endpoint /scopes. Assicurati di aggiornare l'oggetto JSON degli ambiti in modo che contenga solo gli ambiti che desideri consentire.

curl -X PUT "https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/applications/<clientID>/scopes"
-H "accept: application/json"
-H "Content-Type: application/json"
-d "{\ "scopes":\ [\ <scopesObject>" ]}"

Eliminazione dei ruoli nella console

Se non hai più bisogno di un ruolo specifico, puoi eliminarlo utilizzando la UI App ID.

L'eliminazione di un ruolo rimuove l'accesso a tutti gli utenti e alle applicazioni che attualmente lo utilizzano.

Vai a Profiles and roles > Roles nel dashboard del servizio.
Nella riga relativa al ruolo che vuoi eliminare, seleziona Delete dal menu Actions.
Conferma di aver compreso che l'eliminazione del ruolo influisce su tutti gli utenti e le applicazioni che lo stanno attualmente utilizzando.
Fai clic su Delete.

Eliminazione dei ruoli con l'API

Se non hai più bisogno di un ruolo specifico, puoi eliminarlo utilizzando le API App ID.

L'eliminazione di un ruolo rimuove l'accesso a tutti gli utenti e alle applicazioni che attualmente lo utilizzano.

Ottieni l'ID e il nome del ruolo. Se già conosci il tuo ID o nome del ruolo, vai al passo successivo.

curl -X GET "https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/roles"
-H "accept: application/json"

Effettua una richiesta all'endpoint /roles che contenga un oggetto JSON dei ruoli che vuoi assegnare.

curl -X DELETE "https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/roles/<roleID>"
-H "accept: application/json"