Skip to main content

Pentaho+ documentation has moved!

The new product documentation portal is here. Check it out now at docs.hitachivantara.com

 

Hitachi Vantara Lumada and Pentaho Documentation

OIDC with OAuth support

Parent article

Lumada Data Catalog supports OpenID Connect 1.0 (OIDC) and OAuth 2.0 protocols. Comprehensive support for OIDC also includes support for the JOSE family of specifications, including JWT, JWS, and JWE.

The two major Data Catalog workflows, the WebUI and the REST API, support different parts of OIDC functions.

  • 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 a complex dialog with the OIDC SSO server during the 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 the request authorization.

Enable OIDC Log in

Perform the following steps to enable the OIDC login.

Procedure

  1. Navigate to the $LDC_HOME/app-server/conf directory and open the configuration.json file.

  2. Locate the ldc.web.enabled.auth.methods property and set the "value" attribute to include "OIDC" as follows:

    "ldc.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
      }
  3. Save and close the file.

  4. Restart the application server.

    Your login page now displays the OIDC Log in option.OIDC Log in screen

OIDC configuration

Because of 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.

  • WebUI OIDC configuration file

    <LDC-HOME>/app-server/conf/oidc-client-web.properties.

  • REST API OIDC configuration file

    <LDC-HOME>/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= falseThe OIDC/OAuth global kill switch. The default value is false if this property is not specified explicitly. This property enables OIDC functions according to the other properties in the file. This property applies independently to each security context, Web or REST.

OIDC provider OP configuration

These properties specify configuration of the OIDC provider, which is 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 parameter is the only OP configuration that must be specified in the property file,. The rest of the parameters are 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/ldc/app-server/conf/jwks.jsonAn 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 that are used for token decryption and digital signature verification.
op.iss_uri = http://127.0.0.1:8080/c2idThe unique URI of the OIDC OP token issuer. This property is mandatory if the local OP configuration override is enabled.
op.authz_uri = http://127.0.0.1:8080/c2id-loginThe authorization endpoint URI of the OIDC OP token issuer. This property is mandatory if the local OP configuration override is enabled. This property points to the OP endpoint which accepts the OAuth style authorization code grant and redirects using the client browser.

Even though the code grant and browser redirects are not used for REST API, this option still must be provided for proper initialization. Its value is not used.

op.token_uri = http://127.0.0.1:8080/c2id/tokenThe token retrieval endpoint URI of the OIDC OP token issuer. This property is mandatory if the 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/userinfoThe UserInfo OP retrieval endpoint URI. This property is optional based on local requirements. If local OP setup does not require the UserInfo lookup, you can disable this part of the OIDC/OAuth style flow by leaving this property value empty or disabling it.
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 specifications. If JWKS refresh is not required, you can disable it by disabling this property and the op.jwks_refresh_interval = PT4H property. The default value is empty and the JWKS refresh mechanism is disabled if not 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 specifications. If the JWKS refresh is not required, you can disable it by disabling this property and the op.jwks_refresh_start = PT0H property. The default value is empty and the JWKS refresh mechanism is disabled if not specified.
op.connect_timeout = 250The 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 = 250The 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 after a successful client authentication and authorization is completed.

This property is not needed for the REST API configuration. However, it is mandatory for the WebUI security context. 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 to make a token request. The client_secret_basic is the most-commonly used authentication method on that OP endpoint. See your OP documentation for details.

This property is defined during registration and applies to WebUI only.

rp.token_endpoint_auth_signing_alg =The authorization signature. This is an additional OP token endpoint security feature. This property is optional and only used if explicitly required by OP policies. See your OP documentation and SSO team for details.

This property is defined during registration and applies to WebUI only.

rp.code_challenge_method = The authorization code challenge method. This property is an additional OP token endpoint security feature. It is optional and only used if explicitly required by OP policies. See your OP documentation and SSO team for details.

This property is defined during registration and applies to WebUI only.

rp.token_jws_alg = RS256This property defines the signed JWT digital signature algorithm. Both symmetric (AES) and asymmetric (RSA, ECDSA) digital signatures are supported. See your OP documentation and security team for details about recommended cryptography.

This property applies to both WebUI and REST API contexts.There is no default. The algorithm is defined during client registration.

rp.token_jws_len = 256This property defines signed JWT digital signature key length for symmetric digital signatures. See your OP documentation and security team for details on recommended cryptography.

This property applies to both WebUI and REST API contexts.There is no default. The 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. See your OP documentation and security team for details on recommended cryptography.

This property applies to both WebUI and REST API contexts. There is no default. The algorithm is defined during client registration.

rp.token_jwe_method = A256GCMThis property defines the encrypted JWT content encryption method. See your OP documentation and security team for details on recommended cryptography. This property applies to both WebUI and REST API contexts. There is no default. The 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 an access token refresh is not required, then disable this property. The default value is empty and the access token refresh mechanism is disabled if not specified.

Optional claim verification

The following properties define if the optional JWT claims must be strictly enforced or not. By default, optional claims are not enforced unless specified. You can 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 = WDSWhen this property is specified, the optional JWT aud (audience) claim is mandatory and is strictly validated against the value of this property.
rp.strict_claim_iat = falseWhen this property is specified, the optional JWT iat (issued at) claim to is mandatory and is strictly validated for timeline consistency with the exp (expiration) claim.
rp.strict_claim_nbf = falseWhen this property is specified, the optional JWT nbf (not before) claim is mandatory and is strictly validated for timeline consistency with exp (expiration) claim.
rp.strict_claim_iss = falseWhen this property is specified, the optional JWT iss (issuer) claim is mandatory and is strictly validated against the issuer OP metadata field.

Secret RP properties

Relying party (RP) properties contain confidential information. You may further protect these properties by moving them into a separate property location protected by ACL, which is not accessible to regular users.

PropertyDescription
rp.secret_properties_uri = file:///opt/ldc/app-server/conf/secret-oidc-client.propertiesOptional property that specifies the URI of a protected S3 bucket, local file, etc., that contains mandatory secret properties. It is accessible only to privileged users who have unspecified external access control mechanisms.
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. There is no default. This value can be obfuscated by using the provided utility.

Debugging

The following property is for RP debugging:

PropertyDescription
rp.debug_mode = trueWhen this optional property is set to true, allows special instrumented versions of key management modules to provide extensive diagnostics in the log. Default value is false.

JWT and JWKS generator utility configuration

The following properties are required by the test JWT generator utility. If you are using public key encryption for JWT digital signatures or if you are using token encryption as defined by the previous corresponding properties, then the location of the RSA key pair is required.

PropertyDescription
gen.public_key_uri = file:///opt/ldc/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/ldc/app-server/conf/wds-example-private-keyPrivate key of the RSA key pair used to sign or encrypt JWT in the OpenSSL key format.