Tutoriel sur l'API SCIM

Ce tutoriel vous guidera à travers certaines procédures courantes de gestion des utilisateurs via notre API SCIM. L'API SCIM vous permet d'afficher, de créer, de mettre à jour et de supprimer des utilisateurs et des groupes par programmation, en dehors de l'UI de gestion des utilisateurs.

Exigences

Avant d'utiliser ce tutoriel, nous vous recommandons de lire :

Autres ressources connexes :

Certains documents RFC SCIM 2.0 de l'Internet Engineering Task Force sont les plus pertinents : RFC 7643 - SCIM Core Resources and Extensions, RFC 7643 - JSON Representation et RFC 7644 - SCIM Protocol.

Présentation

Ce didacticiel vous montre comment accomplir certaines des tâches les plus courantes nécessaires à l'ajout d'utilisateurs à New Relic à partir d'un service de fournisseur d'identité et à leur gestion à partir de là. Il est destiné à compléter notre ressource API SCIM principale.

Notez que l'utilisation de la gestion automatisée des utilisateurs signifie que vos groupes d'utilisateurs sont importés dans New Relic. Cela signifie que vous ne pouvez pas utiliser notre UI de gestion des utilisateurs pour ajouter des utilisateurs à des groupes. Les groupes sont créés et gérés du côté de votre fournisseur d’identité.

Une fois que vous avez terminé d'intégrer vos groupes d'utilisateurs dans New Relic, vous devez utiliser notre UI Access management pour donner à ces groupes l'accès aux rôles et aux comptes. Pour plus d'informations, voir Concepts de gestion utilisateur.

Configurez votre domaine d'authentification pour SCIM

Avant de pouvoir utiliser l'API SCIM, vous devez d'abord activer SCIM pour votre domaine d'authentification. Notez que le jeton d'accès API ne s'affiche qu'une seule fois après avoir enregistré la configuration, alors enregistrez-le dans un endroit sûr pour une utilisation ultérieure.

Conseil

Si vous devez visualiser un jeton porteur plus tard, la seule façon de le faire est d'en générer un nouveau, ce qui invalidera l'ancien et toute intégration utilisant l'ancien jeton.

Créez des groupes d'utilisateurs et d'utilisateurs dans votre système

L'API SCIM est généralement utilisée par les scripts pour importer des utilisateurs et des groupes dans New Relic à partir d'une base de données ou d'un fournisseur d'identité tiers qui n'a pas de configurations préconfigurées pour New Relic.

Si vous souhaitez utiliser l'API SCIM d'application personnalisée ou pour des requests ad hoc, découvrez comment vous connecter à l'API SCIM.

Se connecter à l'API SCIM

L'API SCIM est disponible à l'adresse https://scim-provisioning.service.newrelic.com/scim/v2 et cette URL est visible dans la page des paramètres du domaine d'authentification. Pour accéder à l'API SCIM, votre client doit inclure un bearer token avec chaque requête. Le jeton s'affiche après avoir enregistré la configuration de votre domaine d'authentification.

Si vous utilisez un fournisseur d’identité tiers, configurez-le pour utiliser Bearer token authorization et connectez votre jeton d’accès API. Reportez-vous à la documentation de votre fournisseur d'identité pour obtenir de l'aide sur la configuration de cette fonction. Une fois configuré, vous êtes prêt à importer des utilisateurs et des groupes.

Plutôt que de lire l'intégralité des RFC du protocole SCIM, il existe trois sections spécifiques que vous pourriez trouver utiles : voir RFC 7643 - Ressources et extensions de base SCIM et RFC 7643 - Représentation JSON pour les détails. Reportez-vous à la RFC 7644 - Protocole SCIM pour plus d'informations sur le protocole utilisé dans ce didacticiel.

Pour toutes requests adressées à l'API SCIM, vous devez fournir le jeton porteur dans un en-tête Authorization. Voici un exemple avec curl:

bash

$curl -X 'GET' -H 'Accept: application/json' -H "Authorization: Bearer $TOKEN" 'https://scim-provisioning.service.newrelic.com/scim/v2/Users'

Toute demande dans le reste de ce didacticiel recevra une réponse 401 Unauthorized si le jeton d’accès API est manquant ou non valide.

Exemple de réponse :

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "detail": "invalid authentication token",
  "status": "401"
}

Créez un utilisateur dans votre domaine d'authentification

Vous pouvez utiliser l'API SCIM pour envoyer une requête POST à /scim/v2/Users afin de créer un utilisateur. Les attributs utilisateur suivants sont required:

userName Cet identifiant must doit être unique au sein d'un domaine d'authentification. Utilisez l'adresse e-mail de l'utilisateur.
emails Identique à userName. L'adresse email de l'utilisateur. (Bien qu'il soit appelé emails, pour cette procédure, n'en saisissez qu'un seul.)
active Booléen indiquant si l'utilisateur doit être actif ou inactif dans New Relic.

Nous vous recommandons de fournir l'attribut suivant pour une meilleure expérience utilisateur :

name.givenName Le prénom ou le nom de l'utilisateur.
name.familyName Le nom de famille de l'utilisateur.
timezone Le fuseau horaire de l'utilisateur au format de la base de données des fuseaux horaires IANA.

bash

$curl -X 'POST' -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" 'https://scim-provisioning.service.newrelic.com/scim/v2/Users' --data-binary @- <<EOF
${
$  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
$  "userName": "bjensen@example.com",
$  "name": {
$    "familyName": "Jensen",
$    "givenName": "Barbara"
$  },
$  "emails": [
$    {
$      "primary": true,
$      "value": "bjensen@example.com"
$    }
$  ],
$  "active": true,
$  "timezone": "America/Los_Angeles"
$}
$EOF

Important

Prenez note de l'utilisateur renvoyé id. Pour mettre à jour un utilisateur à l'avenir, vous devrez fournir le même identifiant avec la demande.

Exemples de réponses

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "id": "5a1d580f-323c-450c-8c62-479b5c9085d6",
  "externalId": null,
  "userName": "bjensen@example.com",
  "name": {
    "familyName": "Jensen",
    "givenName": "Barbara"
  },
  "emails": [
    {
      "value": "bjensen@example.com",
      "primary": true
    }
  ],
  "timezone": "America/Los_Angeles",
  "active": true,
  "meta": {
    "resourceType": "User",
    "created": "2021-07-20T21:32:58.167Z",
    "lastModified": "2021-07-20T21:32:58.167Z"
  },
  "groups": []
}

Créez des groupes dans votre domaine d’authentification

Vous pouvez utiliser l'API SCIM pour envoyer une requête POST à /scim/v2/Groups afin de créer un groupe. Le seul attribut de groupe required est :

displayName Le nom du groupe.

bash

$curl -X 'POST' -H 'Content-Type: application/json' -H "Authorization: Bearer $YOUR_TOKEN" 'https://scim-provisioning.service.newrelic.com/scim/v2/Groups' --data-binary @- <<EOF
${
$  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
$  "displayName": "Example Group"
$}
$EOF

Important

Prenez note du groupe renvoyé id. Pour mettre à jour un groupe ou ses membres à l'avenir, vous devrez fournir le même identifiant avec la demande.

Exemples de réponses

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "id": "df2b9a04-0426-4a3e-bf5f-54d5341f4e5b",
  "displayName": "Example Group",
  "meta": {
    "resourceType": "Group",
    "created": "2021-07-20T22:41:50.414Z",
    "lastModified": "2021-07-20T22:41:50.414Z"
  },
  "members": []
}

Afficher les utilisateurs et les groupes dans votre domaine d'authentification

Après avoir créé des utilisateurs et des groupes, vous les verrez dans l'UI de gestion des utilisateurs. Vous pouvez également les récupérer à partir de l'API SCIM.

Dans ce didacticiel, vous rechercherez des utilisateurs et des groupes spécifiques, mais ce n'est pas la seule façon d'afficher les utilisateurs et les groupes. Reportez-vous à la référence de l'API SCIM et à la RFC 7644 pour toutes les options de requête disponibles.

Pour récupérer un utilisateur par e-mail, envoyez une requête GET à /scim/v2/Users avec un paramètre de requête filter . Le paramètre filter doit être codé en URL.

bash

$curl -X 'GET' -H 'Accept: application/json' -H "Authorization: Bearer $YOUR_TOKEN" 'https://scim-provisioning.service.newrelic.com/scim/v2/Users' --get --data-urlencode 'filter=userName eq "bjensen@example.com"'

Exemple de réponse :

{
  "totalResults": 1,
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "Resources": [
    {
      "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
      "id": "5a1d580f-323c-450c-8c62-479b5c9085d6",
      "externalId": null,
      "userName": "bjensen@example.com",
      "name": {
        "familyName": "Jensen",
        "givenName": "Barbara"
      },
      "emails": [
        {
          "value": "bjensen@example.com",
          "primary": true
        }
      ],
      "timezone": "America/Los_Angeles",
      "active": true,
      "meta": {
        "resourceType": "User",
        "created": "2021-07-20T21:32:58.167Z",
        "lastModified": "2021-07-20T21:32:58.167Z"
      },
      "groups": []
    }
  ]
}

De même, envoyez une requête GET à /scim/v2/Groups avec un paramètre de requête filter pour récupérer un groupe par nom.

bash

$curl -X 'GET' -H 'Accept: application/json' -H "Authorization: Bearer $YOUR_TOKEN" 'https://scim-provisioning.service.newrelic.com/scim/v2/Groups' --get --data-urlencode 'filter=displayName eq "Example Group"'

Exemple de réponse :

{
  "totalResults": 1,
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "Resources": [
    {
      "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
      "id": "df2b9a04-0426-4a3e-bf5f-54d5341f4e5b",
      "displayName": "Example Group",
      "meta": {
        "resourceType": "Group",
        "created": "2021-07-20T22:41:50.414Z",
        "lastModified": "2021-07-20T22:41:50.414Z"
      },
      "members": []
    }
  ]
}

Mettre à jour l'attribut d'un utilisateur

L'API SCIM prend en charge les méthodes PUT et PATCH pour la mise à jour de l'utilisateur. Reportez-vous aux actions prises en charge par l'API SCIM et à la RFC 7644 pour plus de détails sur l'utilisation PATCH. Ce tutoriel montre la mise à jour de l'attribut d'un utilisateur avec la méthode PUT .

New Relic ne nécessite pas que tous les attributs utilisateur soient inclus dans le corps de la requête, seul l'attribut que vous souhaitez mettre à jour est nécessaire. Envoyez une demande PUT à /scim/v2/Users/${ID} pour mettre à jour l'utilisateur.

bash

$curl -X 'PUT' -H 'Content-Type: application/json' -H "Authorization: Bearer $YOUR_TOKEN" 'https://scim-provisioning.service.newrelic.com/scim/v2/Users/5a1d580f-323c-450c-8c62-479b5c9085d6' --data-binary @- <<EOF
${
$  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
$  "timezone": "America/Chicago"
$}
$EOF

Exemples de réponses

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "id": "5a1d580f-323c-450c-8c62-479b5c9085d6",
  "externalId": null,
  "userName": "bjensen@example.com",
  "name": {
    "familyName": "Jensen",
    "givenName": "Barbara"
  },
  "emails": [
    {
      "value": "bjensen@example.com",
      "primary": true
    }
  ],
  "timezone": "America/Chicago",
  "active": true,
  "meta": {
    "resourceType": "User",
    "created": "2021-07-20T21:32:58.167Z",
    "lastModified": "2021-07-21T02:12:05.348Z"
  },
  "groups": []
}

Mettre à jour les membres d'un groupe

L'API SCIM prend en charge les méthodes PUT et PATCH pour la mise à jour des groupes. Ce tutoriel montrera comment mettre à jour les membres d'un groupe avec la méthode PATCH . Reportez-vous aux actions prises en charge par l'API SCIM et à la RFC 7644 pour plus de détails sur l'utilisation PUT.

PATCH est pratique pour ajouter ou supprimer des membres d'un groupe sans avoir besoin de spécifier la liste complète des membres dans la demande. Pour ajouter un utilisateur à un groupe, utilisez le paramètre d'opération suivant :

op régler sur Add
path régler sur members
value définir une liste de {"value": "${USER_ID}"} avec chaque ID utilisateur à ajouter au groupe

Envoyez une demande PATCH à /scim/v2/Groups/${ID} pour mettre à jour les membres du groupe.

bash

$curl -X 'PATCH' -H 'Content-Type: application/json' -H "Authorization: Bearer $YOUR_TOKEN" 'https://scim-provisioning.service.newrelic.com/scim/v2/Groups/df2b9a04-0426-4a3e-bf5f-54d5341f4e5b' --data-binary @- <<EOF
${
$  "schemas": [
$    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
$  ],
$  "Operations": [{
$    "op": "Add",
$    "path": "members",
$    "value": [{
$      "value": "5a1d580f-323c-450c-8c62-479b5c9085d6"
$    }]
$  }]
$}
$EOF

Exemple de réponse :

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "id": "df2b9a04-0426-4a3e-bf5f-54d5341f4e5b",
  "displayName": "Example Group",
  "meta": {
    "resourceType": "Group",
    "created": "2021-07-20T22:41:50.414Z",
    "lastModified": "2021-07-20T22:41:50.414Z"
  },
  "members": [
    {
      "type": "User",
      "value": "5a1d580f-323c-450c-8c62-479b5c9085d6"
    }
  ]
}

Pour supprimer un utilisateur d'un groupe, utilisez le paramètre d'opération suivant :

op régler sur Remove
path régler sur members
value définir une liste de {"value": "${USER_ID}"} avec chaque ID utilisateur à supprimer du groupe

bash

$curl -X 'PATCH' -H 'Accept: application/json' -H "Authorization: Bearer $YOUR_TOKEN" 'https://scim-provisioning.service.newrelic.com/scim/v2/Groups/df2b9a04-0426-4a3e-bf5f-54d5341f4e5b' --data-binary @- <<EOF
${
$  "schemas": [
$    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
$  ],
$  "Operations": [{
$    "op": "Remove",
$    "path": "members",
$    "value": [{
$      "value": "5a1d580f-323c-450c-8c62-479b5c9085d6"
$    }]
$  }]
$}
$EOF

Exemple de réponse :

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "id": "df2b9a04-0426-4a3e-bf5f-54d5341f4e5b",
  "displayName": "Example Group",
  "meta": {
    "resourceType": "Group",
    "created": "2021-07-20T22:41:50.414Z",
    "lastModified": "2021-07-20T22:41:50.414Z"
  },
  "members": []
}

Supprimer l'utilisateur et les groupes

Pour supprimer un utilisateur d’un domaine d’authentification, envoyez une demande DELETE à /scim/v2/Users/${ID}.

bash

$curl -X 'DELETE' -H 'Accept: application/json' -H "Authorization: Bearer $YOUR_TOKEN" 'https://scim-provisioning.service.newrelic.com/scim/v2/Users/d0f4d8e3-5413-4894-a8f9-de709994e18c'

Exemple de réponse :

204 No Content

De même, pour supprimer un groupe de votre domaine d’authentification, envoyez une demande DELETE à /scim/v2/Groups/${ID}.

bash

$curl -X 'DELETE' -H 'Accept: application/json' -H "Authorization: Bearer $YOUR_TOKEN" 'https://scim-provisioning.service.newrelic.com/scim/v2/Groups/df2b9a04-0426-4a3e-bf5f-54d5341f4e5b'

Exemple de réponse :

204 No Content

Prochaines étapes

Une fois votre intégration terminée, les prochaines étapes potentielles incluent :

Votre utilisateur New Relic démarrera par défaut comme un utilisateur de base et vous avez la possibilité de le mettre à niveau. Pour plus d'informations, voir Gérer le type d'utilisateur.
Configurer SAML SSO.
Une fois vos groupes d'utilisateurs dans New Relic, vous devrez leur attribuer des rôles et des comptes spécifiques. En savoir plus sur le fonctionnement de l’accès utilisateur.

Optionnel : Gérer le type d'utilisateur

Une fois l'intégration de votre API SCIM terminée, tous les utilisateurs introduits dans New Relic démarrent en tant qu'utilisateurs de base. Vous pouvez utiliser notre méthode par défaut pour gérer le type d'utilisateur, qui utilise l'UI de gestion des utilisateurs. En option, vous pouvez utiliser notre API SCIM à la place. Pour ce faire, vous pouvez définir la mise à jour de la configuration de votre domaine d’authentification sur Déléguer le contrôle du type d’utilisateur à votre fournisseur d’identité ou à votre application personnalisée.

L'attribut de type de l'utilisateur est défini dans le schéma personnalisé urn:ietf:params:scim:schemas:extension:newrelic:2.0:User. Incluez ce schéma et l'attribut de chaîne nrUserType dans votre demande de création ou de mise à jour pour définir le type d'un utilisateur.

Les valeurs valides pour nrUserType incluent, toutes sensibles à la casse :

Full User
Core User
Basic User

Pour créer un nouveau Basic User envoyez une POST requête /scim/v2/Users et incluez l'extension de schéma New Relic personnalisée :

bash

$curl -X 'POST' -H 'Content-Type: application/json' -H "Authorization: Bearer $YOUR_TOKEN" 'https://scim-provisioning.service.newrelic.com/scim/v2/Users' --data-binary @- <<EOF
${
$  "schemas": [
$    "urn:ietf:params:scim:schemas:core:2.0:User",
$    "urn:ietf:params:scim:schemas:extension:newrelic:2.0:User"
$  ],
$  "userName": "jbenson@example.com",
$  "name": {
$    "givenName": "James",
$    "familyName": "Benson"
$  },
$  "emails": [{
$    "primary": true,
$    "value": "jbenson@example.com",
$    "type": "work"
$  }],
$  "active": true,
$  "timezone": "America/Chicago",
$  "urn:ietf:params:scim:schemas:extension:newrelic:2.0:User": {
$    "nrUserType": "Basic User"
$  }
$}
$EOF

Exemples de réponses

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:newrelic:2.0:User"
  ],
  "id": "8ab6c464-983c-4bb4-9507-720f28763a43",
  "externalId": null,
  "userName": "jbenson@example.com",
  "name": {
    "familyName": "Benson",
    "givenName": "James"
  },
  "emails": [
    {
      "value": "jbenson@example.com",
      "primary": true
    }
  ],
  "timezone": "America/Chicago",
  "active": true,
  "meta": {
    "resourceType": "User",
    "created": "2021-07-21T19:53:33.470Z",
    "lastModified": "2021-07-21T19:53:33.470Z"
  },
  "groups": [],
  "urn:ietf:params:scim:schemas:extension:newrelic:2.0:User": {
    "nrUserType": "Basic User"
  }
}

Pour mettre à jour le type d'un utilisateur, envoyez une requête PUT scim/v2/Users/${ID} et incluez l'extension de schéma New Relic personnalisée :

bash

$curl -X 'PUT' -H 'Content-Type: application/json' -H "Authorization: Bearer $YOUR_TOKEN" 'https://scim-provisioning.service.newrelic.com/scim/v2/Users' --data-binary @- <<EOF
${
$  "schemas": [
$    "urn:ietf:params:scim:schemas:core:2.0:User",
$    "urn:ietf:params:scim:schemas:extension:newrelic:2.0:User"
$  ],
$  "urn:ietf:params:scim:schemas:extension:newrelic:2.0:User": {
$    "nrUserType": "Full User"
$  }
$}
$EOF

Exemples de réponses

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:newrelic:2.0:User"
  ],
  "id": "8ab6c464-983c-4bb4-9507-720f28763a43",
  "externalId": null,
  "userName": "jbenson@example.com",
  "name": {
    "familyName": "Benson",
    "givenName": "James"
  },
  "emails": [
    {
      "value": "jbenson@example.com",
      "primary": true
    }
  ],
  "timezone": "America/Chicago",
  "active": true,
  "meta": {
    "resourceType": "User",
    "created": "2021-07-21T19:53:33.470Z",
    "lastModified": "2021-07-21T20:15:56.718Z"
  },
  "groups": [],
  "urn:ietf:params:scim:schemas:extension:newrelic:2.0:User": {
    "nrUserType": "Full User"
  }
}

Cette traduction automatique est fournie pour votre commodité.

Exigences .css-21sua1{background:none;border:none;width:0;padding:0;}

Présentation

Configurez votre domaine d'authentification pour SCIM

Conseil

Créez des groupes d'utilisateurs et d'utilisateurs dans votre système

Se connecter à l'API SCIM

401 Non autorisé

Créez un utilisateur dans votre domaine d'authentification

Important

Exemples de réponses

201 Créé

400 Mauvaise requête

409 Conflit

Créez des groupes dans votre domaine d’authentification

Important

Exemples de réponses

201 Créé

400 Mauvaise requête

409 Conflit

Afficher les utilisateurs et les groupes dans votre domaine d'authentification

200 d'accord

200 d'accord

Mettre à jour l'attribut d'un utilisateur

Exemples de réponses

200 d'accord

409 Conflit

Mettre à jour les membres d'un groupe

200 d'accord

200 d'accord

Supprimer l'utilisateur et les groupes

Prochaines étapes

Optionnel : Gérer le type d'utilisateur

Exemples de réponses

200 d'accord

409 Conflit

400 Mauvaise requête

Exemples de réponses

200 d'accord

400 Mauvaise requête

Exigences