Authentication
Majority of requests to IP Fabric platform need to be authenticated. We provide multiple authentication methods. They differ to each other, please review all of them before committing to any.
API Token
API Token needs to be passed as a request header. Please see API Tokens on how to create an API Token in the UI.
- Allows for limiting the scope of API calls. This allows for giving less rights than has account creating the token.
- Long-lived static token (secure storage is important).
Content-Type: application/json
X-API-Token: YOUR_API_TOKEN_GENERATED_VIA_IPFABRIC_UI
Basic Authentication
Using Basic Authentication requires Base64 encoding username:password
and
passing that into the Authorization
header.
- Call will always have the same rights as the user account. This may be really unnecessary for many use-cases.
- In case this approach is use, we highly encourage creation of a “bot”/” service” user account with limited access scope.
- Another form of long-lived static token / authentication details (secure storage is important).
osadmin@ipfabric:~$ echo -n "username:password" | base64
dXNlcm5hbWU6cGFzc3dvcmQ=
osadmin@ipfabric:~$ curl -X GET 'https://demo3.ipfabric.io/api/v5.0/snapshots' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ='
Token Authentication
Token authentication allows to exchange username and password for pair of tokens
– access and refresh. Exchange is facilitated via login
endpoint. Access
token is then passed to the consecutive API calls in the Authorization
header.
- Call will always have the same rights as the user account. This may be really unnecessary for many use-cases.
- In case this approach is use, we highly encourage creation of a “bot”/” service” user account with limited access scope.
- Storage of refresh token is important as it allows for maintaining long-term access.
Types of Tokens
- Access Token
-
An access token is JSON Web Token (JWT) as per RFC-7519 signed using SHA-256 with RSA encryption. The token expires in 30 minutes since being generated and it can’t be revoked during its lifetime.
-
What is inside access token?
Access token is a JWT which concists of three parts separated by dots – Header, Payload, and Signature. You don’t need to parse any of these fields. You can use https://jwt.io/ for inspecting content of JWT. You will not be able to verify its validity as you don’t have access to signing key.
The payload contains an object with the following fields:
id
– User IDexp
– Token expiration time (in seconds since Unix epoch)iat
– Token issued time (in seconds since Unix epoch)scope
– Array of strings representing granted user accessusername
– String containing the username of the userisAdmin
– A boolean value whether a user is an adminaud
– String containing the recipient for which the JWT is intendediss
– String containing the issuer of the JWT
- Refresh Token
-
A refresh token is a token that can be used to obtain a renewed access token. It can be requested for new access tokens until the refresh token is used, revoked, or expired.
-
A refresh token expires after 24 hours of not being used for generation of a new access token. Refresh tokens must be stored securely by an application as it creates a new Access Token and allowing access to the system.
-
Starting in IP Fabric version
6.1.0
therefreshToken
is rotated after every use and a new one is issued.
Token API
Login
To log in and obtain an Access and Refresh token, please see the below curl example:
curl -X POST 'https://demo3.ipfabric.io/api/v6.1/auth/login' \
-H 'Content-Type: application/json' \
--data-raw '{"username":"<USERNAME>","password":"<PASSWORD>"}'
This returns a JSON response with accessToken
and refreshToken
:
{
"eula": false,
"scope": ["read"],
"id": "2473545443652",
"accessToken": "eyJhbGc...",
"refreshToken": "YvnTNW..."
}
Using the accessToken
The accessToken
is then placed in the Authorization
header as seen below.
Please ensure it is formatted as Authorization: Bearer <ACCESS_TOKEN>
.
curl -X GET 'https://demo3.ipfabric.io/api/v5.0/snapshots' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer eyJhbGc...'
Using the refreshToken
To create a new accessToken
from the refreshToken
:
curl -X POST 'https://demo3.ipfabric.io/api/v5.0/auth/token' \
-H 'Content-Type: application/json' \
--data-raw '{"refreshToken":"YvnTNW..."}'
Which then returns a new accessToken
to use in subsequent calls and a new
refreshToken
to use for request the next accessToken
:
{
"eula": false,
"scope": ["read"],
"id": "2473545443652",
"accessToken": "eyJhbGc...",
"refreshToken": "bofZw..."
}
Logout
To log out of IP Fabric:
curl -X POST 'https://demo3.ipfabric.io/api/v5.0/auth/logout' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer eyJhbGc...'
Changing Default Token Expiration
The default token expiration is as follows:
accessToken
– 30 minutes (1800 seconds)refreshToken
– 24 hours (86400 seconds)
Many company standards requires shorter expiration times and this can be accomplished via the CLI settings.
Warning
Any action on the command-line interface (CLI) using the root
, osadmin
, or autoboss
account may cause irreversible detrimental changes to the product. Actions taken without direct communication with the IP Fabric Support or Solution Architect teams can render the system unusable.
- Log in to IP Fabric CLI as
osadmin
- Elevate to root using
sudo -s
andosadmin
password. -
Create new file
/opt/nimpee/conf.d/api.json
or extend existing one with the below JSON. In this example theaccessToken
expires in 10 minutes andrefreshToken
expires in 15 minutes:{ "app": { "accessToken": { "expiresIn": 600 }, "refreshToken": { "expiresIn": 900, "length": 80 } } }
-
Change file permissions
chmod 644 /opt/nimpee/conf.d/api.json
- Restart API
systemctl restart nimpee-api.service
Disabling local authentication
In case you don’t want to use local authentication (username/password) and log in only via SSO or LDAP, you can disable it via the CLI settings (both token and basic authentication will be disabled). Please note that API Tokens will still work.
Warning
Any action on the command-line interface (CLI) using the root
, osadmin
, or autoboss
account may cause irreversible detrimental changes to the product. Actions taken without direct communication with the IP Fabric Support or Solution Architect teams can render the system unusable.
- Log in to IP Fabric CLI as
osadmin
- Elevate to root using
sudo -s
andosadmin
password. -
Create new file
/opt/nimpee/conf.d/api.json
or extend existing one with the below JSON:{ "app": { "enableLocalAuthentication": false } }
-
Change file permissions
chmod 644 /opt/nimpee/conf.d/api.json
- Restart API
systemctl restart nimpee-api.service
Token Errors
The API returns an object with a machine-readable error code and a human-readable error message in response body when an error is encountered:
{
"code": "API_EXPIRED_API_TOKEN",
"message": "Expired API Token"
}
Code | Message |
---|---|
API_EXPIRED_API_TOKEN | The provided API key expired. |
API_INVALID_API_TOKEN | The provided API key doesn’t exist. It was removed, or it never existed. |
API_EXPIRED_ACCESS_TOKEN | The provided access token (from Authorization header) is expired. |
API_INVALID_ACCESS_TOKEN | The provided access token (from Authorization header) is invalid. |
API_INVALID_REFRESH_TOKEN | The provided refresh token (typically sent in the request body) is revoked (blacklisted) or expired. |