.. _authinfo:

Resource: Authentication Info
------------------------------

These endpoints return information about the server's authentication configuration.
They require no authentication token and are intended to be called before login to
allow clients to adapt their login UI accordingly.

.. _authinfo_logintypes:

Method: Get Enabled Login Types
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Description
^^^^^^^^^^^

Returns a list of which multi-factor authentication methods are enabled on this
particular StoredSafe appliance. Call this endpoint before presenting a login form
to determine which options to offer the user.

URL Syntax
^^^^^^^^^^

/api/{version}/authinfo/logintypes

HTTP Method
^^^^^^^^^^^

GET

Successful HTTP Response
^^^^^^^^^^^^^^^^^^^^^^^^^

200

Parameters
^^^^^^^^^^

No parameters required. No authentication token needed.

Response Attributes
^^^^^^^^^^^^^^^^^^^

+-------------------------------+------------------------------------------+---------+
| Attribute                     | Description                              | Type    |
+===============================+==========================================+=========+
| CALLINFO.status               | SUCCESS or FAIL                          | String  |
+-------------------------------+------------------------------------------+---------+
| CALLINFO.handler              | Handler used                             | String  |
+-------------------------------+------------------------------------------+---------+
| CALLINFO.errors               | Number of errors                         | Integer |
+-------------------------------+------------------------------------------+---------+
| CALLINFO.errorcodes           | Number of error codes                    | Integer |
+-------------------------------+------------------------------------------+---------+
| CALLINFO.enabled_login_types  | Array containing one list of enabled     | Array   |
|                               | login type strings                       |         |
+-------------------------------+------------------------------------------+---------+

Possible login type strings in ``CALLINFO.enabled_login_types[0]``:

+---------------+--------------------------------------------+
| Value         | Description                                |
+===============+============================================+
| ``totp``      | Time-based OTP (Google Authenticator etc.) |
+---------------+--------------------------------------------+
| ``yubikey_otp`` | Yubico OTP / HOTP                        |
+---------------+--------------------------------------------+
| ``smartcard`` | X.509 client certificate (TLS smartcard)   |
+---------------+--------------------------------------------+

Example
^^^^^^^

**Request**

::

    GET /api/1.0/authinfo/logintypes

**Response**

::

    HTTP/2 200
    Content-Type: application/json
    {
        "CALLINFO": {
            "errorcodes": 0,
            "errors": 0,
            "general": [],
            "handler": "AuthInfoHandler",
            "status": "SUCCESS",
            "enabled_login_types": [
                ["totp", "yubikey_otp"]
            ]
        },
        "DATA": [],
        "HEADERS": { ... },
        "PARAMS": []
    }

.. _authinfo_smcuser:

Method: Get Smartcard User
~~~~~~~~~~~~~~~~~~~~~~~~~~

Description
^^^^^^^^^^^

Looks up which StoredSafe user is associated with the TLS client certificate
presented by the caller. Intended for smartcard login flows where the client
certificate is passed by the TLS layer (via nginx ``$ssl_client_cert``).

Returns the matching username and the certificate's subject fields. Returns
HTTP 401 if no valid client certificate is found or if it is not registered
to any active user.

.. note::
   This endpoint requires the TLS layer (nginx) to be configured to request and
   forward client certificates. The certificate must have been registered on a
   user account using the ``/usercert`` endpoint.

URL Syntax
^^^^^^^^^^

/api/{version}/authinfo/smcuser

HTTP Method
^^^^^^^^^^^

GET

Successful HTTP Response
^^^^^^^^^^^^^^^^^^^^^^^^^

200

Parameters
^^^^^^^^^^

No query parameters. The client certificate is passed transparently by the TLS
layer — no ``X-Http-Token`` header is needed or accepted.

Response Attributes
^^^^^^^^^^^^^^^^^^^

+---------------------+--------------------------------------------------+---------+
| Attribute           | Description                                      | Type    |
+=====================+==================================================+=========+
| CALLINFO.status     | SUCCESS or FAIL                                  | String  |
+---------------------+--------------------------------------------------+---------+
| CALLINFO.handler    | Handler used                                     | String  |
+---------------------+--------------------------------------------------+---------+
| CALLINFO.errors     | Number of errors                                 | Integer |
+---------------------+--------------------------------------------------+---------+
| CALLINFO.errorcodes | Number of error codes                            | Integer |
+---------------------+--------------------------------------------------+---------+
| CALLINFO.username   | StoredSafe username matching the certificate,    | String  |
|                     | or absent if no match found                      |         |
+---------------------+--------------------------------------------------+---------+
| CALLINFO.subject    | Certificate subject fields (CN, O, OU, C, etc.)  | Object  |
+---------------------+--------------------------------------------------+---------+

Example
^^^^^^^

**Request**

::

    GET /api/1.0/authinfo/smcuser
    (TLS client certificate presented)

**Response (certificate matched to a user)**

::

    HTTP/2 200
    Content-Type: application/json
    {
        "CALLINFO": {
            "errorcodes": 0,
            "errors": 0,
            "general": [],
            "handler": "AuthInfoHandler",
            "status": "SUCCESS",
            "username": "alice",
            "subject": {
                "CN": "Alice Example",
                "O":  "Example AB",
                "C":  "SE"
            }
        },
        "DATA": [],
        "HEADERS": { ... },
        "PARAMS": []
    }

**Response (no matching certificate)**

::

    HTTP/2 401
    Content-Type: application/json
    {
        "CALLINFO": {
            "errorcodes": 1,
            "errors": 1,
            "general": ["No valid certificate found"],
            "handler": "AuthInfoHandler",
            "status": "FAIL"
        }
    }