Configuring single sign-on

These instructions discuss how to configure single sign-on authentication for NexJ applications.

Authentication is a security process which involves identifying and verifying the credentials of users attempting to access a protected resource. NexJ Model Engine uses Windows Authentication and the SPNEGO negotiation mechanism to securely authenticate users and determine their level of authorization. If Windows Authentication is not an option, Java Kerberos can be used as an alternative.

Single sign-on is a form of access control which uses one set of credentials for multiple applications. It consolidates and streamlines authentication procedures for users and provides administrators with efficient management solutions. Once a user has been authenticated, they are able to access other enterprise applications without having to again log in until their session has expired.

Info

Kerberos authentication is an alternative to native Windows Authentication. Only one method of single sign-on authentication can be set up. It is recommended to use Windows Authentication when possible.

The following steps are required to configure single sign-on authentication:

Create a Windows domain user for the AppServer service.
Run the AppServer service under the domain account.
Create a user domain group for NexJ applications.
Install the SetSPN utility on a domain controller.
Create Kerberos service principal names.
Configure IIS for Kerberos authentication.
Configure native Windows Authentication. (Native Windows Authentication only)
Configure Kerberos for SPNEGO. (Java Kerberos authentication only)
Configure logins.
Enable SPNEGO authentication.
Configure client browsers.

Single sign-on prerequisites

You need to use the following information throughout the single sign-on configuration process:

DOMAIN.EXT
The full name and extension of the Windows domain to which the users of the NexJ application belong. For example, yourcompany.local.

NEXJ_PLUGIN
The directory where NexJ Studio is located. For example, C:\Java\eclipse\plugins\com.nexjsystems.nexjstudio_version.

SERVER_HOME
The root directory of the application server.

Tip

To get the value of DOMAIN.EXT, open the System Properties dialog for the machine on which the Windows server is running. Click on the Computer Name tab. The full computer name and domain are displayed.

Ensure that the following components have been properly set up:

A supported version of Microsoft Windows Server running the Active Directory Domain Controller and associated Kerberos Key Distribution Center (KDC). For more information on supported platforms, see the relevant version of the Release Notes document for your product.
Client computers with Internet browsers that support the SPNEGO authentication mechanism. Refer to the release notes for the list of supported Internet browsers

Creating a Windows domain user for the AppServer service

Using the Active Directory Microsoft Management Console, create a special Windows service user to run application server processes.

To create a new Windows service user for the AppServer service:

Open the Active Directory Microsoft Management Console.
Open DOMAIN.EXT.
Right-click the Users folder and select New → User to create a new user. Fill in the New User dialog and click Next.

Info

Any valid login name may be used. For example, nexjsvr.
Set a password. Uncheck User must change password and check Password never expires.
If prompted, disable Create an Exchange mailbox. The user should not have an email address.
Click Finish to create the new account.
Add this user to the "Domain Users" group. Ensure the user does not belong to any other groups.
Provide this user with the authorization to make read requests to the Active Directory, including the names and properties of users that exist on the domain.

The new service user has been created.

Running the AppServer service under the domain account

For single sign-on to work, the AppServer service must run under the domain account.

To configure the AppServer service:

Start the Windows Services Microsoft Management Console snap-in from Control Panel → Administration Tools → Services or type services.msc at a command prompt.
Navigate to the application server service that was specified during installation. If the default name was used, it would be modeld.
Edit the service by right-clicking it and selecting Properties. Set the login account in the Log On tab to the Windows domain user login ID and password.

Your AppServer service will now run under the domain account.

Creating a user domain group for NexJ applications

For single sign-on to work, NexJ application users must be added to a new domain group. The new group must be created in the same domain as the NexJ application users themselves.

Domain groups provide a single point of administrative control to deny access from unauthorized users. After a user has been authenticated, the application verifies if they have been granted access to the NexJ application based on their domain group affiliation. If the user is a member of a domain group (for example, nexjusers), then they proceed to access the protected application. If they do not belong to a domain group, they are denied access.

Info

The default group is nexjusers. You can use a different group name by specifying the name in the authGroup security property in your environment file. For example, if you want to use a group called samplegroup, open your environment file in NexJ Studio and edit the authgroup property to specify samplegroup.

To create a domain group for NexJ application users:

Open the Active Directory Microsoft Management Console.
Right-click on the Domain icon and choose New → Group to create a new group.
In the New Group dialog, set the group name to nexjusers (one word, all lower-case).
If prompted, disable Create Exchange Mailbox.
Click Finish.
Add all NexJ application users as members of the group.

Your new domain group has been created and NexJ application users have been added.

Installing the SetSPN utility on a domain controller

The setspn.exe tool is used to create service principal names which are used in the Kerberos authentication process. It authorizes a Windows domain user to make authentication requests to the Active Directory Domain Controller on behalf of a service.

The setspn.exe utility is part of the Windows Support Tools package. These tools are available from the Microsoft website or the Windows Server Install CD. On the install CD, the Suptools.msi file can be found in the Support\Tools\ directory.

After installing the setspn.exe tool, execute it on the domain controller within DOMAIN.EXT. This will allow the service user (in this example, nexjsvr) to make authentication requests to the Active Directory Domain Controller on behalf of the NexJ application.

Creating Kerberos service principal names

Kerberos service principal names are created using the setspn.exe tool in the Windows Support Tools package.

Info

Kerberos service principal names are required for single sign-on using both Windows Authentication and Java Kerberos. Both methods of single sign-on authentication require these steps.

To allow the application server to accept Kerberos authentication requests:

Log into the domain controller where the Windows Support Tools are installed.
Open the Command Prompt.
Run the following command in the Command Prompt:
setspn -a HTTP/<host.domain.ext> <DOMAIN.EXT>\nexjsvr

Note

host.domain.ext is the canonical DNS name of the application server host and DOMAIN.EXT is the Kerberos realm, corresponding to the Active Directory domain name. Domain names are case-sensitive: host.domain.ext must be in lowercase and DOMAIN.EXT must be in uppercase.

Tip

The principal names for the account can also be viewed and modified using the adsiedit.msc MMC snap-in (attribute servicePrincipalName, available in the object Property pages).
Confirm the service principal name has been successfully added by running the following command in the Command Prompt:
setspn –L DOMAIN.EXT\nexjsvr
If multiple clusters with separate HTTP redirectors are set up on the same domain, map all HTTP redirector SPNs to nexjsvr.
Make sure no other user or computer has the same SPN value. Use setspn -l DOMAIN.EXT\user to view
SPNs for a given user, and setspn -l host to view SPN for a given computer. If the same SPN is mapped
to another user or computer, it can be deleted using one of the following commands:
TEXT
```
setspn -d HTTP/host.domain.ext DOMAIN.EXT\user 
setspn -d HTTP/host.domain.ext computer
```

Your application server will now be able to receive and process Kerberos authentication requests.

Configuring IIS for Kerberos authentication

When IIS is installed, it creates two Kerberos service principal names for itself. These principal names will conflict with the newly created service principal name for <DOMAIN.EXT\nexjsvr>. They must be deleted for single sign-on authentication to work with native Windows Authentication or Java Kerberos.

Info

These instructions assume that IIS is running on the <host.domain.ext> machine.

These instructions assume that IIS is running on the host.domain.ext machine.

To remove the conflicting IIS Kerberos service principal names:

Log into the domain controller where Windows Support Tools are installed.
Open the Command Prompt.
Run the following command in the Command Prompt:
setspn -d HTTP/<host.domain.ext> <host>
Run the following command in the Command Prompt:
setspn -d HTTP/<host> <host>

Note

Removing the conflicting Kerberos service principal names will conflict with SPNEGO authentication for any existing services being provided by IIS that already use SPNEGO, including the HTTP redirector. The application pools in IIS that have to use Kerberos authentication (including the one with the redirector) must be modified to run under the NexJ service user (in this example, nexjsvr). This user should be made a member of the IIS_WPG user group.

The conflicting IIS Kerberos service principal names are now removed. Kerberos service principal names will now be compatible with Windows Authentication or Java Kerberos single sign-on.

Configuring native Windows Authentication (Windows only)

Configuring native Windows Authentication on the application server allows users to access protected resources using their local login credentials.

If the application server is using a Windows operating system and authenticating with Active Directory, it is recommended to use the NexJ native library for SPNEGO authentication. This library (nexjauth.dll) uses Windows APIs to authenticate users.

Info

The application server cannot be running while completing these steps.

To configure the NexJ native SPNEGO authentication library:

Navigate to %NEXJ_PLUGIN%\lib\win32 using Windows Explorer.
Copy nexjauth.dll.
Navigate to %JAVA_HOME%\jre\bin and paste the file.

The SPNEGO authentication library has been configured to work with the NexJ Model Engine using native Windows Authentication.

Configuring Kerberos for SPNEGO (Java Kerberos only)

Kerberos authentication for SPNEGO is an alternative to configuring single sign-on using native Windows Authentication. Kerberos should only be configured if using Windows Authentication is not an option.

Configuring Kerberos for SPNEGO involves:

Creating a krb5.conf file to configure information for the Java GSSAuthenticator. This locates the Kerberos domain controller.
Creating and initalizing the krb5.keytab file. This file contains information needed by the GSSAuthenticator to validate the authenticity of communications from the Kerberos domain controller.
Invoking the kinit tool. This program initiates a session between the service principal (in this example, nexjsvr) and the Kerberos domain controller, allowing the Kerberos domain controller to trust requests from the application.

To configure Kerberos for SPNEGO:

Create the directory SERVER_HOME on your application server machine.
Run the ktab command in %SERVER_HOME%\spnego to create a keytab file with the server's service principal name and service user (e.g. nexjsvr) password:
ktab -a HTTP/<appServerHost.domain.ext> -k %SERVER_HOME%\spnego\krb5.keytab

Info

Ensure that the path %SERVER_HOME%\spnego\krb5.keytab has no spaces. If it does, copy krb5.keytab to a directory without spaces and adjust the entered path in these instructions accordingly.
Verify that the keytab works by creating a temporary entry:
ktab -a user@DOMAIN.EXT -k %SERVER_HOME%\spnego\krb5.keytab
View the keytab file to verify entries using the command:
ktab -l
Issue a kinit command:
kinit -k -t krb5.keytab nexjsvr@<DOMAIN.EXT>
Remove the temporary entry you created in step 3 by running the following command:
ktab -d user@<DOMAIN.EXT>

Create the Kerberos configuration file %JAVA_HOME%\lib\security\krb5.config, with the following content:

TEXT

[libdefaults] 
        default_realm = <DOMAIN.EXT> 
        default_keytab_name = FILE:%SERVER_HOME%\spnego\krb5.keytab 
        default_tkt_enctypes = rc4-hmac des-cbc-md5 default_tgs_enctypes = rc4-hmac des-cbc-md5 
[realms] 
        <DOMAIN.EXT> = { 
                kdc = <kdc_host.domain.ext:88> 
        } 
[domain_realm] 
        <.domain.ext> = <DOMAIN.EXT>

Note

Domain names are case-sensitive. All <DOMAIN.EXT> values must be capitalized in the configuration.

The following is an example Kerberos configuration file:

TEXT

[libdefaults] 
        default_realm = NEXJSYSTEMS.LOCAL 
        default_keytab_name = FILE:C:\java\modeld\spnego 
\krb5.keytab 
        default_tkt_enctypes = rc4-hmac des-cbc-md5 
        default_tgs_enctypes = rc4-hmac des-cbc-md5 
[realms] 
        NEXJSYSTEMS.LOCAL = { 
                kdc = nexj-prd-1.nexjsystems.local:88 
        } 
[domain_realm] 
        .yourcompany.local = YOURCOMPANY.LOCAL

Kerberos is now configured to work with the SPNEGO negotiation mechanism.

Configuring user logins for single sign-on

When a user is logging into a NexJ application, the credentials of the current desktop session are sent to the application server.

For single sign-on to work, the domain that the user is logged into must have the same name as the Authentication Domain parameter in the SPNEGO configuration for the application server.

Alternatively, the user login name must match the principal name format of username@DOMAIN.EXT, for example, jsmith@YOURCOMPANY.LOCAL. When creating users in the application server, you must also create login names that match the principal name format of username@DOMAIN.EXT.

Note

The domain name and extension must be in upper case.

Using basic authentication to configure logins

For single sign-on authentication to work, all NexJ application users must have login IDs that match the Kerberos service principal name format.

To change user login IDs to match the Kerberos service principal name format:

Log into NexJ Admin Console using the default account.
In the menu bar, click the User button. The User screen opens in the middle column.
Click Users to retrieve a list of all NexJ users.
Select the nexjsa account.
Use the Edit button
in the right column to open the Edit Local User dialog.
Change the Login value to match the Kerberos service principal name format (for example, nexjsa@YOURCOMPANY.LOCAL).
Click OK.
Set at least one user account to that of a real domain user. Provide this account with Administrator privileges.
Save your changes and close NexJ Admin Console Console.

Users should now have login IDs that match the Kerberos service principal name format.

Enabling SPNEGO authentication

Your application server will require modification before it can be compatible with the SPNEGO negotiation mechanism. Use NexJ Studio to change the server's authentication properties.

To configure the application server to use SPNEGO authentication:

Open NexJ Studio.
Open the environment or server file from the Deployment tab to configure your production server's settings.
In the Security tab, define the following values:
- Authentication Protocol: <spnego>
- Authentication Domain: <DOMAIN.EXT>
- Authentication Service: <HTTP/host.domain.ext>
Save the environment or server file.
Deploy the NexJ Model on the application server using the Deploy Model button
on the toolbar.

Any administrative user (in this example, jsmith@NEXJDEMO.LOCAL) can now log into NexJ CRM or NexJ Admin Console without being prompted.

Configuring user browsers for silent single sign-on

Silent single sign-on allows users to access NexJ applications without being prompted to supply login information multiple times per session. Client Internet browsers must be configured to share their login information with the application server. For silent single sign-on to work, the browser must recognize the application server as a trusted domain.

Info

If silent single sign-on fails on a Windows operating system, look in the system event log for warning entries entitled "LSA SPNEGO" and in the application event log for group policy update errors. If you find these errors, remove any entries from Control Panel → User Accounts → Advanced → Manage Passwords and reboot the computer.

Configuring silent single sign-on for Internet Explorer

In Microsoft Internet Explorer, the application server host URL must be listed in the browser preferences as a trusted domain.

To set the application server as a trusted domain in Internet Explorer:

In the browser, from the Tools menu open the Internet Options dialog. Click the Security tab.
Select the Local Intranet icon and click the Sites button.
In the Local Intranet dialog, ensure that the Include all local (intranet) sites not listed in other zones checkbox is selected. Click the Advanced button.
In the Advanced Local Intranet dialog, fill in the Add this Web site to the zone field with the Web address of the host name: http[s]://host.domain.ext.
Click Close to complete this step. The Local Intranet window closes.
Click the Advanced tab in the Internet Options dialog.
In the Settings list, ensure that the Enable Integrated Windows Authentication checkbox is selected.
Click OK to close the Internet Options dialog.
Restart Internet Explorer to activate these settings.

Your browser is now compatible with silent single sign-on authentication.

Configuring servers for cross-server SSO

As of NexJ CRM 9.9, an extension of the existing NexJ single sign-on (SSO) system supports use cases with multiple NexJ servers. The expected usage is for more than one AFL server, where the Portal server acts as the primary source of trust and the Portal application hosts portlets from other remote servers, possibly in a cross-domain setup. The remote portlets must be set to use secure communications using HTTPS. It is recommended both server types use HTTPS.

On the Portal server, the portlets participating in the RemoteToken SSO extension must be listed in the Hosts section of the environment file. In addition, you must create a user for remote login using the service with the sso:RemoteTokenValidate privilege to validate the implementation.

On the secondary remote portlet server, the sso:RemoteToken channel must be configured in the environment file, with the URL set to the Portal server's JSON endpoint and the user set to the previously mentioned remote login user. NexJ recommends that you use certificates to verify identity. In addition, the user with the same login must exist on both servers. It is assumed that the user login belongs to the same user as long as the login matches.

When upgrading to NexJ CRM 9.9, the contents of the SSOSecurityContextConfig table in the database will be reset. If any settings were changed in the database without modifying the project's model, they will need to be set again after upgrading.