Auth Token by Login

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 to the BIG-IQ and by including a valid BIG-IQ authentication token in the X-F5-Auth-Token header. Whenever you perform an authenticated login to the BIG-IQ, and request a token using the Auth Token by Login API described on this page, 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 access 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 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/login

Requests

POST /mgmt/shared/authn/login

Request a new token from the BIG-IQ using an authenticated login. Using your username and password, log into the BIG-IQ. Whenever you perform an authenticated login to the BIG-IQ, and request a token using this API you receive both a new access token and refresh token.

Request Parameters

Name Type Description
username string The system’s default admin user ID, which is the user getting a token.
password string The system’s default admin user password.
loginReference string Reference to the authentication provider provided as a link. If you’re using the local authentication provider you can omit the property or set it to an empty value.

Query Parameters

None

Response

HTTP/1.1 200 OK

Name Type Description
username string The system’s default admin user ID that is getting a token.
loginReference string Reference to the authentication provider provided as a link.
token object Access token object
     token string You can use the value of the access 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 system’s default admin user ID that is getting 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” indicates an access token.
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 access 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.

Permissions

Role Allow
Administrator 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

Request a new access token from the BIG-IQ using an authenticated login

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/login
{
  "username":"admin",
  "password":"admin"
}

The response can look similar to the following.

HTTP/1.1 200 OK
{
  "username": "admin",
  "loginReference": {
    "link": "https://localhost/mgmt/cm/system/authn/providers/local/login"
  },
  "loginProviderName": "local",
  "token": {
    "token": "eyJraWQiOiJlNmQ2NjgwNC1mYWJjLTRiNWYtODU5/.../6eegA2O8oXX0N9bMgbWElWa7U2L3gJ3FbhO1mKf",
    "userName": "admin",
    "authProviderName": "local",
    "user": {
      "link": "https://localhost/mgmt/shared/authz/users/admin"
    },
    "groupReferences": [],
    "timeout": 300,
    "address": "10.100.100.100",
    "type": "ACCESS",
    "jti": "eem2pBY8pmRQPFd1oQBxeQ",
    "exp": 1476680018,
    "iat": 1476679718,
    "generation": 1,
    "lastUpdateMicros": 1476679719091834,
    "kind": "shared:authz:tokens:authtokenitemstate",
    "selfLink": "https://localhost/mgmt/shared/authz/tokens/eyJraWQiOiJlNmQ2NjgwNC1mYWJjLTRiNWYtODU5/.../6eegA2O8oXX0N9bMgbWElWa7U2L3gJ3FbhO1mKf"
  },
  "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": "S8pRqgWbJNxPJNlmZiK6aw",
    "exp": 1476715719,
    "iat": 1476679719,
    "generation": 2,
    "lastUpdateMicros": 1476679719125773,
    "kind": "shared:authz:tokens:authtokenitemstate",
    "selfLink": "https://localhost/mgmt/shared/authz/tokens/eyJraWQiOiJlNmQ2NjgwNC1mYWJjLTRiNWYtODU5/.../fbYg8w-N1O6hXLGKJ99IB37ET0MK2IkH4GGv_2F"
  },
  "generation": 17,
  "lastUpdateMicros": 1476679719141837
}

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 shell of 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