Travailler avec des attributs personnalisés

Introduction

L'annuaire IBM Security Verify Cloud Directory définit un schéma SCIM d'attributs utilisateur qui peut être complété par des attributs personnalisés spécifiques à votre locataire. Dans ce guide, vous apprendrez à créer un attribut personnalisé pour étendre le schéma SCIM, ainsi qu'à créer, mettre à jour et rechercher des utilisateurs avec cet attribut personnalisé. L'API de gestion des attributs et l'API de l'annuaire en nuage seront présentées à l'aide d'exemples cURL pour vous apprendre à appeler les API REST d' IBM Security Verify.

Prérequis

Vous aurez besoin d'un client API qui dispose des droits suivants dans IBM Verify:

Gérer les attributs (pour créer des attributs personnalisés)
Lire les utilisateurs et les groupes (pour lire les enregistrements des utilisateurs)
Gérer les utilisateurs et les groupes standard (pour lire et gérer les dossiers des utilisateurs)

Voir Créer un client d' API pour plus d'informations sur la création d'un client d'API qui peut être utilisé avec le flux de type de subvention OAuth Client Credentials pour obtenir un jeton d'accès.

Variables

Les variables suivantes sont nécessaires pour exécuter le flux décrit dans ce guide :

Variables	Valeur exemple	Description
uRL du locataire	tenant.verify.ibm.com	URL de votre locataire IBM Security Verify.
jeton d'accès	eWn4Z5xChc3q9B9dqbGgFlsHDh7uhAOnmNeKW5Ez	Le jeton d'accès obtenu à partir du point de terminaison du jeton.
adresse_électronique	[email protected]	Adresse e-mail de l'utilisateur.
first_name	jane	Prénom de l’utilisateur.
last_name	forgeron	Nom de l'utilisateur.

Des étapes pour vous guider avec des exemples

Créez un attribut SCIM personnalisé appelé hobbies.
Créer un utilisateur avec des valeurs définies pour les loisirs.
Mettez à jour l'enregistrement de l'utilisateur avec des valeurs différentes pour les hobbies.
Recherchez l'utilisateur à l'aide de différents filtres pour les loisirs.

1. Créer un attribut personnalisé

Il est recommandé d'utiliser l'interface utilisateur pour créer un attribut personnalisé, qui propose un assistant vous guidant à travers toutes les options. Vous pouvez créer jusqu'à 160 attributs personnalisés pour étendre le schéma de l'utilisateur SCIM. Il existe 150 attributs de schéma personnalisés prédéfinis, appelés customAttribute1 à customAttribute150, et 10 attributs personnalisés hachés prédéfinis, appelés hashedCustomAttribute1 à hashedCustomAttribute10, qui peuvent être associés à un nom de schéma SCIM. Dans l'API REST de gestion des attributs, nous créons un attribut personnalisé en associant un attribut de schéma personnalisé disponible à un nom d'attribut de schéma SCIM, puis il peut être géré via l'API REST SCIM des utilisateurs de Cloud Directory.

Dans cet exemple, nous utilisons customAttribute1 et le mappons au nom SCIM *hobbies qui supportera plusieurs valeurs.

Nom du SCIM	Attribut du schéma
loisirs	customAttribute1

Appel de l'API REST de gestion des attributs pour créer un attribut personnalisé à l'aide de cURL::

curl -X POST "https://${tenant_url}/v1.0/attributes" -H "Authorization: Bearer ${access_token}" -H "Content-Type: application/json" --data-raw '{ "datatype":"string[]", "description":"The user'\''s hobbies.",  "name":"hobbies",  "schemaAttribute":{ "name":"customAttribute1", "scimName":"hobbies" },"scope":"tenant","sourceType":"schema"}'

En cas de succès, vous obtiendrez un code d'état HTTP 201 ainsi qu'un corps de réponse contenant l'identifiant de l'attribut qui peut être utilisé pour récupérer / modifier / supprimer l'attribut.

{"id":"f6067c0a-a88d-4b69-8e4e-0893c7663ff6"}

Voir la référence API pour la création d'un attribut pour plus d'informations sur la création d'un attribut personnalisé à l'aide de l'API REST.

Obtenir l'attribut par son ID

En utilisant l'"id" renvoyé dans la réponse de l'API REST lors de la création de l'attribut, nous pouvons obtenir l'attribut par son ID.

Utilisation de cURL:

curl -X GET "https://${tenant_url}/v1.0/attributes/f6067c0a-a88d-4b69-8e4e-0893c7663ff6" -H "Authorization: Bearer ${access_token}"

En cas de succès, vous obtiendrez un code d'état HTTP 200 et un corps de réponse en JSON contenant les informations relatives à l'attribut.

{
    "id": "f6067c0a-a88d-4b69-8e4e-0893c7663ff6",
    "name": "hobbies",
    "description": "The user's hobbies.",
    "scope": "tenant",
    "sourceType": "schema",
    "datatype": "string[]",
    "schemaAttribute": {
        "name": "customAttribute1",
        "scimName": "hobbies",
        "customAttribute": true,
        "scimFilter": "urn:ietf:params:scim:schemas:extension:ibm:2.0:User:customAttributes.hobbies"
    }
}

Voir la référence API pour obtenir un attribut pour plus d'informations sur l'obtention d'un attribut à l'aide de l'API REST.

2. Créer un utilisateur avec des hobbies

Maintenant que l'attribut personnalisé est créé, vous pouvez en définir les valeurs à l'aide de l'API REST SCIM Utilisateurs de Cloud Directory. Créons un utilisateur avec
des passe-temps tels que la peinture et la photographie. Dans le schéma SCIM, l'attribut personnalisé est ajouté à l'élément
urn urn:ietf:params:scim:schemas:extension:ibm:2.0:User:customAttributes:[ ] array.

Utilisation de cURL:

curl -X POST "https://${tenant_url}/v2.0/Users" -H "Authorization: Bearer ${access_token}" -H "Content-Type: application/scim+json; charset=utf-8" -H "Accept: application/scim+json; charset=utf-8" --data-raw '{ "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User", "urn:ietf:params:scim:schemas:extension:ibm:2.0:User" ], "userName": "${email_address}", "name": { "familyName": "${family_name}", "givenName": "${given_name}" }, "emails":[ {"type":"work", "value":"${email_address}"} ], "urn:ietf:params:scim:schemas:extension:ibm:2.0:User": { "customAttributes":[ { "name":"hobbies", "values":["painting", "photography"] } ] }}'

En cas de succès, vous obtiendrez un code d'état HTTP 201 et le corps de la réponse en JSON contenant l'utilisateur créé.

{
    "emails": [
        {
            "type": "work",
            "value": "[email protected]"
        }
    ],
    "meta": {
        "created": "2021-11-03T13:38:19Z",
        "location": "https://gtatenantadmin.ite1.idng.ibmcloudsecurity.com/v2.0/Users/608000CXT7",
        "lastModified": "2021-11-03T13:38:19Z",
        "resourceType": "User"
    },
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:ibm:2.0:User"
    ],
    "urn:ietf:params:scim:schemas:extension:ibm:2.0:User": {
        "pwdReset": true,
        "userCategory": "regular",
        "twoFactorAuthentication": false,
        "realm": "cloudIdentityRealm",
        "pwdChangedTime": "2021-11-03T13:38:19Z",
        "customAttributes": [
            {
                "values": [
                    "painting",
                    "photography"
                ],
                "name": "hobbies"
            }
        ]
    },
    "name": {
        "formatted": "Jane Smith",
        "givenName": "Jane",
        "familyName": "Smith"
    },
    "active": true,
    "id": "608000CXT7",
    "userName": "[email protected]"
}

NOTE : un mot de passe temporaire sera envoyé à l'adresse électronique de l'utilisateur.

Voir la référence API pour créer un utilisateur pour plus d'informations sur la création d'un utilisateur à l'aide de l'API REST.

3. Mettez à jour l'enregistrement de l'utilisateur avec des valeurs différentes pour les hobbies.

En utilisant l'API PATCH /v2.0/Users/{id } de Cloud Directory, vous pouvez mettre à jour l'enregistrement avec différentes valeurs pour Vous pouvez mettre à jour l'enregistrement avec différentes valeurs pour loisirs. En fonction de ce que vous voulez faire, il y a différentes façons de mettre à jour les valeurs pour les hobbies. Examinons-le plus en détail.

Le corps de la requête PATCH suivante utilise le chemin urn urn:ietf:params:scim:schemas:extension:ibm:2.0:User:customAttributes avec l'opération add.

Prenons l'exemple de la charge utile ci-dessous. La valeur contient un tableau car le chemin d'accès est celui du tableau customAttributes[ ]. L'opération d' ajout ajoute les hobbies au tableau customAttributes[ ] s'il n'existe pas. S'il existe, il remplacera les valeurs par celles de la peinture, de la photographie et de la décoration.

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "add",
      "path": "urn:ietf:params:scim:schemas:extension:ibm:2.0:User:customAttributes",
      "value":[
        {
            "name":"hobbies",
            "values":["painting", "photography", "decorating"]
        }
      ]
    }
  ]
}

Lorsque ce chemin est utilisé, les opérations "add", "replace" et "remove" effectuent des opérations sur le tableau customAttributes[ ].

Voici un tableau qui résume ce que fait chaque opération lors de l'utilisation du chemin urn urn:ietf:params:scim:schemas:extension:ibm:2.0:User:customAttributes

Opération	Description
ajouter	Ajoute l'attribut personnalisé au tableau customAttributes[ ] s'il n'existe pas. Si l'attribut personnalisé existe, les valeurs sont mises à jour.
retirer	Supprime tous les attributs personnalisés du tableau customAttributes[ ]. Aucune valeur ne doit être spécifiée dans la charge utile PATCH.
remplacer	Remplace tous les attributs personnalisés du tableau customAttributes[ ] par ceux spécifiés dans le payload pour la valeur.

Appel de l'API PATCH de Cloud Directory avec l'opération d' ajout en utilisant cURL::

curl -X PATCH "https://${tenant_url}/v2.0/Users/608000CXT7" -H "Authorization: Bearer ${access_token}" -H "Content-Type: application/scim+json; charset=utf-8" -H "Accept: application/scim+json; charset=utf-8" --data-raw '{"schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], "Operations": [ {"op": "add","path": "urn:ietf:params:scim:schemas:extension:ibm:2.0:User:customAttributes","value":[{"name":"hobbies","values":["painting", "photography", "decorating"]}]}]}'

En cas de succès, vous devriez obtenir le statut HTTP 204 No content.

La fiche de l'utilisateur comporte désormais 3 hobbies, à savoir la peinture, la photographie et la décoration.

L'exemple suivant montre comment ajouter la course à pied et supprimer la décoration de l'attribut personnalisé hobbies. Remarquez que la valeur dans la charge utile est un tableau de chaînes, car le chemin d'accès met spécifiquement à jour le tableau values[] pour l'attribut personnalisé hobbies.

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "add",
      "path": "urn:ietf:params:scim:schemas:extension:ibm:2.0:User:customAttributes[name eq \"hobbies\"].values",
      "value":["running"]
    },
    {
      "op": "remove",
      "path": "urn:ietf:params:scim:schemas:extension:ibm:2.0:User:customAttributes[name eq \"hobbies\"].values",
      "value": ["decorating"]
    }
   ]
}

Appel de PATCH utilisant cURL pour ajouter la course à pied et supprimer la décoration des loisirs de l'utilisateur :

curl -X PATCH "https://${tenant_url}/v2.0/Users/608000CXT7" -H "Authorization: Bearer ${access_token}" -H "Content-Type: application/scim+json; charset=utf-8" -H "Accept: application/scim+json; charset=utf-8" --data-raw '{"schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],"Operations": [{"op": "add","path": "urn:ietf:params:scim:schemas:extension:ibm:2.0:User:customAttributes[name eq \"hobbies\"].values","value":["running"]},{"op": "remove","path": "urn:ietf:params:scim:schemas:extension:ibm:2.0:User:customAttributes[name eq \"hobbies\"].values","value": ["decorating"]}]}'

En cas de succès, vous devriez obtenir le statut HTTP 204 No content.

Voici un tableau qui résume ce que fait chaque opération lors de l'utilisation du chemin urn :ietf:params:scim:schemas:extension:ibm:2.0:User:customAttributesname [eq "hobbies"].values

Opération	Description
ajouter	Ajoute à l'attribut personnalisé le tableau values[].
retirer	Supprime de l'attribut personnalisé le tableau values[].
remplacer	Remplace l'attribut personnalisé values[] array.

Voir la référence API pour modifier un utilisateur pour plus d'informations sur la mise à jour d'un ou plusieurs attributs d'un utilisateur à l'aide de l'API REST.

4. Rechercher l'enregistrement de l'utilisateur à l'aide de filtres d'attributs personnalisés.

L'API REST de Cloud Directory prend en charge les filtres permettant de rechercher des utilisateurs sur la base de valeurs d'attributs personnalisées. Voici les filtres de recherche les plus courants que vous pouvez utiliser à l'aide de l'exemple d'enregistrement d'utilisateur que nous avons créé.

Retourne les enregistrements qui ont une valeur pour les hobbies.

curl -X GET "https://${tenant_url}/v2.0/Users?filter=urn:ietf:params:scim:schemas:extension:ibm:2.0:User:customAttributes.hobbies+pr&attributes=userName,urn:ietf:params:scim:schemas:extension:ibm:2.0:User:customAttributes" -H "Authorization: Bearer ${access_token}"

Retourne les enregistrements dont la valeur pour les loisirs est la course à pied.

curl -X GET "https://${tenant_url}/v2.0/Users?filter=urn:ietf:params:scim:schemas:extension:ibm:2.0:User:customAttributes.hobbies+eq+%22running%22&attributes=userName,urn:ietf:params:scim:schemas:extension:ibm:2.0:User:customAttributes" -H "Authorization: Bearer ${access_token}"

En cas de succès, les deux recherches d'utilisateurs ci-dessus renverront un code d'état HTTP 200 et un corps de réponse en JSON contenant ce qui suit.

{
  "totalResults" : 1,
  "schemas" : [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "Resources" : [
    {
      "urn:ietf:params:scim:schemas:extension:ibm:2.0:User" : {
        "customAttributes" : [
          {
            "values" : [
              "painting",
              "photography",
              "running"
            ],
            "name" : "hobbies"
          }
        ]
      },
      "id" : "608000CXT7",
      "userName" : "[email protected]"
    }
  ]
}

Voir la référence API pour get users pour plus d'informations sur la récupération des utilisateurs à l'aide de l'API REST.

tim Moore, IBM Security

Brad Fraley, IBM Security