Préparer un identifiant ServiceNow
01En bref #sec_563ebc7f
REVIEWIT collecte une instance ServiceNow par un client OAuth que vous enregistrez dans l'instance, en mode client credentials . Ce client agit au nom d'un compte de service que vous créez pour lui, et ce compte ne reçoit que des droits de lecture . Vous confiez à REVIEWIT trois valeurs : le nom d'hôte de l'instance, le Client ID et le secret du client OAuth.
ServiceNow n'a pas de portées : ce que REVIEWIT peut lire, ce sont les tables que vos ACL ouvrent au compte de service. REVIEWIT lit dix tables, toutes en lecture, par l'API Table. Chaque appel qu'il a le droit de faire est écrit dans le contrat de la ressource, et rien d'autre ne part.
Prérequis : une instance en version Washington DC ou plus récente (le mode client credentials n'existe pas avant), et un administrateur qui peut prendre le rôle security_admin pour créer des ACL.
021. Autoriser le mode client credentials #sec_0a07fa2b
Le mode est désactivé par défaut dans toute instance.
- System Properties (tapez sys_properties.list dans le navigateur de l'instance) ;
- cherchez glide.oauth.inbound.client.credential.grant_type.enabled . Elle n'existe pas dans une instance neuve : créez-la ( New ), type true | false ;
- valeur true .
Sans elle, ServiceNow refuse la demande de jeton par unsupported_grant_type .
032. Créer le compte de service #sec_ac894809
User Administration › Users › New :
| Champ | Valeur |
|---|---|
| User ID | par exemple svc_reviewit |
| First name / Last name | par exemple REVIEWIT / Reader |
| Web service access only | coché : le compte ne peut pas se connecter à l'interface |
| Active | coché |
Ne lui donnez aucun mot de passe utile : il n'agit que par le jeton du client OAuth.
043. Créer le rôle de lecture et ses ACL #sec_22038682
- User Administration › Roles › New : nom reviewit_reader , description Lecture des tables collectées par REVIEWIT .
- Prenez le rôle security_admin (menu de l'utilisateur › Elevate role ).
- System Security › Access Control (ACL) › New , pour chacune des dix tables ci-dessous, deux ACL :
- type record , opération read , nom <table> et champ -- None -- (la ligne) ;
- type record , opération read , nom <table> et champ \ * (les colonnes) ;
- dans les deux, Requires role : reviewit_reader , sans condition ni script.
| Table | Ce qu'elle ouvre à REVIEWIT |
|---|---|
| sys_user | Comptes, comptes de service, dernière connexion |
| sys_user_group | Groupes, leur type et leur responsable |
| sys_user_grmember | Membres des groupes |
| sys_user_has_role | Rôles attribués aux personnes |
| sys_group_has_role | Rôles accordés par les groupes |
| sys_user_role | Définition des rôles (privilégiés, élévation) |
| sys_user_role_contains | Rôles contenus dans d'autres rôles |
| license_role | Rôles soumis à licence (si l'instance a le plugin) |
| oauth_entity | Clients OAuth enregistrés (jamais leurs secrets) |
| sys_user_delegate | Délégations entre personnes |
- Ajoutez trois ACL de lecture, elles aussi réservées à reviewit_reader , pour deux champs que ServiceNow protège à part :
| ACL (type record, opération read) | Ce qu'elle ouvre à REVIEWIT |
|---|---|
| sys_package et sys_package.* | Le paquet de chaque rôle : c'est ce qui distingue les rôles créés par vous des rôles natifs. Sans elles, la ressource « rôles créés chez le client » reste vide. |
| oauth_entity.active | L'état actif ou inactif de chaque client OAuth. Sans elle, cet état reste inconnu. |
- Donnez au compte de service les rôles reviewit_reader , role_viewer , usage_admin et snc_read_only .
Deux tables portent des ACL natives de type « Deny Unless » , que vos ACL de lecture ne lèvent pas :
| Table | Ce qui l'ouvre |
|---|---|
| sys_user_role | Le rôle natif role_viewer . Sans lui, la table répond vide : le compte ne voit que les rôles qu'il aurait le droit d'attribuer. |
| license_role | Le rôle natif usage_admin (il contient sn_sub_man.admin ). Sans lui, la table est refusée et la ressource des licences n'est pas collectable. |
snc_read_only interdit toute écriture au compte, quels que soient ses autres rôles : usage_admin et role_viewer ne lui servent qu'à lire. Ne lui donnez jamais admin : ce rôle contourne les ACL et peut tout modifier. Si le compte porte admin ou s'il lui manque snc_read_only , REVIEWIT accepte la connexion mais l' avertissement s'affiche sur l'identifiant.
Une table que vous n'ouvrez pas ne bloque pas la connexion : les ressources qui en dépendent restent non collectables , et l'étape Préparer de l'assistant les nomme.
054. Enregistrer le client OAuth #sec_5d7bcc81
Selon votre version :
- Brazil : System OAuth › Inbound Integrations , qui ouvre la Machine Identity Console › New integration › OAuth - Client credentials grant ;
- Zurich à Australia : System OAuth › Inbound Integrations › New Integration › OAuth - Client credentials grant ;
- Washington DC à Yokohama : System OAuth › Application Registry › New › Create an OAuth API endpoint for external clients .
Réglez le client :
| Champ | Valeur |
|---|---|
| Name | par exemple REVIEWIT Collector |
| Provider name | par exemple REVIEWIT |
| OAuth application user | le compte de service de la section 2 (cherchez-le par son nom affiché, REVIEWIT Reader ) |
| Active | coché |
Depuis Zurich, le client exige une portée d'autorisation ( Auth scope ), et l'option Allow access only to APIs in selected scope est cochée d'office. N'utilisez pas useraccount , qui ouvre toutes les API au compte : Create auth scope , nom reviewit_read , puis dans Limit authorization to the following APIs , choisissez Table API seulement. REVIEWIT n'appelle que l'API Table.
Enregistrez : ServiceNow génère le Client ID et le Client Secret . Les jetons durent 30 minutes.
065. Relever les trois valeurs #sec_16c316c6
| Valeur | Où la trouver |
|---|---|
| Instance | Le nom d'hôte seul, sans https:// : acme.service-now.com (ou ….servicenowservices.com pour une instance gouvernementale) |
| Client ID | La fiche du client OAuth |
| Client secret | Même fiche (icône de cadenas pour l'afficher) |
Un domaine personnalisé ( itsm.votre-entreprise.com ) n'est pas accepté : saisissez l'adresse native de l'instance, qui existe toujours.
Dans REVIEWIT : Connexions › Nouvelle connexion › ServiceNow , saisissez les trois valeurs. La vérification :
- obtient un jeton de l'instance saisie ;
- lit le compte de service dans l'annuaire de l'instance ;
- lit ses rôles et avertit s'il pourrait écrire.
Puis la preuve des droits lit chacune des dix tables. Une table qui ne peut pas être vide (les comptes, les rôles) et qui répond vide est signalée comme lecture filtrée : une ACL plus ancienne, avec une condition, cache une partie des lignes. Vérifiez alors les ACL de cette table.
076. Si la connexion est refusée #sec_c2e25297
| Message | Cause | Geste |
|---|---|---|
| unsupported_grant_type | La propriété de la section 1 n'est pas à true | Section 1 |
| access_denied / server_error , ou invalid_client | Client ID ou secret faux, client OAuth inactif, ou client sans utilisateur d'application | Recopier les valeurs depuis la fiche du client, vérifier la section 4 |
| Une table « en lecture filtrée » | Une ACL « Deny Unless » cache ses lignes ( sys_user_role sans role_viewer ) | Section 3 |
| 401 sur l'API | Le compte de service est inactif | Section 2 |
| 403 sur l'API | Le compte de service ne lit pas sys_user | Section 3 |
| instance may be hibernating | Instance de développement en veille, ou adresse qui n'est pas une instance | Réveiller l'instance, vérifier l'adresse |
| The ServiceNow instance must be the bare host… | Adresse avec https:// , un chemin, ou un domaine personnalisé | Section 5 |
Le secret ne change que si vous le régénérez : faites-le à chaque départ d'une personne qui l'a vu, puis remplacez-le dans REVIEWIT.