SmartWeb supports several login methods that can also be activated at the same time — for browser clients, for server-to-server clients and for gRPC clients. The whole authentication configuration lives under smartweb.authentication in the application.yaml file.

Supported Authentication Modes

The smartweb.authentication.authModes list determines which authentication mechanisms are activated. Several modes can be combined; the appropriate mode is selected for each request based on the URL path and the credentials presented. The default value is AUTH_CREDENTIALS_IN_SESSION.

Mode	Purpose	Prerequisites

Mode	Purpose	Prerequisites
`AUTH_CREDENTIALS_IN_SESSION`	Username / password authentication against native D2000 users — verified by opening a D2000 JAPI session directly for that user	—
`AUTH_CREDENTIALS_IN_RPC`	Username / password authentication delegated to a custom D2000 RPC method (application-defined users). The JAPI session is opened under the technical account `authSessionUsername`	requires the technical account `authSessionUsername` / `authSessionPassword` and the authentication RPC method `authRpc`
`AUTH_AUTO_LOGON_IN_SESSION`	Automatic login to D2000 with a predefined service user — no login dialog is shown	used on its own, not combined with other modes; requires the technical account `authSessionUsername` / `authSessionPassword`
`AUTH_CERTIFICATE_LOCALLY`	X.509 client certificate validated locally against the servlet container truststore	`AUTH_CREDENTIALS_IN_SESSION` or `AUTH_CREDENTIALS_IN_RPC`
`AUTH_CERTIFICATE_REMOTELY`	X.509 client certificate validated remotely by a D2000 RPC method (the Base64-encoded certificate is sent to D2000)	`AUTH_CREDENTIALS_IN_SESSION` or `AUTH_CREDENTIALS_IN_RPC`; requires the authentication RPC method `authRpc`
`AUTH_SPNEGO_REMOTELY`	SPNEGO / Kerberos (Windows Integrated Authentication); the SPNEGO token is forwarded to D2000, which validates the Kerberos ticket and opens the JAPI session	`AUTH_CREDENTIALS_IN_SESSION`
`AUTH_SPNEGO_LOCALLY`	SPNEGO / Kerberos validated locally by SmartWeb against a keytab; the extracted username is passed to the authentication method. Requires the `spnego` block	`AUTH_CREDENTIALS_IN_RPC`
`AUTH_WEBAUTHN_LOCALLY`	Passkey login (WebAuthn / FIDO2) verified locally by SmartWeb; see Passkey (WebAuthn) Login Configuration	`AUTH_CREDENTIALS_IN_RPC` (optionally also `AUTH_CERTIFICATE_LOCALLY` / `AUTH_CERTIFICATE_REMOTELY`; other modes are not allowed)
`AUTH_OIDC_LOCALLY`	Login through an external identity provider (OIDC / IAM, single sign-on). SmartWeb exchanges the authorization code for tokens and validates the ID token itself; see Login via OIDC / IAM (SSO)	`AUTH_CREDENTIALS_IN_RPC`
`AUTH_OIDC_REMOTELY`	Planned. Login through OIDC where the authorization code is validated by the D2000 kernel. Not usable yet — see Login via OIDC / IAM (SSO)	`AUTH_CREDENTIALS_IN_SESSION`

[!NOTE] The mandatory mode combinations are checked at application startup. If the configuration does not satisfy one of the conditions, SmartWeb does not start and writes the specific error to the log (e.g. „When AUTH_OIDC_LOCALLY mode is specified in smartweb.authentication.authModes property, AUTH_CREDENTIALS_IN_RPC mode is required!“).

[!IMPORTANT] The AUTH_AUTO_LOGON_IN_SESSION mode is listed in authModes on its own. Automatic login with a predefined service user is not combined with other login methods — all users work under a single D2000 account, so verifying identity with another mode makes no sense.

[!IMPORTANT] The AUTH_CREDENTIALS_IN_SESSION mode and the authSessionUsername / authSessionPassword parameters are mutually exclusive. With AUTH_CREDENTIALS_IN_SESSION the session is opened directly under the user being logged in, so a technical account makes no sense and specifying it stops the application from starting. Conversely, the technical account is mandatory for AUTH_AUTO_LOGON_IN_SESSION and AUTH_CREDENTIALS_IN_RPC.

Authentication of Server-to-Server Clients

Independently of authModes, static API keys can be enabled for machine-to-machine clients. They apply to the paths /api/rest/**, /api/odata/**, /api/open/**, /api/oauth2/**, /api/opentsdb/** and to the gRPC API.

Method	HTTP header / gRPC metadata	Configuration

Method	HTTP header / gRPC metadata	Configuration
API key	`X-API-Key: <key>`	`smartweb.authentication.apiKeys`
Username and password (HTTP Basic)	`Authorization: Basic <base64(user:password)>`	governed by the `authModes` setting, same as a browser login

[!NOTE] SmartWeb accepts no other way of authenticating server-to-server clients — the Authorization: Bearer <token> header is not evaluated on these paths. Logging a browser user in through an external identity provider is handled by the AUTH_OIDC_LOCALLY mode, see Login via OIDC / IAM (SSO).

Configuration Parameters

Overview

smartweb:
  authentication:
    # List of activated authentication modes (mandatory). Allowed values are:
    #   AUTH_CREDENTIALS_IN_SESSION    username/password against native D2000 users
    #   AUTH_CREDENTIALS_IN_RPC        username/password validated by a custom application RPC method
    #   AUTH_AUTO_LOGON_IN_SESSION     automatic login with a service account (listed on its own)
    #   AUTH_CERTIFICATE_LOCALLY       client certificate validated by SmartWeb
    #   AUTH_CERTIFICATE_REMOTELY      client certificate validated by D2000
    #   AUTH_SPNEGO_REMOTELY           Kerberos ticket validated by D2000
    #   AUTH_SPNEGO_LOCALLY            Kerberos ticket validated by SmartWeb against a keytab
    #   AUTH_WEBAUTHN_LOCALLY          passkey login (WebAuthn / FIDO2)
    #   AUTH_OIDC_LOCALLY              login through an external IdP, tokens validated by SmartWeb
    #   AUTH_OIDC_REMOTELY             login through an external IdP, code validated by D2000 (planned)
    # An overview of the prerequisites of each mode is in the Supported Authentication Modes chapter.
    # The example below combines application-defined users with remote certificate validation:
    authModes:
      - AUTH_CREDENTIALS_IN_RPC
      - AUTH_CERTIFICATE_REMOTELY

    # Predefined technical D2000 user under which the JAPI session is opened.
    # Mandatory for AUTH_AUTO_LOGON_IN_SESSION and AUTH_CREDENTIALS_IN_RPC.
    # MUST NOT be specified together with the AUTH_CREDENTIALS_IN_SESSION mode.
    authSessionUsername: D2000UserName
    authSessionPassword: D2000UserPassword

    # Alias of the root certificate in the truststore — mandatory for AUTH_CERTIFICATE_LOCALLY
    caCertificateAlias: SmartWebUsersCert

    # Custom RPC method that validates the user credentials.
    # Mandatory for AUTH_CREDENTIALS_IN_RPC; also used with AUTH_CERTIFICATE_REMOTELY.
    # The RPC must declare an OUT BOOL parameter named _OK.
    authRpc:
      eventName: E.SMARTWEB_USER
      interfaceName: I.XXX            # optional
      methodName: authenticate
      useJava: false                  # optional
    authRpcParams:
      - USERNAME
      - PASSWORD
      - CERTIFICATE
      - NONE
      - _OK

    # Optional RPC method called after a successful authentication
    # (typical use: setting the session context of the given user in D2000)
    logOnRpc:
      eventName: E.SW_DT_Connect
      methodName: logOn
    logOnRpcParams:
      - USERNAME
      - PASSWORD
      - _OK
    # Optional: when logOnUsername is filled in, this fixed account is sent to logOnRpc
    # instead of the user being logged in
    logOnUsername: D2000LogOnUser
    logOnPassword: D2000LogOnPassword

    # Optional RPC method called on logout (when the session ends). Called without parameters.
    logOutRpc:
      eventName: E.SW_DT_Connect
      methodName: logOff

    # Optional RPC method called when a browser tab/window is closed (the CometD connection ends)
    closeTabRpc:
      eventName: E.SW_DT_Connect
      methodName: closeTab
    closeTabRpcParams:
      - USERNAME
      - CONNECTION_ID
      - _OK

    # API key authentication for server-to-server REST / OData / OpenAPI / OpenTSDB / gRPC clients
    apiKeys:
      enabled: true
      keystore:
        path: ./apikeys.p12
        password: ""

    # SPNEGO / Kerberos (Windows Integrated Authentication) — used by the
    # AUTH_SPNEGO_LOCALLY mode (keytab for validating Kerberos tickets locally).
    spnego:
      keyTabPath: config/cert/smartweb.keytab
      servicePrincipal: HTTP/smartweb.example.com@EXAMPLE.COM
      debug: false

    # Passkey login — read only with the AUTH_WEBAUTHN_LOCALLY mode.
    # Details on the separate page Passkey (WebAuthn) Login Configuration.
    webauthn:
      relyingPartyId: smartweb.example.com
      relyingPartyName: SmartWeb

    # Login through an external IdP (OIDC/IAM) — read only with the AUTH_OIDC_LOCALLY
    # and AUTH_OIDC_REMOTELY modes; see the Login via OIDC / IAM (SSO) chapter
    oidc:
      registrationId: keycloak
      usernameClaim: preferred_username
      usernameClaimFallback: email
      postLogoutRedirectUri: https://smartweb.example.com/logout.html

    # Local administrator of the admin console (independent of D2000)
    localAdminUsername: swadmin
    localAdminPassword: changeit

    # List of client IP addresses allowed to log in to the admin console (masks supported)
    adminAllowedHosts:
      - "*"

    # Protection against password guessing: after 5 failed logins of the same username from the
    # same IP address, further attempts are rejected for 300 seconds. Blocking is active only when
    # both parameters are set and both are greater than 0; otherwise attempts are not tracked.
    maxFailedLoginsPerIpAddressAndUser: 5
    durationFailedLoginsPerIpAddressAndUser: 300

    # How many concurrent sessions one user may have (e.g. several open browsers
    # or computers). -1 = unlimited.
    maxSessionCountWithSameUsername: -1

    # How long (in milliseconds) to wait for the D2000 JAPI session to be created at login.
    # Once the limit expires the login is rejected; increase it for a slow or loaded D2000.
    japiSessionCreationTimeoutMs: 30000

    # The same for a login via a SPNEGO/Kerberos SSO token. It is deliberately shorter: with SSO
    # the user waits without any interaction, so a long wait looks like a frozen page.
    japiSessionSpnegoCreationTimeoutMs: 15000

    # Allows logging in with credentials passed as URL parameters. The username and password then
    # end up in the browser history and in the server logs — intended for TESTING ONLY,
    # leave it false in a production deployment.
    allowAuthByUrlParams: false

Basic Parameters

Parameter	Mandatory	Default value	Description

Parameter	Mandatory	Default value	Description
`authModes`	yes	`[AUTH_CREDENTIALS_IN_SESSION]`	List of activated authentication modes (see Supported Authentication Modes). An empty list stops the application from starting.
`authSessionUsername`	conditionally	—	Name of the technical D2000 user under which the JAPI session is opened and under which `authRpc` is executed. Mandatory for `AUTH_AUTO_LOGON_IN_SESSION` and `AUTH_CREDENTIALS_IN_RPC`. Must not be specified together with `AUTH_CREDENTIALS_IN_SESSION`.
`authSessionPassword`	conditionally	—	Password of the technical user. An empty value (`""`) is acceptable; the parameter must always be present whenever `authSessionUsername` is present.
`caCertificateAlias`	conditionally	—	Alias of the root (CA) certificate in the truststore that signed the client certificates. Mandatory for `AUTH_CERTIFICATE_LOCALLY`.
`localAdminUsername`	no	—	Name of the local administrator of the admin console. A login under this name is validated solely against `localAdminPassword` and does not require D2000 (fallback access when D2000 or the IdP is unavailable).
`localAdminPassword`	no	—	Password of the local administrator (compared case-insensitively).
`apiKeys.enabled`	no	`false`	Enables API key authentication for server-to-server clients.
`apiKeys.keystore.path`	no	`./apikeys.p12`	Path to the keystore file (PKCS12) holding the API keys. The file is watched — after a change the keys are reloaded without a restart.
`apiKeys.keystore.password`	no	`""`	Password of the API key keystore.
`spnego.keyTabPath`	conditionally	—	Path to the Kerberos keytab. Mandatory for `AUTH_SPNEGO_LOCALLY`. A relative path is resolved against the configuration directory.
`spnego.servicePrincipal`	conditionally	—	Service principal of SmartWeb, e.g. `HTTP/smartweb.example.com@EXAMPLE.COM`. Mandatory for `AUTH_SPNEGO_LOCALLY`.
`spnego.debug`	no	`false`	Enables verbose logging of the GSS/Kerberos layer.
`webauthn`	no	—	Passkey login configuration; read only when `AUTH_WEBAUTHN_LOCALLY` is listed in `authModes`. See Passkey (WebAuthn) Login Configuration.
`oidc`	conditionally	—	Configuration of the login through an external IdP; mandatory (at least `registrationId`) when one of the `AUTH_OIDC_*` modes is listed in `authModes`. See Login via OIDC / IAM (SSO).

RPC Methods Called During Authentication

During the login lifecycle SmartWeb can call four RPC methods of the D2000 application:

Block	When it is called	Note

Block	When it is called	Note
`authRpc` + `authRpcParams`	when validating the credentials	Mandatory for `AUTH_CREDENTIALS_IN_RPC`. `authRpcParams` must contain `_OK`; if the RPC returns `_OK` = `FALSE`, the login is rejected.
`logOnRpc` + `logOnRpcParams`	after a successful authentication and once the session is open	Typically used to set the application context of the user. When `logOnUsername` is filled in, that account is sent to the RPC instead of the user being logged in.
`logOutRpc`	when the session ends (logout, timeout)	Called without parameters — the RPC must not have formal parameters, which is why there is no `logOutRpcParams`. The application identifies the user being logged out by the HOBJ of the session the call came from.
`closeTabRpc` + `closeTabRpcParams`	when a browser tab/window is closed (the CometD connection ends)	Called fire-and-forget — the `_OK` return value is not evaluated. The `CONNECTION_ID` parameter carries the identifier of the CometD connection.

[!NOTE] The logOutRpc method is called from the session of the user being logged out, so even though it receives no parameters, the application can determine the user from the HOBJ of that session — in ESL it is returned by %GetRPCCallerProcess(). The session HOBJ → username pair is usually stored at login in logOnRpc and looked up and removed by HOBJ in logOutRpc. A complete worked example is in the guide User Identification in an RPC Method.

Every RPC block is defined by the same structure:

Attribute	Mandatory	Description

Attribute	Mandatory	Description
`eventName`	yes	Name of the D2000 event, e.g. `E.SW_APPLICATION_AUTH`
`methodName`	yes	Name of the RPC procedure in the event
`interfaceName`	no	Name of the event interface when the RPC is called through an interface
`processName`	no	Process name when a specific instance has to be addressed
`useJava`	no	`true` for a Java event process (`false` by default = ESL)

The …RpcParams arrays define the order and meaning of the formal parameters of the RPC procedure. Allowed values:

Value	Value sent

Value	Value sent
`USERNAME`	Login name of the user (TEXT)
`PASSWORD`	Password of the user (TEXT); `NaN` when no password is available (e.g. with a passkey or OIDC login)
`CERTIFICATE`	Base64-encoded client certificate (TEXT); an empty string when no certificate was presented
`AUTH_TYPE`	Authentication type (`UI`, `API`, …) (TEXT)
`USED_AUTH_MODE`	The mode the user was actually authenticated with (TEXT), e.g. `AUTH_OIDC_LOCALLY`; `NaN` when it cannot be determined
`OIDC_CLAIMS`	All claims of the OIDC user serialized as a single JSON string (TEXT); filled in only with `AUTH_OIDC_LOCALLY`, `NaN` otherwise
`CONNECTION_ID`	Connection identifier (TEXT) — used in `closeTabRpc`; `NaN` otherwise
`NODE`	Node context of the client (TEXT); `NaN` when not defined
`NONE`	`NaN` — filler for a parameter SmartWeb does not use
`_OK`	OUT parameter of type BOOL into which the RPC writes the validation result

Limits, Timeouts and the Admin Console

Parameter	Default value	Description

Parameter	Default value	Description
`maxFailedLoginsPerIpAddressAndUser`	— (disabled)	Number of failed logins from one IP address for one username after which further logins are blocked. Blocking is active only when both parameters are set and both are greater than 0.
`durationFailedLoginsPerIpAddressAndUser`	— (disabled)	Blocking period in seconds once the failed-login limit is reached.
`maxSessionCountWithSameUsername`	`-1`	Maximum number of concurrent sessions of one username (several open browsers or computers). Once the limit is reached, further logins are rejected; `-1` means unlimited.
`japiSessionCreationTimeoutMs`	`30000`	Timeout (in milliseconds) for creating the D2000 JAPI session at login. Once it expires the login is rejected — increase the value for a slow or loaded D2000, or over a slow network link.
`japiSessionSpnegoCreationTimeoutMs`	`15000`	The same for a login via a SPNEGO/Kerberos SSO token. The default is deliberately shorter: with SSO the user types nothing, so a long wait looks like a frozen page.
`adminAllowedHosts`	`["*"]`	List of client IP addresses allowed to log in to the admin console. Masks with `` and `?` are supported (e.g. `10.0.0.`).
`allowAuthByUrlParams`	`false`	Allows logging in with credentials passed as URL parameters. The username and password then end up in the browser history and in the server logs — intended for testing only, leave it disabled in production.

Configuration Examples

Simple Authentication Against D2000 Users

smartweb:
  authentication:
    authModes:
      - AUTH_CREDENTIALS_IN_SESSION

The username and password entered in the login dialog are validated by opening a D2000 JAPI session for that user.

Simple Authentication Against Application-Defined Users

Users are defined inside D2000 (typically in a structure managed by ESL scripts). The username and password are validated by a custom RPC method. logOnRpc is configured here as well, so that the D2000 application can set up the context of the given user after a successful login.

smartweb:
  authentication:
    authModes:
      - AUTH_CREDENTIALS_IN_RPC

    # Predefined technical D2000 user that opens the JAPI session
    # under which the authRpc method is executed
    authSessionUsername: D2000UserName
    authSessionPassword: D2000UserPassword

    authRpc:
      eventName: E.SW_APPLICATION_AUTH
      methodName: authenticate
    authRpcParams:
      - USERNAME
      - PASSWORD
      - _OK

    logOnRpc:
      eventName: E.SW_APPLICATION_AUTH
      methodName: logOn
    logOnRpcParams:
      - USERNAME
      - _OK

Authentication Against a D2000 User with Local Client Certificate Validation

Client certificates are validated locally on the SmartWeb side. Every client certificate must be stored in the servlet container truststore under an alias identical to the D2000 login name (case-sensitive). All client certificates must be signed by the root certificate stored under the alias defined in caCertificateAlias. The HTTPS connector of the embedded Tomcat (under server.ssl.*) must be configured to require a client certificate (client-auth: REQUIRE or OPTIONAL).

server:
  ssl:
    enabled: true
    key-store: config/cert/keystore.p12
    key-store-password: changeit
    trust-store: config/cert/truststore.p12
    trust-store-password: changeit
    client-auth: REQUIRE

smartweb:
  authentication:
    authModes:
      - AUTH_CREDENTIALS_IN_SESSION
      - AUTH_CERTIFICATE_LOCALLY

    caCertificateAlias: SmartWebUsersCert

Authentication Against a D2000 User with Remote Client Certificate Validation

The client certificate (Base64-encoded) is forwarded to D2000 by calling a custom RPC method. The truststore configured on the Tomcat HTTPS connector must contain the root certificate used to sign the client certificates.

smartweb:
  authentication:
    authModes:
      - AUTH_CREDENTIALS_IN_SESSION
      - AUTH_CERTIFICATE_REMOTELY

    authRpc:
      eventName: E.SW_APPLICATION_AUTH
      methodName: authenticate
    authRpcParams:
      - USERNAME
      - CERTIFICATE
      - _OK

Authentication Against Application-Defined Users with Client Certificate Validation

Local certificate validation (AUTH_CERTIFICATE_LOCALLY):

smartweb:
  authentication:
    authModes:
      - AUTH_CREDENTIALS_IN_RPC
      - AUTH_CERTIFICATE_LOCALLY

    authSessionUsername: D2000UserName
    authSessionPassword: D2000UserPassword

    caCertificateAlias: SmartWebUsersCert

    authRpc:
      eventName: E.SW_APPLICATION_AUTH
      methodName: authenticate
    authRpcParams:
      - USERNAME
      - PASSWORD
      - _OK

    logOnRpc:
      eventName: E.SW_APPLICATION_AUTH
      methodName: logOn
    logOnRpcParams:
      - USERNAME
      - _OK

Remote certificate validation (AUTH_CERTIFICATE_REMOTELY) — the certificate is sent to authRpc:

smartweb:
  authentication:
    authModes:
      - AUTH_CREDENTIALS_IN_RPC
      - AUTH_CERTIFICATE_REMOTELY

    authSessionUsername: D2000UserName
    authSessionPassword: D2000UserPassword

    authRpc:
      eventName: E.SW_APPLICATION_AUTH
      methodName: authenticate
    authRpcParams:
      - USERNAME
      - PASSWORD
      - CERTIFICATE
      - _OK

    logOnRpc:
      eventName: E.SW_APPLICATION_AUTH
      methodName: logOn
    logOnRpcParams:
      - USERNAME
      - _OK

Configuration of Authentication