iControl REST Authentication Token Management

Introduction

The Token Authentication (hereinafter "token") is an iControl REST authentication method introduced in BIG-IP v12.0. It allows accesses for not only local users but also remotes users (such as RADIUS or LDAP) unlike the conventional Basic Authentication (uses HTTP's Authorization header) which is only good for local users.

This article describes methods for managing tokens.

The example calls shown here use curl. The command options used are

-s: silent - Do not show the progress meter.
-k: insecure - Does not verify the server certificate.
-u: user - User name and passwords (e.g., admin:admin).
-H: header - Additional HTTP request header. The X-F5-Auth-Token header is used to provide the token.
-d: data - The data to POST/PATCH.

The following variables embedded in the example calls represents:

$HOST - BIG-IP management IP.
$TOKEN - A token (e.g., ABCDEFGHIJKLMNOPQRSTUVWXYZ)

Things you should know about token

When you use tokens, remember the following characteristics:

1. A token expires

By default, a token expires after 1,200s (20 min). You can extend the token lifespan by modifying the "timeout" property in the token object. The maximum lifespan is 36,000s (10 hrs). If you attempt to change the timeout property longer than the maximum, you will get the 406 error "Auth-token absolute timeout (36000 seconds) exceeded".

2. Limited number of tokens

Each user can request up to 100 tokens at any point in time. Your 101-th token request will be rejected with the 400 error "Bad Request: user xxx has reached maximum active login tokens". You need to either wait for the tokens to expire or explicitly delete them. This limitation applies to all users, irrespective of local/remote and roles (even administrator). The only exception is the "admin" user.

3. You can only manage your own token

You cannot view (GET), modify (PATCH) or delete (DELETE) a token generated for somebody else. Such requests will be rejected with the 400 error "Authorization failed". If you need to manage tokens for other users, use the user with an appropriate role (e.g., administrator).

Token management

1. Get a token

To obtain a token for user foo (and his password is fooPass), run the following call.

curl -sk https://$HOST/mgmt/shared/authn/login -X POST -H "Content-Type: application/json" \
 -d '{"username":"foo", "password":"fooPass", "loginProviderName":"tmos"}'

An example output is shown below:

{
  "generation": 0,
  "lastUpdateMicros": 0,
  "loginProviderName": "tmos",
  "loginReference": {
    "link": "https://localhost/mgmt/cm/system/authn/providers/tmos/1f44a60e-11a7-3c51-a49f-82983026b41b/login"
  },
  "token": {
    "address": "192.168.184.10",
    "authProviderName": "tmos",
    "expirationMicros": 1588199929471000,
    "generation": 1,
    "kind": "shared:authz:tokens:authtokenitemstate",
    "lastUpdateMicros": 1588198729470534,
    "name": "DCECRMQ66WOSPTSGPR7OAGG5SI",
    "partition": "[All]",
    "selfLink": "https://localhost/mgmt/shared/authz/tokens/DCECRMQ66WOSPTSGPR7OAGG5SI",
    "startTime": "2020-04-30T10:18:49.471+1200",
    "timeout": 1200,
    "token": "DCECRMQ66WOSPTSGPR7OAGG5SI",
    "user": {
      "link": "https://localhost/mgmt/cm/system/authn/providers/tmos/1f44a60e-11a7-3c51-a49f-82983026b41b/users/acbd18db-4cc2-385c-adef-654fccc4a4d8"
    },
    "userName": "foo"
  },
  "username": "foo"
}

The "token" or "name" property inside the "token" property shows the token. It is a 26 character long string consisting of uppercase alphabets and numbers. In the above example, it is DCECRMQ66WOSPTSGPR7OAGG5SI.

2. Find the time when your token will expire

In the output above, the "timeout" property shows the lifespan of the token in seconds. As shown, the default value is 1200s (20 min).

The "expirationMicros" property shows the date/time that the token will expire. The value is a Unix epoch time in GMT with microseconds precision. You can parse the number by using Node.js (preinstalled on any BIG-IP 12.1 and later) as below:

# To GMT
node -p 'new Date(1588202764161000/1000)'

# To your local time
node -p 'new Date(1588197991778710/1000).toString()'

3. Use your token

Add the X-F5-Auth-Token HTTP request header with the token value to any call you make. For example, to send a GET request to /mgmt/tm/sys/version (equivallent to 'tmsh show sys version'), run below:

curl -sk https://$HOST/mgmt/tm/sys/version -H "X-F5-Auth-Token: $TOKEN"

4. Check your token

You can check you token by sending the following GET request.

curl -sk https://$HOST/mgmt/shared/authz/tokens/$TOKEN -H "X-F5-Auth-Token: $TOKEN"

An example output is shown below:

{
  "address": "192.168.184.10",
  "authProviderName": "tmos",
  "expirationMicros": 1588217373992000,
  "generation": 1,
  "kind": "shared:authz:tokens:authtokenitemstate",
  "lastUpdateMicros": 1588216173991714,
  "name": "7CLLGEKL5UZLUI7BO4SE7MUGMI",
  "partition": "[All]",
  "selfLink": "https://localhost/mgmt/shared/authz/tokens/7CLLGEKL5UZLUI7BO4SE7MUGMI",
  "startTime": "2020-04-30T15:09:33.992+1200",
  "timeout": 1200,
  "token": "7CLLGEKL5UZLUI7BO4SE7MUGMI",
  "user": {
    "link": "https://localhost/mgmt/cm/system/authn/providers/tmos/1f44a60e-11a7-3c51-a49f-82983026b41b/users/acbd18db-4cc2-385c-adef-654fccc4a4d8"
  },
  "userName": "foo"
}

5. Modify the timeout value of your token

By changing the value of the timeout property (default 1,200), you can extend or shorten the lifespan of the token.

You may need to consider:

Extending it if your iControl REST session is expected to last long (e.g., a script with hundreds of calls) to avoid timeout in the middle of the session.
Shortening it if you successively run multiple iControl REST calls that request tokens each time to avoid running out the tokens.

The example below extends the token's lifespan to 4,200s (70 min).

curl -sk https://$HOST/mgmt/shared/authz/tokens/$TOKEN \
 -X PATCH -H "Content-type: application/json" -H "X-F5-Auth-Token: $TOKEN" \
 -d '{"timeout" : 4200}'

6. Delete your token

You can explicitly delete your token.

curl -sk https://$HOST/mgmt/shared/authz/tokens/$TOKEN -X DELETE -H "X-F5-Auth-Token: $TOKEN"

As aforementioned, you can only delete your own token. If you need to remove ALL the tokens in one shot, run the following call from the authorized user such as admin:

curl -sku $PASS https://$HOST/mgmt/shared/authz/tokens -X DELETE

7. Fnd the owner of the token from the user reference link

As shown in the Merhod 1 and 4, a token object contains the owner (or the requester) of the token (the "userName" property). If it does not contain the readable user information, alternatively, you can send a GET request to the endpoint shown in the "user" property.

curl -sk https:/$HOST/mgmt/cm/system/authn/providers/tmos/1f44a60e-11a7-3c51-a49f-82983026b41b/users/acbd18db-4cc2-385c-adef-654fccc4a4d8 \
 -H "X-F5-Auth-Token: $TOKEN"

The 8-4-4-4-12 format strings are UUIDs computed from the login provider name (the value you provided via the loginProviderName property when you requested your token) and user name. For example, 1f44a60e-11a7-3c51-a49f-82983026b41b in between "tmos" and "users" is from the string "tmos". acbd18db-4cc2-385c-adef-654fccc4a4d8 is from "foo".

An UUID (Universally Unique Identifier) is a 128 bits long unique identifier defined in RFC 4122. There are a number of variants and versions in the UUIDs. F5 iControl REST uses version (0011) and variant (10) (represented in binary). See Section 4.1.3 and 4.1.1 of the RFC for details.

An example output from the above call is shown below:

{
  "generation": 23,
  "id": "acbd18db-4cc2-385c-adef-654fccc4a4d8",
  "kind": "cm:system:authn:providers:tmos:1f44a60e-11a7-3c51-a49f-82983026b41b:users:usersstate",
  "lastUpdateMicros": 1585693423008243,
  "name": "foo",
  "selfLink": "https://localhost/mgmt/cm/system/authn/providers/tmos/1f44a60e-11a7-3c51-a49f-82983026b41b/users/acbd18db-4cc2-385c-adef-654fccc4a4d8"
}