Thomas Hampel

 16 February 2017
This is the fourth post our of a series of blog posts describing how to move from password based to seamless authentication.
In Level 3 - SPNEGO I have explained how to configure SPNEGO authentication for providing seamless authentication. A drawback of this method was that users can only log in with the current OS user, switching to a different context was not possible. In this level I am providing a solution to switch the user without switching the OS user.

Level 3 - SPNEGO with fallback option
The SPNEGO configuration from Level 3 - SPNEGO alone will automatically log in the user with his OS credentials. There are cases where the machine is used by multiple users which -for whatever reason- share the same OS user, or when the OS user is not member of the ActiveDirectory, or the current OS user does'nt have the required Notes name listed in LDAP..... However, think of kiosk machines, etc. where the OS user has little to no access rights in corporate applications. So we would like to provide them with an option to authenticate with credentials other than the OS user.

Pros and Cons
+ Seamless authentication for browser clients on Windows
+ Ability to switch user without logging off/on from OS
- It's Windows only
- Does'nt work for Traveler and Sametime

Prerequisites

• You have successfully completed Level 3 - SPNEGO
• You have (at least) two IP addresses on your Domino server or have at least two Domino servers in your environment

Idea and Concept
Main idea is to handle to handle login and not authenticated errors and redirect user sessions to a fallback authentication page hosted on a Domino server that does not use SPNEGO.
This brief workflow diagram describes how its done:

The first part of the authentication flow is shown in the "Conceptual Overview" graphic in this article where the sequence is as follows

1	The user is trying to access a protected resource (e.g. “serviceurl.company.com”) by using a web browser. The browser is establishing an SSL session on Port 443 and sends HTTP GET / Post request.
2	Domino returns HTTP401 WWW-Authenticate:Negotiate
3	The Client sends HTTP GET / Post request via SSL with an authorization SPNEGO Token
4	Domino verifies if the token format received from the Browser is SPNEGO
5	Domino validates the ticket against Kerberos Domain Controller to authenticate the user
6	With the Kerberos name is returned, Domino will make an outbound call in order to find the Domino distinguished name (e.g. attribute “mailNickname” ) within ActiveDirectory by looking up the Kerberos name. For successful authentication the result is a Notes User name which will be used for this session, continue with 7a. For unsuccessful authentication the result is HTTP Not Authorized, continue with 7b
7a	Domino returns an LTPAToken to the client and proceeds to the requested resource by verifying access rights in the ACL. At this point the user is authenticated and the process will end here.
7b	Domino returns HTTP403 Not Authorized, The user will be redirected to a custom logon page for non-SPNEGO users, continue with step #9 in the next chapter.

For a concept with a fallback option you'll need at least two internet sites or two Domino servers with a different configuration for each.
Users trying to access a protected resource (e.g. application) that they are not authorized to use, will get a custom error page returned with a javascript that will redirect to a non-SPNEGO site.
This graphic shows two Domino servers where one is using internet sites and one is using an old style web configuration - both use a web SSO configuration document called "LtpaToken".

8	The user was trying to access a protected resource (e.g. “authenticationURL.company.com”) by using a web browser. The browser is establishing an SSL session on Port 443 and sends HTTP GET / Post request. Internally Domino is returning HTTP 403 – Not Authorized, which causes Domino to check if a custom error handler has been configured for the requested URL.
9	Domino returns the custom error page configured for this URL. If no custom error handler has been configured only the browser default error message for HTTP403 Not Authorized will be displayed.
10	The browser will render the custom error page, which contains a JavaScript to redirect the client to a fallback authentication page.

Depending on the type of resource, a custom login page will be displayed, either the iNotes login page or a custom one.


More details:

11	The user is trying to access a protected resource by using a web browser.The browser is establishing an SSL session on Port 443 and sends HTTP GET / Post request
12	Domino returns a username password dialog box which has been configured for this URL. The layout of this form depends on the URL requested. See Domcfg.nsf
13	The user is entering his ActiveDirectory- or DominoHTTP username / password.Credentials are sent via SSL to the server for verification.
14	Domino is verifying credentials against the Directories configured in its directory assitence database. Multiple directories can be specified, Domino will process all of them. The connection to an Active Directory server is established via LDAP / SSL using its own credentials configured in the directory assistance database.
15	For successfully authenticated users, the AD user object is returned to Domino. Domino will read the attribute “mailNickname” from the user object and will use this as Notes user name for the user session.
16	Domino returns an LTPAToken to the client and will verify access rights in the ACL of the requested resource or will redirect the user back to the URL he wanted to access in the beginning
17	The browser will receive the LTPAToken in form of a cookie which is valid for the DNS Domain defined in the WebSSO key. At this point the user is authenticated. The browser can now present this cookie to any server which is member of this DNS domain to identify himself.

How to...
Assuming LDAP authentication + SPNEGO have been configured already + domcfg.nsf exists, here is what to do:

1. Create a Web SSO Configuration for SPNEGO Enabled
In this example I'm using "DominoSPNEGOEnabled" as the configuration name.

Organization	yourCompany
DNS Domain	.yourdomain.com
Map names in LTPA tokens	Enabled
Require SSL protected communication (HTTPS)	Disabled
Restrict use of the SSO token to HTTP/HTTPS	Disabled
Configuration Name	DominoSPNEGOEnabled
Participating Server Names	List of all servers in the Domain
Windows single sign-on integration (if available)	Enabled
Token Expiration	180 minutes

2. Create a Web SSO Configuration for SPNEGO Disabled
Copy and paste the document for the SPNEGO enabled configuration, and change the following elements:

• Configuration Name: DominoSPNEGODisabled
• Windows single sign-on integration (if available): Disabled

Key is to have the same WebSSO key for both configurations, which is a value computed when creating a new document. So make sure to copy/paste the existing Web SSO Configuration document to obtain the same key. In case the key will be changed, make sure to update the document which you copied accordingly.

3. Create Internet Site Documents
Prerequisite for the configuration is to use internet site documents for Domino servers providing HTTP services.
Each of the Internet Sites configured should be configured to use the Web SSO configuration created before

• Web SSO Configuration: DominoSPNEGOEnabled
  This is the name of the Web SSO Key created in the previous step.
• Force login on SSL: Yes

Then create another Internet Site document to be used as authentication URL, which will be using the DominoSPNEGODisabled

Note that you should use an SSL certificate for each domain. When both internet site documents are located on the same server, you'll need one IP addresses for each domain to properly handle the SSL certificate binding
If you only have one IP address per server, you need two servers where one is using internet sites and one is using web configurations.
Hint: To use the same SSO Key for both types you need to copy/paste the WebSSO document and remove (or add) the company field in one of them

4. Create a Custom Login Form Mapping
This will provide a nice looking a new A username/password dialog box is displayed when SPNEGO can not be used,as alternative for authenticating via username / password.
This form can be customized according to your needs, I'm using the iNotes login form here
Target Database : Domcfg.nsf
Target Form : iNotesLoginForm

5. Create a Custom ‘Not Authorized’ Error Form
This form will be displayed to users who have successfully authenticated against Domino/Active Directory but are not allowed to access the application.
Open the file “domcfg.nsf” in your Domino Designer client, and create a new form called “NotAuthorized”

• Set the Window Title to “Not Authorized”
• Set the HTML Head Content to client/formula:

• Add one new field “database” of type text/computed for display
  Formula : @UrlQueryString( "database" )
• Add some HTML code to the body of the form indicating that there is no access to this resource, and mark it as passthru-html using the menu “Text\Passthru-HTML”
  
  
• Add the following HTML code to the body of the form, note it contains two computed text blocks
  
  
  
  where the formula for is : @Name([CN];@UserName)
  and the formula for is : @LowerCase(@RightBack( @LeftBack( @UpperCase(@UrlQueryString( "database" ));".NSF"); "/")) + ".nsf"
• Enable the flag “Available to Public Access users” in the form properties
  

6. Create a Custom Redirect Form
This form is used for redirecting anonymous users to a different site than users who have authenticated already.
Open the file “domcfg.nsf” in your Domino Designer client, and create a new form called “AnonymousRedirect”

• Set the Window Title to “Redirecting”
• Add the following HTML code to the body of the form, and mark it as passthru-html using the menu “Text\Passthru-HTML”
  Where 'Authentication URL' is the defined DNS name of the Domino server which is hosting the nonSPNEGO Web SSO Configuration.

• Type the (non-passthru-html) text “Redirecting…” into the body of the form.
  This text will be displayed to users while the redirect is in progress.
• Add one new field “RedirectTo” of type text/editable with a default value of “/” at the bottom of the form

Note: There are different options to redirect users, this method is based on a simple JavaScript which will redirect anonymous users to another place than users who have already authenticated but are not authorized to access the resource.

7. Custom Error Handler
Within “domcfg.nsf”, a custom error handler for authorization failures will need to be created in order to redirect users who can not participate in SPNEGO.
Use the view “Error and Response Mapping” and click the "Add Mapping" button.
Applies To  : All Web Sites/Entire Server
For Authentication failures and for Authorization failures, use the same mapping:
Target Database : Domcfg.nsf
Target Form : AnonymousRedirect


Result:
Seamless authentication works fine as before but in addition you get propper error handling.
If users are not authenticated, or not allowed to access the resource, they will be redirected to a page that will allow them to log in as different user.

Troubleshooting

• The following Notes.ini variables will help to analyze problems:
• Technote 1394592 - Troubleshooting Windows single sign-on for Web clients (SPNEGO)
• Make sure the LDAP attribute used for name mapping contains the Notes Name of the user in DN format.
  This is the fully canonical name but slash “/” replaced by a comma “,”
  e.g. for “Peter Mueller/Department/Org” this would be: “CN=Peter Mueller,OU=Department,O=Org”
• Use the developer tools in your internet browser to display your cookies. You should have a LtpaToken Cookie set.
• Last but not least: drop a mail or call the author of this blog post.