ABOUT DEVCENTRAL

DevCentral News Technical Forum Technical Articles Technical CrowdSRC Community Guidelines DevCentral EULA Get a Developer Lab License Become a DevCentral MVP

RESOURCES

Product Documentation White Papers Glossary Customer Stories Webinars Free Online Courses F5 Certification LearnF5 Training

SUPPORT

Manage Subscriptions Professional Services Professional Services Create a Service Request Software Downloads Support Portal

PARTNERS

Find a Reseller Partner Technology Alliances Become an F5 Partner Login to Partner Central

---

©2024 F5, Inc. All rights reserved.

iControl REST. It’s iControl SOAP’s baby, brother, introduced back in TMOS version 11.4 as an early access feature but released fully in version 11.5.

Several articles on basic usage have been written on iControl REST so the intent here isn’t basic use, but rather to demystify some of the finer details of using the API. This article will cover the details on how to retrieve and use an authentication token from the BIG-IP using iControl REST and the python programming language. This token is used in place of basic authentication on API calls, which is a requirement for external authentication. Note that for configuration changes, version 12.0 or higher is required as earlier versions will trigger an un-authorized error.

The Fine Print

The details of the token provider are here in the wiki. We’ll focus on a provider not listed there: tmos. This provider instructs the API interface to use the provider that is configured in tmos. For this article, I’ve configured a tacacs server and the BIG-IP with custom remote roles as shown below to show BIG-IP version 12’s iControl REST support for remote authentication and authorization. Details for how this configuration works can be found in the tacacs+ article I wrote a while back.

BIG-IP tacacs+ configuration

auth remote-role {\n    role-info {\n        adm {\n            attribute F5-LTM-User-Info-1=adm\n            console %F5-LTM-User-Console\n            line-order 1\n            role %F5-LTM-User-Role\n            user-partition %F5-LTM-User-Partition\n        }\n        mgr {\n            attribute F5-LTM-User-Info-1=mgr\n            console %F5-LTM-User-Console\n            line-order 2\n            role %F5-LTM-User-Role\n            user-partition %F5-LTM-User-Partition\n        }\n    }\n}\nauth remote-user { }\nauth source {\n    type tacacs\n}\nauth tacacs system-auth {\n    debug enabled\n    protocol ip\n    secret $M$Zq$T2SNeIqxi29CAfShLLqw8Q==\n    servers { 172.16.44.20 }\n    service ppp\n}

Tacacs+ Server configuration

id = tac_plus {\ndebug = PACKET AUTHEN AUTHOR\n\naccess log = /var/log/access.log\naccounting log = /var/log/acct.log\n\nhost = world {\naddress = ::/0\nprompt = \"\\nAuthorized Access Only!\\nTACACS+ Login\\n\"\nkey = devcentral\n}\n\ngroup = adm {\nservice = ppp {\nprotocol = ip {\nset F5-LTM-User-Info-1 = adm\nset F5-LTM-User-Console = 1\nset F5-LTM-User-Role = 0\nset F5-LTM-User-Partition = all\n}\n}\n}\n\n    group = mgr {\n    service = ppp {\n        protocol = ip {\n            set F5-LTM-User-Info-1 = mgr\n            set F5-LTM-User-Console = 1\n           set F5-LTM-User-Role = 100\n            set F5-LTM-User-Partition = all\n            }\n        }\n    }\n\nuser = user_admin {\npassword = clear letmein00\nmember = adm\n}\nuser = user_mgr {\npassword = clear letmein00\nmember = mgr\n}\n}

 Basic Requirements

Before we look at code, however, let’s take a look at the json payload requirements, followed by response data from a query using Chrome’s Advanced REST Client plugin. First, since we are sending json payload, we need to add the Content-Type: application/json header to the query. The payload we are sending with the post looks like this:

{\n\"username\": \"remote_auth_user\",\n\"password\": \"remote_auth_password\",\n\"loginProviderName\": \"tmos\"\n}

You submit the same remote authentication credentials in the initial basic authentication as well, no need to have access to the default admin account credentials. A successful query for a token returns data like this:

{\nusername: \"user_admin\"\nloginReference: {\nlink: \"https://localhost/mgmt/cm/system/authn/providers/tmos/1f44a60e-11a7-3c51-a49f-82983026b41b/login\"\n}-\ntoken: {\nuuid: \"4d1bd79f-dca7-406b-8627-3ad262628f31\"\nname: \"5C0F982A0BF37CBE5DE2CB8313102A494A4759E5704371B77D7E35ADBE4AAC33184EB3C5117D94FAFA054B7DB7F02539F6550F8D4FA25C4BFF1145287E93F70D\"\ntoken: \"5C0F982A0BF37CBE5DE2CB8313102A494A4759E5704371B77D7E35ADBE4AAC33184EB3C5117D94FAFA054B7DB7F02539F6550F8D4FA25C4BFF1145287E93F70D\"\nuserName: \"user_admin\"\nuser: {\nlink: \"https://localhost/mgmt/cm/system/authn/providers/tmos/1f44a60e-11a7-3c51-a49f-82983026b41b/users/34ba3932-bfa3-4738-9d55-c81a1c783619\"\n}-\ngroupReferences: [1]\n0:  {\nlink: \"https://localhost/mgmt/cm/system/authn/providers/tmos/1f44a60e-11a7-3c51-a49f-82983026b41b/user-groups/21232f29-7a57-35a7-8389-4a0e4a801fc3\"\n}-\n-\ntimeout: 1200\nstartTime: \"2015-11-17T19:38:50.415-0800\"\naddress: \"172.16.44.1\"\npartition: \"[All]\"\ngeneration: 1\nlastUpdateMicros: 1447817930414518\nexpirationMicros: 1447819130415000\nkind: \"shared:authz:tokens:authtokenitemstate\"\nselfLink: \"https://localhost/mgmt/shared/authz/tokens/4d1bd79f-dca7-406b-8627-3ad262628f31\"\n}-\ngeneration: 0\nlastUpdateMicros: 0\n}

Among many other fields, you can see the token field with a very long hexadecimal token. That’s what we need to authenticate future API calls.

Requesting the token programmatically

In order to request the token, you first have to supply basic auth credentials like normal. This is currently required to access the /mgmt/shared/authn/login API location. The basic workflow is as follows (with line numbers from the code below in parentheses):

\n
1. Make a POST request to BIG-IP with basic authentication header and json payload with username, password, and the login provider (9-16, 41-47)
\n
2. Remove the basic authentication (49)
\n
3. Add the token from the post response to the X-F5-Auth-Token header (50)
\n
4. Continue further requests like normal. In this example, we’ll create a pool to verify read/write privileges. (1-6, 52-53)
\n

And here’s the code (in python) to make that happen:

def create_pool(bigip, url, pool):\n    payload = {}\n    payload['name'] = pool\n\n    pool_config = bigip.post(url, json.dumps(payload)).json()\n    return pool_config\n\n\ndef get_token(bigip, url, creds):\n    payload = {}\n    payload['username'] = creds[0]\n    payload['password'] = creds[1]\n    payload['loginProviderName'] = 'tmos'\n\n    token = bigip.post(url, json.dumps(payload)).json()['token']['token']\n    return token\n\n\nif __name__ == \"__main__\":\n    import os, requests, json, argparse, getpass\n    requests.packages.urllib3.disable_warnings()\n\n    parser = argparse.ArgumentParser(description='Remote Authentication Test - Create Pool')\n\n    parser.add_argument(\"host\", help='BIG-IP IP or Hostname', )\n    parser.add_argument(\"username\", help='BIG-IP Username')\n    parser.add_argument(\"poolname\", help='Key/Cert file names (include the path.)')\n    args = vars(parser.parse_args())\n\n    hostname = args['host']\n    username = args['username']\n    poolname = args['poolname']\n\n    print \"%s, enter your password: \" % args['username'],\n    password = getpass.getpass()\n\n    url_base = 'https://%s/mgmt' % hostname\n    url_auth = '%s/shared/authn/login' % url_base\n    url_pool = '%s/tm/ltm/pool' % url_base\n\n    b = requests.session()\n    b.headers.update({'Content-Type':'application/json'})\n    b.auth = (username, password)\n    b.verify = False\n\n    token = get_token(b, url_auth, (username, password))\n    print '\\nToken: %s\\n' % token\n\n    b.auth = None\n    b.headers.update({'X-F5-Auth-Token': token})\n\n    response = create_pool(b, url_pool, poolname)\n    print '\\nNew Pool: %s\\n' % response

Running this script from the command line, we get the following response:

FLD-ML-RAHM:scripts rahm$ python remoteauth.py 172.16.44.15 user_admin myNewestPool1\nPassword: user_admin, enter your password:\n \nToken: 2C61FE257C7A8B6E49C74864240E8C3D3592FDE9DA3007618CE11915F1183BF9FBAF00D09F61DE15FCE9CAB2DC2ACC165CBA3721362014807A9BF4DEA90BB09F\n\n\nNew Pool: {u'generation': 453, u'minActiveMembers': 0, u'ipTosToServer': u'pass-through', u'loadBalancingMode': u'round-robin', u'allowNat': u'yes', u'queueDepthLimit': 0, u'membersReference': {u'isSubcollection': True, u'link': u'https://localhost/mgmt/tm/ltm/pool/~Common~myNewestPool1/members?ver=12.0.0'}, u'minUpMembers': 0, u'slowRampTime': 10, u'minUpMembersAction': u'failover', u'minUpMembersChecking': u'disabled', u'queueTimeLimit': 0, u'linkQosToServer': u'pass-through', u'queueOnConnectionLimit': u'disabled', u'fullPath': u'myNewestPool1', u'kind': u'tm:ltm:pool:poolstate', u'name': u'myNewestPool1', u'allowSnat': u'yes', u'ipTosToClient': u'pass-through', u'reselectTries': 0, u'selfLink': u'https://localhost/mgmt/tm/ltm/pool/myNewestPool1?ver=12.0.0', u'serviceDownAction': u'none', u'ignorePersistedWeight': u'disabled', u'linkQosToClient': u'pass-through'}\n

You can test this out in the Chrome Advanced Rest Client plugin, or from the command line with curl or any other language supporting REST clients as well, I just use python for the examples well, because I like it. I hope you all are digging into iControl REST! What questions do you have? What else would you like clarity on? Drop a comment below.

iControl REST. It’s iControl SOAP’s baby, brother, introduced back in TMOS version 11.4 as an early access feature but released fully in version 11.5.

Several articles on basic usage have been written on iControl REST so the intent here isn’t basic use, but rather to demystify some of the finer details of using the API. This article will cover the details on how to retrieve and use an authentication token from the BIG-IP using iControl REST and the python programming language. This token is used in place of basic authentication on API calls, which is a requirement for external authentication. Note that for configuration changes, version 12.0 or higher is required as earlier versions will trigger an un-authorized error.

The Fine Print

The details of the token provider are here in the wiki. We’ll focus on a provider not listed there: tmos. This provider instructs the API interface to use the provider that is configured in tmos. For this article, I’ve configured a tacacs server and the BIG-IP with custom remote roles as shown below to show BIG-IP version 12’s iControl REST support for remote authentication and authorization. Details for how this configuration works can be found in the tacacs+ article I wrote a while back.

BIG-IP tacacs+ configuration

auth remote-role {\n    role-info {\n        adm {\n            attribute F5-LTM-User-Info-1=adm\n            console %F5-LTM-User-Console\n            line-order 1\n            role %F5-LTM-User-Role\n            user-partition %F5-LTM-User-Partition\n        }\n        mgr {\n            attribute F5-LTM-User-Info-1=mgr\n            console %F5-LTM-User-Console\n            line-order 2\n            role %F5-LTM-User-Role\n            user-partition %F5-LTM-User-Partition\n        }\n    }\n}\nauth remote-user { }\nauth source {\n    type tacacs\n}\nauth tacacs system-auth {\n    debug enabled\n    protocol ip\n    secret $M$Zq$T2SNeIqxi29CAfShLLqw8Q==\n    servers { 172.16.44.20 }\n    service ppp\n}

Tacacs+ Server configuration

id = tac_plus {\ndebug = PACKET AUTHEN AUTHOR\n\naccess log = /var/log/access.log\naccounting log = /var/log/acct.log\n\nhost = world {\naddress = ::/0\nprompt = \"\\nAuthorized Access Only!\\nTACACS+ Login\\n\"\nkey = devcentral\n}\n\ngroup = adm {\nservice = ppp {\nprotocol = ip {\nset F5-LTM-User-Info-1 = adm\nset F5-LTM-User-Console = 1\nset F5-LTM-User-Role = 0\nset F5-LTM-User-Partition = all\n}\n}\n}\n\n    group = mgr {\n    service = ppp {\n        protocol = ip {\n            set F5-LTM-User-Info-1 = mgr\n            set F5-LTM-User-Console = 1\n           set F5-LTM-User-Role = 100\n            set F5-LTM-User-Partition = all\n            }\n        }\n    }\n\nuser = user_admin {\npassword = clear letmein00\nmember = adm\n}\nuser = user_mgr {\npassword = clear letmein00\nmember = mgr\n}\n}

 Basic Requirements

Before we look at code, however, let’s take a look at the json payload requirements, followed by response data from a query using Chrome’s Advanced REST Client plugin. First, since we are sending json payload, we need to add the Content-Type: application/json header to the query. The payload we are sending with the post looks like this:

{\n\"username\": \"remote_auth_user\",\n\"password\": \"remote_auth_password\",\n\"loginProviderName\": \"tmos\"\n}

You submit the same remote authentication credentials in the initial basic authentication as well, no need to have access to the default admin account credentials. A successful query for a token returns data like this:

{\nusername: \"user_admin\"\nloginReference: {\nlink: \"https://localhost/mgmt/cm/system/authn/providers/tmos/1f44a60e-11a7-3c51-a49f-82983026b41b/login\"\n}-\ntoken: {\nuuid: \"4d1bd79f-dca7-406b-8627-3ad262628f31\"\nname: \"5C0F982A0BF37CBE5DE2CB8313102A494A4759E5704371B77D7E35ADBE4AAC33184EB3C5117D94FAFA054B7DB7F02539F6550F8D4FA25C4BFF1145287E93F70D\"\ntoken: \"5C0F982A0BF37CBE5DE2CB8313102A494A4759E5704371B77D7E35ADBE4AAC33184EB3C5117D94FAFA054B7DB7F02539F6550F8D4FA25C4BFF1145287E93F70D\"\nuserName: \"user_admin\"\nuser: {\nlink: \"https://localhost/mgmt/cm/system/authn/providers/tmos/1f44a60e-11a7-3c51-a49f-82983026b41b/users/34ba3932-bfa3-4738-9d55-c81a1c783619\"\n}-\ngroupReferences: [1]\n0:  {\nlink: \"https://localhost/mgmt/cm/system/authn/providers/tmos/1f44a60e-11a7-3c51-a49f-82983026b41b/user-groups/21232f29-7a57-35a7-8389-4a0e4a801fc3\"\n}-\n-\ntimeout: 1200\nstartTime: \"2015-11-17T19:38:50.415-0800\"\naddress: \"172.16.44.1\"\npartition: \"[All]\"\ngeneration: 1\nlastUpdateMicros: 1447817930414518\nexpirationMicros: 1447819130415000\nkind: \"shared:authz:tokens:authtokenitemstate\"\nselfLink: \"https://localhost/mgmt/shared/authz/tokens/4d1bd79f-dca7-406b-8627-3ad262628f31\"\n}-\ngeneration: 0\nlastUpdateMicros: 0\n}

Among many other fields, you can see the token field with a very long hexadecimal token. That’s what we need to authenticate future API calls.

Requesting the token programmatically

In order to request the token, you first have to supply basic auth credentials like normal. This is currently required to access the /mgmt/shared/authn/login API location. The basic workflow is as follows (with line numbers from the code below in parentheses):

\n
1. Make a POST request to BIG-IP with basic authentication header and json payload with username, password, and the login provider (9-16, 41-47)
\n
2. Remove the basic authentication (49)
\n
3. Add the token from the post response to the X-F5-Auth-Token header (50)
\n
4. Continue further requests like normal. In this example, we’ll create a pool to verify read/write privileges. (1-6, 52-53)
\n

And here’s the code (in python) to make that happen:

def create_pool(bigip, url, pool):\n    payload = {}\n    payload['name'] = pool\n\n    pool_config = bigip.post(url, json.dumps(payload)).json()\n    return pool_config\n\n\ndef get_token(bigip, url, creds):\n    payload = {}\n    payload['username'] = creds[0]\n    payload['password'] = creds[1]\n    payload['loginProviderName'] = 'tmos'\n\n    token = bigip.post(url, json.dumps(payload)).json()['token']['token']\n    return token\n\n\nif __name__ == \"__main__\":\n    import os, requests, json, argparse, getpass\n    requests.packages.urllib3.disable_warnings()\n\n    parser = argparse.ArgumentParser(description='Remote Authentication Test - Create Pool')\n\n    parser.add_argument(\"host\", help='BIG-IP IP or Hostname', )\n    parser.add_argument(\"username\", help='BIG-IP Username')\n    parser.add_argument(\"poolname\", help='Key/Cert file names (include the path.)')\n    args = vars(parser.parse_args())\n\n    hostname = args['host']\n    username = args['username']\n    poolname = args['poolname']\n\n    print \"%s, enter your password: \" % args['username'],\n    password = getpass.getpass()\n\n    url_base = 'https://%s/mgmt' % hostname\n    url_auth = '%s/shared/authn/login' % url_base\n    url_pool = '%s/tm/ltm/pool' % url_base\n\n    b = requests.session()\n    b.headers.update({'Content-Type':'application/json'})\n    b.auth = (username, password)\n    b.verify = False\n\n    token = get_token(b, url_auth, (username, password))\n    print '\\nToken: %s\\n' % token\n\n    b.auth = None\n    b.headers.update({'X-F5-Auth-Token': token})\n\n    response = create_pool(b, url_pool, poolname)\n    print '\\nNew Pool: %s\\n' % response

Running this script from the command line, we get the following response:

FLD-ML-RAHM:scripts rahm$ python remoteauth.py 172.16.44.15 user_admin myNewestPool1\nPassword: user_admin, enter your password:\n \nToken: 2C61FE257C7A8B6E49C74864240E8C3D3592FDE9DA3007618CE11915F1183BF9FBAF00D09F61DE15FCE9CAB2DC2ACC165CBA3721362014807A9BF4DEA90BB09F\n\n\nNew Pool: {u'generation': 453, u'minActiveMembers': 0, u'ipTosToServer': u'pass-through', u'loadBalancingMode': u'round-robin', u'allowNat': u'yes', u'queueDepthLimit': 0, u'membersReference': {u'isSubcollection': True, u'link': u'https://localhost/mgmt/tm/ltm/pool/~Common~myNewestPool1/members?ver=12.0.0'}, u'minUpMembers': 0, u'slowRampTime': 10, u'minUpMembersAction': u'failover', u'minUpMembersChecking': u'disabled', u'queueTimeLimit': 0, u'linkQosToServer': u'pass-through', u'queueOnConnectionLimit': u'disabled', u'fullPath': u'myNewestPool1', u'kind': u'tm:ltm:pool:poolstate', u'name': u'myNewestPool1', u'allowSnat': u'yes', u'ipTosToClient': u'pass-through', u'reselectTries': 0, u'selfLink': u'https://localhost/mgmt/tm/ltm/pool/myNewestPool1?ver=12.0.0', u'serviceDownAction': u'none', u'ignorePersistedWeight': u'disabled', u'linkQosToClient': u'pass-through'}\n

You can test this out in the Chrome Advanced Rest Client plugin, or from the command line with curl or any other language supporting REST clients as well, I just use python for the examples well, because I like it. I hope you all are digging into iControl REST! What questions do you have? What else would you like clarity on? Drop a comment below.