# Connection Info auth plugins

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

---

Site [llms.txt](/llms.txt)

---

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](/docs/cmp/configure/integrations/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](/docs/cmp/configure/integrations/connection-info/#add-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.
1. Next to **Auth Plug-in**, select the pencil icon.
1. 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.
1. 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](#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.
1. 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.

```python
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.

```python
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)}."
```

<div class="alert alert-warning" role="alert"><div class="h4 alert-heading" role="heading">Keep secrets out of output</div>


Never log, print, or return the token or the password in a message. The Verify Connection dialog shows the message from `verify_connection()` to the admin.
</div>


## 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.

```python
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.

```python
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.

```python
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](/docs/cmp/configure/integrations/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.
1. 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](#add-an-auth-plugin).

## 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.

```bash
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.
