Contrôle de l'accès

Avec IBM Cloud® App ID, vous pouvez définir quels utilisateurs et applications peuvent accéder à des fonctions spécifiques ou exécuter des actions spécifiques dans vos applications. Pour contrôler l'accès, vous pouvez créer des portées et les regrouper pour former un rôle. Vous pouvez ensuite affecter ce rôle à un ou plusieurs utilisateurs de votre application et applications.

Une portée (scope) est une action d'exécution dans votre application que vous enregistrez avec App ID pour créer un droit d'accès. Un rôle est une collection de portées qui affectent différents droits à différents types d'utilisateurs d'application et applications. Par exemple, si votre entreprise emploie des développeurs, elle peut créer un rôle (Développeur) qui les autorise à effectuer des opérations de lecture (read) et écriture (write) dans le code. Si vous employez des auditeurs, vous pouvez disposer d'un rôle d'affichage uniquement (Afficheur) comme illustré dans l'image suivante.

Diagramme montrant le flux de travail du contrôle d'accès App ID en quatre étapes : enregistrement des actions d'exécution en tant que champs d'application, compilation des champs d'application en rôles, attribution de rôles aux utilisateurs ou aux applications et vérification des champs d'application dans les jetons d'accès au moment de l'exécution. — Fonctionnement du contrôle d'accès App ID

Enregistrez des actions d'exécution pouvant se produire dans votre application avec App ID.
Compilez les portées en groupes pour former des rôles.
Contrôlez les droits d'accès en affectant des rôles à vos utilisateurs ou applications.
Configurez votre application pour vérifier les portées qui sont renvoyées dans votre jeton d'accès aux utilisateurs lors de l'exécution (ou dans votre jeton d'application si le flux de données d'identification du client).

Pour plus d'informations sur les applications, voir Identité et autorisation de l'application.

Avant de commencer

Vous devez disposer d'une application.
Assurez-vous de bien comprendre comment chaque type de rôle et de portée peut avoir un impact sur votre application. Comme c'est vous qui octroyez l'accès, vous devez être sûr que seules les personnes qui en ont besoin en bénéficient.
Soyez conscient des limites en vigueur.

Création de champs d'application dans la console

Une portée est une action d'exécution définie dans votre application qui peut être effectuée par les utilisateurs disposant des droits requis. Les portées sont créées lors de l'enregistrement de votre application avec App ID. Si votre application est déjà enregistrée, vous pouvez l'éditer pour y ajouter des portées.

Les valeurs des noms de portée doivent répondre aux exigences suivantes :

être alphanumérique
être en minuscules
ne pas commencer par appid ou openid
ne pas contenir de caractères spéciaux sauf des points (.) ou des traits de soulignement (_)
comporter moins de 50 caractères.

Pour créer une portée, vous pouvez utiliser l'interface utilisateur d'App ID.

Accédez à Applications dans le tableau de bord App ID.
Cliquez sur Ajouter une application pour ouvrir l'écran de configuration. Si vous disposez déjà des données d'identification que vous souhaitez utiliser, cliquez sur Editer dans le menu Actions sur la ligne que vous voulez mettre à jour.
Attribuez un nom à votre application et sélectionnez le type d'application dont vous disposez.
Entrez une valeur pour votre portée personnalisée et cliquez sur le symbole plus (+). Un exemple de valeur de portée peut être read ou write.
Répétez l'étape précédente jusqu'à ce que vous avez fini d'ajouter toutes vos portées à l'application.
Cliquez sur Sauvegarder.

Création de portées avec l'API

Les valeurs des noms de portée doivent répondre aux exigences suivantes :

être alphanumérique
être en minuscules
ne pas commencer par appid ou openid
ne pas contenir de caractères spéciaux sauf des points (.) ou des traits de soulignement (_)
comporter moins de 50 caractères.

Pour créer une portée, vous pouvez utiliser l'interface utilisateur d'App ID.

Créez les portées en envoyant la demande suivante au noeud final /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>}" ]}"

Variable	Description
`region`	Région dans laquelle votre instance App ID est mise à disposition. Reportez-vous à cette section sur les régions disponibles.
`tenantID`	Identificateur unique de votre instance App ID. Vous pouvez trouver cette valeur dans les données d'identification de votre application car celles-ci figurent dans l'onglet Applications du tableau de bord du service.
`clientID`	Identificateur unique de votre application. Vous pouvez trouver cette valeur dans les données d'identification de votre application car celles-ci figurent dans Applications sur le tableau de bord du service.
`scopesObject`	Objet JSON de toutes les portées que vous souhaitez créer pour votre application.
{ : caption="Variables requises pour appeler le point de terminaison `/scopes` " caption-side="top"}

Facultatif : vérifiez que les portées ont bien été créées.

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

Création de rôles dans la console

Un rôle est un groupe de portées qui s'appliquent au même type d'utilisateur. Par exemple, si vous créez un rôle d'administrateur, la section Portées peut autoriser ce rôle à exécuter des actions de lecture (read), d'écriture (write) ou de création (create). Toutefois, si vous créez un autre rôle appelé viewer, les utilisateurs qui sont affectés à ce rôle ont un accès en lecture seule. Pour créer un rôle, vous pouvez utiliser l'interface utilisateur d'App ID UI.

Accédez à Profils et rôles > Rôles dans le tableau de bord App ID.
Cliquez sur Créer un rôle pour ouvrir l'écran de configuration.
Attribuez au rôle un nom et une description.
En vous servant des portées que vous avez créées à la section précédente, affectez les portées à un rôle en utilisant le format suivant. Cliquez sur le signe plus (+) pour ajouter la portée.
```
<appName>/<scope>
```
Si vous n'avez qu'une seule application, vous n'avez pas besoin d'indiquer le nom de votre application (app_name). Vous pouvez ajouter la portée toute seule.
Répétez l'étape précédente pour ajouter d'autres portées.
Cliquez sur Sauvegarder.

Création de rôles avec l'API

Un rôle est un groupe de portées qui s'appliquent au même type d'utilisateur. Par exemple, si vous créez un rôle d'administrateur, la section Portées peut autoriser ce rôle à exécuter des actions de lecture (read), d'écriture (write) ou de création (create). Toutefois, si vous créez un autre rôle appelé viewer, les utilisateurs qui sont affectés à ce rôle n'ont accès qu'à un accès en lecture seule. Pour créer un rôle, vous pouvez utiliser les API d'App ID.

Envoyez une demande au noeud final /roles pour créer le rôle.

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>" ] } ]}"

Variable	Description
`region`	Région dans laquelle votre instance App ID est mise à disposition. Reportez-vous à cette section sur les régions disponibles.
`tenantID`	Identificateur unique de votre instance App ID. Vous pouvez trouver cette valeur dans les données d'identification de votre application car celles-ci figurent dans l'onglet Applications du tableau de bord du service.
`clientID`	Identificateur unique de votre application. Vous pouvez trouver cette valeur dans les données d'identification de votre application car celles-ci figurent dans Applications.
`roleName`	Nom que vous souhaitez attribuer à votre rôle.
`roleDescription`	Courte phrase qui présente ce que votre rôle est censé faire.
`applicationID`	Identificateur unique de votre application. Vous pouvez trouver cette valeur dans les données d'identification de votre application car celles-ci figurent dans Applications.
`scopes`	Un objet JSON de toutes les portées que vous souhaitez appliquer à un rôle.
{ : caption="Variables requises pour appeler le point de terminaison `/scopes` " caption-side="top"}

Facultatif : vérifiez que les rôles ont bien été créés.

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

La réponse est similaire à l'exemple suivant :

{
   "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"
         ]
         }
      ]
   }
   ]
}

Attribution de rôles aux utilisateurs dans la console

Après avoir créé des rôles, vous pouvez les attribuer au profil de votre utilisateur. Vous pouvez également affecter des rôles lorsque vous créez un futur utilisateur.

Accédez à Profils et rôles > Profils d'utilisateur dans le tableau de bord de votre service App ID.
Dans le menu Actions sur la ligne correspondant à l'utilisateur spécifique auquel vous affectez un rôle, cliquez sur Affecter un rôle.
Sélectionnez le ou les rôles que vous souhaitez ajouter dans la liste des rôles disponibles.
Facultatif : si vous ne voyez pas le rôle que vous recherchez, cliquez sur Créer un rôle et fournissez les informations pour ajouter une autre option.
Cliquez sur Sauvegarder.

Affectation de rôles aux utilisateurs avec l'API

Après avoir créé des rôles, vous pouvez les attribuer au profil de votre utilisateur. Vous pouvez également affecter des rôles lorsque vous créez un futur utilisateur.

Pour obtenir votre ID utilisateur, effectuez une recherche dans la liste de vos utilisateurs App ID avec une requête d'identification, telle qu'une adresse e-mail.

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

Exemple :

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...."

Facultatif : obtenez l'ID ou le nom du rôle. Si vous connaissez déjà l'ID ou le nom de votre rôle, passez à l'étape suivante.

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

Envoyez une demande au noeud final /roles contenant un objet JSON avec les rôles que vous souhaitez affecter.

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>"

Pour supprimer un rôle à un utilisateur, envoyez à nouveau la demande PUT, mais en retirant l'ID du rôle.

Ajout de rôles utilisateur dans les jetons

Par défaut, les rôles ne sont pas renvoyés dans un jeton utilisateur. Il est recommandé de configurer vos décisions d'exécution en fonction des portées. Cependant, si vous souhaitez utiliser des rôles, vous pouvez les mapper à vos jetons en utilisant un mappage de revendications personnalisées.

Lorsque vous vous authentifiez, veillez à utiliser username : client ID et password : secret pour l'application et l'utilisateur pour lesquels vous avez configuré les contrôles.

Affectation de rôles à une application

Après avoir créé des rôles, vous pouvez les attribuer à vos applications à l'aide des API d'App ID.

Les rôles d'application ne sont valides que dans le flux de données d'identification client.

Obtenez votre ID client d'application en interrogeant la liste des applications. Vous pouvez également obtenir cette valeur dans l'onglet Applications de l'interface utilisateur App ID.

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

Exemple :

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...."

Obtenez l'ID rôle.

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

Envoyez une demande au noeud final /roles contenant un objet JSON avec les rôles que vous souhaitez affecter. Cette demande remplace les rôles en cours par les ID rôle fournis. Veillez à attribuer les rôles appropriés.

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>"

Pour supprimer un rôle à un utilisateur, envoyez à nouveau la demande PUT, mais en retirant l'ID du rôle.

Contrôle de l'accès lors de l'exécution

Lorsqu'un utilisateur ou une application tente d'accéder à l'une de vos ressources protégées, des jetons sont créés et renvoyés par App ID. Toutes les portées attribuées à un utilisateur ou à une application sont renvoyées dans le jeton d'accès. Vous pouvez utiliser le jeton d'accès pour prendre des décisions lors de l'exécution. Selon la stratégie de protection de vos applications, la méthode utilisée pour vérifier les portées peut varier.

Utilisation de la stratégie d'application Web

Vous pouvez utiliser la stratégie d'application Web pour vérifier si une demande contient des portées en utilisant la méthode hasScope. Lorsqu'un utilisateur avec un rôle affecté s'affiche, il est autorisé à accéder à un jeton App ID qui contient toutes les portées définies dans le rôle.Par exemple, si vous utilisez le SDK Node.js, votre fragment de code sera similaire à ceci :

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");
    }
});

Utilisation de la stratégie d'API

Vous pouvez définir les portées nécessaires pour accéder à un noeud final spécifique en ajoutant une variable de portée dans votre code de stratégie d'API. Par exemple, si vous disposez d'une application écrite en Node.js et que vous utilisez le SDK Node.js, votre fragment de code sera similaire à ceci :

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

Comprendre les variables utilisées dans la stratégie API
Variable	Description
`scope`	Portées requises, séparées par un espace.
`audience`	ID client de l'application.

Retrait de l'accès

Vous pouvez supprimer une portée ou un rôle qui n'est plus nécessaire.

Suppression des champs d'application dans la console

Si vous n’avez plus besoin d'une portée, vous pouvez la supprimer à l'aide de l'interface utilisateur d'App ID.

Lorsque vous supprimez une portée, elle est supprimée de tous les rôles à laquelle elle est associée.

Vous pouvez utiliser le tableau de bord du service App ID pour supprimer des portées.

Accédez à Applications dans le tableau de bord App ID.
Dans le menu Actions sur la ligne correspondant à l'application dont vous voulez éditer les portées, cliquez sur Editer.
Cliquez sur le X dans la case correspondant à la portée que vous souhaitez supprimer.
Cliquez sur Sauvegarder.

Suppression de portées avec l'API

Si vous n’avez plus besoin d'une portée, vous pouvez la supprimer à l'aide de l'API d'App ID. Pour supprimer une portée, supprimez-la de votre objet JSON et créez une nouvelle demande PUT pour le nœud final /scopes.

Lorsque vous supprimez une portée, elle est supprimée de tous les rôles à laquelle elle est associée.

Modifiez ou supprimez une portée avec la demande suivante au noeud final /scopes. Veillez à mettre à jour l'objet JSON de vos portées pour qu'il contienne uniquement les portées que vous souhaitez autoriser.

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>" ]}"

Suppression de rôles dans la console

Si vous n'avez plus besoin d'un rôle spécifique, vous pouvez le supprimer à l'aide de l'interface utilisateur App ID.

La suppression d'un rôle supprime l'accès de tous les utilisateurs et applications qui utilisent actuellement le rôle.

Accédez à Profils et rôles > Rôles dans le tableau de bord du service.
Sur la ligne correspondant au rôle que vous souhaitez supprimer, sélectionnez Supprimer dans le menu Actions.
Confirmez que vous avez compris que la suppression du rôle affecte l'ensemble des utilisateurs et des applications qui utilisent actuellement le rôle.
Cliquez sur Supprimer.

Suppression de rôles avec l'API

Si vous n'avez plus besoin d'un rôle spécifique, vous pouvez le supprimer à l'aide des API App ID.

La suppression d'un rôle supprime l'accès de tous les utilisateurs et applications qui utilisent actuellement le rôle.

Obtenez l'ID ou le nom du rôle. Si vous connaissez déjà l'ID ou le nom de votre rôle, passez à l'étape suivante.
```
curl -X GET "https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/roles"
-H "accept: application/json"
```

Envoyez une demande au noeud final /roles contenant un objet JSON avec les rôles que vous souhaitez affecter.

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