Chapter 2: Authentication

Home Prev	cOS Core 15.00.02 REST API Guide	Next

This section describes the usage of the cOS Core REST API with authentication. When the API is used with authentication, an external computer can perform the following management operations on a cOS Core configuration:

List currently authenticated users.
Retrieve information for a single currently authenticated user.
Add a new authenticated user.
End authentication of user.

A REST API Authentication Use Case

A typical use case for the REST API with authentication is where an external DHCP server is handing out IP addresses to clients on a private WiFi network in a public space such as a train station or airport. The clients might access resources such as the public Internet via a Clavister Next Generation Firewall.

As the DHCP server allocates IP addresses, it therefore needs to add and delete and possibly list the authenticated users in cOS Core. This can be done by using the REST API.

The sections that follow describe how to perform these operations.

2.1. Listing Currently Authenticated Users

To list information about all currently authenticated users, an HTTP GET must be sent to the URI:

/api/oper/userauth

The GET can have only the following optional parameter:

num - The maximum number of users to return (default value: 100).

cOS Core will send its reply back in JSON format. Below is an example of a reply to a GET:

{
  "error": false,
  "active_users_count": 2,
  "active_users": [
    {
      "username": "user1",
      "ip": "203.0.113.5",
      "groups": "group1,group2",
      "interface": "wan",
      "agent_type": "Identity Awareness",
      "session_timeout": 60,
      "idle_timeout": 60
    },
    {
      "username": "user2",
      "ip": "203.0.113.7",
      "groups": "group4,group5",
      "interface": "wan",
      "agent_type": "Identity Awareness",
      "session_timeout": 160,
      "idle_timeout": 60
    }
  ]
}

In the above JSON reply, there are 2 users listed with usernames user1 and user2. The user called user1 has an IPv4 address of 203.0113.5 and belongs to the groups group1 and group2. The user called user2 has an IPv4 address of 203.0113.7 and belongs to the groups group4 and group5. Both users have connected to cOS Core through the wan interface.

The agent-type value indicates the origin of the authenticated user. If a user was added to the authenticated list with the REST API then its agent-type value will always be "Identity Awareness".

If there are no authenticated users, the response will be the following:

{
  "error":false,
  "active_users_count":0,"active_users":[]
}