Skip to content

Restrict Access to the Jobclient API via OIDC

Overview

As of DPF 4.3.0, access to the Jobclient API (seal-dpf-jobclient-api) can be restricted via OIDC. By default, OIDC authentication stays disabled: Digital Process Factory runs without authentication unless AUTH_TYPE is explicitly set to oidc.

DPF provides more than one REST API, for example seal-dpf-management-api. The keys on this page apply only to seal-dpf-jobclient-api. They do not affect other REST APIs, and they are unrelated to DPF Tracker's own, separate OIDC configuration for user login.

This page describes the OIDC configuration on both sides: seal-dpf-jobclient-api and DPF Batch Client. Once OIDC authentication is enabled, DPF Batch Client only works with its own OIDC settings, see Configure DPF Batch Client.

Caution - not supported by every client

Enabling OIDC authentication requires every client calling seal-dpf-jobclient-api to send a valid token. Not all clients support this yet. For example, PLOSSYS Output Engine's DPF conversion uses the seal-convert-dpf service, which sends no token, so it can no longer create jobs once OIDC authentication is enabled.

Caution - not backward compatible with DPF 3

DPF 3 had its own OIDC authentication for the Jobclient API, implemented differently. An existing DPF 3 OIDC configuration does not carry over to DPF 4.

Enable OIDC Authentication

  1. Set AUTH_TYPE to oidc for seal-dpf-jobclient-api. Every request now requires a JSON Web Token (JWT). Default: none, no authentication required.

  2. Specify the OIDC connection for the seal-dpf-jobclient-api service with the following keys:

    • ID_PROVIDER_NAME: Name of the OIDC identity provider. Mandatory. The service compares it against the issuer claim of the JWT and rejects tokens issued by any other identity provider.
    • ID_PROVIDER_CERT: Path and file name of the certificate generated by the OIDC identity provider, in PEM format. Set this or AUTH_ISSUER_URL to verify the JWT signature. Takes precedence if both are set.
    • AUTH_ISSUER_URL: URL of the identity provider. Used to discover the signing key automatically via OpenID Connect Discovery. Optional, not needed if ID_PROVIDER_CERT is set.
    • AUTH_PROXY: Proxy URL, optional, only needed if the identity provider is only reachable through a proxy.

    Hint - changed ID_PROVIDER_NAME as of Keycloak 21.0.1

    As of SEAL-specific Keycloak version 21.0.1, the URL needed for ID_PROVIDER_NAME has changed:

    • old value: ID_PROVIDER_NAME=https://<id_provider_server>:32769/auth/realms/SEAL
    • new value: ID_PROVIDER_NAME=https://<id_provider_server>:32769/realms/SEAL

    To accept tokens from an old and a new identity provider at the same time, separate both names by a blank.

    Example - enabling OIDC authentication via DPF CLI

    dpf config set AUTH_TYPE oidc --service dpf-jobclient-api --insecure
dpf config set ID_PROVIDER_NAME https://<id_provider_server>:32769/realms/SEAL --service dpf-jobclient-api --insecure
dpf config set AUTH_ISSUER_URL https://<id_provider_server>:32769/realms/SEAL --service dpf-jobclient-api --insecure

  3. Restart seal-dpf-jobclient-api.

Restrict Access by Client and Role

Additionally, you can restrict the access by client and role. To do so, follow these steps:

  1. Set ALLOWED_OIDC_CLIENTS to the allowed OIDC clients and roles. This is enough as long as the identity provider issues roles in one of the standard Keycloak claims, resource_access.<client>.roles or realm_access.roles.

    Example - configuration giving access to client seal-dpf-batch-client for role default-roles-seal

    {
  "seal-dpf-batch-client": {
    "roles": {
      "default-roles-seal": {}
    }
  }
}

  2. Optional: If the identity provider puts roles in a different JWT property, set JWT_ROLES to that property name in addition.

  3. Restart seal-dpf-jobclient-api.

Configure DPF Batch Client

As of DPF 4.3.0, DPF Batch Client supports authentication via OIDC. If an access token expires, DPF Batch Client requests a new one automatically and retries the call.

As of SEAL-specific Keycloak version 26.7.4, a new installation provides the preconfigured client seal-dpf-batch-client for DPF Batch Client. Updating an existing Keycloak does not add the client. In this client, set Service accounts roles to On.

You have to configure the authentication via OIDC on server and client side. If authentication via OIDC is specified on the client side, but not configured for the server, the server ignores the authentication without a warning.

You have three ways to specify the authentication for DPF Batch Client. If specified in more than one way, a command line parameter takes precedence over an environment variable, which in turn takes precedence over the configuration file.

Hint - AUTH_ISSUER_URL and AUTH_TOKEN_ENDPOINT

AUTH_ISSUER_URL is sufficient, as long as your IDP supports OpenID Connect Discovery.

You have to specify both URLs if:

  • Your IDP does not support automatic discovery or the feature is disabled.

  • Your IDP is behind a proxy or otherwise blocks access to the .well-known path.

You can test it by calling <auth_issuer_url>/.well-known/openid-configuration in a browser. If automatic discovery is supported, the server returns a JSON file containing the OpenID configuration.

...with Command Line Parameters

For the authentication with client id and secret you have to specify:

  • --auth-client-id <client-id>: Client id, mandatory

  • --auth-client-secret <client_secret>: Client secret, mandatory

  • --auth-issuer-url <url>: URL of the token issuer, mandatory

  • --auth-token-endpoint <url>: URL of the token endpoint, optional

  • --auth-additional-scopes <scopes>: Additional scopes to use, optional

For the authentication with a bearer token specify:

  • --bearer <token>: JSON Web Token (JWT) for authentication, optional

Example - authentication with client id and client secret

dpfclient -wf example -host localhost:4303 -protocol http -loglevel T -v --auth-client-id seal-dpf-batch-client --auth-client-secret a1B2c3D4e5F6g7H8i9J0k1L2m3N4o5P6 --auth-issuer-url https://localhost:32769/realms/SEAL/ --insecure

...with Environment Variables

Instead of command line parameters, you can set the corresponding value as an environment variable before calling DPF Batch Client:

  • AUTH_CLIENT_ID: Client id

  • AUTH_CLIENT_SECRET: Client secret

  • AUTH_ISSUER_URL: URL of the token issuer

  • AUTH_TOKEN_ENDPOINT: URL of the token endpoint

  • AUTH_ADDITIONAL_SCOPES: Additional scopes to use

...in the Configuration File

If you use client id and client secret for authentication, you can specify the credentials in the configuration file dpfclient.xml for DPF Batch Client. This way, you do not have to add them via command line parameters for each call.

  1. Open the configuration file dpfclient.xml in an editor. It is located at:

    • Windows: C:\SEAL\applications\tools\bin_winnt5\dpfclient.xml
    • Linux: /opt/seal/tools/bin_linux223/dpfclient.xml

  2. Add the following section at the same level as the ENVIRONMENTS key and adapt the credentials as needed.

    <OIDC_AUTH
    AUTH_ISSUER_URL="https://localhost:32769/realms/SEAL/"
    AUTH_CLIENT_ID="<client-id>"
    AUTH_CLIENT_SECRET="<secret>"
    AUTH_TOKEN_ENDPOINT="<token_endpoint>"
    AUTH_ADDITIONAL_SCOPES="<additional_scopes>"
/>

    Example - dpfclient.xml with client id and client secret

    <?xml version="1.0" encoding="ISO-8859-1"?>
<DPF>
    <config>
        <dpfclient>
            <COMMANDLINE FLAGS="">
                <PROPERTIES>
                </PROPERTIES>
            </COMMANDLINE>
            <ENVIRONMENTS
                DB_HOST="dpfsrv-120"
                DB_PORT="7128"
            />
            <REST_LOCAL
                REST_HOST="dpf-jobclient-api"
                REST_PORT="4303"
                REST_PROTOCOL="http"
            />
            <OIDC_AUTH
                AUTH_ISSUER_URL="https://localhost:32769/realms/SEAL/"
                AUTH_CLIENT_ID="seal-dpf-batch-client"
                AUTH_CLIENT_SECRET="a1B2c3D4e5F6g7H8i9J0k1L2m3N4o5P6"
            />
        </dpfclient>
    </config>
</DPF>

Troubleshooting

If DPF Batch Client exits with return code 6, check the authentication too. DPF Batch Client reports a rejected token the same way as a missing connection:

Error while connecting to DPF server.
Error: dpfclient exits with code 6.

Hint - possible causes with OIDC enabled

  • DPF Batch Client sends no token.
  • The token is invalid.

If access is unexpectedly denied, set JWT_LOG_TOKEN to Y for seal-dpf-jobclient-api:

dpf config set JWT_LOG_TOKEN Y --service dpf-jobclient-api --insecure

Then restart seal-dpf-jobclient-api. The service then logs the JWT payload at info log level, so you can check its claims, for example the client, roles, or issuer, against ALLOWED_OIDC_CLIENTS, JWT_ROLES, and ID_PROVIDER_NAME.

The JWT payload can contain personal data, for example user names or e-mail addresses. After the analysis, set JWT_LOG_TOKEN back to N and restart seal-dpf-jobclient-api.

Back to top