iControlREST Auth Token and Transaction Example (Postman)

Problem this snippet solves:

This is an example set for iControlREST which generates an Authentication Token and a Transaction session to add a new Data Group.

This is only a single change but you can add many changes into the Transaction before VALIDATING and committing them.

Steps taken:

1. Get Auth Token - Request to generate a new Authentication Token and saves into the Environment variable X-F5-Auth-Token
2. Extend Token Timeout - Increases the timeout value of the Auth Token, not always needed but good if you are running the command manually
3. Get New Transaction - Request to generate a new Transaction session and saves into the Environment variable Coordination-Id
4. POST new DG in Transaction - Creates a new Data Group
5. Get Transaction Commands - Optional request to list all the commands and the order in the transaction
6. Commit Transaction - Sends VALIDATING request to validate and commit the commends
7. Get DG test - Optional to get the Data Group to confirm it has been created

Find more information about iControlREST Transactions here https://devcentral.f5.com/s/articles/demystifying-icontrol-rest-part-7-understanding-transactions-21404 and in the user guides https://clouddocs.f5.com/api/icontrol-rest/

How to use this snippet:

Download and install Postman https://www.getpostman.com/downloads/

Save the below JSON to a file and import as a new Postman Collection (see https://learning.getpostman.com/docs/postman/collections/intro_to_collections/ and https://learning.getpostman.com/docs/postman/collections/data_formats/#importing-postman-data).

Finally setup a new Environment (https://learning.getpostman.com/docs/postman/environments_and_globals/manage_environments/) within Postman and ensure you have the following elements:

• hostIP - the Management IP of the F5 BIG-IP system
• hostName - the Hostname of the F5 BIG-IP system
• f5user - the username used to generate an Authentication Token
• f5pass - the password used to generate an Authentication Token
• X-F5-Auth-Token - leave blank will auto populate
• Coordination-Id - leave blank will auto populate

e.g.

Then you can run the Postman collection one request at a time or run via Postman's Collection Runner (https://learning.getpostman.com/docs/postman/collection_runs/using_environments_in_collection_runs).

Code :

{
  "info": {
    "_postman_id": "67195ea2-5ac0-4599-a650-5951b1bc1184",
    "name": "iControl Transaction Example",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "item": [
    {
      "name": "Get Auth Token",
      "event": [
        {
          "listen": "test",
          "script": {
            "id": "6e3f6680-4199-4c4a-a210-272b4d2eef38",
            "exec": [
              "tests[\"Status code is 200\"] = responseCode.code === 200;",
              "var jsonData = JSON.parse(responseBody);",
              "postman.setEnvironmentVariable(\"X-F5-Auth-Token\", jsonData.token.name);",
              "",
              ""
            ],
            "type": "text/javascript"
          }
        }
      ],
      "request": {
        "method": "POST",
        "header": [
          {
            "key": "Host",
            "type": "text",
            "value": "{{hostName}}"
          },
          {
            "key": "Content-Type",
            "value": "application/json"
          }
        ],
        "body": {
          "mode": "raw",
          "raw": "{\r\n\t\"username\":\"{{f5user}}\",\r\n\t\"password\":\"{{f5pass}}\",\r\n\t\"loginProviderName\": \"tmos\"\r\n}"
        },
        "url": {
          "raw": "https://{{hostIP}}/mgmt/shared/authn/login",
          "protocol": "https",
          "host": [
            "{{hostIP}}"
          ],
          "path": [
            "mgmt",
            "shared",
            "authn",
            "login"
          ]
        }
      },
      "response": []
    },
    {
      "name": "Extend Token Timeout Copy",
      "event": [
        {
          "listen": "test",
          "script": {
            "id": "3bcdcdc6-fcad-46db-b9c0-4d7a8e8e1a69",
            "exec": [
              "var jsonData = JSON.parse(responseBody);",
              "tests[\"Status code is 200\"] = responseCode.code === 200;",
              "tests[\"Token has been set\"] = jsonData.timeout == 36000;",
              "tests[\"Token is valid\"] = jsonData.userName === postman.getEnvironmentVariable(\"f5user\");",
              ""
            ],
            "type": "text/javascript"
          }
        }
      ],
      "request": {
        "method": "PATCH",
        "header": [
          {
            "key": "Host",
            "value": "{{hostName}}",
            "type": "text"
          },
          {
            "key": "Content-Type",
            "value": "application/json"
          },
          {
            "key": "X-F5-Auth-Token",
            "value": "{{X-F5-Auth-Token}}"
          }
        ],
        "body": {
          "mode": "raw",
          "raw": "{\n\t\"timeout\":\"36000\"\n}"
        },
        "url": {
          "raw": "https://{{hostIP}}/mgmt/shared/authz/tokens/{{X-F5-Auth-Token}}",
          "protocol": "https",
          "host": [
            "{{hostIP}}"
          ],
          "path": [
            "mgmt",
            "shared",
            "authz",
            "tokens",
            "{{X-F5-Auth-Token}}"
          ]
        }
      },
      "response": []
    },
    {
      "name": "Get New Transaction",
      "event": [
        {
          "listen": "test",
          "script": {
            "id": "cb847d93-2c3a-4990-8242-020d95532be6",
            "exec": [
              "var jsonRsponse = JSON.parse(responseBody)",
              "pm.environment.set(\"Coordination-Id\", jsonRsponse.transId);",
              "",
              ""
            ],
            "type": "text/javascript"
          }
        }
      ],
      "request": {
        "auth": {
          "type": "noauth"
        },
        "method": "POST",
        "header": [
          {
            "key": "Host",
            "value": "{{hostName}}",
            "type": "text"
          },
          {
            "key": "content-type",
            "value": "application/json",
            "type": "text"
          },
          {
            "key": "X-F5-Auth-Token",
            "value": "{{X-F5-Auth-Token}}",
            "type": "text"
          }
        ],
        "body": {
          "mode": "raw",
          "raw": "{}"
        },
        "url": {
          "raw": "https://{{hostIP}}/mgmt/tm/transaction/",
          "protocol": "https",
          "host": [
            "{{hostIP}}"
          ],
          "path": [
            "mgmt",
            "tm",
            "transaction",
            ""
          ]
        }
      },
      "response": []
    },
    {
      "name": "POST new DG in Transaction",
      "request": {
        "auth": {
          "type": "noauth"
        },
        "method": "POST",
        "header": [
          {
            "key": "Host",
            "value": "{{hostName}}",
            "type": "text"
          },
          {
            "key": "content-type",
            "value": "application/json",
            "type": "text"
          },
          {
            "key": "X-F5-Auth-Token",
            "value": "{{X-F5-Auth-Token}}",
            "type": "text"
          },
          {
            "key": "X-F5-REST-Coordination-Id",
            "value": "{{Coordination-Id}}",
            "type": "text"
          }
        ],
        "body": {
          "mode": "raw",
          "raw": "{\n    \"partition\": \"Common\",\n    \"name\": \"url_filter_dg\",\n    \"records\": [\n        {\n            \"name\": \"/data\",\n            \"data\": \"Allow\"\n        },\n        {\n            \"name\": \"/filter\",\n            \"data\": \"Block\"\n        },\n        {\n            \"name\": \"/hello\",\n            \"data\": \"Black\"\n        },\n        {\n            \"name\": \"/login\",\n            \"data\": \"Allow\"\n        }\n    ],\n    \"type\":\"string\"\n}"
        },
        "url": {
          "raw": "https://{{hostIP}}/mgmt/tm/ltm/data-group/internal",
          "protocol": "https",
          "host": [
            "{{hostIP}}"
          ],
          "path": [
            "mgmt",
            "tm",
            "ltm",
            "data-group",
            "internal"
          ]
        }
      },
      "response": []
    },
    {
      "name": "PUT DG in Transaction",
      "request": {
        "auth": {
          "type": "basic",
          "basic": [
            {
              "key": "password",
              "value": "admin",
              "type": "string"
            },
            {
              "key": "username",
              "value": "admin",
              "type": "string"
            }
          ]
        },
        "method": "PUT",
        "header": [
          {
            "key": "Host",
            "value": "{{hostName}}",
            "type": "text"
          },
          {
            "key": "content-type",
            "value": "application/json",
            "type": "text"
          },
          {
            "key": "X-F5-REST-Coordination-Id",
            "value": "{{Coordination-Id}}",
            "type": "text"
          }
        ],
        "body": {
          "mode": "raw",
          "raw": "{\n    \"records\": [\n        {\n            \"name\": \"/data\",\n            \"data\": \"Allow\"\n        },\n        {\n            \"name\": \"/filter\",\n            \"data\": \"Block\"\n        },\n        {\n            \"name\": \"/hello\",\n            \"data\": \"Allow\"\n        },\n        {\n            \"name\": \"/login\",\n            \"data\": \"Allow\"\n        }\n    ]\n}"
        },
        "url": {
          "raw": "https://{{hostIP}}/mgmt/tm/ltm/data-group/internal/~common~url_filter_dg",
          "protocol": "https",
          "host": [
            "{{hostIP}}"
          ],
          "path": [
            "mgmt",
            "tm",
            "ltm",
            "data-group",
            "internal",
            "~common~url_filter_dg"
          ]
        }
      },
      "response": []
    },
    {
      "name": "Get Transaction Commands",
      "event": [
        {
          "listen": "test",
          "script": {
            "id": "cb847d93-2c3a-4990-8242-020d95532be6",
            "exec": [
              "",
              "",
              ""
            ],
            "type": "text/javascript"
          }
        }
      ],
      "protocolProfileBehavior": {
        "disableBodyPruning": true
      },
      "request": {
        "auth": {
          "type": "noauth"
        },
        "method": "GET",
        "header": [
          {
            "key": "Host",
            "value": "{{hostName}}",
            "type": "text"
          },
          {
            "key": "content-type",
            "value": "application/json",
            "type": "text"
          },
          {
            "key": "X-F5-Auth-Token",
            "value": "{{X-F5-Auth-Token}}",
            "type": "text"
          }
        ],
        "body": {
          "mode": "raw",
          "raw": "{}"
        },
        "url": {
          "raw": "https://{{hostIP}}/mgmt/tm/transaction/{{Coordination-Id}}/commands",
          "protocol": "https",
          "host": [
            "{{hostIP}}"
          ],
          "path": [
            "mgmt",
            "tm",
            "transaction",
            "{{Coordination-Id}}",
            "commands"
          ]
        }
      },
      "response": []
    },
    {
      "name": "Commit Transaction",
      "event": [
        {
          "listen": "test",
          "script": {
            "id": "8308b285-b26b-4ddf-8ea9-e4f420cccd42",
            "exec": [
              "var jsonResponse = JSON.parse(responseBody)",
              "",
              "pm.test(\"Transaction status is COMPLETED\", function () {",
              "",
              "    pm.expect(jsonResponse.state == \"COMPLETED\");",
              "});"
            ],
            "type": "text/javascript"
          }
        }
      ],
      "request": {
        "auth": {
          "type": "noauth"
        },
        "method": "PATCH",
        "header": [
          {
            "key": "Host",
            "value": "{{hostName}}",
            "type": "text"
          },
          {
            "key": "content-type",
            "value": "application/json",
            "type": "text"
          },
          {
            "key": "X-F5-Auth-Token",
            "value": "{{X-F5-Auth-Token}}",
            "type": "text"
          },
          {
            "key": "X-F5-REST-Coordination-Id",
            "value": "1557741207510527",
            "type": "text",
            "disabled": true
          }
        ],
        "body": {
          "mode": "raw",
          "raw": "{ \"state\":\"VALIDATING\" }"
        },
        "url": {
          "raw": "https://{{hostIP}}/mgmt/tm/transaction/{{Coordination-Id}}",
          "protocol": "https",
          "host": [
            "{{hostIP}}"
          ],
          "path": [
            "mgmt",
            "tm",
            "transaction",
            "{{Coordination-Id}}"
          ]
        }
      },
      "response": []
    },
    {
      "name": "Get DG test",
      "request": {
        "auth": {
          "type": "noauth"
        },
        "method": "GET",
        "header": [
          {
            "key": "Host",
            "value": "{{hostName}}",
            "type": "text"
          },
          {
            "key": "X-F5-Auth-Token",
            "value": "{{X-F5-Auth-Token}}",
            "type": "text"
          }
        ],
        "body": {
          "mode": "raw",
          "raw": ""
        },
        "url": {
          "raw": "https://{{hostIP}}/mgmt/tm/ltm/data-group/internal/~common~url_filter_dg",
          "protocol": "https",
          "host": [
            "{{hostIP}}"
          ],
          "path": [
            "mgmt",
            "tm",
            "ltm",
            "data-group",
            "internal",
            "~common~url_filter_dg"
          ]
        }
      },
      "response": []
    }
  ]
}

Tested this on version: