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.


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 forestrootThis 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 ldapqueryThis 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:

  1. The dsquery utility can be installed with Microsoft's Remote Server Administration Tools.
  2. Journyx does not recommend using the password Asdf1234! As always, follow your organization's best-practices standards.
  3. Journyx highly recommends ensuring that the user (ldapquery in this example) cannot log into the network interactively and has only directory store query permissions.
  4. 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.