BIG-IQ Access Configuration Interface Quick Introduction

Introduction

Prior to the introduction of BIG-IQ 8.0, you had to use the BIG-IQ graphical user interface (GUI) and the visual policy editor (VPE) to configure access policies and associate them with a virtual server.

Starting with BIG-IQ 8.0, a new REST endpoint was created to simplify Access configuration workflows.  The aim is to make the configuration of BIG-IP APM configuration using a one-shot API call. You are now able to store the configuration in your versioning tool (Git, SVN, etc.), and easily integrate the configuration of BIG-IP APM in your automation and pipeline tools. 

The focus of the endpoint described below is to create a security assertion mark-up language (SAML) service provider (SP) on a BIG-IP APM device and associate it to a new virtual server. The BIG-IP will then insert a header on the serve-rside providing session information to the back-end server. 

For more information about SAML SP, please refer to this short video. The F5 BIG-IP APM implementation and use-cases of SAML are discussed in this support page. 

As a reminder the BIG-IQ API reference documentation can be found here. Documentation for the Access Simplified Workflow can be found here.

 

The API is designed to achieve the following on (a) target BIG-IP(s):

·     Create an access policy with the following elements:

o  Configure a SAML Service Provider (SP) on BIG-IQ

o  Associate up to two (2) idP connectors to a SP profiles

o  Configure an access policy to take into account up to two (2) key-value-pairs in the SAML assertion

o  Add up to two (2) authentication contexts

o  Integrate back-end single-sign-on functionality
 

·     Create a virtual server with the following characteristics:

o  Up to 2 pool members

o  An associated access profile (as created above)

 

The figure below shows a simplified workflow of the configuration process.

A few shortcuts are taken in the figure above as it is meant to illustrate the advantage of the simplified workflow.

 

Configuration

For the configuration the administrator needs to:

-Create a JSON blurb or payload that will be sent to the BIG-IQ API

-Authenticate to the BIG-IQ API

-Send the payload to the BIG-IQ

-Ensure that the workflow completes successfully

-Deploy the newly created policy and virtual server to the BIG-IP

 

The following aims to provide a step-by-step manual configuration leveraging the API. In practice, the steps will be automated and will be included in the pipeline used to deploy the application leveraging the enterprise tooling and processes in place.

 

1.- Authenticate to the API

API interactions with the BIG-IQ API requires the use of a token. The initial REST call should look like the following:

REST Endpoint : /mgmt/shared/authn/login

HTTP Method: POST

Headers:

-content-type: application/json

Content:

{
 "username": "",
 "password": "",
 "loginProviderName": ""
}

Example:

POST https://10.0.0.1/mgmt/shared/authn/login HTTP/1.1
Headers:
content-type: application/json
Content:
{
 "username": "username",
 "password": "complicatedPassword!",
 "loginProviderName": "RadiusServer"
}

The call above will authenticate the user “bob” to the API. The result of a successful authentication is the response from the BIG-IQ API with a token.

 

2.- Push the configuration to BIG-IQ

To send the configuration to the BIG-IQ you will need to send:

-HTTP POST Request

-To the following URI: /mgmt/cm/access/workflow/access-workflow

-With the custom authentication header: X-F5-Auth-Token with a value of the authentication token resulting from the previous authentication.

 

The payload of the POST request will look like the following (broken up into segments for clarity - full sample file is in attachment.):

 

To start the JSON payload, you will need to give it a name and make sure the type is "samlSP" as shown below and define which BIG-IQ Access Group to associate the configuration with:

{
  "name": "workflow_saml_3",
  "type": "samlSP",
  "accessDeviceGroup": "BIG-IQ-Access-Device-Group",
  "configurations": {

In the "configurations" sections, you will need to define the SP Service - this will look like the sample below:

    "samlSPService": {
      "entityId": "https://www.testsaml.lab",
      "idpConnectors": [
        {
          "connector": {
            "entityId": "https://www.testidp.lab",
            "ssoUri": "https://www.testidp.lab/sso"
          }
        }
      ],
      "attributeConsumingServices": [
        {
          "service": {
            "serviceName": "service_01",
            "isDefault": true,
            "attributes": [
              {
                "attributeName": "service_attribute"
              }
            ]
          }
        }
      ],
      "authContextClassList": {
        "classes": [
          {
            "value": "urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport"
          }
        ]
      }
    },

In the declaration above the following items are configured:

-idP SAML connector URL

-idP SAML connector URI

-Name of the service

-Define the SP service as the default

-The attributes that will be used for processing in the assertion

-Authentication Context information

 

In the "virtualServers" section of the configuration JSON payload focusses on the creation of virtual server and related pool and pool-member configuration. In the sample blurb below, we have:

-A new virtual server listening on [IP address]:443

-A device in the BIG-IQ access device group to deploy the configuration to

-New client and server SSL profiles based on the default profiles

-Related pool/pool members and monitoring parameters

    "virtualServers": [
      {
        "port": "443",
        "destinationIpAddress": "[IP address]",
        "targetDevice": "BOS-vBIGIP01.termmarc.com",
        "clientsideSsl": "/Common/clientssl",
        "serversideSsl": "/Common/serverssl",
        "poolServer": {
          "monitors": {
            "https": [
              "/Common/https"
            ]
          },
          "members": [
            {
              "ipAddress": "[IP address]",
              "port": "443",
              "priorityGroup": 10
            },
            {
              "ipAddress": "[IP address]",
              "port": "443"
            }
          ]
        }
      }
    ],
    "accessProfile": {},
    "singleSignOn": {
      "type": "httpHeaders",
      "httpHeaders": [
        {
          "headerName": "Authorization",
          "headerValue": "%{session.saml.last.identity}"
        },
        {
          "headerName": "Authorization2",
          "headerValue": "%{session.saml.last.identity2}"
        }
      ]
    },

You can also chose to deploy endpoint checks for the configuration. This will allow device posture checking before granting access to the protected resource. A sample endpoinCheck configuration is provided below:

    "endpointCheck": {
      "clientOS": {
        "windows": {
          "windows7": true,
          "windows10": true,
          "windows8_1": true,
          "antivirus": {},
          "firewall": {},
          "machineCertAuth": {}
        },
        "windowsRT": {
          "antivirus": {},
          "firewall": {}
        },
        "linux": {
          "antivirus": {
            "dbAge": 102,
            "lastScan": 102
          },
          "firewall": {}
        },
        "macOS": {
          "antivirus": {
            "dbAge": 103,
            "lastScan": 103
          }
        },
        "iOS": {},
        "android": {},
        "chromeOS": {
          "antivirus": {
            "dbAge": 104,
            "lastScan": 104
          },
          "firewall": {}
        }
      }
    }
  }
}

After the HTTP POST, the BIG-IQ will respond with a transaction id. A sample of what looks like is given below:

{
[…]
"accessDeviceGroup":" BIG-IQ-Access-Device-Group ",
"id":"edc17b06-8d97-47e1-9a78-3d47d2db70a6",
"status":"STARTED",
"name":"workflow_saml_3",
[…]
}

The initial status of the workflow is “STARTED” as shown above. 

To check on the status of the workflow, you can send an HTTP GET Request to the following BIG-IQ URI: https://[BIG-IQ Mgmt IP Addess or Hostname]/mgmt/cm/access/workflow/access-workflow/[workflow_id]

 

Once the status returns with FINISHED two new items are available on BIG-IQ:

-One new SAML SP Access Policy (name matches the workflow name in the JSON payload)

 

-One new Virtual Server with associated Pool and Pool Members (name matches the workflow name in the JSON payload)

 

3.- Deploy the changes to BIG-IP

 

This is achieved with the usual deployment process that you are familiar with.

 

Conclusion

You are now able to create a new policy and associated artifacts (Virtual Server, Pool, Pool Members) using a single call to the BIG-IQ API. These items can then be manipulated, assigned and deployed as needed on the managed BIG-IPs.