Connection Info auth plugins
11 minute read
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
-
Go to Admin > Connection Info and select the Connection Info’s name.
-
Next to Auth Plug-in, select the pencil icon.
-
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.
-
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.
- Select Verify Connection. A dialog opens, and CMP runs the plugin’s
verify_connection()function. - 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, andport: where the system is.usernameandpassword: the credentials to log in with.headers: the Connection Info’s static headers, as a JSON string.tokenandrefresh_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 callsauthenticate()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()andconnection_info.get_auth_session()get a fresh token first when the stored one is missing or about to expire. Callget_auth_headers()before you readconnection_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)}."
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.
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 ifrefresh()fails, it callsauthenticate(). - 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
- On the Overview tab, select the x icon next to the plugin’s name.
- 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.