Skip to main content

F5 BIG-IP

Flowchart for F5 Corsha Integration

The above diagram details the sequence of making a request to an upstream service through Big IP with a Corsha Cred Check.

  1. A Corsha Authenticator sits beside the client, adding a Corsha cred header to each client request. The client makes a request to the F5 Virtual Server with a Corsha cred.
  2. The Virtual Server then extracts the cred into memory.
  3. Then, the configured HTTP Connector passes the cred to the Corsha mIDP to validate or reject the request.
  4. The Corsha mIDP responds with a 200 or a 403.
  5. The HTTP Connector checks the response and references the access policy to decide what to do with the response.
  6. If the cred is valid, the HTTP Connector forwards the request to the upstream service. If it is not valid, the request does not go through.

Getting Started​

tip

At any point on the F5 UI, you can navigate to the Help panel on the lefthand side to get more information about each field.

Certs and SSL Profiles​

Import Certs​

To use certificates with F5, we first must import them as certificate objects.

Here, you will upload the auth server certs given to you by your Corsha TPOC to authenticate against the Corsha mIDP.

You may also wish to upload a cert, key, and CA bundle for TLS between the downstream client and F5 or from F5 to the upstream service.

  1. Go to System>Certificate Management>Traffic Certificate Management

  2. Click Import

  3. Import Type: Certificate

  4. Certificate Name: Give a name (Ex: mycert)

  5. Certificate Source: Upload file

  6. Repeat steps 2-5 with Key

Create a Client SSL Profile​

A Client SSL Profile enables the BIG-IP system to accept and terminate client requests using a fully SSL-encapsulated protocol. A Client Profile is optional, but it is recommended that TLS be enforced between the downstream client and F5.

  1. Go to Local Traffic>Profiles>SSL>Client

  2. Click Create

  3. Under General Properties

    a. Enter a Name: test-client

    b. Parent Profile: clientssl (default)

  4. Under Configuration

    a. Check Custom

    b. Certificate Key Chain: click Add and choose your client certificate, key, and ca certificate

  5. Leave everything else as default

  6. Click Finished

Create a Server SSL Profile​

A Server SSL Profile allows the BIG-IP system to decrypt client requests before sending them to a server and encrypt server responses before sending them back to the client. For this integration, the Server SSL Profile is for mTLS between F5 and the Corsha mIDP.

  1. Go to Local Traffic>Profiles>SSL>Server

  2. Click Create

  3. Under General Properties

    a. enter a Name:Corsha-test

  4. Under Configuration

    a. Click Advanced

    b. Check Custom

    c. Choose your certificate and key from the drop down menus

    d. Set Server Name: auth-server-{{ domain }}-proxy-auth.corsha.io

    e. ensure Enabled is checked for Renegotiation

    f. check Enabled for Default SSL Profile for SNI

  5. Under Server Authentication

    a. Check Custom

    b. Server Certificate: require

    c. Authenticate Name: auth-server-{{ domain }}-proxy-auth.corsha.io

    tip

    this should be a FQDN that matches the server name above

    d. Trusted Certificate Authorities: ca-bundle.crt (default)

    e. Click Finished

HTTP Connector and Access Profiles/Policies​

Use the HTTP Connector to post an HTTP request to an external HTTP server. The typical use for an HTTP Connector is to provide access to an external API or service. In our case, we will use an HTTP Connector to make a request to authenticate with the Corsha mIDP.

For more information about F5 HTTP Connectors, visit the F5 docs.

Create a HTTP Connector Transport​

An HTTP Connector Transport provides the DNS resolver info and connection settings for an HTTP Connector Request.

  1. On the Main tab, click Access>Authentication>HTTP Connector>HTTP Connector Transport

  2. Click Create

  3. Specify a Name for the connector transport (ex: proxy-client.corsha.io)

  4. Select a DNS Resolver or create one by clicking the plus symbol (+)

  5. Server SSL Profile: Select the previously created Server SSL Profile

  6. Click Save

Create a HTTP Connector Request​

In our use case, we will configure the HTTP Connector Request to forward the Corsha cred to the Corsha mIDP.

  1. On the Main tab, click Access>Authentication>HTTP Connector>HTTP Connector Request

  2. Click Create

  3. HTTP Connector Transport: Select the previously created HTTP Connector Transport

  4. URL: Type the URL on which the HTTP Connector Request action will occur including the path:

    https://auth-server-{{ domain }}-proxy-auth.corsha.io/api/v1/x-corsha-cred

  5. In the Method field, enter POST

  6. Request Headers: paste X-Corsha-Cred: %{perflow.custom}

  7. Set the Response Action to Parse

  8. Click Save.

Create an Access Profile​

We need to create an access profile to attach to our virtual server in order to establish a secured session

  1. Go to Access>Profiles/Policies>Access Profiles (Per-Session Policies)

  2. Click Create

  3. Under General Properties

    a. Enter a Name: test-client

    b. Profile Type: All

  4. Under Settings

    a. Enter 10 for both Max Concurrent Users and Max Sessions Per User

  5. Chose a language for accepted languages.

  6. Click Finished.

  7. Click Edit

"Edit" button in the F5 interface

  1. Click Deny and Switch to Allow

  2. Click Save

  3. Click Apply Access Policy

"Apply Access Policy" F5 interface page

Create a Pool​

A pool is a logical set of devices, such as web servers, that you group together to receive and process traffic. The upstream service will be a pool member.

For more information about F5 Pools, visit the F5 docs.

  1. Navigate to Local Traffic>Pools>Pool List

  2. Click Create

  3. Fill in the Name

  4. Add a new member (A pool member is a logical object that represents a physical node on the network)

    a. If using a domain name for the upstream service, check New FQDN Node

    b. If using an IP for the upstream service, check New Node

    c. specify the port of 443

    d. click Add

  5. click Finished

Configure a per-request policy for an HTTP Connector​

A per-request policy runs each time the client makes an HTTP or HTTPS request and must provide the logic for determining how to process URL requests.

For more information about F5 per-request policies, visit the F5 docs.

The Corsha mIDP returns a 200 when the cred is valid and a 403 when the cred is not valid. We will configure the per-request policy to reject requests when the Corsha mIDP returns a 403 unauthorized.

  1. On the Main tab, click Access>Profiles / Policies>Per-Request Policies

  2. Click Create

  3. Fill in the Name

  4. Policy Type: All

  5. Chose a language for accepted languages.

  6. Click Finished

  7. Click Edit Under the Per-Request Policy

"Edit" button in the F5 interface

  1. Click the Add New Subroutine button.

  2. Type a Name for the new subroutine.

    a. For example, because this subroutine performs a cred check, you can name it cred-check

  3. On the Select Subroutine template list, keep the selection Empty

  4. click Save

Add the HTTP Connector to a subroutine​

  1. Expand the subroutine by clicking the [+] icon

    a. The subroutine displays a default configuration

  2. Click the (+) icon anywhere in the subroutine to add a new item

  3. Click the General Purpose tab.

  4. Select the HTTP Connector item, and click Add Item.

  5. From HTTP Connector Request, select the HTTP connector request you configured previously.

  6. Click the Branch Rules tab.

  7. Change the name of the default Successful rule to Valid Cred

    a. The expression should match the below screenshot

"Branch Rule" policy with the name "Valid Cred"

  1. Click Save

  2. Click Edit Terminals

  3. Click Add Terminal

    a. Update the names to Success/Fail

Setting the names of the Branch Rules to "Success" and "Fail"

  1. Click Save

  2. This is now what the subroutine should look like

Subroutine terminal diagram in the F5 interface

Add an HTTP Connector to a subroutine to per-request policy​

  1. Add the subroutine to the per-request policy:

    a. On a per-request policy branch, click the (+) icon. (shown in the red circle below)

"+" icon in the f5 interface

  1. Select the Subroutines tab.

    a. Select the subroutine we made, cred-check and click Add Item

    b. This should now look like the below screenshot

Subroutine terminal diagram in the F5 interface

Create an iRule​

First, you'll create an iRule that defines the redirection behavior.

  1. Go to Local Traffic > iRules > iRules List

  2. Click Create

  3. Enter a name for the iRule (e.g., Add_cred_to_header).

  4. In the Definition field, enter the following iRule:

    # Instruct BIG-IP system to NOT restrict the execution of certain iRule events that would otherwise be limited by the Access Policy.
    when CLIENT_ACCEPTED {
        ACCESS::restrict_irule_events disable
    }

    # Tell F5 that the client is not a browser and to handle the request as a non client
    when HTTP_REQUEST {
        HTTP::header insert "clientless-mode" 1
    }

    # Get Corsha Cred and store as perflow.custom variable
    when ACCESS_ACL_ALLOWED {
        set cred [HTTP::header values "X-Corsha-Cred"]
        set id [ACCESS::perflow get perflow.irule_agent_id]
        ACCESS::perflow set perflow.custom $cred
    }

If you wish to explicitly specify the target host, which may be necessary to route the request to the correct host, you can update the Host header within the HTTP_REQUEST event like below.

Replace X.X.X.X with the appropriate source IP the calls will be coming from and docs.corsha.com with the target host:

when HTTP_REQUEST {
    if { [HTTP::host] equals "X.X.X.X" } {
        # Rewrite the Host header
        HTTP::header replace "Host" "docs.corsha.com"
    }
    HTTP::header insert "clientless-mode" 1
}

Click Finished to save the iRule.

Create a Virtual Server​

tip

A virtual server is a traffic-management object on the BIG-IP system that is represented by an IP address and a service. Clients on an external network can send application traffic to a virtual server, which then directs the traffic according to the configuration instructions

For more information abuot F5 Virtual Servers, visit the F5 docs.

  1. Go to Local Traffic>Virtual Servers>Virtual Server List

  2. Click Create

  3. Under General Properties

    a. Enter a Name: test-server

    b. Source Address: 0.0.0.0/0

    c. Destination Address/Mask: 10.0.1.30

tip

Specifies destination IP address information to which the virtual server sends traffic

d. Service Port: 443

  1. Under Configuration

    a. HTTP Profile (Client): http

    b. SSL Profile (Client): select ssl client created above

    c. SSL Profile (Server): serverssl-insecure-compatible

    d. Source Address Translation: Auto Map

  2. Under Access Policy

    a. Access Profile: select the access profile we created

    b. Per-Request Policy: select the policy we created

  3. Under Resources

    a. for iRules, add the iRule we created

    b. for Default Pool, choose the pool we created earlier

  4. Click Finished

You have now configured Corsha with a F5 Big IP!