Embed the Reporting Hub in Your App

A scenario we're often asked about is how to embed the Reporting Hub inside an existing application. Technically, this is done by loading the Reporting Hub inside an iframe element on one of your app's pages. Below we describe several ways of embedding the Reporting Hub in your app.

The biggest challenge with embedding the Reporting Hub in an iframe is authentication. Most authentication providers, like Microsoft and Google, will block their login pages from loading in an iframe, which means that your end users won't be able to log in to the embedded Reporting Hub.

You need an Enterprise or Commercial license to embed the Reporting Hub in an iframe.

Enable Cross-Site Cookies in Your Reporting Hub

If you are embedding the Reporting Hub in your web app, regardless of authentication scheme, you need to enable cross-site cookies in your Reporting Hub.

In your Reporting Hub's appsettings.json file, add the following snippet:

"trhSecurity": {
     "allowCrossite": true
},

Use the Reporting Hub as your OpenID Connect server

The best way to embed Reporting Hub reports in your app is to use the Reporting Hub as the OpenID Connect (OIDC) server for your application. This provides the smoothest experience: users log in to your app and can view the embedded Reporting Hub without having to log in again in the iframe. You can use any of the supported authentication schemes for your Reporting Hub: Microsoft SSO, Okta, OpenId, etc.

What happens when using the Reporting Hub as your OIDC server is:

Users will go to your app (yourapp.com) and be redirected to your Reporting Hub site, which in turn will redirect to your authentication provider.
Once they've logged in successfully, they'll be redirected back to your app. Your Reporting Hub site will pass along the authorization token to your application.
When a user clicks on the page in your app with an embedded report, it will load because they're already authenticated with the Reporting Hub.

See the following documentation for instructions on using the Reporting Hub as an OpenID Connect server.

Create a Link to Open the Reporting Hub in a New Tab

Rather than embedding the Reporting Hub in an iframe within your app, create a link that opens the Reporting Hub in a new window. This avoids the problem of the login form being blocked in an iframe. For customers who don't wish to configure the Reporting Hub as an OpenID Connect server and are comfortable with it opening in a new tab, this is an effective solution.

If you can't use the Reporting Hub as the OIDC server for your app but still need to embed it in an iframe, the next best solution is to configure your app to load the Reporting Hub login in a new window, then return to your application once login is complete. This solution requires users to login once to your app, then to log in again to the Reporting Hub.

Configure your identity provider to allow loading in an iframe

If none of the solutions above will work for you, the next best solution is to configure your identity provider to load in an iframe if you can. Your identity provider must allow you to configure this setting; most identity providers do not.

Set up the Reporting Hub to be an OpenID Connect Server

Not only can the Reporting Hub use OIDC for authentication, but you may also need to use the Reporting Hub as an OIDC server that can then be used to authenticate other applications. Here are the steps to do so:

Here is a diagram that shows how the code flow works:

The Client application will make an Authorization request to OpenID Connect Server.
There are 2 possibilities:
1. If the user is already authenticated in the browser, then the server returns the authorization code.
2. If the user is not authenticated, they will have to login and then the server will send out the authorization code.
This is where the redirect URL matters
1. The OpenID Connect Server will look for a clientid and redirect_URL in appsettings.json file in the Reporting Hub. If it matches, then the Server has authorization to return the authorization code.
Once the Client application gets the authorization code and state back from the Server, the Client application asks for the token for that authorization code .
1. The token has all the information required in it to authenticate the user.
Client Application receives the Token (the token can have multiple tokens; in the example above, the Client application receives ID and Access tokens. Could also include Refresh token).

Set up the Reporting Hub application to act as the OpenID Connect Server:

Create a 2048 bit RSA key pair (wherever you feel comfortable generating this such as: GitBash, OpenSSL, etc.) and save them to a folder under the TRH web application
1. site/wwwroot/keys [ RSAKey1Pr.key RSAKey1Pub.key ]
Edit the appsettings.json file
1. On the root of web app running the Reporting Hub application, you’ll find a file named appsettings.json
2. Add the following to the JSON file:

"Auth0Settings": {
    "issuer": "ShiftAnalytics.ca", // this will be your name of choice if you are going to be validating in client
    "PrivateKeyPath": "keys\\RSAKey1Pr.key", // keep the keys on root of the TRH app    
    "PublicKeyPath": "keys\\RSAKey1Pub.key", // keep the keys on root of the TRH app
    "TokenExpiresIn": 86400,
    "clients": {
        "localhost:7180/account/code": { //this string is based on your redirect URL; where the Client Application receives the authorization code from the Reporting Hub
            "Aud": "demoSite",  // Audience, use your application name
            "Issuer": "shiftanalytics.cs",  // Who is issuing the authorization code
            "ClientId": "A4CFF2DD-119E-44CA-810E-30561D267FA4", // replace the ID between the quotations with your Client ID
            "ClientSecret": "testcodebbe53e86686224934fe09ae5402ebe6d50cb74df"  // replace the secret between the quotations with your Client Secret
        }
    }
},

Set up the Client Application

The following code needs to be stored within your Client Application (configuration file, database, this is your choice):

"openidConnect": {
     "ClientId": " A4CFF2DD-119E-44CA-810E-30561D267FA4", // matches the Client ID on the Server side
     "ClientSecret": "testcodebbe53e86686224934fe09ae5402ebe6d50cb74df", // matches the Secret on the Server side
     "authorizeurl": "https://domain_name_of TRH_app/authorize", // replace “domain_name_of TRH_app” with the domain name of the Reporting Hub application, keep the rest
     "tokenurl": "https://domain_name_of_TRH_app/authorize/token" // replace “domain_name_of TRH_app” with the domain name of the Reporting Hub application, keep the rest
},

The Client Application makes a POST request for token which follows the OpenID Connect Code flow path as described above. The POST request should include:

client_id // the ID of the Client Application and corresponds to the ID that is set up on the Reporting Hub application side (in the appsettings.json file)
client_secret // the Secret of the Client Application and corresponds to the ID that is set up on the OpenID Connect Server side
code // this the authorization code
grant_type = "credentials"

PreviousSecondary Environment (Test/Prod)NextUsage Analytics

Last updated 1 month ago