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:
- Detects if it's being accessed from Teams
- Gets the AAD token
- Validates the token
- Tries to find the user in Domino Directory
- Generates a LTPA token for that user
- 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).
Detailed steps - https://docs.microsoft.com/en-us/microsoftteams/platform/tabs/how-to/authentication/auth-aad-sso
1. Create your AAD app
Create a new app, leave the redirect URI empty.
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
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)
- offline_access
- OpenId
- profile
And click on Grant admin consent for <your tenant>, so we don't have to deal with consents later.
2. Deploy the app to Domino
Download the app template from https://github.com/mpradny/teams_domino_sso/releases
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)
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.
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.
Congratulations, now you are ready to Test and Distribute the app.
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)
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
Post a Comment