==========================
Server side authentication
==========================

One of the tasks of the OPCUA server stack is to manage sessions,
including their timeouts and the processing of user tokens. The
server tracks the lifetime of sessions and checks if requests are
being performed under a valid session.

During session activation, the server receives a user token,
decrypts it, and checks its validity. The user represented
by the token is not validated, leaving the validation process up
to the developer.

Identity token policies
=======================

To support user authentication, it is necessary to configure user
identity token policies. The server returns to the client the
parameters of supported identity token policies. Using this information,
the client can create a user token with the required parameters.

The user identity policies on the server are specified in the
*userIdentityTokens* field:

.. literalinclude:: ../examples/server/server_configure_auth.lua
    :language: lua
    :lines: 7-59

`Full source <../_static/server/server_configure_auth.lua>`__

Authentication callback
=======================

When the server receives a user token from the client, it first
validates its consistency and checks its security parameters.
Then, it is required to check the content of the token, such as
the username and password, certificate validity, JWT signatures,
roles, etc. To perform all of these checks, the server can call
an authentication callback function. This callback is specified
in the server configuration file in the authenticate field.

The following example demonstrates an implementation of such a
function:

.. literalinclude:: ../examples/server/server_configure_auth.lua
    :language: lua
    :lines: 9-25

`Full source <../_static/server/server_configure_auth.lua>`__

The authentication callback function receives a token, validates
the token, and must return a boolean value:

* *true* - indicates that the server allows access
* *false* - indicates that the server rejects access.

The authentication callback is called with specific parameters for
each type of token. The following sections describe the parameters
for each supported token type.

Anonymous token
===============

To use anonymous (or absent) authentication, you need to add the
following element to the userIdentityTokens configuration table:


.. literalinclude:: ../examples/server/server_auth_anonymous.lua
    :language: lua
    :lines: 19-24

`Full source <../_static/server/server_auth_anonymous.lua>`__

The authentication callback is called with only the tokenType equal
to "anonymous".
The example:

.. literalinclude:: ../examples/server/server_auth_anonymous.lua
    :language: lua
    :lines: 9-16

`Full source <../_static/server/server_auth_anonymous.lua>`__


User Name and password
======================

Configuration file should contain a section with username token policy:

.. literalinclude:: ../examples/server/server_auth_username.lua
    :language: lua
    :lines: 18-29

`Full source <../_static/server/server_auth_username.lua>`__

If a token policy has a security policy, then the corresponding
security policy must be configured in the securityPolicies field,
as it contains the server certificate and key that are used for
encrypting passwords. It's important to configure the security
policies correctly in order to ensure secure user authentication.

The authentication callback is called with three parameters:

* **tokenType** is equal to *"username"*.
* **token** with password.
* **userName** with user name.

.. literalinclude:: ../examples/server/server_auth_username.lua
    :language: lua
    :lines: 9-16

`Full source <../_static/server/server_auth_username.lua>`__


X509 user certificate
=====================

To enable certificate-based user authentication, the configuration
file should include a section with the Certificate user identity
policy. This allows clients to provide their certificate to the
server for authentication:

.. literalinclude:: ../examples/server/server_auth_x509.lua
    :language: lua
    :lines: 20-25

`Full source <../_static/server/server_auth_x509.lua>`__

The authentication callback is called with two parameters:

* **tokenType** is equal to *"x509"*.
* **token** with certificate in der format.

.. literalinclude:: ../examples/server/server_auth_x509.lua
    :language: lua
    :lines: 9-17

`Full source <../_static/server/server_auth_x509.lua>`__

Issued tokens
=============

The OPCUA server can support authentication using tokens issued
by third-party identity services. These types of tokens can be
useful in allowing users to authenticate using their existing
login credentials from other systems or services, without the need
to create new usernames and passwords for the OPCUA server:

The OPCUA server currently supports the following types of issued
tokens:

* *JWT*
* *Azure*
* *OAuth2*

To configure authentication using issued tokens, it is necessary
to add a section with tokenType equal to IssuedToken. Each section
should include the following fields:

* **policyId** name of the policy.
* **tokenType** equals to *IssuedToken*
* **issuerEnpointUrl** URL of the identiti server which issues tokens.
* **issuedTokenType** type of the issued token: JWT, Azure etc...
* **securityPolicyUri** encryption parameters should be applied to token.
    If absent then token is sent without encryption.

Here is an example of how to configure different issued token policies:

.. literalinclude:: ../examples/server/server_auth_issued_token.lua
    :language: lua
    :lines: 23-53

`Full source <../_static/server/server_auth_issued_token.lua>`__

The authentication callback for all types of issued tokens is called with
three parameters:

* **tokenType** is equal to one of *"jwt"*, *"oauth2"*, *"azure"*.
* **token** with token content.
* **issuerEnpointUrl** The parameter issuerEndpointUrl specifies the URL
    of the server that issued the token. The value of this field is
    taken from the corresponding token policy in the userIdentityTokens
    field of the configuration table.

.. literalinclude:: ../examples/server/server_auth_issued_token.lua
    :language: lua
    :lines: 9-20

`Full source <../_static/server/server_auth_issued_token.lua>`__