https: T8989: auth_methods AI comments fixed

1 files changed, 88 insertions, 0 deletions

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
                     </td>
                 <td>
                         <div>The API key configured on the VyOS device.</div>
+                        <div>Set <code>ansible_httpapi_api_key</code> in inventory or the <code>VYOS_API_KEY</code> environment variable.</div>
                 </td>
             </tr>
             <tr>
@@ -77,6 +80,12 @@ Parameters
                                 <div>var: ansible_vyos_auth_method</div>
                     </td>
                 <td>
+                        <div>Authentication method to use.</div>
+                        <div><code>key</code> sends the API key as a form field (default, backward-compatible).</div>
+                        <div><code>header</code> sends the API key as an <code>X-API-Key</code> header.</div>
+                        <div><code>bearer</code> exchanges the API key for a short-lived JWT via <code>POST /token</code> and sends it as an Authorization Bearer header for subsequent requests.</div>
+                        <div><code>mtls</code> uses mutual TLS client certificate authentication. No API key is sent. Requires <code>ansible_httpapi_client_cert</code> and <code>ansible_httpapi_client_key</code> to be set at the connection level.</div>
+                        <div><code>oidc</code> fetches a Bearer token from an external identity provider using the OAuth2 client credentials grant and sends it as an Authorization Bearer header. Requires <code>ansible_vyos_oidc_token_url</code>, <code>ansible_vyos_oidc_client_id</code>, and <code>ansible_vyos_oidc_client_secret</code>.</div>
                 </td>
             </tr>
             <tr>
@@ -94,6 +103,8 @@ Parameters
                                 <div>var: ansible_vyos_oidc_client_id</div>
                     </td>
                 <td>
+                        <div>OAuth2 client ID for the client credentials grant.</div>
+                        <div>Required when <code>auth_method=oidc</code>.</div>
                 </td>
             </tr>
             <tr>
@@ -111,6 +122,8 @@ Parameters
                                 <div>var: ansible_vyos_oidc_client_secret</div>
                     </td>
                 <td>
+                        <div>OAuth2 client secret for the client credentials grant.</div>
+                        <div>Required when <code>auth_method=oidc</code>.</div>
                 </td>
             </tr>
             <tr>
@@ -137,9 +150,84 @@ Parameters
     <br/>
 
 
+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 <seconds>``.
+   - 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
+