Configure OSP for Dimensions CM

You can configure One SSO Provider (OSP) to enable single sign-on authentication for OpenText Dimensions CM. This topic explains how to set up OSP with file-based or LDAP authentication and configure OpenText Dimensions CM to integrate with OSP.

OSP is an OAuth 2.0/OpenID Connect 1.0 Authorization Server that provides centralized authentication for various OpenText products.

Prerequisites

Before you begin, ensure that you have the following requirements in place:

  • OpenText Dimensions CM installed and configured.

  • Apache Tomcat 10.1 or later.

  • Java 17 or later.

  • Administrative access to the OpenText Dimensions CM server and Tomcat.

  • OSP WAR files and configuration files.

Back to top

Step 1: Install and configure OSP

Install OSP on your Tomcat server and configure the basic settings.

To install OSP WAR files:

  1. Download the OSP WAR files from the OpenText repository.

  2. Copy the WAR files to the Tomcat webapps directory:

    <TOMCAT_HOME>/webapps

  3. Download the OSP configuration files (netiq_osp_file-minimal).

  4. Copy the configuration files to the Tomcat conf directory:

    <TOMCAT_HOME>/conf/

  5. Edit the OSP configuration file:

    <TOMCAT_HOME>/conf/netiq_osp_file-minimal/osp-configuration.properties

  6. Change the hostname to your Tomcat server hostname.

Back to top

Step 2: Configure file-based user authentication

Configure OSP to authenticate users using file-based (CSV) authentication. User accounts are stored in a CSV file under the OSP folder.

Note: This is one of two authentication options. If you plan to use LDAP instead, go to Configure OSP for Dimensions CM.

To configure file-based authentication:

  1. Edit the authcfg.xml file:

    <TOMCAT_HOME>/conf/netiq_osp_file-minimal/WEB-INF/conf/current/dimensions/services/authcfg.xml

  2. Add the following file data source configuration:

    Copy code 
    <FileDataSource displayName="CSV File Data Source" id="ds-file" path="../../../../../osp-users.csv">
        <Field index="0" use="naming" unique="true">
            <IdentityData classifier="system.preferred-name"/>
        </Field>
        <Field index="1" use="password" hashAlgorithm="${com.opentext.dimensions.osp.csv-pwd-hash-alg:SHA-512}"/>
    </FileDataSource>

    <FileAuthenticationSource displayName="CSV File User Authentication" id="as-file">
        <Reference refId="ds-file" type="DataSource"/>
        <AttributeMapping>
            <AttributeMapEntry localName="username" nativeName="0"/>
        </AttributeMapping>
    </FileAuthenticationSource>

  3. Edit the osp-users.csv file to add user accounts. The default dmsys user is already present.

  4. To add new users, hash their passwords using the following command:

    echo -n '<PASSWORD>' | shasum -a 512 | xxd -r -p | base64 -w 0

Note: Users must also be present in OpenText Dimensions CM.

Step 3: Configure LDAP user authentication

Configure OSP to authenticate users using LDAP authentication.

Note: This is one of two authentication options. If you plan to use file-based authentication instead, go to Configure OSP for Dimensions CM.

To configure LDAP authentication:

  1. In the authcfg.xml file, replace the CSV blocks with the following LDAP configuration:

    Copy code 
    <LDAPDataSource
        displayName="LDAP Data Source"
        id="ds-ldap"
        adminName="${com.opentext.dimensions.osp.ldap.admin-dn}"
        adminPassword="${com.opentext.dimensions.osp.ldap.admin-pwd}"
        dirType="${com.opentext.dimensions.osp.ldap.dir-type:eDir}"
        instanceStoreAttributeName="${com.opentext.dimensions.osp.ldap.trustsource-attr-name:oidpInstanceData}">
        <Server
            secureConnection="${com.opentext.dimensions.osp.ldap.use-tls:true}"
            host="${com.opentext.dimensions.osp.ldap.host}"
            maxConnections="${com.opentext.dimensions.osp.ldap.max-connections:31}"
            port="${com.opentext.dimensions.osp.ldap.port:389}"/>
    </LDAPDataSource>

    <LDAPAuthenticationSource
        displayName="Authentication from LDAP"
        id="as-ldap"
        restrictToContexts="${com.opentext.dimensions.osp.as.restrict-to-contexts:false}">
        <Reference refId="ds-ldap" type="DataSource"/>
        <NamingAttr name="${com.opentext.dimensions.osp.as.naming-attr:cn}"/>
        <NamingAttr name="${com.opentext.dimensions.osp.as.duplicate-resolution-naming-attr:mail}"/>
        <Context context="${com.opentext.dimensions.osp.as.users-container-dn}" scope="${com.opentext.dimensions.osp.as.scope:subtree}"/>
        <Context context="${com.opentext.dimensions.osp.as.admins-container-dn}" order="1" scope="${com.opentext.dimensions.osp.as.scope:subtree}"/>
        <AttributeMapping>
            <AttributeMapEntry localName="dn" nativeName="{$dn}"/>
            <AttributeMapEntry localName="username" nativeName="${com.opentext.dimensions.osp.as.naming-attr:cn}"/>
            <AttributeMapEntry localName="mail" nativeName="mail"/>
            <AttributeMapEntry localName="roles" nativeName="groupMembership"/>
            <AttributeMapEntry localName="mobile" nativeName="mobile"/>
            <AttributeMapEntry localName="givenName" nativeName="givenName"/>
            <AttributeMapEntry localName="surname" nativeName="surname"/>
        </AttributeMapping>
    </LDAPAuthenticationSource>

  2. Add the following LDAP properties to the osp-configuration.properties file:

    Copy code 
    com.opentext.dimensions.osp.ldap.dir-type = AD
    com.opentext.dimensions.osp.as.naming-attr = sAMAccountName
    com.opentext.dimensions.osp.ldap.usersearchfilter = (&(objectClass=user)(sAMAccountName={0}))
    com.opentext.dimensions.osp.as.users-container-dn = CN=Users,DC=example,DC=com
    com.opentext.dimensions.osp.ldap.connect-timeout = 30000
    com.opentext.dimensions.osp.ldap.admin-dn = CN=Administrator,CN=Users,DC=example,DC=com
    com.opentext.dimensions.osp.ldap.admin-pwd = <encoded-password>
    com.opentext.dimensions.osp.ldap.host = ldap-host
    com.opentext.dimensions.osp.ldap.use-tls = false
    com.opentext.dimensions.osp.ldap.port = 389

LDAP administrator password encoding

When using LDAP authentication, store the administrator password in the osp-configuration.properties file and set the encoding mode in authcfg.xml. OSP supports three encoding modes: NONE, BASE64, and XOR.

Note: These encoding modes are obfuscation methods, not encryption. Use XOR for production environments and avoid NONE except for lab or test systems.

To configure a plain text password (NONE):

  1. In authcfg.xml, do not set the passwordEncoding attribute on the <LDAPDataSource> element.

  2. In osp-configuration.properties, set the password directly:

    com.opentext.dimensions.osp.ldap.admin-pwd = your_plain_password

To configure a BASE64 encoded password:

  1. In authcfg.xml, add passwordEncoding to the <LDAPDataSource> start tag. Example (start tag only):

    <LDAPDataSource
        displayName="LDAP Data Source"
        id="ds-ldap"
        adminName="${com.opentext.dimensions.osp.ldap.admin-dn}"
        adminPassword="${com.opentext.dimensions.osp.ldap.admin-pwd}"
        dirType="${com.opentext.dimensions.osp.ldap.dir-type:eDir}"
        instanceStoreAttributeName="${com.opentext.dimensions.osp.ldap.trustsource-attr-name:oidpInstanceData}"
        passwordEncoding="BASE64">

  2. In osp-configuration.properties, set a BASE64 encoded password:

    com.opentext.dimensions.osp.ldap.admin-pwd = your_base64_encoded_password

To configure an XOR encoded password:

  1. In authcfg.xml, add passwordEncoding to the <LDAPDataSource> start tag. Example (start tag only):

    <LDAPDataSource
        displayName="LDAP Data Source"
        id="ds-ldap"
        adminName="${com.opentext.dimensions.osp.ldap.admin-dn}"
        adminPassword="${com.opentext.dimensions.osp.ldap.admin-pwd}"
        dirType="${com.opentext.dimensions.osp.ldap.dir-type:eDir}"
        instanceStoreAttributeName="${com.opentext.dimensions.osp.ldap.trustsource-attr-name:oidpInstanceData}"
        passwordEncoding="XOR">

  2. Create the XOR key by concatenating the service ID from authcfg.xml with the tenant ID from tenantcfg.xml (<TOMCAT_HOME>/conf/netiq_osp_file-minimal/WEB-INF/conf/current/<TENANT_ID>/tenantcfg.xml). Example key: authdimensions.

  3. Generate the XOR BASE64 value using PowerShell:

    powershell -NoProfile -Command "$password = '{LDAP_ADMIN_PASSWORD}'; $key = '{SERVICE_ID+TENANT_ID}'; $plain = [Text.Encoding]::UTF8.GetBytes($password); $keyb  = [Text.Encoding]::UTF8.GetBytes($key); $out = New-Object byte[] $plain.Length; [int]$state = 0; $ki = 0; for ($i = 0; $i -lt $plain.Length; $i++) { $state = ($state -bxor $plain[$i] -bxor $keyb[$ki]) -band 0xFF; $out[$i] = [byte]$state; $ki++; if ($ki -ge $keyb.Length) { $ki = 0 } }; [Convert]::ToBase64String($out)"

    Replace {LDAP_ADMIN_PASSWORD} with the LDAP admin password and {SERVICE_ID+TENANT_ID} with the concatenated key.

  4. In osp-configuration.properties, set the XOR BASE64 value:

    com.opentext.dimensions.osp.ldap.admin-pwd = your_xor_base64_encoded_password

Note: Use the PowerShell command above for customer-facing guidance. Internal Java utilities in the OSP WAR are for developer reference only.

Back to top

Step 4: Configure OAuth2 client in authcfg.xml

Configure the OAuth2 client settings to enable OpenText Dimensions CM to authenticate with OSP.

To configure the OAuth2 client:

  1. In the authcfg.xml file, locate the OAuth2Clients section.

  2. Add or verify the following client configuration:

    Copy code 
    <OAuth2Clients>
        <Reference refId="oauth-DimCMWeb-template" type="OAuth2ApplicationTemplate"/>
        <Client id="DimCM" secret="HelloDimensionsCM">
            <RedirectUrlList>
                <Url>${com.opentext.dimensions.oauth.client1.redirect-uri}/adminconsole?jsp=login_openid</Url>
                <Url>${com.opentext.dimensions.oauth.client1.redirect-uri}/dimensions?jsp=login_openid</Url>
                <Url>${com.opentext.dimensions.oauth.client1.redirect-uri}/pulse/login/oauth2/code/default</Url>
                <Url>${com.opentext.dimensions.oauth.client1.redirect-uri}/vault-server/login/oauth2/code/default</Url>
            </RedirectUrlList>
        </Client>
    </OAuth2Clients>

Note: Ensure that the Client ID and Client Secret match across all configuration files, including dm.cfg and the web.xml files for the Web Client and Administration Console.

Back to top

Step 5: Generate Self-Signed Certificates (Local OSP Setup)

For local OSP setup, generate self-signed certificates for Dimensions by running a provided script.

To create self-signed certificates for Dimensions:

  1. Navigate to the following directory:

    C:\Program Files\OpenText\Dimensions 26.1\CM\utils\ssl

  2. Run the script ssl-setup.cmd to generate certificates using the system hostname.

Back to top

Step 6: Add Certificates for Desktop Client or Common Tools (Local OSP Setup)

If you are using the Desktop Client or the Common Tools installer, add the generated certificate to the Windows Root store.

To add the certificate to the Windows Root store:

  1. Export the certificate from the Tomcat keystore:

    Copy code 
    keytool -exportcert -alias tomcat -keystore "C:\Program Files\Apache Software Foundation\Tomcat 10.1\conf\sample-ssl.jks" -storepass serena -rfc -file C:\tmp\osp-server.crt

  2. Add the certificate to the Windows Root store:

    Copy code 
    certutil -addstore Root "C:/tmp/osp-server.crt"

Back to top

Step 7: Configure SSL on Tomcat (Remote OSP Setup)

For remote OSP setup, configure SSL on Tomcat to enable secure HTTPS connections on port 8443.

To configure the HTTPS connector:

  1. Open the Tomcat server.xml file:

    <TOMCAT_HOME>/conf/server.xml

  2. Update the HTTPS Connector configuration:

    Copy code 
    <Connector
        port="8443"
        protocol="org.apache.coyote.http11.Http11NioProtocol"
        maxThreads="150"
        acceptCount="100"
        SSLEnabled="true"
        scheme="https"
        secure="true"
        clientAuth="false"
        sslProtocol="TLS"
        protocols="TLSv1.2,TLSv1.3"
        ciphers="TLS_AES_256_GCM_SHA384,TLS_AES_128_GCM_SHA256,TLS_CHACHA20_POLY1305_SHA256,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_DHE_RSA_AES_128_GCM_SHA256"
        relaxedQueryChars="[,]"
        keystoreFile="conf/netiq_osp_file-minimal/WEB-INF/certs/keystore.jks"
        keystorePass="password"
        keyAlias="your-alias"/>

Back to top

Step 8: Configure Dimensions server

Configure the OpenText Dimensions CM server to use OSP for authentication.

To configure dm.cfg:

  1. Open the dm.cfg file on the OpenText Dimensions CM server.

  2. Add or update the following settings:

    Copy code 
    DM_AUTH_TYPE_DBS                  = SSO_OPENID
    OPENID_CONNECT_JWKS_ENDPOINT      = https://your-osp-host:8443/osp/a/dimensions/auth/oauth2/jwks
    OPENID_CONNECT_AUTH_ENDPOINT      = https://your-osp-host:8443/osp/a/dimensions/auth/oauth2/auth
    OPENID_CONNECT_INTROSPECT_ENDPOINT = https://your-osp-host:8443/osp/a/dimensions/auth/oauth2/introspect
    OPENID_CONNECT_CLIENT_ID          = DimCM
    OPENID_CONNECT_CLIENT_SECRET      = $$OPENID_CONNECT_CLIENT_SECRET$$
    OPENID_CONNECT_WEB_CLIENT_ID      = DimCMWeb
    OPENID_CONNECT_WEB_CLIENT_SECRET  = $$OPENID_CONNECT_WEB_CLIENT_SECRET$$

  3. Use the dmpasswd utility to store the client secrets securely:

    dmpasswd OPENID_CONNECT_CLIENT_SECRET -add -pwd HelloDimensionsCM
    dmpasswd OPENID_CONNECT_WEB_CLIENT_SECRET -add -pwd HelloDimensionsCMWeb

Back to top

Step 9: Configure Web Client and Administration Console

Update the web.xml files for the Web Client and Administration Console to enable OSP authentication.

To configure the web.xml files:

  1. Open the web.xml file for the Web Client:

    <TOMCAT_HOME>/webapps/dimensions/WEB-INF/web.xml

  2. Add the following init-param entries in the main servlet section (above the multipart-config element):

    Copy code 
    <init-param>
        <param-name>openid_connect__auth_endpoint</param-name>
        <param-value>https://your-osp-host:8443/osp/a/dimensions/auth/oauth2/grant</param-value>
    </init-param>
    <init-param>
        <param-name>openid_connect__client_id</param-name>
        <param-value>DimCM</param-value>
    </init-param>
    <init-param>
        <param-name>openid_connect__client_secret</param-name>
        <param-value>HelloDimensionsCM</param-value>
    </init-param>

  3. Repeat the same changes for the Administration Console web.xml file:

    <TOMCAT_HOME>/webapps/adminconsole/WEB-INF/web.xml

Back to top

Step 10: Configure desktop client

To enable OSP authentication for the desktop client, additional configuration is required.

To configure the desktop client:

  1. In the desktop client dm.cfg file, add the following setting:

    DM_TEMP_LOGINWIZ Y

  2. In the Tomcat server.xml file, under the 8443 connector with protocol="org.apache.coyote.http11.Http11NioProtocol", add the following attributes:

    relaxedPathChars="[]" and relaxedQueryChars="[]"

Back to top

Step 11: Configure Pulse UNO

If using Pulse UNO, configure it to authenticate with OSP.

To configure Pulse UNO:

  1. Open the Pulse UNO startup.properties file:

    C:\ProgramData\OpenText\PulseUno\pulse_data\conf\startup.properties

  2. Add the following properties:

    Copy code 
    authentication.type=OIDC
    authentication.oidc.baseurl=https://osp-server-host:8443/osp/a/dimensions/auth/oauth2
    authentication.oidc.clientid=DimCM
    authentication.oidc.secret=HelloDimensionsCM

Back to top

Step 12: Restart services

After completing the configuration, restart all relevant services.

To restart services:

  1. Restart the Tomcat service.

  2. Restart the OpenText Dimensions CM listener service.

Back to top

Step 13: Verify the configuration

Verify that OSP is configured correctly and that authentication is working.

To verify the configuration:

  1. Navigate to the OSP OpenID configuration endpoint:

    https://your-osp-host:8443/osp/a/dimensions/auth/oauth2/.well-known/openid-configuration

  2. Verify that the endpoint returns valid JSON configuration data.

  3. Log in to OpenText Dimensions CM using the Web Client or Administration Console.

  4. Verify that you are redirected to the OSP login page and can authenticate successfully.

Back to top

Troubleshooting

If you encounter issues with token validation after the login page appears, verify that certificates are properly imported.

To verify certificate installation:

  1. Open the Windows Certificate Manager (certmgr).

  2. Navigate to Trusted Root Certification Authorities.

  3. Verify that your certificate is listed and properly imported.

Back to top

See also: