ANSI C Based OPC UA Client/Server SDK  1.8.1.381
Authentication

Overview

The server allows to authenticate users by username and password when a session is activated. The user’s credentials are then verified with one of the available authentication modules. Only one module can be activated at the same time.

There are four authentication modules available:

Internal Authentication Module
File based module, available on all OS that have a filesystem
PAM Authentication Module
Linux only, needs PAM configuration file
SASL Authentication Module
Linux only, needs running saslauthd daemon
Win32 Authentication Module
Windows only

To activate a module, the according define has to be set to OPCUA_CONFIG_YES when compiling the SDK. After this step, the chosen module can be set after the UaServer has been initialized:

UaServer_SetUserAuthenticationTypeEx(&g_UaServer, UserAuthType_Internal, OpcUa_Null);

Additionally, the server’s endpoint has to be configured to accept UserName UserIdentityTokens. If no anonymous logon should be allowed, the Anonymous UserIdentityToken has to be disabled. Following code shows how to enable the UserName logon only:

UaServer_Configuration *pServerConfig = UaServer_GetConfiguration(&g_UaServer);
UaServer_Endpoint *pEndpoint = OpcUa_Null;
pServerConfig->uNoOfEndpoints = 1;
pServerConfig->pEndpoints = OpcUa_Alloc(sizeof(UaServer_Endpoint));
UaServer_Endpoint_Initialize(&pServerConfig->pEndpoints[0]);
pEndpoint = &pServerConfig->pEndpoints[0];
... configure endpoint ...
pEndpoint->uNoOfUserTokenPolicy = 1;
pEndpoint->pUserTokenPolicy = OpcUa_Alloc(pEndpoint->uNoOfUserTokenPolicy * sizeof(OpcUa_UserTokenPolicy));
OpcUa_UserTokenPolicy_Initialize(&pEndpoint->pUserTokenPolicy[0]);
OpcUa_String_StrnCat(&pEndpoint->pUserTokenPolicy[0].PolicyId,
OpcUa_String_FromCString("0"),
OPCUA_STRING_LENDONTCARE);
OpcUa_String_StrnCat(&pEndpoint->pUserTokenPolicy[0].SecurityPolicyUri,
OpcUa_String_FromCString(OpcUa_SecurityPolicy_Basic256),
OPCUA_STRING_LENDONTCARE);

As an alternative, the UaServer_UserAuthType can be set to UserAuthType_User. Then the third parameter of the UaServer_SetUserAuthenticationTypeEx method expects a pointer to a callback function that handles the authentication.

Modules

Internal Authentication Module

Define: #define UASERVER_SUPPORT_AUTHENTICATION_INTERNAL OPCUA_CONFIG_YES
Enum value: UserAuthType_Internal

Using Username and Password

The internal authentication module reads its authentication information from a file that is defined in the uaserver_config.h file, UASERVER_AUTHFILE_PASSWD. This file contains the usernames and the SHA1 hashes of the according passwords.

The following example shows the layout of the file. The first line just denotes the contents of the single columns, it must not appear in the actual file. Also, the UserId and GroupId columns have to contain valid values, even if they are used only in connection with Authorization. The UserId and GroupId are expected to be positive integers, the username can be any string, the SHA1 hash is expected in hexadecimal representation. If the username contains spaces, it has to be enclosed in quotation marks.

<UserId> <GroupId> <UserName> <SHA1 hash of password>
0 0 root e5e9fa1ba31ecd1ae84f75caaa474f3a663f05f4
1 1 anonymous 0000000000000000000000000000000000000000
2 4 joe 21298df8a3277357ee55b01df9530b535cf08ec1
3 5 john 4f26aeafdb2367620a393c973eddbe8f8b846ebd
4 6 sue e122d28c768ab44ceafe00d71adedc80a535cdf1
5 7 "jane doe" da882eab5e403421ac24258a5f7d5f965c29c849

This sample configuration is delivered with the UA ANSI C SDK. It should never actually be used in a running system. The passwords of the sample users are:

  • root: secret
  • joe: god
  • john: master
  • sue: curly
  • jane doe: pass word

Using X509 Certificates

The internal authentication module can also be used to authenticate users by using X509 certificates. This feature is enabled by default when the internal authentication module is enabled, only the endpoint has to be configured to allow X509IdentityTokens (TokenType OpcUa_UserTokenType_Certificate).

The folder containing the accepted certificates is set by the define UASERVER_USERCERTS_DIR, the folder for storing certificate revocation lists belonging to the certificates is set by the define UASERVER_USERCRL_DIR.

If authorization is enabled, the “Subject Common Name” is used as user name for looking up the authorization information in the passwd and group file. Hence, in this configuration these files have to exist and be filled with reasonable values.

PAM Authentication Module

Define: #define UASERVER_SUPPORT_AUTHENTICATION_PAM OPCUA_CONFIG_YES
Enum value: UserAuthType_PAM

The PAM authentication module uses the PAM library for validating the user’s credentials. The service name passed to the PAM library is “opcua”, so a “/etc/pam.d/opcua” PAM configuration file is expected to be existing. The service name can be changed in the uaserver_auth_pam.c file if necessary. The following shows the content of a sample “opcua” PAM configuration file that uses the shadow mechanism for authentication:

# Install this file to /etc/pam.d/
account required pam_unix2.so nullok
auth required pam_unix2.so nullok

If PAM is configured to use the shadow mechanism, the server has to be running in the context of a user who has read access to the /etc/shadow file.

If this module is used, the application needs to be linked against the “pam” library and the PAM development package has to be installed (usually named “pam-devel”).

More information on PAM can be found under http://www.linux-pam.org/.

SASL Authentication Module

Define: #define UASERVER_SUPPORT_AUTHENTICATION_SASL OPCUA_CONFIG_YES
Enum value: UserAuthType_SASL

The SASL authentication module uses the saslauthd daemon on the local machine for validating the user’s credentials. The saslautd daemon is expected to listen on “/var/run/sasl2/mux” for incoming connections, this value can be changed in uaserver_auth_sasl.c if necessary. The service passed to the saslauthd daemon is “imap”, this can also be changed in the same file.

If this module is used, the application needs to be linked against the “sasl2” library and the SASL development package has to be installed (usually named “sasl-devel”).

Win32 Authentication Module

Define: #define UASERVER_SUPPORT_AUTHENTICATION_WIN32 OPCUA_CONFIG_YES
Enum value: UserAuthType_Win32

The Win32 authentication module validates the user’s credentials against the windows logon provider. If the user is in a domain, the domain name can be passed together with the user name. There are two notations available that are recognized by the Win32 authentication module:

  • UPN (User Principal Name): UserName@DomainName (e.g. testuser@testdomain.com)
  • Down-Level User Logon Name: DomainName\UserName (e.g. TESTDOMAIN\testuser)

For these notations, username and domain are split at the separator automatically and are passed to the windows logon provider separately.