Lab 1.2: REST API Authentication & example Templates

One of the many fundamental concepts related to interaction with REST APIs is how a particular consumer is authenticated to the system. BIG-IP supports two types of authentication: HTTP BASIC and Token-Based (TBA). It is important to understand both of these authentication mechanisms, as consumers of the API will often make use of both types depending on the use case. This lab will demonstrate how to interact with both types of authentication.

Throughout this and other classes in the series, we will make use of the Postman REST API Client. You can find more information about Postman at https://getpostman.com

Task 1 - Import the Postman Collection & Environment

In this task, you will Import a Postman Collection & Environment for this lab. Perform the following steps to complete this task:

1. Open the Postman tool by clicking the icon of the desktop of your Windows Jump host. The initial window may take a few moments to appear.

   Note

   The Postman client receives frequent updates. If you are prompted to update the client please click the Remind me later button to skip updating the version installed in your lab environment

2. By default, the Postman client requires verification of SSL/TLS Certificates to a public Root Certificate Authority. However, by default, BIG-IP and many other devices use a self-signed certificate for SSL/TLS connections. To allow connections with self-signed certificates, we need to modify the default settings of Postman.

   • Open the Postman Settings windows by clicking File > Settings:

     

   • Verify your client is configured to allow self-signed certificates by ensuring that the SSL certificate verification setting is set to OFF

     

   • Click the X in the top right of the Settings window

3. A Postman Collection lets you group individual REST requests. This Postman collection can then be shared and imported. To import a Postman Collection, click the Import button in the top left of the Postman window

   

4. Click the Import from Link tab. Paste the following URL into the text box and click Import

   https://raw.githubusercontent.com/f5devcentral/f5-agility-labs-automation/master/docs/class01/files/Class_1.postman_collection.json
   

   

5. You should now see a collection named F5 Programmability: Class 1 in your Postman Collections sidebar. Postman automatically resizes its GUI depending on its window size. It might be necessary to use the short Ctrl + \ (on Windows) or click the show sidebar icon at the bottom left corner of postman if you do not see the sidebar.

   

6. To assist in multi-step procedures, we make heavy use of the Environments capability in Postman. This capability allows us to set various global variables that are then substituted into the request before it is sent. Import the Environment file by clicking: menu selection:Import > Import from Link and pasting the following URL and clicking Import:

   https://raw.githubusercontent.com/f5devcentral/f5-agility-labs-automation/master/docs/class01/files/Class_1.postman_environment.json
   

7. Set your environment to F5 Programmability: Class 1 by using the menu at the top right of your Postman window:

   

Task 2 - HTTP BASIC Authentication

In this task, we will use the Postman client to send API requests using HTTP BASIC authentication. As its name implies, this method of authentication encodes the user credentials via the existing BASIC authentication method provided by the HTTP protocol. The mechanism this method uses is to insert an HTTP header named Authorization with a value that is built by Base 64 encoding the string <username>:<password>. The resulting header takes this form:

Authorization: Basic YWRtaW46YWRtaW4=

It should be noted that cracking this method of authentication is TRIVIAL; as a result, API calls should always be performed using HTTPS encryption (F5 default) with a certificate signed by authority rather than HTTP.

Perform the following steps to complete this task:

1. Click the Collections tab on the left side of the screen, expand the F5 Programmability: Class 1 collection on the left side of the screen, expand the Lab 1.2 - API Authentication & `example` Templates folder:

   

2. Click the Step 1: HTTP BASIC Authentication item. Click the Authorization tab and select Basic Auth as the Type. Fill in the username and password (admin/Agility2020!) and click the Send button:

   

3. Click the Headers tab and examine the HTTP header. Notice that the number of Headers in the Headers tab changed from 1 to 9. This is because Postman automatically created the HTTP header and updated your request to include it.

   

4. Click the Body tab, if the request succeeded you should be presented with a listing of the /mgmt/tm/ltm Organizing Collection:

   

5. Click the Test Results tab and ensure all the tests for this request have passed:

   

6. Update the credentials and specify an INCORRECT password. Send the request again and examine the response:

   

7. Check the Test Results tab and notice that our Unit Tests for this request are now failing (as expected):

   

Important

As you progress through this lab be sure to check the Test Results tab. We have included Unit Tests where applicable to help you verify the requests being sent are succeeding. If you notice a test has failed, please double check your input or ask for help.

Task 3 - Token Based Authentication

One of the disadvantages of BASIC Authentication is that credentials are sent with every request. This can result in a much higher attack surface being exposed unnecessarily. As a result, Token Based Authentication (TBA) is preferred in many cases. TBA only sends the credentials once, on the first request. The system then responds with a unique token for that session, and the consumer then uses that token for all subsequent requests. BIG-IP supports token-based authentication that drops down to the underlying authentication subsystems available in TMOS. As a result, the system can be configured to support external authentication providers (Active Directory, RADIUS, TACACS, etc.), and those authentication methods can flow through to the REST API. In this task, we will demonstrate TBA using the local authentication database. However, authentication to external providers is fully supported.

Note

For more information about external authentication providers see the section titled About external authentication providers with iControl REST in the iControl REST API User Guide available at https://devcentral.f5.com/d/icontrolr-rest-api-user-guide-version-1300-241 (v13)

Perform the following steps to complete this task:

1. Click the Step 2: Retrieve Authentication Token item in the Lab 1.2 Folder.

2. Notice that we send a POST request to the /mgmt/shared/authn/login endpoint.

   

3. Click the Body tab and examine the JSON that we will send to BIG-IP to provide credentials and the authentication provider:

   

4. Modify the JSON Body and add the required credentials (admin/Agility2020!). Then click the Send button.

5. Examine the response status code. If authentication succeeded and a token was generated, the response will have a 200 OK status code. If the status code is 401 then check your credentials:

   • Successful:

     

   • Unsuccessful:

     

6. Once you receive a 200 OK status code, examine the Response Body. The various attributes show the parameters assigned to the particular token. Find the token attribute and copy it into your clipboard (Ctrl + C) for use in the next step.

   

7. Click the Step 3: Verify Authentication Works item in the Lab 1.2 Postman collection. Click the Headers tab and paste the token value copied above as the VALUE for the X-F5-Auth-Token header. This header is required to be sent on all requests when using token-based authentication.

   

8. Click the Send button. If your request is successful, you should see a 200 OK status and a listing of the ltm Organizing Collection.

9. We will now update your Postman environment to use this auth token for the remainder of the lab. Click the Environment menu in the top right of the Postman window and click Manage Environments:

   

10. Click the F5 Programmability: Class 1 item:

    

11. Update the value for bigip_a_auth_token by Pasting (Ctrl + V) in your auth token:

    

12. Click the Update button and then close the Manage Environments window. Because the subsequent requests refer to the {{bigip_a_auth_token}} variable, you will not have to set the token in the header of the following requests.

13. Click the Step 4: Set Authentication Token Timeout item in the Lab 1.2 Postman folder. This request will PATCH your token Resource (notice the URI) and update the timeout attribute so we can complete the lab easily. Examine the request type and JSON Body and then click the Send button. Verify that the timeout has been changed to 36000 in the response:

    

Task 4 - Get a pool example Template

In order to assist with REST API interactions, you can request a template of the various attributes of a Resource type in a Collection. This template can then be used as the body of a POST, PUT or PATCH request as needed.

Perform the following steps:

1. Click the Step 5: Get `example` of a Pool Resource item in the Lab 1.2 Postman collection.

2. Examine the URI. Notice the addition of example at the end of the collection name:

   

3. Click Send and examine the FULL response. You will see descriptions and then all the attributes for the Pool resource type. The response also shows the default values for the attributes if applicable: