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 - https://docs.microsoft.com/en-us/microsoftteams/platform/tabs/how-to/authentication/auth-aad-sso

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. 

App

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

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.

Testing

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.

Conclusion

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.

Comments

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 https://answers.microsoft.com/en-us/office/forum/office_2010-word/ms-word-header-styles-are-showing-black-boxes/c427b21c-dcda-46ce-a506-b9a16c9f2f3f


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 section in h…

WSL, HCL Volt and some Docker

My list of new technologies to try was growing fast in past months, but now I finally can try to catch up with all the cool improvements that can be used to enhance my/your dev experience.
Microsoft has enhanced the Windows Subsystem for Linux this year and Docker completely changed the way Docker Desktop for Windows is integrated into the operating system. The most important change for me was that I can finally run Docker Desktop and VMWare Workstation on my machine in parallel. When I was looking for some good use cases to try how it works, HCL Domino was a logical choice. HCL started to even publish official Docker images for every release and some pre-releases are only available as Docker images. I have many test Domino machines running in VMs, but I had no HCL Volt. If you don't know that HCL Volt is - it's a new low-code platform that brings HCL Form Builder experience, now know as HCL Leap, to HCL Domino, which then serves as a data store and application server. When I…

XPages ${} risk of code injection

While working on app optimization I experimented a bit more with 'Compute on page load' vs. 'Compute dynamically' behavior. There have been several discussions in past about possible combination of ${} and #{}, for example posts from Marky RodenSven Hasselbach and Paul Withers . What struck me today was risk of code injection.

In this app many elements are read from configuration documents that are loaded into beans and later used using ${} binding. This is recommended way as it is static information, so it's efficient. It works nicely until you insert expressions into your data. This way I realized that a lot of code is prone to code injection that can be contained either in configuration documents or any string that is stored and later read this way.

To simulate the issue I created simple page with one field, one button and one text:


All it does is saving entered value into applicationScope and then displaying it. Since the text uses ${} Compute on page load, I…