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.

To set up federated authentication Dundas BI requires two things:

  1. Federated Authentication Manifest, which is a JSON array containing all of the properties required for the federated authentication.
  2. 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 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 and tick the Show Advanced Settings checkbox, then click Edit next to Federation Manifest.

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 of any desired authentication providers:

  • Federated Authentication Provider ID. If multiple authentication providers are specified in the manifest, all of their IDs must be unique with respect to each other.
  • Federated Authentication Protocol ID. Specifies which protocol will be used by the authentication provider. Dundas BI supports the following protocols:
  • Protocol Properties. Protocol-specific information required, such as a metadata URL, client ID, and client secret.
  • Claim Types Mapping. A mapping of which claim types returned correspond to specific types of information. The minimum required mapping is for the claim that corresponds to Account Name.
  • Account Auto-Creation Mode (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.
    • 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 later modified.
  • Account Name Prefix (optional). A prefix that is pre-appended to the account names extracted from the claims.

Click Edit value and paste the following example into the text field:

[
  {
    "Id": "AAD-WSFed",
    "ProtocolId": "WS-Federation",
    "Properties":
    {
        "metadataAddress": "https://login.windows.net/0ed31aeb-3f9f-48c2-950f-e9741e248894/federationmetadata/2007-06/federationmetadata.xml",
        "realm": "spn:c5557ea3-a513-4f70-96ab-05d15e70a734",
    },
    "ClaimTypes":
    {   "AccountName": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
        "DisplayName": "http://schemas.microsoft.com/identity/claims/displayname",
    },
  },
  {
    "Id": "Google",
    "ProtocolId": "GoogleOAuth2",
    "Properties":
    {
        "clientId": "01234567890-abcdefghijklmnopqrstuvwxyz012345.apps.googleusercontent.com",
        "clientSecret": "skljdsf978dsf74A-cjmr7B6",
    },
    "AccountAutoCreationMode": "Open",
    "AccountNamePrefix": "GoogleAccount_",
  },
]

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 scheme. If HTTP schemes are required, disable the authentication property Federation URIs Must Be HTTPS.

2.1. Claim Types Mapping

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

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

These default mappings may be overridden by the authentication protocol or the authentication provider.

2.2. Authentication Protocols

The following are some protocol-specific properties.

2.2.1. SAML 2.0

Protocol ID: SAML2

This protocol requires installing an extension.

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.

Properties:

  • 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.
  • idpMetadataLocation. The URL of the identity provider's metadata document.
  • 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
At this time, Dundas BI does not support unsolicited IDP-initiated SAML responses; the SP-initiated flow must be used.

2.2.2. WS-Federation

Protocol ID: WS-Federation

Properties:

  • metadataAddress. The URL of the identity provider's metadata document.
  • realm (optional). The value of the wtrealm parameter used in the protocol. If not specified, the Federation Bridge URL will be used. This value may be generated by the identity provider. If the generated value is not a valid URI, it will require the prefix spn:.
  • audienceUri (optional). An audience restriction for the protocol.

2.2.3. OpenID Connect

Protocol ID: OpenIdConnect

The Azure Portal has to be used to modify the manifest of the App Registration for Dundas BI if you want to configure Azure Active directory groups. Locate the groupMembershipClaims property and change it to SecurityGroup

Properties:

  • mode. Specifies which mode of operation should be used. This must be set to AAD when using Azure Active Directory.
  • metadataAddress (optional). The URL of the identity provider's metadata document.
  • authority. 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. The secret key provided by the identity provider used to redeem an authorization code for an access token. This is required for Azure Active Directory.
  • aadTenantId. The tenant ID (Directory ID) for Azure Active Directory. This is required if Azure Active Directory returns group IDs in the claims.
  • aadResourceId. The Azure Active Directory resource ID to use when redeeming ab authorization code for an access token. This is required if Azure Active Directory returns group IDs in the claims. If not specified, will default to https://graph.windows.net.

Overridden claim type mappings (when working with Azure Active Directory mode):

DataClaim Type
Account Name http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn
Display Name name
Email http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
clientID appID

Note
In order for Dundas BI to be able to query Azure Active Directory for the names of groups corresponding to the returned group IDs, an Azure Active Directory administrator may need to provide consent. This can be done by temporarily appending &prompt=admin_consent to the authentication URL.

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:

{AuthBridgeUri}/signin-google/{providerId}

For example, if you've 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:

DataClaim Type
Account Name http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

2.2.5. Microsoft Account

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:

{AuthBridgeUri}/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:

DataClaim Type
Account Name 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:

{AuthBridgeUri}/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:

DataClaim Type
Account Name 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.

3.1. FAB 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. FAB 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:

{FAB Base URL}/Auth/ExternalAuth?providerId={providerId}&returnUrl={return URL}

Where:

  • {FAB Base URL} is the base URL of the FAB web application.
  • {providerId} is the ID of the federated authentication provider.
  • {return URL} is the URL to where the user should be redirected once authentication succeeds. Usually this would be the Dundas BI instance.

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

  • {cookiePath}. Contains the path segment from the return URL on which the session cookie should be set.
  • debug. If specified with a value of true, an intermediate screen will be shown before the final redirection, containing information about the authentication operation.

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 and the {cookiePath} placeholder can be automatically set by the application.

For example:

https://dbi.example.com:8003/Auth/ExternalAuth?providerId=ADFS1&cookiePath={cookiePath}

3.4. Service Provider metadata

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

{AuthBridgeUri}/Auth/FederationMetadata/{providerId} 

For example:

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

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

4. 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: 7am-6pm, ET, Mon-Fri