Table des matières

Introduction

Conditions préalables

Exigences

Composants utilisés

Configurer

1.Créez votre clé API

2. Générer un jeton d'accès API

3.Gérer les listes de destinations

Obtenir toutes les listes de destinations

Obtenir toutes les destinations dans une liste de destinations

Créer une nouvelle liste de destinations

Ajouter des destinations à une liste de destinations

Supprimer une liste de destinations

Supprimer des destinations d'une liste de destinations

Dépannage

Informations connexes

Introduction

Ce document décrit comment gérer des listes de destinations via curl avec l'API d'accès sécurisé.

Conditions préalables

Exigences

Cisco vous recommande de prendre connaissance des rubriques suivantes :

- Accès sécurisé

- API d'accès sécurisé

- enrouler

- Json

Composants utilisés

Les informations contenues dans ce document sont basées sur les versions de matériel et de logiciel suivantes :

- Accès sécurisé

- API d'accès sécurisé

- enrouler

- Json

The information in this document was created from the devices in a specific lab environment. All of the devices used in this document started with a cleared (default) configuration. Si votre réseau est en ligne, assurez-vous de bien comprendre l’incidence possible des commandes.

Configurer

1.Créez votre clé API

Accédez à Secure Access Dashboard.

- Cliquez sur Admin > Api Keys > Add

Créer votre clé API 1

Créer votre clé API 2

- Ajoutez les API Key Name , Description (Optional) , Expiry Date souhaités si nécessaire

Créez votre clé API 3

- Sous Key Scope, sélectionnez Policies puis Développer les stratégies

- Choisissez Destination Lists et Destinations

- Modifiez Scope si nécessaire, sinon conservez comme Read/Write

- Cliquez sur CREATE KEY

Créez votre clé API 4

- Copiez le API Keyet le Key Secret et cliquez sur ACCEPT AND CLOSE

Créez votre clé API 5

Remarque : il n'y a qu'une seule opportunité de copier votre secret API. Secure Access n'enregistre pas votre secret API et vous ne pouvez pas le récupérer après sa création initiale.

2. Générer un jeton d'accès API

Afin de générer le jeton d'accès à l'API, faites une demande d'autorisation de jeton :

Demande d'autorisation de jeton

Utilisez les informations d'identification de l'API d'accès sécurisé que vous avez créées pour votre organisation afin de générer un jeton d'accès à l'API.

- Dans l'exemple curl, remplacez votre clé d'API Secure Access et votre mot de passe secret

curl --user key:secret --request POST --url https://api.sse.cisco.com/auth/v2/token -H Content-Type: application/x-www-form-urlencoded -d grant_type=client_credentials

- Copie et enregistrement du jeton API Bearer généré

Remarque : un jeton d'accès OAuth 2.0 d'accès sécurisé expire dans une heure (3 600 secondes). Il est recommandé de ne pas actualiser un jeton d'accès tant que celui-ci n'est pas presque arrivé à expiration.

3.Gérer les listes de destinations

Il existe plusieurs façons de gérer les listes de destinataires, notamment :

Obtenir toutes les listes de destinations

Ouvrez l’invite de commandes Windows ou Mac terminal pour exécuter la commande :

curl -L --location-trusted --request GET --url https://api.sse.cisco.com/policies/v2/destinationlists -H "Authorization: Bearer YourAccessToken" -H "Content-Type: application/json"

Extrait d'un exemple de sortie :

{"id":23456789,"organizationId":1234567,"access":"none","isGlobal":false,"name":" Test Block list","thirdpartyCategoryId":null,"createdAt":1694070823,"modifiedAt":1702819637,"isMspDefault":false,"markedForDeletion":false,"bundleTypeId":2,"meta": {"destinationCount":2,"domainCount":2,"urlCount":0,"ipv4Count":0,"applicationCount":0}

Notez le destinationListId qui est listé dans le champ "id" de la sortie qui est utilisée plus loin pour les requêtes GET, POST ou DELETE spécifiques à cette liste de destination.

Obtenir toutes les destinations dans une liste de destinations

- Obtenez la destinationListId en utilisant cette étape de mention précédente, Obtenir toutes les listes de destinations

Ouvrez l’invite de commandes Windows ou Mac terminal pour exécuter la commande :

curl -L --location-trusted --request GET --url https://api.sse.cisco.com/policies/v2/destinationlists/destinationListId/destinations -H "Authorization: Bearer YourAccessToken"

Exemple de sortie :

{"status":{"code":200,"text":"OK"},"meta":{"page":1,"limit":100,"total":3},"data": [ {"id":"415214","destination":"cisco.com","type":"domain","comment":null,"createdAt":"2024-02-20 09:15:46"},{"id":"7237895","destination":"www.cisco.com","type":"domain","comment":null,"createdAt":"2024-02-20 10:19:51"},{"id":"29275814","destination":"10.10.10.10","type":"ipv4","comment":null,"createdAt":"2024-02-20 09:15:46"},{"id":"71918495","destination":"www.subdomain.cisco.com/resoucre","type":"url","comment":null,"createdAt":"2024-02-20 10:29:02"} ]}

Créer une nouvelle liste de destinations

Ouvrez l’invite de commandes Windows ou Mac terminal pour exécuter la commande :

curl -L --location-trusted --request POST --url https://api.sse.cisco.com/policies/v2/destinationlists -H "Authorization: Bearer YourAccessToken" -H "Content-Type: application/json" -H "Accept: application/json" -d "{\"access\":\"none\",\"isGlobal\":false,\"name\":\"Destination List Name\"}"

Remarque : remplacez « Destination List Name » par le nom souhaité.

Exemple de sortie :

{"id":23456789,"organizationId":1234567,"access":"none","isGlobal":false,"name":"API List 1","thirdpartyCategoryId":null,"createdAt":1708417690,"modifiedAt":1708417690,"isMspDefault":false,"markedForDeletion":false,"bundleTypeId":1,"meta":{"destinationCount":0}}

Ajouter des destinations à une liste de destinations

- Obtenez la destinationListId en utilisant cette étape de mention précédente, Obtenir toutes les listes de destinations

Ouvrez l’invite de commandes Windows ou Mac terminal pour exécuter la commande :

curl -L --location-trusted --request POST --url https://api.sse.cisco.com/policies/v2/destinationlists/{destinationListId}/destinations -H "Authorization: Bearer YourAccessToken" -H "Content-Type: application/json" -d "[{\"destination":"cisco.com\"},{\"destination\":\"10.10.10.10\"},{\"destination\":\"www.subdomain.cisco.com\/resource\"}]"

Exemple de sortie :

{"status":{"code":200,"text":"OK"},"data":{"id":17804929,"organizationId":1234567,"access":"none","isGlobal":false,"name":"API List 1","thirdpartyCategoryId":null,"createdAt":1708417690,"modifiedAt":1708420546,"isMspDefault":false,"markedForDeletion":false,"bundleTypeId":1,"meta": {"destinationCount":3}}}

Supprimer une liste de destinations

- Obtenez la destinationListId en utilisant cette étape de mention précédente, Obtenir toutes les listes de destinations

Ouvrez l’invite de commandes Windows ou Mac terminal pour exécuter la commande :

curl -L --location-trusted --request DELETE --url https://api.sse.cisco.com/policies/v2/destinationlists/destinationListId -H "Authorization: Bearer YourAccessToken"

Exemple de sortie :

{"status":{"code":200,"text":"OK"},"data":[]}

Supprimer des destinations d'une liste de destinations

- Obtenez la destinationListId en utilisant cette étape de mention précédente, Obtenir toutes les listes de destinations

- Obtenir la id destination particulière dans la liste qui doit être supprimée en utilisant cette étape mentionnée précédemment, Obtenir toutes les destinations dans une liste de destinations

Ouvrez l’invite de commandes Windows ou Mac terminal pour exécuter la commande :

curl -L --location-trusted --request DELETE --url https://api.sse.cisco.com/policies/v2/destinationlists/destinationListId/destinations/remove -H "Authorization: Bearer YourAccessToken" -H "Content-Type: application/json" -H "Accept: application/json" -d "[id1,id2]"

Exemple de sortie :

{"status":{"code":200,"text":"OK"},"data":{"id":17804929,"organizationId":1234567,"access":"none","isGlobal":false,"name":"API List 1","thirdpartyCategoryId":null,"createdAt":1708417690,"modifiedAt":1708525645,"isMspDefault":false,"markedForDeletion":false,"bundleTypeId":1,"meta":{"destinationCount":2}}}

Dépannage

Les points de terminaison de l'API d'accès sécurisé utilisent des codes de réponse HTTP pour indiquer la réussite ou l'échec d'une requête API. En général, les codes de la plage 2xx indiquent la réussite, les codes de la plage 4xx indiquent une erreur qui résulte des informations fournies et les codes de la plage 5xx indiquent des erreurs de serveur. L'approche à adopter pour résoudre le problème dépend du code de réponse reçu :

API REST - Codes de réponse 1

REST API - Codes de réponse 2

En outre, lors du dépannage d'erreurs ou de problèmes liés à l'API, voici les limites de débit à connaître :

- Limites API d'accès sécurisé

Informations connexes

- Guide de l'utilisateur Cisco Secure Access

- Assistance technique de Cisco et téléchargements

- Ajouter des clés d'API Secure Access

- Guide de l'utilisateur développeur