Scripted API
Les connecteurs Scripted API sont des connecteurs ICF basés sur un connecteur propriétaire nommé Scripted API. Ce dernier est un connecteur générique offrant des fonctions utilitaires qui peuvent être utilisées dans des scripts Groovy afin de créer des connecteurs ICF spécifiques. Ceux-ci peuvent ensuite être personnalisés facilement pour répondre aux besoins d'affaires de chaque organisation. Cela peut se faire grâce à une interface graphique intégrée à même RAC/M Identity.
Prérequis
- RAC/M Identity 3.17 ou plus récent
- Un référentiel de données accessible via une API (par exemple, Workday)
Création du script
Cette étape consiste à créer un script Groovy qui sera utilisé par le connecteur Scripted API.
- Dans la barre de menu, cliquez sur CONFIGURATION> Fichiers de script.
- Cliquez sur le nom du script correspondant au connecteur désiré débutant par
reference-scripts/scripted-api-. Cela ouvrira le script. Par exemple, pour créer un connecteur pour Workday, sélectionnez le scriptreference-scripts/scripted-api-19.0.0.0/workday.groovy. Choisissez la version la plus récente. Si le connecteur n'existe pas déjà, vous pouvez en créer un en vous basant sur les scripts de référence. - Cliquez sur le bouton Dupliquer en bas à droite de l'écran pour créer une copie du script. Cela permettra de conserver le script de référence intact.
- Dans la fenêtre qui apparaît, donnez un nom approprié au script et cliquez sur Dupliquer.
- (Au besoin) Modifiez-le pour répondre à vos besoins spécifiques. Assurez-vous d'enregistrer régulièrement vos modifications pour éviter de les perdre.
- Cliquez sur Enregistrer pour sauvegarder le script.
Création du connecteur
Cette étape consiste à créer un connecteur Scripted API qui utilisera le script créé précédemment. Suivez d'abord les étapes de création d'un connecteur dans Configuration d'un connecteur ICF. Sélectionnez Scripted API comme type de connecteur. Utilisez la même version que celle utilisée pour le script.
Configuration en tant que système cible
Les paramètres suivants sont nécessaires:
| Configuration | Description |
|---|---|
| Script Path | Chemin vers le script Groovy créé précédemment. |
| API URL | URL de l'API à laquelle se connecter. |
| Preferred Authentication Method | Méthode d'authentification à utiliser ("password", "bearer", "userToken" ou "oauth2", 'saml2'). |
| Authentication URL | L'URL servant à l'authentification. |
| Custom Config 1 à 5 | Des configurations personnalisées pouvant être utilisées par le script. |
| Username | Le nom d'utilisateur à utiliser pour l'authentification. |
| Password | Le mot de passe à utiliser pour l'authentification. |
| User Token | Le jeton d'utilisateur à utiliser pour l'authentification. |
| Bearer Token | Le "bearer token" à utiliser pour l'authentification. |
| Custom Secret 1 à 5 | Des secrets personnalisés pouvant être utilisés par le script, qui seront chiffrés et manipulés de façon sécuritaire. |
Configuration avancée
Les paramètres suivants sont nécessaires:
| Configuration | Description |
|---|---|
| Timeout | Délai d'attente en millisecondes. |
| Time between retries | Correspond au temps d'attente avant qu'une requête HTTP ne soit réessayée. Laissez vide pour utiliser 500 ms par défaut |
| Thread Pool Size | Le nombre de threads à utiliser pour les opérations concurrentes. Laissez vide pour utiliser tous les threads disponibles. |
Authentification (oauth2)
Le connecteur peut utilisé le protocole OAuth2 pour s'authentifier auprès de l'API. Cela implique que la configuration nécessite quelques propriétés supplémentaires afin de permettre au flux d'authentification de se dérouler correctement :
| Configuration | Doit Contenir |
|---|---|
| Custom Config 1 | Le grant_type. |
| Custom Config 2 | Le client_id. |
| Custom Secret 1 | Le client_secret. |
| Preferred Authentication Method | oauth2 |
| Authentication URL | L'URL servant à l'authentification. |
Authentification (saml2)
Le connecteur peut utilisé le protocole OAuth2 saml2 pour s'authentifier auprès de l'API. Cela implique que la configuration nécessite quelques propriétés supplémentaires afin de permettre au flux d'authentification de se dérouler correctement :
| Configuration | Doit Contenir |
|---|---|
| Script Path | Chemin vers le script Groovy créé précédemment. |
| API URL | scim https://<api?>.sapsf.com/rest/iam/scim/v2 |
| Preferred Authentication Method | saml2 |
| Authentication URL | L'URL servant à l'authentification. |
| Custom Config 1 | grant_type urn:ietf:params:oauth:grant-type:saml2-bearer |
| Custom Config 2 | client_id |
| Custom Config 3 | company_id |
| Custom Config 4 | token_url https://<api?>.sapsf.com/oauth/token |
| Username | user_id |
| Custom Secret 1 | private_key |
Authentification (Bearer)
| Configuration | Doit contenir |
|---|---|
| Bearer Token | The "Access Token". |
| Preferred Authentication Method | Bearer |
Authentification (password)
| Configuration | Description |
|---|---|
| Authentication method | password |
| Username | Le nom d'utilisateur utilisé pour se connecter à l'API. |
| Password | Le mot de passe utilisé pour se connecter à l'API. |
Authentification (userToken)
| Configuration | Description |
|---|---|
| Authentication method | userToken |
| User Token | Le nom d'utilisateur utilisé pour se connecter à l'API. |
Dépannage
En cas d'erreur, assurez-vous que la configuration est correcte, que le script est valide et que l'API est accessible. Vous pouvez également consulter les journaux pour plus de détails sur l'erreur (voir Visionner les journaux).
Aspects techniques
La meilleure façon de comprendre le fonctionnement du connecteur Scripted API est de consulter les scripts de référence. Ceux-ci contiennent des commentaires qui en expliquent le fonctionnement. De la même manière, il est préférable de développer un nouveau connecteur en se basant sur les scripts de référence.
Schéma de données
Le schéma de données utilisé par les connecteurs Scripted API est composé de "ScriptedAPIObjectClass". Chaque "ScriptedAPIObjectClass" contient des "ScriptedAPIAttribute" qui sont utilisés pour représenter les attributs d'un objet. Par exemple, un utilisateur Workday est représenté par un "WorkerObjectClass" contenant les attributs "EMPLOYEE_ID", "FIRST_NAME", "LAST_NAME", etc.
Fonctions
Le connecteur Scripted API communique avec le script Groovy en appelant certaines fonctions par leur nom. Le script doit donc obligatoirement contenir certaines fonctions afin de fonctionner correctement.
Les fonctions suivantes doivent être implémentées :
| Fonction | Description |
|---|---|
| test | Teste la connexion |
| schema | Retourne le schéma de données |
| search | Recherche des objets |
| create | Crée un objet |
| update | Met à jour un objet |
| delete | Supprime un objet |
| addAttributeValues | Ajoute des valeurs à un attribut d'un objet |
| removeAttributeValues | Supprime des valeurs d'un attribut d'un objet |
Pour consulter les paramètres et des exemples d'implémentation de ces fonctions, veuillez vous référer aux scripts de référence.
Librairies
Les librairies suivantes sont incluses dans le connecteur Scripted API et peuvent être utilisées par les scripts :
| Librairie | Utilisation |
|---|---|
| connid-connector-framework | Framework de connecteur ICF |
| okhttp | Requêtes HTTP |
| org.json | Manipulation de JSON |
Threads
Le connecteur Scripted API prend en charge les opérations concurrentes. Pour ce faire, il utilise un pool de threads. Cela permet d’effectuer plusieurs appels API en parallèle afin d’améliorer les performances. C’est particulièrement utile lors de l’importation d’un grand nombre d’utilisateurs.
Le nombre de threads à utiliser peut être configuré via le paramètre « Thread Pool Size ». Laissez ce paramètre vide pour utiliser tous les threads disponibles.