Single sign-on (SSO)
1. Overview
Single sign-on (SSO) allows users to log in once on their workstation, and gain access to multiple systems without being prompted to log in again. This article provides guidelines and summarizes how to use SSO within the application.
There are multiple ways to accomplish single sign-on, listed below.
2. SSO with Windows logon
To enable Single Sign-On using Windows Authentication, follow the Automatic Windows Log On configuration settings example.
Once SSO is enabled, automatic logon will occur for all URLs that do not require explicit authentication. For example, navigating to http://yourinstance/ will take you directly to the home screen, whereas http://yourinstance/LogOn/ will still show the Log On screen.
3. Federated authentication
Federated authentication behaves as Single Sign On (SSO), enabling the user to access multiple services without the need for further authentication. Authentication is possible using SAML 2.0, OpenID Connect (OIDC), Azure Active Directory/Microsoft Identity, JWT, and other protocols. Automatic logon with federated authentication can be accomplished by setting the custom logon page configuration setting to the authentication URL:
https://yourinstance/AuthBridge/Auth/ExternalAuth
For more information about single sign-on using federated authentication with automatic logon, see Enabling federated authentication.
4. Custom accounts provider
In cases where local, Windows, or federated authentication are not desired and another form of authentication is being used, a custom accounts provider can be created. A custom accounts provider manages user accounts and authentication. This is done by creating a .NET extension that has a class that extends ExtensionPackageInfo and another class that implements the IAccountsProvider2 interface. This will allow for single sign-on as logging on is controlled by the extension.
For more information, see Create a custom accounts provider.
5. Anonymous logon
This can be used to provide access to some or all content without any users needing to take any action to log on. This is commonly used to facilitate implementation of a public dashboard/reporting site or kiosk. Users are automatically logged onto a specific account specified in the application configuration settings Anonymous User Name and Anonymous Password.
For more information, see How to enable anonymous log on.
6. Embedding
When embedding within another application, besides the above options such as automatic logon with federated authentication or Windows, your application can also use the API to create either of the following one-time tokens to enable users to be logged on automatically and securely:
- Create and pass a one-time logon token. When used, this will create a session for the specified user and log them on at that time.
- Or, log on through the API to create the session ahead of time and create a one-time session token that will access that session when used. This allows your server-side code to set session properties such as custom attributes, and to confirm ahead of time that the logon was successful (e.g., given any license restrictions).
For example, your server-side code can create these one-time, time-limited tokens and pass them to your client application's JavaScript or HTML.
6.1. Creating tokens
You can create logon tokens through the .NET API using GetLogonToken(LogOnParameters) or through the REST API using POST /LogOn/Token. Specify the EffectiveAccountName in the options when calling with administrator account privileges to log on a different, specified user account. For more information and a working example, see POST /LogOn/Token.
For session tokens, first log on the desired user using ILogonService in .NET or POST /LogOn using REST. Similar to logon tokens, you can specify the EffectiveAccountName when calling with administrator account privileges. In version 24.4 and higher, you can also specify CustomAttributes to apply or AccountProperties for creating or updating accounts; otherwise, use the session ID you obtain by logging on to call ISessionService methods or a REST method such as POST /Session/CustomAttributes to customize the session. Finally, create a session token using ILogonService.GetSessionToken or POST /Logon/GetSessionToken.
6.2. Using tokens
To make use of a one-time logon or session token, you can:
- Pass it as logonTokenId or sessionToken in the URL's query string parameters (e.g., https://dbi.example.com/?logonTokenId=<token>), or set the respective option when using the embed library. This will automatically log the user on.
- Use the token in your own API calls to obtain a session ID to pass in subsequent calls when performing actions on the user's behalf. To use a logon token to access the REST API, for example, call POST /LogOn specifying the LogOnToken option instead of credentials to get the session ID, then pass that in Authorization request headers (e.g., Authorization: Bearer <session ID>) to other REST API methods. To exchange a one-time session token for a session ID instead, call POST /LogOn/ExecuteSessionToken.
For a sample web application that uses server-side code to get a logon token and use it to embed Dundas or Logi Symphony's Managed Dashboards and Reports, see the viewer integration sample. The article on embedding without iframes describes how to use tokens with that embedding method.