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

XPages EL/class-loader memory leak (now with solution)

 We have recently experienced OutOfMemory crashes of XPages app server. The server was recently upgraded to 12.0.1FP1, but we were getting some panic crashes in HTTP even before the upgrade (it was 9.0.1FP10). Our hopes were that the upgrade would stabilize the server, but it's not the case. At least now I start to see what's the problem.  update 8.12.2022 There were actually 3 different leaks. I have rewritten the article to be a bit more clear. I also re-run some of the tests on 9.0.1FP10, so I assume the problems are also in earlier versions. Problem 1 The server is hosting over 1000 NSF sharing the same design + some other custom apps. Not all NSFs are used via web as the app still has classic Notes UI in parallel, so it's a bit tricky to estimate the load. By using tell http xsp show modules I usually see around 350 NSFs active. We kept the default application timeout that should provide reasonable application recycling if it's not used continuously.  We started to

HCL Domino 12.0.2, Engage 2022 and HCL Factory tour Milan

 I haven't published my recap after Engage this year and the recent HCL Factory tour in Milan is a great opportunity to write a summary about what's happening in HCL (mostly Domino) space. It's a mix of news about 12.0.2, future directions, and my impressions, so it can be a bit chaotic, but I got the impression that many people see it similarly.  Engage 2022 Engage 2022 was great (as always). I love the atmosphere in Brudges. I visited it once after Engage a few years ago and I was happy to come back. This was also the first time I had the opportunity to speak at Engage, which obviously made it a bit more stressful, but also more fun. Together with Domino Jams, HCL continued conversations with customers and partners about the future of their products at Engage. Many of these ideas were now discussed in greater detail in Milan, some of them were even demoed.  My main takeaways from Engage were: Nomad (web and mobile) are a great addition to Notes family Restyle is a great g