Skip to main content

HCL Domino SSO with Microsoft Teams

 Microsoft Teams is probably one of the most used tools this year, it was already quite popular before the pandemic started to spread across the world this spring, but now most of the businesses I work with use it. After using it just like a chat/conferencing tool, many start to explore further capabilities of the platform. When working with Domino data in apps that are web-enabled, it can be quite easy - just add a web tab anywhere you want. The problem is, that you need to deal with user authentication. 

I still remember the situation 20 years ago, when many businesses were running Lotus/IBM Notes client as the primary collaboration tool and we wanted to integrate external systems into it. Notes had an embedded web browser, or we were able to pull the raw data into NSFs using DECS or LEI. Now we need the opposite, allow easy access to data stored in Domino. Luckily, since then systems moved to the web as the standard platform, and MS Teams just embrace it. It's primarily designed as a cloud tool, but it can easily access on-premises data when you have a direct connection too.

Seamless user experience

Users these days don't care where the application/data is and they usually don't have any clue about authentication that is needed to get there. If you have 1 or 2 systems, they may remember, but everyone is touching way more systems these days. IT must be able to provide a secure and seamless user experience to make users happy and also reduce the security risks. Every password prompt usually means one more password that written somewhere (on paper on the monitor or underneath the keyboard, right?).

Microsoft Teams security

Microsoft Teams runs on top of Microsoft 365 and Azure, so one may think that once you are logged into Teams, the apps can access all your data in Microsoft cloud. Luckily, it's not the case. Apps are usually running client-side, in an isolated sandbox, communicating with OAuth secured resources. Microsoft has pre-approved their apps to be able to access your data, so it just works, but if you want to access anything more, you need to dive into the security settings. Even if you want to add a SharepointOnline site as a team tab, you can't do it as a standard web tab, because that would require the users to sign in (now there is a separate Sharepoint app that wraps the authentication for you, but earlier you had to use a custom entry page teamslogon.aspx to get the access - more details).

SAML option

When I started to check the options, SAML SSO was logically the first option. HCL Domino can use SAML with Azure Active Directory since version 10, if I remember correctly. I tried the setup on V11 and it worked just fine, not like SSO setups I remember from the past where we spent hours talking to security guys and getting all the parameters right. 

If your Domino servers use SAML with AAD and your workstations are AAD joined, then the user experience is great. You don't need to sign into teams and when you try to access a Domino web app from teams, it just works. It works because both Teams and Domino are capable of SSO with your desktop, so the web browser in Teams just reuses this. There is no direct single-sign-on between Teams and Domino, so if you try this on your mobile phone (or any other device), you will be asked to sign into Azure AD the first time you try this (and every time your session with AAD expires). 

Real SSO with Teams

Last year, Microsoft started to enhance the Teams SDK with single-sign-on capabilities. This way your application can get the identity of current user, an AAD authentication token to be precise, and decide what you want to do with that. You can use this to do your own authentication or further request an access token to access Microsoft Graph. More details -

In the context of Domino applications, we can get user's principal name from AAD and then authenticate him with Domino. 

Silent authentication with Domino

There no official way to get around Domino authentication programmatically. The most official one probably would be a custom DSAPI filter, but it requires C programming and I'm not even sure if it's documented. If you want to do something easier, the following SO question contains the most relevant options

I decided to use Serdar's XSnippet as it doesn't require any additional components on the Domino server, e.g. OpenNTF Domino API. 


With all parts sorted out, I was able to create a simple Domino app that works in a similar way like teamslogon.aspx for Sharepoint.

It basically does the following steps:
  1. Detects if it's being accessed from Teams
  2. Gets the AAD token
  3. Validates the token
  4. Tries to find the user in Domino Directory
  5. Generates a LTPA token for that user
  6. Redirects to the target url
It can be used in personal, team or group chat contexts. For later two it provides a config page, where you can specify the target url and tab name (it's just a simple page that writes the setting using client side Teams SDK).


Deployment of the app itself is pretty easy, the tricky part is on Microsoft side, in AAD and Teams, but it's well documented. Because it's secure - it's linked to domains/host names where the app is running, so I can't just provide a Teams app directly, but you need to create your own. 

The Domino server hosting in the app doesn't have to be publicly accessible. If it's available within your internal network, the tabs will only work there too. It must be HTTPs enabled (at least I think).

1. Create your AAD app

Create a new app, leave the redirect URI empty.

Click Register.

Copy the application ID - you'll need it later

Open Manage / Expose an API section. Click the Set App ID link

and insert host name of the Domino server hosting the app into the ID, so convert 
to (insert your hostname, not mine) and click save

Click Add scope link and give it name access_as_user

You can leave the consent option to admin-only as we'll pre-consent the app immediately, so users won't see any consent dialog. Fill other fields based on your needs.

In the authorized client applications add
  • 1fec8e78-bce4-4aaf-ab1b-5451cc387264 (Teams mobile/desktop application)
  • 5e3ce6c0-2b1f-4285-8d4b-75ee78787346 (Teams web application)

full list:

Open API Permissions and add following permissions
  • User.Read (enabled by default)
  • email
  • offline_access
  • OpenId
  • profile

And click on Grant admin consent for <your tenant>, so we don't have to deal with consents later.
That's all in Azure AD. 

2. Deploy the app to Domino

Install it on a Domino server (I've used Domino 11, but should work on 9.0.1 and newer).

Sign it with an id that has access to the LTPA token configuration.

Open the database and open the settings. 
  • Fill in LTPA configuration name (in form that's used in ($WebSSOConfigs) view).
  • Specify the domain (including the initial . like in the LTPA setup)
  • Specify the SameSite cookie settings (if you use Teams web client, it must be set to None)
  • Insert your AAD API URI that you've configured earlier (or you can leave it blank to skip the verification) 
Save the settings.

Note - if you change the settings, you may need to restart the HTTP server as the parameters are cached in application scope in the app.

3. Create a Teams app

Open the Teams App Studio in your Teams client and create a new app

Fill in the identification details - just use something that makes sense when users see the app.

Go to Tabs section and add a Team tab configuration. Entry url in form https://<domino_hostname>/<app_path.nsf>/config.html . Check the Team and Group chat context.

If you want to create a Personal tab for some known app directly you, can add it too. For example if I want to open kb.nsf, I need to use a redirect in the teams app inf form https://<domino_hostname>/<app_path.nsf>/auth.xsp?dest=/kb.nsf
You should provide the stadnard URL in case something goes wrong witht he SSO. This will allow people open it in a stand-alone browser window.

Go to Domains an permissions sections.

If your app may need to access other servers, you need to white-list them, or you can e.g. add your full domain.
Add app id of the AAD app that you registered earlier and specify the API scope that you've defined in AAD.

Congratulations, now you are ready to Test and Distribute the app.

If you've defined a personal tab, you can just install it. For testing inside of a team, you may need to expand the menu

If all works OK, you should see the content, e.g. 

If you want to check the app in a Team, you should be greeted by a configuration dialog (currently no styling, just simple html)

Enter destination url, e.g. /kb.nsf and tab name

and all should work too. (note - if you want to edit the settings, it doesn't remember current values, so you need to enter it every time, ...)

Congratulations, now you have working Teams Domino SSO setup.


Few words of warning. I have not moved the app to my production tenant yet. If you want to experiment with any Teams or Microsoft cloud related technologies, I strongly suggest that you should create a dev tenant (which is free and gives you 25 E5 users). This is also ideal when you want to play with SAML SSO setup, which may still need AAD Premium (I'm not sure, but I think it was required when I tried it)

All works nicely on iPad and Android phones too.

Teams SSO to trigger SAML with Domino

When I was running the Domino with AAD SAML SSO, I was able to get an SAML assertion from AAD (using OBO flow)that looked valid, but I was not able to force Domino to accept it, because it didn't have any request to correlate the assertion to. If this would work, I should be able to do the SSO using SAML on non-AAD managed devices, which would be nice.


Being able to surface Domino data in Teams allows users to interact with them in the context of modern collaboration tools. I think the Domino platform will evolve in a way that it will allow better integration into modern ecosystems that primarily depend on OAuth, but that would require app modernization too. This approach will work for any web-enabled Domino app and HCL Volt apps should work just fine too, so you can start to enhance your Teams with low-code HCL Volt apps.


Popular posts from this blog

Microsoft Word black box in numbering issue

This is awkward post, primarily to save the solution for future me. I have seen many people mentioning this problem over years and as I've struggled with it several times, I needed to find final and permanent solution. All editions of Microsoft Word from time to time suffer from bug in numbering. Instead of a number, black box is displayed. Sometimes it happens right after document is opened, sometimes during editing. Probably some internal structure of document gets corrupted, so based on level of corruption, different fixes could help. Many of them are listed at I took different approach. Since docx is just standard zip package with xml files, I decided to try if I can fix it manually. And it worked. When I extracted the docx, there was file called numbering.xml in word folder. When I examined that file, I found strange se

Domino CI build with Jenkins and Docker

 I wanted to make this work for a very long time, but there were always some parts missing, so I could not get the full process running. Finally, the wait is over. The following paragraphs describe a way to build Notes/Domino apps automatically on a Jenkins server, allowing parallel builds and all "normal" continuous-integration behavior, without having to think too much about Domino specifics. The Problem Until now, I was running my automated builds of Domino apps using Jenkins in two ways: The official headless-designer way, where you need to pass special commands to Domino Designer and hope for the best as the Designer sometimes gets stuck. I have this wrapped inside a Jenkins pipeline, so I have some control and can e.g. avoid parallel builds by using locks on Jenkins, but still, sometimes it just dies. Some of my headless builds run for more than 30 minutes, so it's really hard to quickly spot an issue without actually connecting to the machi