From ee810434422fa47c403dfe3fed5af9ca1c738128 Mon Sep 17 00:00:00 2001 From: omnom62 <75066712+omnom62@users.noreply.github.com> Date: Mon, 26 Oct 2026 22:46:53 +1000 Subject: T8989: auth_methods (#42) * https: T8989: auth_methods AI comments and conflicts fixed --- docs/vyos.rest.vyos_httpapi.rst | 180 ++++++++++++++++++++++++++++++++++++++-- 1 file changed, 173 insertions(+), 7 deletions(-) (limited to 'docs') diff --git a/docs/vyos.rest.vyos_httpapi.rst b/docs/vyos.rest.vyos_httpapi.rst index e493ebc..b91c229 100644 --- a/docs/vyos.rest.vyos_httpapi.rst +++ b/docs/vyos.rest.vyos_httpapi.rst @@ -5,10 +5,9 @@ vyos.rest.vyos ************** -**HttpApi plugin for VyOS REST API** +**VyOS REST API** -Version added: 1.0.0 .. contents:: :local: @@ -17,9 +16,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``. +- HTTPAPI plugin for interacting with VyOS REST API. +- Supports multiple authentication methods against the VyOS REST API -- ``key`` (API key in the request body), ``header`` (API key as an ``X-API-Key`` header), ``bearer`` (a VyOS-issued bearer token, fetched and cached), ``mtls`` (mutual TLS, no application-level credential), and ``oidc`` (a bearer token obtained from an external OpenID Connect provider via the client_credentials grant, fetched and cached). @@ -48,13 +46,181 @@ Parameters +
ini entries: +

[httpapi]
api_key = VALUE

+
+
env:ANSIBLE_HTTPAPI_API_KEY
env:VYOS_API_KEY
var: ansible_httpapi_api_key
var: ansible_vyos_api_key
-
The API key configured on the VyOS device.
-
Set ansible_httpapi_api_key in inventory or the VYOS_API_KEY environment variable.
+
VyOS API key. Required for auth_method key, header, and bearer.
+ + + + +
+ auth_method + +
+ string +
+ + + + + +
ini entries: +

[httpapi]
auth_method = key

+
+
var: ansible_httpapi_auth_method
+ + +
Authentication method to use against the VyOS REST API.
+ + + + +
+ oidc_allow_insecure_http + +
+ boolean +
+ + + + + +
ini entries: +

[httpapi]
oidc_allow_insecure_http = no

+
+
var: ansible_httpapi_oidc_allow_insecure_http
+ + +
By default the OIDC token endpoint must use https, because the request carries the client secret and the response carries a bearer token. Set this to true to allow a plain http endpoint.
+
Intended for isolated lab setups only. With this enabled the client secret and the access token travel in cleartext and can be captured and replayed by anyone on the network path.
+ + + + +
+ oidc_client_id + +
+ string +
+ + + + +
ini entries: +

[httpapi]
oidc_client_id = VALUE

+
+
var: ansible_httpapi_oidc_client_id
+ + +
OIDC client ID for the client_credentials grant.
+ + + + +
+ oidc_client_secret + +
+ string +
+ + + + +
ini entries: +

[httpapi]
oidc_client_secret = VALUE

+
+
var: ansible_httpapi_oidc_client_secret
+ + +
OIDC client secret for the client_credentials grant.
+ + + + +
+ oidc_timeout + +
+ integer +
+ + + Default:
10
+ + +
ini entries: +

[httpapi]
oidc_timeout = 10

+
+
var: ansible_httpapi_oidc_timeout
+ + +
Timeout, in seconds, for the token request made to the OIDC provider. An unavailable or stalled identity provider would otherwise hang the Ansible task indefinitely.
+ + + + +
+ oidc_token_url + +
+ string +
+ + + + +
ini entries: +

[httpapi]
oidc_token_url = VALUE

+
+
var: ansible_httpapi_oidc_token_url
+ + +
Token endpoint URL of the OIDC provider. Required for auth_method oidc.
+ + + + +
+ oidc_validate_certs + +
+ boolean +
+ + + + + +
ini entries: +

[httpapi]
oidc_validate_certs = yes

+
+
var: ansible_httpapi_oidc_validate_certs
+ + +
Validate the TLS certificate of the OIDC token endpoint.
+
Set to false only for a lab identity provider that uses a self-signed certificate.
-- cgit v1.2.3