Pass-through authentication

The pass-through authentication mechanism is used by setups where front-end servers are performing end-user authentication. It makes use of HTTP headers to pass authenticated user identity to SpectX. The user identity must be registered with SpectX to determine user rights.

If SpectX does not find a matching user in its user database and automatic creation of user accounts is disabled then the user interaction flow falls back to the default authentication scheme via the login screen.

To enable pass-through authentication on SpectX side, specify the name of the HTTP header of user identity as a value of wgui.passThroughAuth.usernameHeader parameter (header name case insensitive).

Additionally Ensure: * The SpectX WUI is accessible at a network level only by the frontend server which performs authentication.

  • The front-end server is configured to forward the remote client’s IP address to SpectX WUI in the custom header, the name of which is set as a value of wgui.remoteIPAddressHeader in SpectX configuration.
  • The frontend server must be configured to disallow passing through the header of authenticated user identity in incoming requests.

Example: enabling pass-through of personal identification code extracted from Estonian ID-card certificates. Nginx is used as an authentication proxy server to SpectX instance running at http://127.0.0.1:8388/. The name of the authenticated user identity HTTP header is X-Username. Note that API requests are configured to be passed through as they use a separate authentication method.

Nginx configuration:

...
http {
    upstream SpectX {
        server 127.0.0.1:8388;
        # ...
    }
    # get serial
    map $ssl_client_s_dn $ssl_client_s_dn_serial {
       default "";
       ~/serialNumber=(?<serialNumber>[^/]+) $serialNumber;
    }
    # get CN
    map $ssl_client_s_dn $ssl_client_s_dn_cn {
        default "";
        ~/CN=(?<CN>[^/]+) $CN;
    }
    server {
        listen 443 ssl;
        # ...
        ssl_verify_client optional;
        ssl_verify_depth 2;

        location / {
                if ($ssl_client_verify != SUCCESS) {
                        return 403;
                }
                proxy_set_header X-Real-IP $remote_addr;
                proxy_set_header X-Username $ssl_client_s_dn_serial;
                # below row can be enabled if wgui.passThroughAuth.autoCreateAccount is set to true
                # proxy_set_header X-Fullname $ssl_client_s_dn_cn;
                proxy_pass http://SpectX;
                # ...
        }
        location /API/ {
                proxy_set_header X-Real-IP $remote_addr;
                proxy_pass http://SpectX/API/;  #pass through API requests as they have separate authentication
                # ...
        }
   }
}
...

SpectX configuration:

...
    wgui.remoteIPAddressHeader=X-Real-IP
    wgui.passThroughAuth.usernameHeader=X-Username
    wgui.passThroughAuth.fullnameHeader=X-Fullname
...

Remember to register user identities in SpectX user database (see Managing Users and Groups). Alternatively, Enable automatic user account creation using the following configuration parameters:

  • wgui.passThroughAuth.autoCreateAccount - boolean setting enabling automatic creation of user accounts in SpectX user database when they first log into SpectX with given authentication method. This feature is off by default

  • wgui.passThroughAuth.autoCreateApiKey - boolean setting enabling automatic creation of SpectX API key for user accounts which get created automatically when they first log into SpectX with given authentication method. The setting is ignored if wgui.passThroughAuth.autoCreateAccount is not set to true. The default value for this setting is false.

  • wgui.passThroughAuth.fullnameHeader - optional parameter specifying a name of a HTTP header containing users’s full name. The value of the header, if it is present, will be used when creating an account in SpectX database.