From ec32197dcda1c0dcabdcc11d81ce8df3ebc3754c Mon Sep 17 00:00:00 2001 From: omnom62 Date: Sun, 20 Sep 2026 09:16:12 +1000 Subject: https: T8989: auth_methods AI comments fixed --- docs/vyos.rest.vyos_httpapi.rst | 88 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 88 insertions(+) (limited to 'docs') diff --git a/docs/vyos.rest.vyos_httpapi.rst b/docs/vyos.rest.vyos_httpapi.rst index 99e1924..2c2d490 100644 --- a/docs/vyos.rest.vyos_httpapi.rst +++ b/docs/vyos.rest.vyos_httpapi.rst @@ -18,6 +18,8 @@ Version added: 1.0.0 Synopsis -------- - This HttpApi plugin provides methods to connect to VyOS devices via their HTTPS REST API. +- Use with ``ansible_connection=ansible.netcommon.httpapi`` and ``ansible_network_os=vyos.rest.vyos``. +- The VyOS REST API must be enabled with ``set service https api keys id ansible key YOUR_KEY``, ``set service https api rest``, then ``commit && save``. @@ -52,6 +54,7 @@ Parameters
The API key configured on the VyOS device.
+
Set ansible_httpapi_api_key in inventory or the VYOS_API_KEY environment variable.
@@ -77,6 +80,12 @@ Parameters
var: ansible_vyos_auth_method
+
Authentication method to use.
+
key sends the API key as a form field (default, backward-compatible).
+
header sends the API key as an X-API-Key header.
+
bearer exchanges the API key for a short-lived JWT via POST /token and sends it as an Authorization Bearer header for subsequent requests.
+
mtls uses mutual TLS client certificate authentication. No API key is sent. Requires ansible_httpapi_client_cert and ansible_httpapi_client_key to be set at the connection level.
+
oidc fetches a Bearer token from an external identity provider using the OAuth2 client credentials grant and sends it as an Authorization Bearer header. Requires ansible_vyos_oidc_token_url, ansible_vyos_oidc_client_id, and ansible_vyos_oidc_client_secret.
@@ -94,6 +103,8 @@ Parameters
var: ansible_vyos_oidc_client_id
+
OAuth2 client ID for the client credentials grant.
+
Required when auth_method=oidc.
@@ -111,6 +122,8 @@ Parameters
var: ansible_vyos_oidc_client_secret
+
OAuth2 client secret for the client credentials grant.
+
Required when auth_method=oidc.
@@ -137,9 +150,84 @@ Parameters
+Notes +----- + +.. note:: + - Bearer tokens are cached in memory for the duration of the connection and refreshed automatically 30 seconds before expiry. + - Token expiry is controlled on the device via ``set service https api rest authentication expiration ``. + - For mTLS, set ``ansible_httpapi_client_cert`` and ``ansible_httpapi_client_key`` at the connection level. The netcommon httpapi connection plugin handles the TLS handshake automatically. + - OIDC tokens are cached and refreshed using the ``expires_in`` value returned by the identity provider. +Examples +-------- + +.. code-block:: yaml + + # inventory.yml - form-field API key (default, backward-compatible) + all: + hosts: + vyos01: + ansible_host: 192.168.1.1 + ansible_connection: ansible.netcommon.httpapi + ansible_network_os: vyos.rest.vyos + ansible_httpapi_use_ssl: true + ansible_httpapi_validate_certs: false + ansible_httpapi_api_key: mysecretkey + + # inventory.yml - X-API-Key header + all: + hosts: + vyos01: + ansible_host: 192.168.1.1 + ansible_connection: ansible.netcommon.httpapi + ansible_network_os: vyos.rest.vyos + ansible_httpapi_use_ssl: true + ansible_httpapi_validate_certs: false + ansible_httpapi_api_key: mysecretkey + ansible_vyos_auth_method: header + + # inventory.yml - Bearer token (JWT) + all: + hosts: + vyos01: + ansible_host: 192.168.1.1 + ansible_connection: ansible.netcommon.httpapi + ansible_network_os: vyos.rest.vyos + ansible_httpapi_use_ssl: true + ansible_httpapi_validate_certs: false + ansible_httpapi_api_key: mysecretkey + ansible_vyos_auth_method: bearer + + # inventory.yml - mTLS client certificate + all: + hosts: + vyos01: + ansible_host: 192.168.1.1 + ansible_connection: ansible.netcommon.httpapi + ansible_network_os: vyos.rest.vyos + ansible_httpapi_use_ssl: true + ansible_httpapi_validate_certs: false + ansible_vyos_auth_method: mtls + ansible_httpapi_client_cert: /etc/ansible/certs/client.pem + ansible_httpapi_client_key: /etc/ansible/certs/client.key + + # inventory.yml - OIDC (Keycloak client credentials) + all: + hosts: + vyos01: + ansible_host: 192.168.1.1 + ansible_connection: ansible.netcommon.httpapi + ansible_network_os: vyos.rest.vyos + ansible_httpapi_use_ssl: true + ansible_httpapi_validate_certs: false + ansible_vyos_auth_method: oidc + ansible_vyos_oidc_token_url: https://keycloak.example.com/realms/vyos/protocol/openid-connect/token + ansible_vyos_oidc_client_id: vyos-api + ansible_vyos_oidc_client_secret: mysecret + -- cgit v1.2.3