Documentum – Login through OTDS without oTExternalID3

As you might know, Documentum “deprecated” (in reality disabled completely) the different Authentication Plugins that were bundled with a Documentum Server. That means that with recent versions of Documentum, you cannot login to your LDAP-managed account anymore without having configured an OTDS and integrated it with your Documentum Server. After you installed the OTDS, and configured it to work with Documentum, you might be faced with an annoying behavior that makes it impossible to login. This is because, by default, it only supports one specific configuration for the user_login_name (i.e. oTExternalID3). There is a workaround, but it’s not documented, as far as I know, so I’m writing this blog to share that information.

When logging in to a Documentum Server, using the “connect” iAPI command, the Repository will verify if the user_login_name exists. If yes, it will send the Authentication request to the JMS, which will contact the OTDS with the details provided. The OTDS will perform the authentication with whatever Identity Provider you configured inside it and return the result to the JMS, which will then confirm the details to the Repository to either allow or deny the login. In this case, it doesn’t matter if the user_source of the dm_user is configured with “LDAP” or “OTDS”. Both will behave in the same way and the request will be sent to the JMS and then the OTDS, that’s the theory at least… That’s working properly for an “indirect” login using the “connect” iAPI command triggered by an already logged in user such as dmadmin. But a “direct” login (DA, dqMan, or direct iAPI with username/password) will fail for an “LDAP” user_source as Documentum will, in this case, try to use the LDAP Auth and then complain that it’s deprecated :)… Might be the subject of another blog.

I. OTDS Synchronization with default configuration

To do some testing or if you are setting-up a freshly installed Documentum Repository (i.e. no previous LDAP integrations), you might want to keep things simple and therefore you would most probably end-up using the default configuration.

The default User Mapping configuration for an OTDS Resource, for Documentum, might be something like:

    Resource Attribute            >> OTDS Attribute          >> Format
    __NAME__                      >> cn                      >> %s
    AccountDisabled               >> ds-pwp-account-disabled >> %s
    client_capability             >>                         >> 0
    create_default_cabinet        >>                         >> F
    user_address                  >> mail                    >> %s
    user_global_unique_id         >> oTObjectGUID            >> %s
    user_login_name               >> oTExternalID3           >> %s
    user_name                     >> cn                      >> %s
    user_privileges               >>                         >> 0
    user_rename_enabled           >>                         >> F
    user_rename_unlock_locked_obj >>                         >> T
    user_type                     >>                         >> dm_user
    user_xprivileges              >>                         >> 0

Please note that the default value for “user_login_name” is “oTExternalID3”. In addition to mapped attributes from the AD / LDAP, OTDS defines some internal attributes that you can use, and this one is one of those. For example, if a cn/sAMAccountName has a value of “MYUSERID”, then you will most probably end-up with something like:

• oTExternalID1 == MYUSERID
• oTExternalID2 == MYUSERID@OTDS-PARTITION-NAME
• oTExternalID3 == [email protected]
• oTExternalID4 == DOMAIN\MYUSERID

Therefore, in this case, with the default configuration, you would need to use “[email protected]” to be able to login to Documentum. Nothing else would work as your dm_user would be synchronized/created/modified to have a user_login_name value of “[email protected]”. As a sidenote, the “%s” in the Format column means to keep the formatting/case from the source attribute. In most AD / LDAP, the cn/sAMAccountName would be in uppercase, so you would only be able to login with the uppercase details. There is a parameter that you can set in the server.ini to be able to have a case-insensitive Repository and another one in the JMS, so you might want to take a look at that for example.

Note: The value of oTExternalID3 can be changed in the Partition > Properties > Extended Functionality page. It is controlled by the value given to the “AD/LDAP attribute” and by default, it should be set to “userPrincipalName” (i.e. [email protected]). However, you can change that value to something else, like “sAMAccountName”, and in this case, oTExternalID3 would end-up with the same value as oTExternalID1.

Here, I’m setting an AD password in an environment variable and then fetching a dm_user details to show you the current content, before triggering a login attempt (using the “connect” iAPI command):

[dmadmin@cs-0 logs]$ read -s -p "  --> Please enter the AD Password: " ad_passwd
  --> Please enter the AD Password:
[dmadmin@cs-0 logs]$
[dmadmin@cs-0 logs]$
[dmadmin@cs-0 logs]$ iapi REPO_NAME -Udmadmin -Pxxx << EOC
> retrieve,c,dm_user where upper(user_login_name) like 'MYUSERID%'
> get,c,l,user_name
> get,c,l,user_login_name
> EOC

        OpenText Documentum iapi - Interactive API interface
        Copyright (c) 2020. OpenText Corporation
        All rights reserved.
        Client Library Release 20.2.0000.0082

Connecting to Server using docbase REPO_NAME
[DM_SESSION_I_SESSION_START]info:  "Session 011234568006fe39 started for user dmadmin."

Connected to OpenText Documentum Server running Release 20.2.00013.0135  Linux64.Oracle
Session id is s0
API> ...
1112345680001d00
API> ...
MYUSERID
API> ...
[email protected]
API> Bye
[dmadmin@cs-0 logs]$
[dmadmin@cs-0 logs]$
[dmadmin@cs-0 logs]$ iapi REPO_NAME -Udmadmin -Pxxx << EOC
> apply,c,NULL,SET_OPTIONS,OPTION,S,trace_authentication,VALUE,B,T
> connect,REPO_NAME,[email protected],dm_otds_password=${ad_passwd}
> apply,c,NULL,SET_OPTIONS,OPTION,S,trace_authentication,VALUE,B,F
> EOC

        OpenText Documentum iapi - Interactive API interface
        Copyright (c) 2020. OpenText Corporation
        All rights reserved.
        Client Library Release 20.2.0000.0082

Connecting to Server using docbase REPO_NAME
[DM_SESSION_I_SESSION_START]info:  "Session 011234568006fe40 started for user dmadmin."

Connected to OpenText Documentum Server running Release 20.2.00013.0135  Linux64.Oracle
Session id is s0
API> ...
q0
API> ...
s1
API> ...
q0
API> Bye
[dmadmin@cs-0 logs]$

As you can see above, the result of the “connect” command is “s1”, which means the session is opened and Documentum was able to verify through the OTDS that the login is correct. On the JMS, there is an “otdsauth.log” file, that gives you this kind of information (might give a bit more information depending on the Documentum Server version used):

[dmadmin@cs-0 logs]$ cat otdsauth.log
...
2025-01-01 13:37:26,417 UTC DEBUG [root] (default task-6) In com.documentum.cs.otds.OTDSAuthenticationServlet
2025-01-01 13:37:26,780 UTC DEBUG [root] (default task-6) userId: [email protected]
2025-01-01 13:37:26,782 UTC DEBUG [root] (default task-6) Password Auth Success: [email protected]
[dmadmin@cs-0 logs]$

The Repository logs will also show the trace_authentication details and the OTDS will also have a successful authentication attempt in its logs. So, all is well in a perfect world, right?

II. OTDS Synchronization with updated configuration

When working with an existing Repository that was initially setup with LDAP Sync and Auth, you might have a “simple” configuration that defined that the user_login_name would be the cn/sAMAccountName attribute from the Active Directory. In this case, you probably don’t want to change anything after the integration of the OTDS… After all, the OTDS is supposed to simplify the configuration and not complexify it. Therefore, you would setup the OTDS to integrate (Synchronized Partition or Non-Synchronized one) with your AD / LDAP and then create a Resource that would replicate and match the exact details of your existing users. Even on a freshly installed Repository without previous LDAP integration, you might choose to login with “MYUSERID” (or “myuserid”) instead of “[email protected]”. The OTDS will allows you to configure that, so users can be synchronized to Documentum however you want.

To achieve that, you would need to change a bit the User Mapping configuration to keep your previous login information / avoid messing with the existing dm_user details. For example, you might want to change the client_capability, user_login_name, user_name and some other things. Here is an example of configuration that allows you to synchronize the users with the cn/sAMAccountName from your AD / LDAP, in lowercase, please note the changes with a wildcard (*):

    Resource Attribute            >> OTDS Attribute          >> Format
    __NAME__                      >> cn                      >> %l (*)
    AccountDisabled               >> ds-pwp-account-disabled >> %s
    client_capability             >>                         >> 2 (*)
    create_default_cabinet        >>                         >> F
    user_address                  >> mail                    >> %s
    user_global_unique_id         >> oTObjectGUID            >> %s
    user_login_name               >> cn (*)                  >> %l (*)
    user_name                     >> displayName (*)         >> %s
    user_privileges               >>                         >> 0
    user_rename_enabled           >>                         >> T (*)
    user_rename_unlock_locked_obj >>                         >> T
    user_type                     >>                         >> dm_user
    user_xprivileges              >>                         >> 32 (*)

The documentation mention in some places to have the same value for both _NAME_ and for user_name but I’m not sure if that’s really required, as I have some customers with different values, and it works anyway. It’s pretty common for customers to have the same value for cn and sAMAccountName and to store the displayName into, well, the displayName attribute… On Documentum side, some customers will use cn as the user_name, but some others will use displayName instead. The user_name is, after all, a kind of displayName so I don’t really understand why OTDS would require both _NAME_ and user_name to be the same. It should instead rely on the user_login_name, no?

After consolidating the OTDS Resource, you should be able to see the correct user_login_name as it was before (with the LDAP Sync job). What’s the purpose of this blog then? Well, the OTDS allows you to change the mapping as you see fit, so that you can replicate exactly what you used to have with an LDAP Sync. But you cannot login anymore…

After the modification of the OTDS Resource User Mapping and its consolidation, here I’m trying to login again (with “myuserid” instead of “[email protected]”) to show the difference in behavior:

[dmadmin@cs-0 logs]$ iapi REPO_NAME -Udmadmin -Pxxx << EOC
> retrieve,c,dm_user where upper(user_login_name) like 'MYUSERID%'
> get,c,l,user_name
> get,c,l,user_login_name
> EOC

        OpenText Documentum iapi - Interactive API interface
        Copyright (c) 2020. OpenText Corporation
        All rights reserved.
        Client Library Release 20.2.0000.0082

Connecting to Server using docbase REPO_NAME
[DM_SESSION_I_SESSION_START]info:  "Session 011234568006fe48 started for user dmadmin."

Connected to OpenText Documentum Server running Release 20.2.00013.0135  Linux64.Oracle
Session id is s0
API> ...
1112345680001d00
API> ...
LastName (Ext) FirstName
API> ...
myuserid
API> Bye
[dmadmin@cs-0 logs]$
[dmadmin@cs-0 logs]$ iapi REPO_NAME -Udmadmin -Pxxx << EOC
> apply,c,NULL,SET_OPTIONS,OPTION,S,trace_authentication,VALUE,B,T
> connect,REPO_NAME,myuserid,dm_otds_password=${ad_passwd}
> apply,c,NULL,SET_OPTIONS,OPTION,S,trace_authentication,VALUE,B,F
> EOC

        OpenText Documentum iapi - Interactive API interface
        Copyright (c) 2020. OpenText Corporation
        All rights reserved.
        Client Library Release 20.2.0000.0082

Connecting to Server using docbase REPO_NAME
[DM_SESSION_I_SESSION_START]info:  "Session 011234568006fe4f started for user dmadmin."

Connected to OpenText Documentum Server running Release 20.2.00013.0135  Linux64.Oracle
Session id is s0
API> ...
q0
API> ...
[DM_SESSION_E_AUTH_FAIL]error:  "Authentication failed for user myuserid with docbase REPO_NAME."


API> ...
q1
API> Bye
[dmadmin@cs-0 logs]$

This time the authentication fails. If you look at the Repository logs, you can see the user is detected properly, and the Repository start the authentication with the OTDS (1st line below). But when the result comes back (2nd and 3rd lines below), it says that it failed:

2025-01-01T13:46:16.446426      188808[188808]  011234568006fe50        [AUTH]  Start-AuthenticateUserByOTDSPassword:UserLoginName(myuserid)
2025-01-01T13:46:16.815111      188808[188808]  011234568006fe50        [AUTH]  otds_password_authentication = false:
2025-01-01T13:46:16.815159      188808[188808]  011234568006fe50        [AUTH]  End-AuthenticateUserByOTDSPassword: 0
2025-01-01T13:46:17.174676      188808[188808]  011234568006fe50        [AUTH]  Final Auth Result=F, LOGON_NAME=myuserid, ...

The JMS otdsauth.log file will have a similar content, it will start the OTDS communications (1st line below) but the result returned (2nd line below) is not the user_login_name of Documentum. Instead, it’s the value of oTExternalID3 and then the JMS says that it failed (3rd line below):

2025-01-01 13:46:16,671 UTC DEBUG [root] (default task-6) In com.documentum.cs.otds.OTDSAuthenticationServlet
2025-01-01 13:46:16,813 UTC DEBUG [root] (default task-6) userId: [email protected]
2025-01-01 13:46:16,814 UTC DEBUG [root] (default task-6) Password Auth Failed: myuserid

On the OTDS side, no problems, the authentication was successful when it was received (in the directory-access.log):

2025-01-01 13:46:16.777|INFO  ||0|0|Authentication Service|Success Access|27,Initial authentication successful|172.0.0.10|""|OTDS-PARTITION-NAME|"[email protected]"|"Authentication success: [email protected] using authentication handler OTDS-PARTITION-NAME for resource __OTDS_AS__"

If you look at the exact timestamp of the messages, you see the exact flow of how things went. In short, the OTDS says that it’s OK and it sends back some information to the JMS. But because the information returned is oTExternalID3, there is a mismatch with the value of the user_login_name and the JMS/Repository then concludes that the authentication failed, which isn’t true…

Therefore, using any user_login_name value other than oTExternalID3 isn’t a problem from a synchronization point of view, but you still cannot login anyway.

III. Workaround

As mentioned in the introduction of this blog, there is a workaround, which is to set the parameter “synced_user_login_name=sAMAccountName” in the otdsauth.properties file that configures how the JMS talks to the OTDS (another workaround might be to change the value of “AD/LDAP attribute” in the Partition as mentioned earlier in this blog, but that will apply to the full OTDS configuration and not just for this repository). I looked at all the OTDS and Documentum documentations, for several versions, as well as KBs, but I couldn’t find this workaround mentioned anywhere. Maybe I’m the one that doesn’t know how to search (don’t blame the search from OT Support website :D). The one and only reference to this parameter is in the Documentum Server Admin & Config doc, but it tells you that it’s optional and it’s only for OTDS token-based authentication. Here, we are doing a password-based auth, we don’t have any OTDS oAuth Client ID/Secret, so this section shouldn’t be required at all. You don’t need the other parameters from this section, but you DO need “synced_user_login_name”, if you would like to login with the cn/sAMAccountName/oTExternalID1/oTSAMAccountName parameter.

However, there is an additional catch… The parameter was apparently only introduced in 20.3. For any older Documentum Server, you will need to check with OT if they have a fix available. I know there is one for 20.2, but it’s only for Windows (c.f. here). Now, you know that you can also use this parameter for that purpose.