Skip to main content
Hitachi Vantara Lumada and Pentaho Documentation

OIDC with OAuth support

Parent article

Lumada Data Catalog supports the OpenID Connect 1.0 (OIDC) and OAuth 2.0 functionality. Comprehensive support for OIDC as an overarching specification also includes support for the JOSE family of specs, namely JWT, JWS, and JWE.

The two major Data Catalog functional scenarios, the WebUI and the REST API, support different parts of the OIDC functionality.

  • WebUI

    Implements the OIDC authorization code grant, an extended version of an OAuth 2.0 authorization code grant with tokens represented as JWTs. Full support for signed or encrypted JWTs using symmetric (AES) or public key encryption (RSA, EC) is available. Data Catalog's WebUI also supports periodic refresh of the active session access tokens using standard refresh token grants or custom validation grants, and periodic server metadata refresh as well. The WebUI support of the authorization code grant requires complex dialog with OIDC SSO server during initial user login but provides the most secure environment when implemented over HTTPS.

  • REST API

    Supports request authentication and authorization using the signed or encrypted JWTs supplied by API clients in the authorization request headers. The REST API OIDC support module focuses on performance and does not require SSO server communication during request authorization.

Enable OIDC Log in

Perform the following steps to enable the OIDC login.

Procedure

  1. Enable the OIDC Log in button on the login page by updating the waterlinedata.web.enabled.auth.methods property in configuration.json under $WLD_HOME/app-server/conf as follows:

    "waterlinedata.web.enabled.auth.methods" : {
        "value" : [ "PASSWORD", "OIDC" ],
        "type" : "STRING",
        "restartRequired" : true,
        "readOnly" : false,
        "description" : "User authentication methods that have been enabled",
        "label" : "User authentication methods that have been enabled",
        "category" : "SECURITY",
        "defaultValue" : [ "PASSWORD" ],
        "visible" : true
      }
  2. Restart the application server.

    Your login screen has the OIDC Log in option as follows:OIDC Log in screen

OIDC configuration

Given the different and sometimes conflicting requirements of configuring OIDC support in WebUI and REST API scenarios, Data Catalog provides two distinct security contexts which can coexist and are configured independently from each other. Each security context configuration is contained in its own configuration file and initial configurations for WebUI and REST API security contexts are identical.

  • The WebUI OIDC configuration file is the waterlinedata/app-server/conf/oidc-client-web.properties.
  • The REST API OIDC configuration file is the waterlinedata/app-server/conf/oidc-client-rest.properties.

Configuration options

The tables below provide a detailed description of all available configuration options.

Global context-specific properties

The following are global context-specific properties:

PropertyDescription
oidc.enable= falseThis is the OIDC/OAuth global kill switch, the default value is false if this property is not specified explicitly. This property enables the OIDC functionality according to the other properties in the file. Again, this property applies independently to each security context, Web or REST.

OIDC provider OP configuration

These properties specify configuration of the OIDC provider, the enterprise SSO system used by Data Catalog if OIDC functionality is enabled. These properties have the op prefix.

PropertyDescription
op.metadata_uri = http://127.0.0.1:8080/c2id/.well-known/openid-configurationThis property points to the OIDC OP metadata endpoint. Typically all OIDC OP's advertise their configuration on a well-known metadata endpoint which allows for OP discovery and automatic client configuration.

Usually this is the only OP configuration that must be specified in the property file, the rest is obtained by the client automatically using this metadata endpoint.

However, for complex configuration scenarios this property can be disabled, in which case several locally specific overrides take effect.

Local OP override configuration

The following configuration options are used if and only if the op.metadata_uri property is disabled or empty.

PropertyDescription
op.jwks_uri = file:///opt/waterlinedata/app-server/conf/jwks.jsonThis is an HTTP URI or a file URI that contains the OP JWKS or a JSON Web Key Set, the SSO OP set of RSA public keys and additional key specifications in JSON format used for token decryption and digital signature verification.
op.iss_uri = http://127.0.0.1:8080/c2idThis is the unique URI of the OIDC OP token issuer, this property is mandatory if local OP configuration override is enabled.
op.authz_uri = http://127.0.0.1:8080/c2id-loginThis is the authorization endpoint URI of the OIDC OP token issuer, this property is mandatory if local OP configuration override is enabled. This property points to the OP endpoint which accepts OAuth style authorization code grant redirect using the client browser. Even though code grant and browser redirect are not used for REST API, this option still must be provided for proper initialization, it's value is not used though.
op.token_uri = http://127.0.0.1:8080/c2id/tokenThis is the token retrieval endpoint URI of the OIDC OP token issuer, this property is mandatory if local OP configuration override is enabled. This property points to the OP endpoint that allows ID and access token retrieval during OAuth's type authorization code grant flow. Even though this property value is not used in the REST API scenario, a valid URI must be provided.
op.userinfo_uri = http://127.0.0.1:8080/c2id/userinfoThis is the UserInfo OP retrieval endpoint URI, this property is optional based on local requirements. If local OP setup does not require the UserInfo lookup, this part of the OIDC/OAuth style flow is disabled by leaving this property value empty or disabling altogether.
op.jwks_refresh_start = PT0HSometimes OIDC OP requires the JWKS refresh on a periodic basis. This property specifies the daily start time of this refresh mechanism according to Java java.time. Duration spec. If JWKS refresh is not required, it is disabled by disabling this and the next property below. The default value is empty and the JWKS refresh mechanism is disabled if not explicitly specified.
op.jwks_refresh_interval = PT4HSometimes OIDC OP requires the JWKS refresh on a periodic basis. This property specifies the interval of this refresh mechanism according to Java 8 java.time.Duration spec. If JWKS refresh is not required, it is disabled by disabling this and the previous property above. The default value is empty and the JWKS refresh mechanism is disabled if not explicitly specified.
op.connect_timeout = 250This is the OP connection timeout in milliseconds, the default value is 250 ms. Increase this value if you are getting connection timeout errors. This property is optional.
op.read_timeout = 250This is the OP read timeout in milliseconds, the default value is 250 ms. Increase this value if you are getting read timeout errors. This property is optional.

Relaying party configuration

These properties specify the configuration of the Data Catalog OIDC client module, or Relaying Party (RP) in OIDC parlance. These properties have the rp prefix.

PropertyDescription
rp.redirect_uri = https://127.0.0.1:4039/oidc-client/cbThis property is the URI endpoint implemented by the WebUI OIDC client (RP). This property value is registered with the OP as part of the OIDC client on-boarding process. This Data Catalog endpoint accepts the authorization code grant redirect from the OP once successful client authentication and authorization is completed. This property is not needed for the REST API configuration, but for the WebUI security context this property is mandatory and there is no default.
rp.token_endpoint_auth_method = client_secret_basicThis property defines the authentication method that must be used by the confidential client for explicit authentication to the OIDC provider server with its registered credentials in order to make a token request. The client_secret_basic is the most-commonly used authentication method on that OP endpoint, consult your OP documentation for details. This is configured on a per-client basis during registration and applies to WebUI only.
rp.token_endpoint_auth_signing_alg =Additional OP token endpoint security feature, the authorization signature. This property is optional and only used if explicitly required by OP policies. Consult your OP documentation and SSO team for details. This is configured on a per-client basis during registration and applies to WebUI only.
rp.code_challenge_method = Additional OP token endpoint security feature, the authorization code challenge method. This property is optional and only used if explicitly required by OP policies. Consult your OP documentation and SSO team for details. This is configured on a per-client basis during registration and applies to WebUI only.
rp.token_jws_alg = RS256This property defines signed JWT digital signature algorithm, both symmetric (AES) and asymmetric (RSA, ECDSA) digital signatures are supported. Consult your OP documentation and security team for details on recommended cryptography. This property applies to both WebUI and REST API contexts and there is no default - the agreed upon algorithm is defined during client registration.
rp.token_jws_len = 256This property defines signed JWT digital signature key length for symmetric digital signatures. Consult your OP documentation and security team for details on recommended cryptography. This property applies to both WebUI and REST API contexts and there is no default - the agreed upon key length is defined during client registration.
rp.token_jwe_alg = RSA-OAEP-256This property defines the encrypted JWT JWE key management algorithm, both symmetric (AES) and asymmetric (RSA, ECDH) encryption schemes are supported. Consult your OP documentation and security team for details on recommended cryptography. This property applies to both WebUI and REST API contexts and there is no default - the agreed upon algorithm is defined during client registration.
rp.token_jwe_method = A256GCMThis property defines the encrypted JWT content encryption method. Consult your OP documentation and security team for details on recommended cryptography. This property applies to both WebUI and REST API contexts and there is no default - the agreed upon method is defined during client registration.
rp.access_token_refresh_interval = PT3MUsually OIDC OP requires the issued access token to be refreshed on a periodic basis. This property specifies the interval of this refresh mechanism according to Java 8 java.time.Duration spec. If access token refresh is not required, it is disabled by disabling this property. The default value is empty and the access token refresh mechanism is disabled if not explicitly specified.

Optional claim verification

The following several properties define if the optional JWT claims must be strictly enforced. By default, optional claims are not strictly enforced unless explicitly specified. Disable optional claim enforcement by removing these properties or setting empty values. These settings apply to both WebUI and REST API contexts.

PropertyDescription
rp.client_audience = WDSIf explicitly specified, this property causes the optional JWT aud (audience) claim to become mandatory and be strictly validated against the expected value of this property.
rp.strict_claim_iat = falseIf explicitly specified, this property causes the optional JWT iat (issued at) claim to become mandatory and be strictly validated for timeline consistency with exp (expiration) claim.
rp.strict_claim_nbf = false If explicitly specified, this property causes the optional JWT nbf (not before) claim to become mandatory and be strictly validated for timeline consistency with exp (expiration) claim.
rp.strict_claim_iss = false If explicitly specified, this property causes the optional JWT iss (issuer) claim to become mandatory and be strictly validated against the issuer OP metadata field.

Secret RP properties

These properties contain confidential information and may be protected by placing them into the separate property location protected by ACL and not accessible to regular users.

PropertyDescription
rp.secret_properties_uri = file:///opt/waterlinedata/app-server/conf/secret-oidc-client.propertiesOptional property that specifies URI of a protected s3 bucket, local file, etc. that contains the following mandatory secret properties and is accessible only to privileged users using unspecified external access control mechanism.
rp.client_id = 000123Unique client ID assigned to this RP during registration process, it is used for RP authentication to OP. This property is mandatory for both WebUI and REST API contexts and there is of course no default.
rp.client_secret = 7wKJNYFaKKg4FxUdi8_R75GGYsiWezvAbcdN1uSumE4Unique client secret phrase generated during RP registration, it is used for RP authentication to OP. This property is mandatory for both WebUI and REST API contexts and there is of course no default. Furthermore, this value can be obfuscated by using the provided utility.

Debugging

The following property is for RP debugging:

PropertyDescription
rp.debug_mode = trueOptional property enabling a special instrumented versions of certain key management modules that provide extensive diagnostics in the log. Default value is false.

JWT and JWKS generator utility configuration

Properties required by the test JWT generator utility. Location of the RSA key pair is required if public key encryption is used for JWT digital signatures or entire token encryption as defined by corresponding properties above.

PropertyDescription
gen.public_key_uri = file:///opt/waterlinedata/app-server/conf/wds-example-public-key.pemPublic key of the RSA key pair in the X.509 PEM format.
gen.private_key_uri = file:///opt/waterlinedata/app-server/conf/wds-example-private-keyPrivate key of the RSA key pair used to sign or encrypt JWT in the openssl key format.