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.

BIG-IQ client certificate authentication is an alternative to using username and password to request the authentication token. If BIG-IQ client certificate authentication is enabled, you can request an authentication token by providing the client’s private key and the corresponding X.509 certificate.

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.
loginProviderName string Name of the authentication provider. For remote authentication, use the provider named in the GUI. If using local authentication, the value can be “tmos” or it can be “ldapServer” if ldapServer is a third party authentication provider which is defined on the BIG-IQ. For more information about user authentication from BIG-IQ, see Managing Authentication, Roles, and Users from BIG-IQ .

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.
loginProviderName string Name of the authentication provider.
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",
  "loginProviderName": {
    "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

BIG-IQ client certificate authentication

If BIG-IQ client certificate authentication is enabled, you can request an authentication token by providing the client’s private key and the corresponding X.509 certificate. These can either be bundled together in a PKCS#12 file or they can be sent as separate arguments. A PKCS#12 file has the extension .p12 or .pfx, and can optionally be password protected.

In the following example curl is used as the client.

PKCS#12 bundle, password protected:

curl -X POST -d "{needsToken=true}" --cert-type P12 --cert /path/to/client.p12:mypassword https://10.100.100.100/mgmt/shared/authn/login

PKCS#12 bundle, no password:

curl -X POST -d "{needsToken=true}" --cert-type P12 --cert /path/to/client.p12 https://10.100.100.100/mgmt/shared/authn/login

Separate files for the certificate and the private key:

curl -X POST -d "{needsToken=true}" --key /path/to/client.key --cert /path/to/client.crt https://10.100.100.100/mgmt/shared/authn/login

If you provide a certificate that’s expired, revoked or has malformed attributes, the certificate validation will fail with error code 400. If the certificate validation succeeds, but the username extracted from the certificate cannot be found in the Active Directory or LDAP directory, or if there is an invalid certificate attribute or bad LDAP settings, the error code 401 will be returned.