Domino SingleSignOn - Level 5 - SAML Federated Authentication for Browser Clients using ADFS- 20 February 2017 - (0) Comments
Thomas Hampel20 February 2017
This is the fifth post our of a series of blog posts describing how to move from password based to seamless authentication.
In previous posts I've been discussing LDAP and SPNEGO configurations which is okay for Windows environments, but not sufficient enough for mixed or very distributed environments.
Next stage is to enter the 21st century by using SAML authentication for your on premises servers.
Level 5 - SAML Federated Authentication for Browser Clients
SAML authentication - Security Assertion Markup Language - allows Browser clients to authenticate against Domino without submitting credentials to the Domino server.
When a browser client is trying to access a Domino resource (=Web site) where SAML is enabled, Domino will refer the browser to the SAML Identity Provider configured for this web site.
The Identity Provider (e.g. IBM Federated Identity Manager or Microsoft Active Directory Federation Services server) will authenticate a user either by prompting for username & password, or by using seamless authentication such as Windows integrated authentication / Kerberos. In both cases the authentication authority remains with the Identity Provider so thats where you define how a user is authenticated (WIA, 2FactorAuth, etc.).
Default scenario for an identity provider initiated logon is a web page proided by the ADFS server where users can select what resource they want to sign in to.
it is also possible to initiate the authentication from the service provider. When Domino needs to authenticate a browser user, it will redirect the user to the identity provider.
Using ADFS it is possible to add an URL parameter that will redirect the authenticated user to another site.
Pros and Cons
+ Seamless authentication for browser clients
+ Independent from operating system of server
- Does'nt work for Traveler
- This blog post only handles browser clients, but not the Notes client.
Idea and Concept
For a better understanding of the SingleSignOn SPNEGO and SAML please see Gabriella's presentation Simplifying The S's: Single Sign-On, SPNEGO and SAML
- You have completed Level 1 - LDAP Authentication
- Domino Server must be running version 9.0.1 or above and -to be on the safe side- should have a current fix / feature pack applied
- Microsoft ADFS 2.0 or 3.0 server (or any other supported SAML Identity Provider)
- SSL is enabled on Domino and the ADFS server
- Active Directory User Object must have an attribute (e.g. internet address) in common with the Domino Directory person document of the Notes user.
- All servers involved in SAML authentication must use time synchronization because SAML depends on time stamps to be correct.
How to configure SAML for Domino
Andy Pedisich did a great job in pulling together all required information in his IBM Connect presentation SHOW100 - AD + SAML + Kerberos + IBM Notes and Domino = SSO!
Since the presentation already covers all the details, I'm only going to highlight the main actions
- Set up and Configure a SAML Identity provider, e.g. Microsoft ADFS Server or a free alternative
- Create and configure the IDP Catalog (idpcat.nsf) - slide #32
- Create a Relying Party Trust in ADFS
- Update Internet Site Configuration to use SAML for session authentication instead of Multi Servers (SSO)
Seamless authentication works fine as before but now using ADFS as identity provider.
Domino servers will never get the username/password of the users - your security folks will like that.
This is the foundation for establishing Multi-Factor Authentication based on ADFS / SAML by your ADFS admin.
Domino SingleSignOn - Level 4 - Seamless Kerberos authentication via SPNEGO with fallback option- 16 February 2017 - (0) Comments
Thomas Hampel16 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
- 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
|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.|
|Domino returns HTTP401 WWW-Authenticate:Negotiate|
|The Client sends HTTP GET / Post request via SSL with an authorization SPNEGO Token|
|Domino verifies if the token format received from the Browser is SPNEGO|
|Domino validates the ticket against Kerberos Domain Controller to authenticate the user|
|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|
|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.|
|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.
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".
|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.
|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.|
Depending on the type of resource, a custom login page will be displayed, either the iNotes login page or a custom one.
|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|
|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|
|The user is entering his ActiveDirectory- or DominoHTTP username / password.Credentials are sent via SSL to the server for verification.|
|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.
|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.|
|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|
|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.|
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.
|Map names in LTPA tokens||Enabled|
|Require SSL protected communication (HTTPS)||Disabled|
|Restrict use of the SSO token to HTTP/HTTPS||Disabled|
|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
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
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
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
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.
- 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.
Domino SingleSignOn - Level 3 - Seamless Kerberos authentication via SPNEGO- 15 February 2017 - (0) Comments
Thomas Hampel15 February 2017
This is the third post our of a series of blog posts describing how to move from password based to seamless authentication.
In level one and two I explained how to configure Domino for LDAP / Active Directory authentication. Although there is no need to remember the Domino HTTP password anymore, users still have to provide username/password when they log into (e.g.) iNotes. The next level is to automatically authenticate users - this is what I am going to describe in this article.
Level 3 - SPNEGO
At first, some basic information:
SPNEGO is a standard specification defined in RFC 2478 - The Simple and Protected GSS-API Negotiation Mechanism, allowing authentication of browser clients.
It can be used for seamless browser authentication aka Windows Integrated Authentication (WIA). It can not be used for Notes clients, Traveler or Sametime.
Pros and Cons
+ Seamless authentication for browser clients on Windows
- It's Windows only
- Does'nt work for Traveler and Sametime
- You can not really log off or switch users anymore.
- SPNEGO will only work for clients and Domino servers running on Windows and are member of a Windows Domain
- Each URL must have exactly ONE ActiveDirectory object to match the Service Principle Name.
- If you plan to run multiple internet sites on the same Domino server, you MUST run the Domino server task using a Domain user account.
- For clustered internet sites, you MUST run the Domino server task using THE VERY SAME user account.
- Running Domino with credentials other than the local system account will make your server fully dependent on this user account.
If its locked out, has expired, or is removed by accident, your Domino servers wont run. All of them... at once!
- You have carefully read the warning (above) and accept the consequences.
- You have successfully completed Level 1 - LDAP Authentication
- Follow this instruction : Deploying Windows single sign-on for Web clients (SPNEGO) in an existing Domino environment
- Then configure browsers as described here : Configuring Web client browsers for Windows single sign-on
- Using SPNEGO you can not really log off anymore, nor switch to another user other than by logging off/on at OS level.
However there is a trick using a custom login form to get this done which I will describe in the next level.
- Although highly recommended SPNEGO does not require SSL, it works with plain HTTP as well this might be useful for debugging purposes.
Frequently Asked Questions
What to do in a mixed environment?
You can use one machine on Windows as your authentication server and configure Domino Multi-Server-SSO.
Experienced admins will take a look at this OpenNTF project : SSO for Web for non Windows Servers
What to do in Non-Windows environment like Linux, AIX, or what if there is no Windows Domain?
Set up a Domino server on Windows (who wants that?) or skip this level and wait for my blog post desribing SAML authentication.
References and further reading
Domino SingleSignOn - Level 2 - Self Service Password Reset Application - 14 February 2017 - (0) Comments
Thomas Hampel14 February 2017
Based on a recent discussion with a customer it seems there still is not enough information on how to simplify authentication for Notes/Domino users.
This is the second post our of a series of blog posts describing how to move from password based to seamless authentication.
Once you have established LDAP Authentication you can approach the next stage:
Level 2 - Self Service Password Reset Application
Combined with a Self Service Password Request HTTP application (or this fancy one ) users can reset Notes password without the help of an administrator just by using a web browser.
Users must be authenticated in order to reset their own password, but due to the configuration done in level 1 they can use Active Directory credentials to log in.
Once authenitcated a user can just define a new password which is applied immediately in the IDVault. And just seconds later the password can be used to log into the Notes Client.
Pros and Cons
+ Lost/forgotten passwords on a monday morning are no longer your problem. Users can handle this problem alone.
+ You don't need to distribute NotesID passwords for newly created users.
- There still is a NotesID password to remember
- There still is a password prompt every time you start the Notes client and/or every time you open an encrypted mail in iNotes
- The Self Service Password Request HTTP application does not apply any feedback on password quality or strength.
- Notes ID Vault has been established and contains the NotesID’s of all users
- User must be authenticated, preferably using Active Directory authentication as described in the previous post level 1
- Custom Password Reset application template,
Please note the template provided by IBM as part of the Domino server is not officially supported and is provided as example only. See Technote 1330905
Setup instructions have already been provided by IBM, so I'm not describing those steps again.
Once completed you should have a functioning PW reset application. However, I would like to highlight a few important details
- The agent and the form needs to be signed with an ID which has IDVault Password Reset authority
- The ACL of this database must have an Administration server defined, the Admin server specified there must be the one that hosts the IDVault.
For improved usability I do recommend a little tuning:
- Create a URL which users can remember, e.g. by creating a web redirect rule
http://yourserver.domain.com/passwordreset ==> /pwreset.nsf
- Modify the form “fmPasswordReset” to display your corporate password rules, e.g.
“The new password must have a minimum of 8 characters. It must contain a mixture of lowercase alphabetic, uppercase alphabetic, numbers and special characters. Three of these four conditions must be met.”
- Modify the source code to confirm the password change request has been submitted and to verify if password rules have been followed.
Without this modification users will not get any feedback if the new password has been applied or not.
so update the source code of the Form “Password Change” , Sub “OnSubmit” as follows:
var k = 0;
var h = 0;
var have = [0, 0, 0, 0];
var characters = ["abcdefghijklmnopqrstuvwxyz", "ABCDEFGHIJKLMNOPQRSTUVWXYZ", "0123456789"];
var minLen = 8;
var minDif = 3;
var pw1 = document.forms.pw1.value;
var pw2 = document.forms.pw2.value;
for (i=0; i
h = 3;
for (k=0; k
if(characters[k].indexOf(pw1.substr(i,1)) >= 0)
h = k;
have[h] = 1;
if ( pw1.length < minLen )
alert("You must enter a password with at least " + minLen + " characters");
else if( pw1 != pw2 )
alert("Entered password don't match");
else if( have + have + have + have < minDif )
alert("Password must be more complex, use Numbers, Lower-, Upper-, Special-Characters");
alert("Thank you, your request has been submitted. The new password can be used now.");
- In order to support clustered environments the source code of the agent “User Password Reset” needs to be updated as follows:
Call Session.ResetUserPassword( session.Currentdatabase.Acl .Administrationserver,"",Doc.GetItemValue("pw1")(0))
Self Service Password Reset application combined with LDAP authentication will eliminate the need to distribute Notes ID passwords to end users.
Administrators can register new NotesID's with completely random passwords that they do not need to remember nor need to distribute to end users.
Notes client setup instructions can be simplified so that end users have to define the password themselfes before they can start Notes for the first time.
- Karl-Henry Martinsson - Free Software – Password Reset for Notes/Domino
- Domino 9.0 - Setting up the sample self-service application to allow ID vault users to reset their Notes passwords
- Domino 8.5 - Setting up the sample self-service application to allow ID vault users to reset their Notes passwords
- Technote 1330905 - Is the sample password reset application supported in a production environment?