Enabling federated authentication

Contents[Hide]

1. Overview

Federated authentication enables users to log on to Dundas BI by authenticating using a third-party identity provider. For example, instead of the logon screen, users may be redirected to a Google logon screen, where they will authenticate with the relevant credentials and redirect back to Dundas BI with information about the user. Once authenticated with the identity provider, federated authentication behaves as a Single Sign On (SSO), enabling the user to access multiple services without the need for further authentication.

Setting up federated authentication Dundas BI requires two things:

  1. A Federated Authentication Manifest, which is a JSON array containing all of the properties required for the federated authentication.
  2. A Federated Authentication Bridge, which is a web application in the Dundas BI infrastructure.

Once federated authentication is set up, External User accounts may be created automatically or an administrator may create External User accounts and External Group accounts, which can be logged on only through federated authentication. See the article on adding an account for more details.

2. Federated authentication manifest

The authentication manifest defines and configures one or more Federated Authentication Providers, which are an external application you are entrusting with authenticating on behalf of Dundas BI. 

To create the manifest, open the Admin section of Dundas BI, then select Setup and Config.

Change the Category to Authentication, ensure Show Advanced Settings is selected on the toolbar, select the Federation Manifest setting and then click Edit on the toolbar.

Edit the Federation Manifest configuration
Edit the Federation Manifest configuration

The manifest is configured in the form of a JSON array containing the following properties for each authentication provider you wish to configure:

  • Id (optional). An arbitrary string used to identify the provider. May be omitted if the manifest only contains one provider. If multiple authentication providers are specified in the manifest, all of their IDs must be unique with respect to each other. Note: for compatibility reasons, the value should only contain characters which can be used in a URL without being escaped.
  • Caption (optional). Specifies the text that should be displayed on the Logon page button for this authentication provider. If not included, the caption will default to the provider ID.
  • ProtocolId. Specifies the ID of the protocol to be used by the authentication provider. Dundas BI supports the following protocols:
  • Properties. A JSON object containing protocol-specific information, such as a metadata URL, client ID, and client secret. See the protocol-specific section for details on the properties which may be specified here.
  • ClaimTypes (optional). A JSON object providing a mapping between claim types and specific kinds of information required by Dundas BI (see the Claim type mappings section below). The minimum required mapping is that one claim corresponds to AccountName. Specifying explicit claim type mappings is not required if the default mappings are already correct.
  • CustomAttributeClaimTypeMapping (optional). A JSON object providing a mapping of custom attribute IDs to claim types. When a user authenticates, the value of each specified custom attribute on their logon session will be populated with the data from the corresponding claim.
  • AccountAutoCreationMode (optional). Specifies how Dundas BI should behave when a user successfully authenticates. The value may be one of the following:
    • None. An external user account should never be automatically created. Only users with pre-existing accounts in Dundas BI should be able to log on.
    • Group (default). If the claim contains a group name corresponding to an External Group account, a virtual user account should be created for the user.
    • Open. A non-virtual user account should be created for any user that successfully authenticates. The created External User account will default to authenticate only via the used identity provider, which can be modified later.
  • AccountNamePrefix (optional). A prefix that is prepended to the account names extracted from the claims.
  • AllowMissingTenantClaim (optional). A value indicating whether the application will allow authentication when there is a tenant name or ID mapping, but no corresponding claim was returned with that information. The value may be either true or false. The default value is false.

Minimal example:

[
  {
    "ProtocolId": "SAML2",
    "Properties":
    {
        "idpMetadataLocation": "https://identityprovider.example.com/FederationMetadata.xml",
    },
  },
]

Extended example:

[
  {
    "Id": "ADFS-Saml2",
    "ProtocolId": "SAML2",
    "Caption": "Windows Active Directory Logon",
    "AccountAutoCreationMode": "Open",
    "Properties":
    {
        "idpMetadataLocation": "https://identityprovider.example.com/FederationMetadata.xml",
        "clientSecret": "skljdsf978dsf74A-cjmr7B6",
    },
    "ClaimTypes":
    {
        "AccountName": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
        "DisplayName": "displayName",
    },
    "CustomAttributeClaimTypeMapping":
    {
        "9f984590-01c6-4b3f-a892-03c10d405823": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/postalcode",
        "38e91753-09fd-4f91-87bb-b2fa8510d61b": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/country",
    },
  },
  {
    "Id": "Google",
    "ProtocolId": "GoogleOAuth2",
    "AccountAutoCreationMode": "Open",
    "AccountNamePrefix": "GoogleAccount_",
    "Properties":
    {
        "clientId": "01234567890-abcdefghijklmnopqrstuvwxyz012345.apps.googleusercontent.com",
        "clientSecret": "skljdsf978dsf74A-cjmr7B6",
    },
  },
]

Manifest example with two authentication providers
Manifest example with two authentication providers

Important
Any URLs specified in the manifest (or read from the identity provider's metadata) must use the HTTPS protocol. If the HTTP protocol is required, disable the Federation URIs Must Be HTTPS configuration setting.

2.1. Claim type mappings

The default claim type mappings in Dundas BI are as follows:

ItemClaim Type
AccountName http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier
DisplayName http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
Email http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
Culture http://schemas.xmlsoap.org/ws/2005/05/identity/claims/locality
GroupName http://schemas.microsoft.com/ws/2008/06/identity/claims/role

These default mappings may be overridden by information built-in to the authentication protocol, and further by the authentication provider using the ClaimTypes property in the federation manifest. See the corresponding protocol-specific section below for information on which claim type mappings are overridden by that protocol (if any).

When using multi-tenancy, additional claim types can optionally be specified in a provider's ClaimTypes property, in order to allow automatically-created accounts to be associated with a particular tenant:

  • TenantId - The GUID of the tenant, or an empty string if the account is not associated with a tenant.
  • TenantName - The Name of the tenant, or an empty string if the account is not associated with a tenant.

If both a tenant ID and a tenant name are included in the claims, the ID takes precedence.

Note
If a mapping for the tenant ID and/or name has been specified, a corresponding claim must be included in the response by the identity provider. This is done for security reasons to reduce the likelihood of an account incorrectly not being associated with a tenant due to misconfiguration of the identity provider's claim rules.

2.2. Authentication protocols

This section lists the federated authentication protocols supported by Dundas BI.

2.2.1. SAML 2.0

Note: This protocol requires installing an extension.

Protocol ID: SAML2

Properties:

  • idpMetadataLocation. The URL of the identity provider's metadata document.
  • spEntityId (optional). This is the service provider ID, which Dundas BI will use to identify itself to the identity provider. If the value is not specified, it will default to the Federation Bridge URL. Note: if a value is specified for this property, it must be a well-formed URI.
  • requestSigningBehavior (optional). The preferred behavior for signing requests. The values may be Always, Never, or IfIdpWantAuthnRequestsSigned (outgoing requests will be signed only if the identity provider metadata specifies that this is required). If the value is not specified, it will default to IfIdpWantAuthnRequestsSigned.
  • minIncomingSigningAlgorithm (optional). The minimal security hash algorithm (SHA) acceptable in the signature. To allow SHA1, the value should be http://www.w3.org/2000/09/xmldsig#rsa-sha1. If the value is not specified, it will default to SHA2.

Note
If the identity provider metadata specifies that authentication requests must be signed, signing will be performed using the certificate specified in the Signing Certificate configuration setting.

Note
At this time, Dundas BI does not support unsolicited IDP-initiated SAML responses; the SP-initiated flow must be used.

2.2.2. OpenID Connect

Protocol ID: OpenIdConnect

Properties:

  • metadataAddress (optional). The URL of the identity provider's metadata document.
  • authority (optional). The authority to use when making OpenID Connect calls. This is required if the metadata location is not specified.
  • clientId. The client_id parameter used in the protocol.
  • clientSecret (optional). The secret key provided by the identity provider used to redeem an authorization code for an access token. Not required in many cases.

2.2.3. Office 365 and Azure Active Directory

Protocol ID: OpenIdConnect

To configure federated authentication using Azure Active Directory, perform the following steps in the Azure Portal (https://portal.azure.com):

  1. Create a new App Registration for Dundas BI. The "home page" URL is the URL to the Dundas BI Federated Authentication Module (AuthBridge). For example: https://dbi.example.com/AuthBridge/
  2. Use the Manage > Certificates & secrets blade to create a new client secret for the App Registration. Use this as the value of the clientSecret property in the federation manifest.
  3. In the Manage > Authentication blade, enable the ID tokens option under the Implicit Grant section, and save your changes.
  4. Use the Manage > API Permissions blade to grant basic permissions to Dundas BI. The following delegated permissions will need to be granted under Microsoft Graph:
    1. User.Read (Sign in and read user profile)
    2. Directory.AccessAsUser.All (Access directory as the signed in user)
  5. Once the above permissions have been added, click the Grant admin consent button, and then Yes on the confirmation popup.
  6. Edit the Manifest of the App Registration, and change the value of the groupMembershipClaims property to "SecurityGroup".

Properties:

  • authority. Typically something like https://login.microsoftonline.com/<TENANT_GUID>.
  • clientId. The application ID from the App Registration in the Azure Portal.
  • clientSecret. The secret key which was generated in the Azure Portal.
  • mode. This must be set to AAD.
  • aadTenantId. The tenant GUID (Directory ID) for the Azure subscription associated with your Azure Active Directory instance.
  • aadResourceId (optional). The Azure Active Directory resource ID to use when redeeming an authorization code for an access token. If not specified, will default to https://graph.windows.net.

Overridden claim type mappings:

ItemClaim Type
AccountName http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
DisplayName name
Email http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name

2.2.4. Google OAuth 2.0

Protocol ID: GoogleOAuth2

The Google API Manager has to be used to enable Google+ API and register the Dundas Authentication Bridge web application. An authorized redirect URI must be specified for the Web platform in the following format:

{Dundas BI Base URL}/AuthBridge/signin-google/{providerId}

For example, if you have set up a Google provider in the federated authentication manifest, and the ID of the provider is MyGoogleProvider, the URI may be something like https://dbi.example.com/AuthBridge/signin-google/MyGoogleProvider.

Properties:

  • clientId. The client ID provided when setting up the OAuth 2.0 credentials in the Google API Manager.
  • clientSecret. The Google-assigned client secret.

Overridden claim type mapping:

ItemClaim Type
AccountName http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

2.2.5. Microsoft Personal Account

Use this protocol for personal Microsoft social accounts (e.g. @outlook.com, @hotmail.com). For corporate accounts, see the Office 365 and Azure Active Directory section above.

Protocol ID: MicrosoftAccount

The Microsoft Application Registration Portal has to be used to register the Dundas Authentication Bridge web application. An authorized redirect URI must be specified for the Web platform in the following format:

{Dundas BI Base URL}/AuthBridge/signin-microsoft/{providerId}

For example, if you've set up a Microsoft Account provider in the federated authentication manifest, and the ID of the provider is MyMicrosoftAccountProvider, the URI may be something like https://dbi.example.com/AuthBridge/signin-microsoft/MyMicrosoftAccountProvider

The Dundas BI account name for this provider is in the format MSAccount_<nameid>, where nameid corresponds to the ID of the Microsoft account. 

Properties:

  • clientID. The client ID provided when setting up the application in the Microsoft Application Registration Portal.
  • clientSecret. The Microsoft-assigned client secret.

Overriden claim type mapping:

ItemClaim Type
AccountName http://schemas.dundas.com/dbi/2016/11/claims/prefixednameid

2.2.6. Facebook

Protocol ID: Facebook

The Facebook Developer Portal has to be used to register the Dundas Authentication Bridge web application. An authorized redirect URI must be specified for the Web platform in the following format:

{Dundas BI Base URL}/AuthBridge/signin-facebook/{providerId}

For example, if you've set up a Facebook provider in the federated authentication manifest, and the ID of the provider is MyFacebookProvider, the URI may be something like https://dbi.example.com/AuthBridge/signin-facebook/MyFacebookProvider

The Dundas BI account name for this provider is in the format Facebook_<nameid>, where nameid corresponds to the ID of the Facebook account. 

Properties:

  • appId. The application ID provided when setting up the application in the Facebook Developer Portal.
  • AppSecret. The Facebook-assigned client secret.

Overridden claim type mapping:

ItemClaim Type
AccountName http://schemas.dundas.com/dbi/2016/11/claims/prefixednameid

3. Federated authentication bridge

Federated authentication is accomplished through a series of redirections, primarily handled by the Federated Authentication Bridge (FAB) web application included in the Dundas BI infrastructure. This web application is an optional module installed (via the Deployment application) as a virtual directory named AuthBridge under the primary Dundas BI web application (BIWebsite).

3.1. Installation

Open the Dundas BI Deployment application and go to the Extras tab.

Select Add Federated Authentication Module and follow the deployment steps.

Add Federated Authentication Module
Add Federated Authentication Module

3.2. Configuration

When a user wants to log on to Dundas BI using a specific authentication provider (for example, their Google credentials), you need to construct an Authentication URL that goes to the FAB. The format of the URL is as follows:

{Dundas BI Base URL}/AuthBridge/Auth/ExternalAuth?providerId={providerId}&returnUrl={return URL}

Where:

  • {Dundas BI Base URL} is the base URL of the Dundas BI web application.
  • {providerId} is the ID of the federated authentication provider. If only one federated authentication provider has been defined in the manifest, this can be omitted.

The following optional elements may be added to the query string of the Authentication URL:

  • {return URL} – A relative URL to where the user should be redirected once authorization succeeds. The URL is relative to {Dundas BI Base URL}. If not specified, the user will be redirected to the Dundas BI home screen.
  • debug – If specified with a value of true, an intermediate screen will be shown before the final redirection, containing information about the authentication operation (the claims sent from the identity provider, the property values Dundas BI was able to extract from those claims, and the result of attempting to create a Dundas BI logon session corresponding to the user).
  • deleteOtherSessions – If specified with a value of true, and the logon cannot succeed because the required seat is not available, the least-used session preventing the logon from succeeding will be terminated.
  • explicitCultureName – The culture to associate with the logon session (for example, explicitCultureName=en-CA). If not specified, the culture associated with the account or the default culture for the application will be used.
  • rememberMe – If not specified or specified with a value of true, the session cookie corresponding to the user's logon session will be created with a long-term expiry. If specified with a value of false, the session cookie may be forgotten when the user's browser is closed.

Important
In order to avoid exposing potentially-sensitive claims data, the ability to set debug to true shoud be disabled in production environments, via the Federated Authentication Debug Screen Allowed configuration setting.

3.3. Automatic log on using federated authentication

Automatic log on using federated authentication can be achieved by pointing the Custom Log On Page configuration setting to the authentication URL. The return URL placeholder will be automatically set by the application.

For example:

https://dbi.example.com/AuthBridge/Auth/ExternalAuth

3.4. Service provider metadata

3.4.1. SAML 2.0

When using the SAML 2.0 protocol, Service Provider (also known as Relying Party) metadata is available using a URL constructed as follows:

{Dundas BI Base URL}/AuthBridge/Auth/FederationMetadata/{providerId}

For example:

https://dbi.example.com/AuthBridge/Auth/FederationMetadata/MySamlProvider

If there is only one federated authentication provider specified in the manifest, the provider ID may be omitted.

3.4.2. Other protocols

If the identity provider requires a URL to identify the Dundas BI application (may be referred to as "sign-on URL", "home page URL", "relying party URL", etc.), provide the URL to the Federated Authentication Bridge.

For example:

https://dbi.example.com/AuthBridge/

4. Troubleshooting

If federated authentication does not succeed, the following tips may be useful for troubleshooting:

  • Check the Dundas BI application log. Often this will contain details corresponding to a failed federated authentication attempt.
  • Take advantage of the debug option in the query string of the authentication URL, in order to see detailed information about the authentication operation. For example: https://dbi.example.com/AuthBridge/ExternalAuth?providerId=MyProvider&debug=true.
  • Check any logs on the identity provider.
  • Check the Console and Network tabs of the browser's Developer Tools window for errors which could be related to the federated authentication operation.

5. See also

Dundas Data Visualization, Inc.
500-250 Ferrand Drive
Toronto, ON, Canada
M3C 3G8

North America: 1.800.463.1492
International: 1.416.467.5100

Dundas Support Hours:
Phone: 9am-6pm, ET, Mon-Fri
Email: 7am-6pm, ET, Mon-Fri