Connection Info auth plugins

Use a plugin on a Connection Info to get, store, and refresh tokens for APIs that issue short-lived tokens

Many APIs do not accept a fixed username and password on every request. They issue a short-lived token that must be requested, reused, then refreshed when it expires. An auth plugin is a CloudBolt plugin you attach to a Connection Info. It holds the code that logs in to your system and returns a token. Cloud Management Platform (CMP) then:

  • Stores the token, refresh token, and expiration on the Connection Info, encrypted.
  • Reuses the token until it is about to expire, then requests a new one when next needed.
  • Runs one refresh at a time, even when many jobs use the same Connection Info simultaneously.
  • Gives your actions and plugins an authenticated HTTP session, the auth headers, or a client that the plugin builds (such as a vendor SDK client).

Your actions and plugins never call the auth plugin directly.

Before you begin

  • You must be a CloudBolt Admin or Super Admin to attach, create, or remove an auth plugin.
  • Create a Connection Info for the target system with its protocol, host, and port. Enter the credentials the plugin logs in with as the username and password. For OAuth2, these are typically the client ID and secret.
  • Find out how your system issues tokens: the token endpoint, what it expects in the request, what it returns, and how long a token lasts.
  • Auth plugins run Python code with CMP’s privileges. Review plugin code before you attach it.

Add an auth plugin

  1. Go to Admin > Connection Info and select the Connection Info’s name.

  2. Next to Auth Plug-in, select the pencil icon.

  3. In the dialog, either:

    • Attach an existing plugin by selecting it from the shared plugins and then selecting Set selected CloudBolt plug-in as auth plug-in, or
    • Create a new plugin from an uploaded file, a URL to the code, or code you enter later, and then complete the form. If you enter the code later, the plugin starts from a template that documents every function it can define.

    The details page now has Code and Repository tabs for the plugin.

  4. If you created a new plugin, edit it on the Code tab. At a minimum, fill in authenticate() so it requests a token from your system and returns it. Uncomment any optional function you need. See Write an auth plugin.

Verify the connection

When a plugin is attached, the Overview tab has a Verify Connection button.

  1. Select Verify Connection. A dialog opens, and CMP runs the plugin’s verify_connection() function.
  2. Read the success or error message, and then select OK.

If the plugin does not define verify_connection(), the dialog reports that the plugin cannot verify the connection.

Write an auth plugin

An auth plugin is a Python module that defines up to five functions. Only authenticate() is required. CMP calls each function the plugin defines. For the others, it uses a default or reports an error, as shown in the following table.

Function Required When CMP calls it When it is not defined
authenticate Yes No token is stored, or a new token is needed and refresh is not available or fails. Requests for a token fail.
refresh No A new token is needed and a refresh token is stored. CMP calls authenticate instead.
get_auth_headers No Every time auth headers are requested. CMP sends Authorization: Bearer <token>.
get_client No Every time code asks the Connection Info for a client. Asking for a client fails. HTTP code uses the session instead.
verify_connection No An admin selects Verify Connection. Verify Connection reports that the plugin cannot verify the connection.

Function arguments

CMP calls every function with the Connection Info as the connection_info keyword argument. Define each function with **kwargs so it keeps working if a later release passes more arguments.

From connection_info, your code can read:

  • protocol, ip, and port: where the system is.
  • username and password: the credentials to log in with.
  • headers: the Connection Info’s static headers, as a JSON string.
  • token and refresh_token: the values CMP has stored.

authenticate

Log in to the system and return the new token as a dictionary:

Key Required Description
token Yes The access token.
refresh_token No A token that refresh() can exchange for a new access token.
expires_in No The number of seconds until the token expires.
expires_at No A datetime when the token expires. A datetime without a time zone is read as UTC. Return either expires_in or expires_at, not both.

If the function returns no token, the call fails and CMP keeps the values it had stored.

If you return no expiration, CMP reuses the token until code calls refresh(), for example after a 401 response.

refresh

Exchange connection_info.refresh_token for a new access token and return the same dictionary as authenticate().

  • If your system issues a new refresh token each time, return it. CMP replaces the stored refresh token.
  • If you return no refresh token, CMP keeps the stored one.
  • If refresh() raises an error, CMP calls authenticate() instead.

get_auth_headers

Return a dictionary of the headers that send the token, using connection_info.token. Define this function when your system expects something other than Authorization: Bearer <token>, such as a custom header name.

When Use Auth Headers is selected, CMP sends the Connection Info’s static headers along with the headers from get_auth_headers(). If both set the same header, CMP uses the value from get_auth_headers().

get_client

Build and return a client for your system. Define this function when your actions need something other than a plain HTTP session, such as a vendor SDK client, a session with certificate settings, or a connection that does not use HTTP.

  • connection_info.get_auth_headers() and connection_info.get_auth_session() get a fresh token first when the stored one is missing or about to expire. Call get_auth_headers() before you read connection_info.token, which holds only the stored value.
  • CMP calls get_client() every time an action asks for a client and does not keep the result. Only the token is stored and shared.
  • CMP cannot retry requests for a client it did not build. When your system rejects the token, the client or the action must call connection_info.refresh() and retry.
from vendor_sdk import VendorClient


def get_client(connection_info, **kwargs):
    connection_info.get_auth_headers()

    return VendorClient(
        host=connection_info.ip,
        port=connection_info.port,
        token=connection_info.token,
    )

verify_connection

Check that the Connection Info can reach and authenticate to the system, and return a tuple of (success, message). The Verify Connection dialog shows the message as a success or an error.

A typical implementation calls connection_info.authenticate() and then makes a read-only request, such as reading the current user.

Example: OAuth2 client credentials

This example gets a token with the OAuth2 client credentials grant, using the Connection Info’s username and password as the client ID and secret. Adapt the token URL and the request to your system.

import requests


def _token_url(connection_info):
    return (
        f"{connection_info.protocol or 'https'}://{connection_info.ip}:{connection_info.port}"
        "/oauth/token"
    )


def _request_token(connection_info, data):
    response = requests.post(
        _token_url(connection_info),
        data=data,
        auth=(connection_info.username, connection_info.password),
        timeout=30,
    )
    response.raise_for_status()
    body = response.json()

    return {
        "token": body["access_token"],
        "refresh_token": body.get("refresh_token"),
        "expires_in": body.get("expires_in"),
    }


def authenticate(connection_info, **kwargs):
    return _request_token(connection_info, {"grant_type": "client_credentials"})


def refresh(connection_info, **kwargs):
    return _request_token(
        connection_info,
        {"grant_type": "refresh_token", "refresh_token": connection_info.refresh_token},
    )


def verify_connection(connection_info, **kwargs):
    try:
        connection_info.authenticate()
    except requests.RequestException as error:
        return False, f"Could not get a token from {_token_url(connection_info)}: {error}"

    return True, f"Got a token from {_token_url(connection_info)}."

Use the Connection Info in actions

Actions, plugins, and other code that call the system get authentication from the Connection Info.

Use the HTTP session

For a REST API, use get_auth_session(). It returns a requests session that adds the auth headers to every request.

  • Pass only the path. The session adds the Connection Info’s protocol, host, and port, and leaves a full URL unchanged.
  • The session sends the auth headers only to the Connection Info’s host. Requests and redirects to other hosts go without them.
  • When the system answers with a 401 response, the session gets a new token and retries the request once. A second 401 is returned to your code.
from utilities.models import ConnectionInfo

connection_info = ConnectionInfo.objects.get(name="My API")
session = connection_info.get_auth_session()

response = session.get("/api/items", params={"page_size": 10}, timeout=30)
response.raise_for_status()

session.post("/api/items", json={"name": "New Item"}, timeout=30)

Use the plugin’s client

When the plugin defines get_client(), call get_client() on the Connection Info to get the client it builds. If the plugin does not define get_client(), the call fails.

from utilities.models import ConnectionInfo

connection_info = ConnectionInfo.objects.get(name="My Platform")
client = connection_info.get_client()

for vm in client.list_vms():
    ...

Use the headers with another client

For another HTTP client or a vendor SDK, ask for the headers with get_auth_headers(). It returns a dictionary and gets a token first when none is stored or the stored one is about to expire.

If the system rejects the token with a 401 response, call refresh() and ask for the headers again before retrying.

from utilities.models import ConnectionInfo

connection_info = ConnectionInfo.objects.get(name="My API")
headers = connection_info.get_auth_headers()

# After a 401 response:
connection_info.refresh()
headers = connection_info.get_auth_headers()

Connection Info methods

Method Returns Description
get_auth_session() A requests.Session A session that sends the auth headers to the Connection Info’s host, resolves paths against its address, and retries once after a 401 response.
get_client() The plugin’s client The client built by the plugin’s get_client(). Fails when not defined.
get_auth_headers() A dictionary The auth headers, merged with the static headers when Use Auth Headers is selected.
refresh() The new token Gets a new token, even if the stored one has not expired.
authenticate() The new token Runs the plugin’s authenticate() and stores the result.
verify_connection() (success, message) Runs the plugin’s verify_connection().

Token storage and refresh

  • The token and refresh token are stored encrypted on the Connection Info. They are never shown in the UI and are not included in API responses or exports.
  • CMP treats a token as expired 60 seconds before its expiration so a request does not start with a token about to expire.
  • When a new token is needed, CMP calls refresh() if the plugin defines it and a refresh token is stored. Otherwise, or if refresh() fails, it calls authenticate().
  • Only one refresh runs for a Connection Info at a time. Jobs that need a token while a refresh is running wait and then use the new token.
  • Changing the Connection Info’s username, password, static headers, Use Auth Headers setting, or auth plugin clears the stored token. The next request logs in again.

Manage the auth plugin

Edit the code

Edit the code on the Connection Info’s Code tab. Several Connection Infos can share one plugin, and a change applies to all of them.

Use source control

Use the Repository tab to link the plugin to a source code repository, push the code to it, and refresh the code from it. See Integrate a remote source code repository. Once the plugin is linked, the tab is named after the repository’s service, such as GitHub.

Remove the plugin

  1. On the Overview tab, select the x icon next to the plugin’s name.
  2. Select Disassociate.

The plugin is removed from the Connection Info but not deleted. Other Connection Infos that share the plugin are not affected.

Change the plugin

Remove the current plugin, then add a different one.

API and export

REST API

In the v3 API, set the authPlugin field to the plugin’s href, which uses the plugin’s global ID. Send null to remove the plugin.

PATCH /api/v3/cmp/connectionInfo/<connection-info-global-id>/
{"authPlugin": "/api/v3/cmp/actions/<plugin-global-id>/"}

Responses link to the attached plugin in _links.authPlugin. They never include the token or refresh token.

Export and import

An exported Connection Info refers to its auth plugin by the plugin’s global ID. The export does not include the plugin itself or the stored tokens.

On import, the Connection Info is linked to the plugin with that global ID. If no such plugin exists, the Connection Info is imported without an auth plugin and CMP logs a warning.

Troubleshooting

Auth plug-in ‘name’ does not define verify_connection(), so it cannot verify this connection

Verify Connection was selected and the plugin has no verify_connection(). Uncomment and fill in verify_connection() on the Code tab, or test the plugin from an action.

Auth plug-in ‘name’ is not implemented yet

Verify Connection ran a function that raised NotImplementedError, typically the template’s authenticate() stub called from verify_connection(). Fill in the plugin’s functions on the Code tab.

Auth plug-in ‘name’ does not define get_client()

Code called get_client() and the plugin has no get_client(). Define get_client() in the plugin, or use get_auth_session() for an HTTP API.

Auth plug-in ‘name’ has no authenticate()

The plugin does not define authenticate(). Add authenticate() to the plugin.

Auth plug-in ‘name’ authenticate() returned no token

The function returned nothing, or a dictionary without a token key. Return a dictionary with a token key, and check the system’s response. The same message appears for refresh().

Connection Info ‘name’ has no auth plug-in

Code asked for a token or a client from a Connection Info without an auth plugin. Attach an auth plugin, or read the Connection Info’s username and password directly.

Requests keep failing with 401 after a refresh

The system rejects each new token. Check the Connection Info’s credentials, the plugin’s token request, and the header format that get_auth_headers() returns.