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.
Requests¶
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.