Auth Token by Exchange¶

Overview¶

F5 disables basic authentication for HTTP/HTTPS requests to the BIG-IQ API by default for security enhancement. You can make HTTP/HTTPS requests to the BIG-IQ API while keeping basic authentication disabled by sending the requests with a valid BIG-IQ X-F5-Auth-Token authentication header. Whenever you perform an authenticated login to the BIG-IQ, and request a token using the Auth Token by Login API, you receive both an access token and refresh token. You can use the access token to send HTTP/HTTPS requests to a BIG-IQ until the token expires after 5 minutes. Any REST requests that use an expired access token receives an error code 401 with the message invalid registered claims from the BIG-IQ.

For up to 10 hours after performing an authenticated login and receiving the refresh token, you can use the Auth Token Exchange API described on this page to exchange the refresh token for a new access token without performing another authenticated login. The timeout counter for the refresh token does not reset after requesting a new access token, and after 10 hours you are required to perform another authenticated login to the BIG-IQ and request new access and refresh tokens using the Auth Token by Login API. Note that you cannot change the default token timeout values.

REST Endpoint: mgmt/shared/authn/refresh¶

Requests¶

POST /mgmt/shared/authn/exchange¶

Exchange an unexpired refresh token for a new access token which you can use to make HTTP/HTTPS requests to the BIG-IQ without performing another authenticated login. The refresh token must still be within the 10 hour expiration period.

Request Parameters¶

Name	Type	Description
refreshToken	object	Refresh token object. This is the refresh token received by a previous authenticated login and use of the Auth Token by Login API.
token	string	The value of the refresh token.

Query Parameters¶

None

Response¶

HTTP/1.1 200 OK

Name	Type	Description
refreshToken	object	Refresh token object
token	string	The value of the refresh token.
userName	string	The system’s default admin user ID that is getting a token.
authProviderName	string	The value “local” indicates the local authentication provider.
user	string	The user ID that is receiving a token.
groupReferences	object array	A list of user groups.
timeout	string	Expiration period of refresh token in seconds.
address	string	The IP address or hostname of the BIG-IQ.
type	string	Type of token. The value “REFRESH” indicates a refresh token.
token	object	Access token object
token	string	The value of the access token. You can use the value of token in the X-F5-Auth-Token header in subsequent REST requests that require authentication.
userName	string	The system’s default admin user ID that is getting a token.
authProviderName	string	The value “local” indicates the local authentication provider.
user	string	The user ID that is a token.
groupReferences	object array	A list of user groups.
timeout	string	Expiration period of access token in seconds.
address	string	The IP address or hostname of the BIG-IQ.
type	string	Type of token. The value is “ACCESS” for an access token.

Permissions¶

Role	Allow
admin	Yes

Use the F5 authentication token header to send an HTTP/HTTPS request to the BIG-IQ API¶

You can use the value of the access token in the X-F5-Auth-Token header in subsequent REST requests that require authentication. The header would look similar to the following. In the following example, the value of the token has been shortened for display purposes using (/…/).

X-F5-Auth-Token: eyJraWQiOiJlNmQ2NjgwNC1mYWJjLTRiNWYtODU5/.../V0I8Up_Zw-1iib_WkxRcQy_Y6eoSKT2xRXdMAOx

Examples¶

Exchange the refresh token for a new access token¶

In the following example response, the values of token and selfLink have been shortened for display purposes using (/…/).

POST https://10.100.100.100/mgmt/shared/authn/exchange
{
  "refreshToken": {
  "token": "eyJraWQiOiJlNmQ2NjgwNC1mYWJjLTRiNWYtODU5/.../fbYg8w-N1O6hXLGKJ99IB37ET0MK2IkH4GGv_2F"}
}

The response can look similar to the following.

{
  "refreshToken": {
    "token": "eyJraWQiOiJlNmQ2NjgwNC1mYWJjLTRiNWYtODU5/.../fbYg8w-N1O6hXLGKJ99IB37ET0MK2IkH4GGv_2F",
    "userName": "admin",
    "authProviderName": "local",
    "user": {
      "link": "https://localhost/mgmt/shared/authz/users/admin"
    },
    "groupReferences": [],
    "timeout": 36000,
    "address": "10.100.100.100",
    "type": "REFRESH",
    "jti": "uZdMlJ7sepOAgXWRNoKkfw",
    "exp": 1476716648,
    "iat": 1476680648,
    "generation": 0,
    "lastUpdateMicros": 0,
    "kind": "shared:authz:tokens:authtokenitemstate",
    "selfLink": "https://localhost/mgmt/shared/authz/tokens/eyJraWQiOiJlNmQ2NjgwNC1mYWJjLTRiNWYtODU5/.../fbYg8w-N1O6hXLGKJ99IB37ET0MK2IkH4GGv_2F"
  },
  "token": {
    "token": "eyJraWQiOiJlNmQ2NjgwNC1mYWJjLTRiNWYtODU5/.../V0I8Up_Zw-1iib_WkxRcQy_Y6eoSKT2xRXdMAOx",
    "userName": "admin",
    "authProviderName": "local",
    "user": {
      "link": "https://localhost/mgmt/shared/authz/users/admin"
    },
    "groupReferences": [],
    "timeout": 300,
    "address": "10.100.100.100",
    "type": "ACCESS",
    "jti": "GSs2Bd5GcWIZ9HMh3AjhpQ",
    "exp": 1476693165,
    "iat": 1476692865,
    "generation": 11,
    "lastUpdateMicros": 1476692865145163,
    "kind": "shared:authz:tokens:authtokenitemstate",
    "selfLink": "https://localhost/mgmt/shared/authz/tokens/eyJraWQiOiJlNmQ2NjgwNC1mYWJjLTRiNWYtODU5/.../V0I8Up_Zw-1iib_WkxRcQy_Y6eoSKT2xRXdMAOx"
  },
  "generation": 0,
  "lastUpdateMicros": 0
}

Use the F5 authentication token header to send an HTTP/HTTPS request to the BIG-IQ API¶

In the following example curl is used as the client and the value of the access token has been shortened for display purposes using (/…/). Log into the BIG-IQ. If the access token is still within the 5 minutes expiration period, you can use the following command to send a REST request with the access token header. The value set in the X-F5-Auth-Token is the access token value.

curl -sk -H "X-F5-Auth-Token: eyJraWQiOiJlNmQ2NjgwNC1mYWJjLTRiNWYtODU5/.../V0I8Up_Zw-1iib_WkxRcQy_Y6eoSKT2xRXdMAOx" https://10.100.100.100/mgmt/shared/diagnostics/device-stats

Previous Next