TABLE OF CONTENTS
- Overview
- Installation
- Configuration
- Where is the information stored in your external authentication store that matches the name entered on the login page?
- How does Journyx know whether this user actually exists in your external directory store?
- How does Journyx authenticate this user?
- Where should Journyx get directory store information in order to update the user information, if so desired?
- If Journyx is supposed to create users for you when a user authenticates, where should we get their user login from the external store?
- Installation
- Windows Considerations
Overview
Journyx provides external authentication abilities through add-on Professional Services products. Primarily there are 2 external authentication mechanisms: Single Sign On (SSO) and Active Directory/LDAP (LDAP). SSO implies that the customer has a portal through which each and every user already authenticates in order to access web resources. Journyx maintains a SAML 2.0 compliant SSO authentication module. The discussion of such authentication is outside the scope of this document.
LDAP authentication implies that when the user enters their credentials (username and password) on the Journyx login screen, the credentials are validated against a 3rd party store to ensure they match before allowing the user access to the Journyx system.
Installation
The Journyx LDAP integration tool comes as a standard zip file. Installation instructions on any operating system are very similar. Prior to installing any tool, Journyx advises that you create a backup of you current environment. Instructions on how to do so are contained in the Journyx System Administrator’s guide, as well as here: https://community.journyx.com/support/solutions/articles/9000133732-installing-journyx-patches-custom-code-hotfixes-and-upgrades-
Windows Considerations
Not every Windows system allows the local IIS Application Pool Identity to issue queries against Active Directory. In point of fact, most will not. Journyx runs under Internet Information Services (IIS) as the ApplicationPoolIdentity.
In the IIS manager, under Application Pools, you will see something like this:
Testing the dsquery commands listed above from a command prompt might work 100%, but configuring them within Journyx does not allow you to log in with Active Directory Credentials. Enabling debug logging (setkey WT_DEBUGLOG=yes from the Journyx Command Line Prompt, since you cannot log in) shows this in the debug.log file:
stderr 'dsquery failed:The parameter is incorrect.\r\ntype dsquery /? for help.'
This error indicates that dsquery was unable to run properly. The cause of this is usually permissions of the underlying user.
To enable IIS to query Active Directory, you may either change the ApplicationPoolIdentity to the built-in Network Service account which uses the Active Directory machine account to query the store, or you can explicitly set the identity to a named user with proper permissions.
Configuration
Once the LDAP tool is installed, you must configure it before logins will start using LDAP. This is a complicated process that differs between Active Directory environments. Journyx will only be able to help guide and most likely cannot assist in the specifics. An example existence/authentication batch script can be found here: https://community.journyx.com/support/solutions/articles/9000171010-sample-ldap-existence-authentication-queries
Where is the information stored in your external authentication store that matches the name entered on the login page?
Journyx highly recommends leaving this as "Journyx Login."
When a user is presented with the Journyx login page, they will enter their external credentials (LDAP, Active Directory, etc) into that login box. You need to answer the question, "What piece of information within Journyx matches the username that is entered?".
If your Journyx users are going to log in with their "short Windows names," for example, and someone regularly logs in as "alan," where is "alan" stored within Journyx? Journyx strongly suggests making this their Journyx user login as well, although the use of other user fields is supported. You could, for example, have them log in by matching an Employee Number.
How does Journyx know whether this user actually exists in your external directory store?
"Alan" just tried to log into Journyx. What and who do I ask in order to determine whether "alan" exists in the external directory store? In the example above, you will see the command:
dsquery user –u ldapquery –p Asdf1234! –samid <user>
This is a very typical command for a Windows installation authenticating against Active Directory. Let's break it down.
| dsquery user forestroot | This uses the Microsoft utility "dsquery" to query Active Directory about a user. "Forestroot" designates checking the entire AD store rather than just in the domain that the querying user resides. |
| -u ldapquery | This uses the user "ldapquery" to bind against the store. |
| -p Asdf1234! | This uses the password Asdf1234! to bind against the store. |
| -samid <user> | This tells Active Directory that you are only interested in getting the details for the username entered on the login page (<user>) which matches the attribute "samid" in Active Directory. |
In this first command, we are only interested in whether the user exists in the external directory. If the user does not exist in the external directory store, we will fail over to internal Journyx authentication. This allows Journyx to have users which both exist in the external directory and are Journyx-only users (such as administrator accounts).
In the case that this command fails or returns no data, Journyx assumes that the user does not exist and falls back to attempting to authenticate the user via internal authentication. This is why there is a user and a password hard-coded into this command. In the event that this command is omitted, all users must exist in the directory store.
Notes:
- The dsquery utility can be installed with Microsoft's Remote Server Administration Tools.
- Journyx does not recommend using the password Asdf1234! As always, follow your organization's best-practices standards.
- Journyx highly recommends ensuring that the user (ldapquery in this example) cannot log into the network interactively and has only directory store query permissions.
- Every infrastructure differs. Working with your IT organization may allow you to run this command without the need to put a user/password combination into the dsquery command.
A similar command on Linux would be:
ldapsearch -LLL -H ldaps://myldap.my.company.com:636 -x -D ldapquery –w Asdf1234\! -E pr=1000/noprompt -b cn=Users,dc=my,dc=company,dc=com 'uid=<user>'
ldapsearch | This user the utility ldapsearch. |
-LLL | This returns LDIFv1 format with no comments and no version information. |
-H ldaps://myldap.my.company.com:636 | This binds securely via LDAPS to port 636 on the noted server. |
-x | This attempts a simple bind (as opposed to Kerberos, etc). |
-D ldapquery | This uses the user ldapquery to bind against the store. |
-w Asdf1234\! | This uses the password Asdf1234! to bind against the store. |
-E pr=1000/noprompt | This limits the output to 1000 lines without prompting during the return. |
-b cn=Users,dc=my,dc=company,dc=com | This specifies the base of the LDAP tree to search. In this case, just look in users in my.company.com. |
'uid=<user>' | This specifies to only return back the information on a user whose LDAP attribute "uid" matches the entered criteria. |
The notes above regarding security apply here as well.
How does Journyx authenticate this user?
This command is basically exactly the same as the first, the difference being now Journyx will actually bind with the entered credentials. If this succeeds, users will be logged in. If not, they will be denied.
"Alan" just tried to log into Journyx. We found out that, yes, he does exist in the external directory. How do we know he entered the right credentials? In the example above, you will see the command:
dsquery user –u <user> –p <password> –samid <user>
In the first example we bind as the designated user "ldapquery" to ensure alan exists in the external directory. Our second command now attempts to bind with the entered credentials.
The modified Linux command noted above would be:
ldapsearch -LLL -H ldaps://myldap.my.company.com:636 -x -D <user> –w <password> -E pr=1000/noprompt -b cn=Users,dc=my,dc=company,dc=com 'uid=<user>'
An advanced example (only allowing users to authenticate who are part of a specific Active Directory Group) can be found in memberOfGroup.bat. This sample batch file would only allow people in the Active Directory group "JournyxLDAP" to log into Journyx. Its usage would be:
Where should Journyx get directory store information in order to update the user information, if so desired?
The ldif.bat file is enclosed within the installer. This echoes back the information gained from the external store using Microsoft's "dsget" and "ldifde" commands. This information is what will be used to update the fields listed in the rest of the Settings page.
This ldif.bat file is provided for sample purposes only. Journyx recommends reading and understanding this script and involving your IT resources in the event you need to modify this. Use at your own risk.
If Journyx is supposed to create users for you when a user authenticates, where should we get their user login from the external store?
If you configured a "user details" command, and you want Journyx to automatically create users who are in your external store, configure this. The most common usage is either sAMAccountName (shown) for Active Directory or "uid" for other LDAP implementations.
Installation
The Journyx LDAP integration tool comes as a standard zip file. Installation instructions on any operating system are very similar. Prior to installing any tool, Journyx advises that you create a backup of you current environment. Instructions on how to do so are contained in the Journyx System Administrator’s guide, as well as here: https://community.journyx.com/support/solutions/articles/9000133732-installing-journyx-patches-custom-code-hotfixes-and-upgrades-
Windows Considerations
Not every Windows system allows the local IIS Application Pool Identity to issue queries against Active Directory. In point of fact, most will not. Journyx runs under Internet Information Services (IIS) as the ApplicationPoolIdentity.
In the IIS manager, under Application Pools, you will see something like this:
Testing the dsquery commands listed above from a command prompt might work 100%, but configuring them within Journyx does not allow you to log in with Active Directory Credentials. Enabling debug logging (setkey WT_DEBUGLOG=yes from the Journyx Command Line Prompt, since you cannot log in) shows this in the debug.log file:
stderr 'dsquery failed:The parameter is incorrect.\r\ntype dsquery /? for help.'
This error indicates that dsquery was unable to run properly. The cause of this is usually permissions of the underlying user.
To enable IIS to query Active Directory, you may either change the ApplicationPoolIdentity to the built-in Network Service account which uses the Active Directory machine account to query the store, or you can explicitly set the identity to a named user with proper permissions.