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.
id = tac_plus {
debug = PACKET AUTHEN AUTHOR
access log = /var/log/access.log
accounting log = /var/log/acct.log
host = world {
address = ::/0
prompt = "\nAuthorized Access Only!\nTACACS+ Login\n"
key = devcentral
}
group = adm {
service = ppp {
protocol = ip {
set F5-LTM-User-Info-1 = adm
set F5-LTM-User-Console = 1
set F5-LTM-User-Role = 0
set F5-LTM-User-Partition = all
}
}
}
group = mgr {
service = ppp {
protocol = ip {
set F5-LTM-User-Info-1 = mgr
set F5-LTM-User-Console = 1
set F5-LTM-User-Role = 100
set F5-LTM-User-Partition = all
}
}
}
user = user_admin {
password = clear letmein00
member = adm
}
user = user_mgr {
password = clear letmein00
member = mgr
}
}
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:
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:
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):
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)
Remove the basic authentication (49)
Add the token from the post response to the X-F5-Auth-Token header (50)
Continue further requests like normal. In this example, we’ll create a pool to verify read/write privileges. (1-6, 52-53)
And here’s the code (in python) to make that happen:
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.
Thanks for the article. Been working a lot with the REST API lately. We use it to automate node activities during code deployments and Microsoft update patching (Windows web servers). Running into a number of issues though. My patch process kicks off a number of Powershell jobs - ~25 or as high as 60. All of these jobs have code to get an F5 token, check if the server is a node, if so, disable it, drain connections and then re-enabled when done. Randomly I'm getting response timeouts and it's really impactful. I'm going to have to code around it by doing retries or aborting but we have tested and at the same time, we'll see slowness in the F5 management GUI. Any tips on optimizing or giving more resources and/or troubleshooting the REST endpoint? We are running 11.6. Thanks!
Hi Casey, that's a good question. Do you know if the timeouts are occurring on token acquisition or in the use of the token? If the former, you might share the token across jobs (assuming credentials are the same.) Any helpful errors in /var/log/restjavad.0.log?
Hi Jason,
Thanks for the quick reply! I'm not 100% sure yet on exactly which web request causes this…
This KB article seems to describe exactly what we see. It kind of makes sense because in the last few months we have begun to use the REST API heavily.
https://support.f5.com/kb/en-us/solutions/public/16000/700/sol16751.html
Jason - where do you change that memory setting?
Also - I'm trying to code in a function to grab all the tokens currently on the F5.... I can get a token and write it to variable...but then running this code returns nothing:
function Get-AllF5Tokens
{
[CmdletBinding()]
param(
[Parameter(Mandatory=$True,ValueFromPipeline=$True,ValueFromPipelineByPropertyName=$True)]
$F5LoadBalancer,
[Parameter(Mandatory=$True,ValueFromPipeline=$True,ValueFromPipelineByPropertyName=$True)]
$token
)
$method = "GET"
$uri = "https://$F5LoadBalancer/mgmt/shared/authz/tokens"
Invoke-F5RestMethod -URL $uri -method $method -token $token | Out-Null
i'm sure there's a tmsh method for changing the memory, but I was referencing the GUI System->Provisioning section. Increasing the management provisioning setting from small to medium or large will increase the memory allocated to that function.
Hi, firstly thanks for whole series, this has been helping me a lot. Regarding this token auth stuff, is the code you wrote supposed to be used by python 3.x? I use Python 2.7, but have issues to run your script even without any changes and I get the error like bellow (hopefully it will not be reformated)
Traceback (most recent call last):
File "auth_test.py", line 46, in
token = get_token(b, url_auth, (username, password))
File "auth_test.py", line 15, in get_token
token = bigip.post(url, json.dumps(payload)).json()['token']['token']
KeyError: 'token'
Sorry, it got reformatted, but hopefully you can see the point. My problem is probably related to this line ---> token = bigip.post(url, json.dumps(payload)).json()['token']['token']. Thank you.
I think I don't get anything since python crashes before it does first request in order to get token. And reason why it crash is something I cannot figure out and that is why I asked whether this python script is not written for python v3 :)
I use Python 2.7 and module requests also version 2.7. Thanks, Zdenek
This is working so far, but according https://clouddocs.f5.com/api/icontrol-soap/authentication_with_the_f5_rest_api.html it says that
"No authentication (basic or token-based) is required to submit the particular API call that creates the authentication token."
Has someone get this working without BasicAuth login to get the Token?
Hi Christian, it's technically correct that the basic auth isn't required to generate the token, but the underlying permissions for the URL require auth, which is why it is needed for the first request. This is covered in the release notes.
Hi Jason, ok thanks. But what is the preferred and supported/upgrade-safe solution to disable AuthType for /mgmt, which is at least a ProxyPassReverse to http://localhost:8100/mgmt/ ?
I have done the above exercise and received my token, but the token seems to expire? The toke works while I am actively running GET and POST requests, but if I take a break and come back after some amount of time, the token no longer works and I receive a 401 error with the following:
{
"code": 401,
"message": "X-F5-Auth-Token does not exist.",
Hi ekaleido - there is a default timeout of I think 10 or 15 minutes? Can't recall. You can pass a timeout value in the JSON in the GET. I've only done it doing REST methods via Powershell but I will post the code so you can see. I do some work with our F5 that takes place over several hours (patching and moving servers in and out of pools) so I grab one token with a very long timeout - I' doing 6 hours. In my experience doing frequent calls to the REST API for tokens can be buggy so the less calls the better for me.
Remote authentication does not work with version 11.5 as of today from what i was told by F5 support:
"I did find a known issue (ID471136) that mentions that "REST Framework (including iControl/REST) does not work with BIG-IP remote AuthN providers" so this is probably what you're running into. Reading over that bug report it looks like we changed this in version 12 and in an upcoming hot fix for 11.5.4."
Is it possible to execute a simple curl command to get the token ? Something like this:
curl -k -u admin:admin -X POST https://10.x.x.x/mgmt/shared/authn/login -H "Content-type: application/json"
I am using this and failing to make it work. 401 error but user/password is good. What am I missing ? Suggestions ?
curl -k -X POST -H "Content-Type: application/json" -d "{'admin':'admin'}" https://10.x.x.x/mgmt/shared/authn/login
Here's what's working for me with curl:
curl -k -u user_admin:letmein00 -X POST -H "Content-Type: application/json" -d '{"username":"user_admin", "password":"letmein00", "loginProviderName":"tmos"}' https://172.16.44.15/mgmt/shared/authn/login
I was trying to get a script to work with F5 APIs, but seems I need to authenticate with tacacs first... I was trying to change the script to Powerhsell and obtain the token, but I'm always getting '(401) Not authorized'. What I'm using:
$body= @"
{
"username": "f5_user",
"password": "f5_user_password",
"loginProviderName": "tmos"
}
"@
$token=Invoke-RestMethod -Uri https://f5_ip_addr/mgmt/shared/authn/login -ContentType 'application/json' -Body $body -Method Post
I'm mostly sure I'm missing something, but been reading the F5 site and other sites and can't get to it... can anyone provide some help? The final objective is to be able to make calls via the F5 APIs, to get stuff like node current connections, etc.
I still get a 401 access denied error, think it's something on F5 side. Need to request to the managing team to verify the appropriate privileges.
Anyway, I'm getting around this error using the iControl Powershell module, so should be able to reach the same result and no errors authenticating with the F5.
I've been trying to get this working with 11.5.1 Build 8.0.175 Hotfix HF8. The Authentication User Directory is 'Remote - Active Directory'. Regardless of the loginProviderName I send, the result is 404 Not Found: And, I cannot locate a loginReference uuid or link anywhere.
Is there some active directory specific documentation to which I can refer, or is token retrieval simply not viable in 11.5.1 Build 8.0.175 Hotfix HF8?
I have two different environments where I'm testing this. I'm getting the RESTAPI to work fine with my TMOS 12.1 environment but in 11.6.1 I'm getting 401 error.
I have tried to create a local user on the 11.6.1 system but I don't think this will help because the RESTAPI users does not work when changing the Auth type from Local to my case "Active Directory". The only local accounts that works then is the admin and root accounts.
Are you saying that getting an auth token isn't expected to work at all before 12.0, or just with a LoginReference. I'm getting an auth token without issue in 11.6 HF4.
However, I'm not having any luck setting the timeout to a non-standard value, using a variation of Casey Robertson' JSON. Is that JSON valid, and is it documented anywhere?
tokens will work, but tokens with remote authentication like tacacs+ or ldap are not expected to work. I personally haven't dealt with non-standard timeouts and if not documented in the user guides, I'd question the reliability of doing so.
Finally I was able to run token based auth with big-ip 11.6.1 and ldap auth provider. I found the login provider reference while I was playing with restcurl cm | grep providers | tail -1 and then simply changed the tailing user-group to login:
{
"code": 401,
"message": "Cannot use 'local' auth provider name when system auth source type is not 'local'",
"originalRequestBody": "{\"username\":\"admin\",\"generation\":0,\"lastUpdateMicros\":0}",
"referer": "10.238.90.21",
"restOperationId": 37917423,
"kind": ":resterrorresponse"
}
I've Googled myself cross-eyed and haven't come across anything helpful.
We use RADIUS authentication for access to our F5s. Based on this error message I think that has something to do with this. It seems that it doesn't like me using a local account when the box is configured for RADIUS, but I can't figure out how to change the post to use RADIUS. I've tried using a known good RADIUS account and that fails with the same message. The local account works with basic authentication when doing a GET to something like /mgmt/tm/ltm, but not when I do a POST to the /mgmt/shared/authn/login.
