Authentication Admin

Authentication Schemes Overview

Authentication is how one determines who someone is and authorization is the process of determining what someone will be given access to. For the Reporting Hub, the authentication scheme refers to both authentication and authorization.

The Reporting Hub supports a number of authentication schemes. With the Essentials tier, the Reporting Hub comes with Active Directory. In higher subscription tiers, you can configure the authentication scheme for each tenant and choose from other options.

Authentication Licensing Considerations

The table below outlines the Reporting Hub subscription tiers and what authentication schemes are supported in each tier.

Note: Tenant-specific authentication allows you to configure the authentication scheme for each of your tenants in a multi-tenant scenario.

Authentication Schemes List

This page lists all the authentication schemes that the Reporting Hub supports. All Reporting Hub applications have a default scheme named 'Reportinghub'. This authentication is the default scheme and can't be deleted or modified.

Verified schemes are marked with a green 'Verified' flag and non-verified schemes are marked with a red 'Not Verified' flag. Once the scheme has been created and verified, the system will not allow changes to be saved. Schemes that are being used by organizations/tenants for authentication can not be deleted. Any scheme not being used can be deleted.

Using an Authentication Scheme

There are three main steps for using an authentication scheme:

Creating a New Authentication Scheme

To create a new authentication scheme, an administrator signs in and navigates to Organization Setup > Authentication Schemes. From here, the administrator will see any current authentication schemes and their status (verified or unverified). If verified, you can use this authentication scheme for your tenant(s). If unverified, it will not appear in the authentication scheme dropdown in Tenant Admin.

The general flow for creating a new authentication scheme is:

Select your profile picture to navigate to the Admin Settings menu.
Select App Settings.
Select the Auth Schemes tab.
Select New Item.
Enter a Name for your scheme and select an Authentication Scheme type from the dropdown list.
Fill out the required fields. Each auth scheme type requires different information and each type is described in detail below.
Select Save.

Reporting Hub Authentication

The default Reporting Hub authentication scheme is Microsoft Entra ID. Users and groups are managed within Entra ID. You can create new user accounts for your users and add the users to security groups to more easily manage access to reports. With this scheme, administrators can configure the login experience in Edit Themes. However, if your organization requires multi-factor authentication, you will need to configure the Microsoft SSO/MFA authentication scheme.

In order to disable MFA to use this auth scheme, you can follow these steps:

1) Go to Entra ID within the Azure Portal -> Under Manage, select Users -> Click on Per User MFA -> Disable MFA for the particular user account.

You can find more information here: https://learn.microsoft.com/en-us/entra/identity/monitoring-health/recommendation-turn-off-per-user-mfa

2) To Disable MFA for the Entra tenant, you can follow the steps on the link below: Go to Entra ID within the Azure Portal -> Under Manage, select Properties -> select Manage Security Defaults -> Set it to disabled.

Microsoft Single Sign On (SSO) / Multifactor Authentication (MFA)

MFA adds a layer of protection to the sign-in process. When accessing The Reporting Hub, users are asked for additional identity verification, such as scanning a fingerprint or entering a code received by phone. If your organization requires MFA, you will need to subscribe to The Reporting Hub business tier or higher.

Callback Path: Default value is /authentication/getcode. At the start of the application, it will test the Azure AD setting and will make correct entries for callback/return URL if needed.

Signed Out Callback Path: Default value is /authentication/rhsignout. When a user logs out, this is sent to Microsoft to complete the log out process. When that's done, Microsoft will redirect back to the Reporting Hub sign-out page.

To customize the branding of your Microsoft login experience see the Microsoft documentation below:

Add company branding to your organization's sign-in pageMicrosoftLearn

Azure Active Directory B2C

This authentication scheme is in preview mode in our Early Adopter release 3.7.8. If you would like to try this feature before its general release, please submit a support ticket.

Azure Active Directory B2C (AAD B2C) provides business-to-customer identity as a service. Your customers can use their preferred social, enterprise, or local account identities to get single sign-on access to your applications and APIs. You can learn more about AAD B2C at the link below:

What is Azure Active Directory B2C?MicrosoftLearn

To add an AAD B2C tenant as an auth scheme:

Register an app in the B2C Tenant, create a client secret and grant API permissions.
Create a user flow (if you haven't already).
Add the auth scheme to the Reporting Hub and verify.

Register an Application in the B2C Tenant and Grant Permissions

In the Azure portal, switch to the B2C tenant if you haven't already and select Azure AD B2C.
Under Register an application, select Get started.
Select New Registration.
Enter a Name for your app registration and, under Supported account types, select Accounts in any identity provider or organizational directory (for authenticating users with user flows).
Under Redirect URI, set Platform to Web and enter <YourReportingHubUrl>/authentication/getcode in the URL field.
Ensure Grant admin consent to openid and offline_access permissions is enabled.
Select Register.
From the App registration page, copy the Application (client) ID and the Directory (tenant) ID to a notepad app -- you will need these values later.
Select Add a certificate or secret.
Select New client secret. Enter a Description for your secret and select an Expires duration. Make note of the expiry date because you will have to generate a new secret and update your Reporting Hub when the client secret expires. Select Add.
Copy the client secret Value to the notepad app that you copied the Application (client) ID to -- you will need it later.
On the left menu, under Manage, select Authentication.
Under the Implicit grant and hybrid flows section, enable: Access tokens (used for implicit flows) and ID tokens (used for implicit and hybrid flows). Select Save.
On the left menu, under Manage, select API Permissions.
Select Add a permission.
Select Microsoft Graph. Select Application permissions.
Add the following permissions:
- Application.ReadWrite.All
- Group.ReadWrite.All
- GroupMember.Read.All
- User.Read.All
Select Add permissions.
Select Grant admin consent for <Your App Registration Name>.

Add an Identity Provider in Azure AD B2C (Optional)

Azure AD B2C lets you use Email sign in as an identity provider without any additional configuration. If you'd like to allow users to sign with their social accounts like Facebook or external identity providers like Google, you can add the identity provider to your Azure Active Directory B2C tenant by following the Microsoft guide linked below.

Add an identity provider - Azure AD B2CMicrosoftLearn

Create a User Flow or Custom Policy in Azure AD B2C

In the Azure portal, create a user flow of type Sign in or Sign up and sign in or create a custom policy. Your user flow/custom policy must include the following user attributes:

Display name
Email address

Your user flow/custom policy must include the following application claims:

Display name
Email addresses
Identity provider
Identity provider access token
User's object ID

If you're using a user flow, once you've created it, get the correct user flow domain:

In the Azure portal, select the User flow and then select Run user flow.
Copy the URL that appears at the top into a notepad and remove the v2.0/.well-known/openid-configuration?p= portion so that the final URL is like https://<yourTenantName>.b2clogin.com/<yourTenantName>.onmicrosoft.com/<userFlowName>

Create and Verify a B2C Authentication Scheme in the Reporting Hub

Go to your Reporting Hub site and select App Settings, then Auth Schemes.
Select New Item.
Add a Name for your auth scheme and select Microsoft SSO B2C from the Authentication Scheme dropdown.
In the Client ID field, enter the Application (client) ID from the App Registration.
In the Client Secret field, enter the Value.
In the Base URL field, enter your B2C user flow address, the one that's like https://<yourtenantname>.b2clogin.com/<yourtenantname>.onmicrosoft.com/<UserFlowName>
In the Tenant Id field, enter the Directory (tenant) ID you copied from the App Registration page.
Leave the Callback Path as /authentication/getcode.
Select Save.
Verify the auth scheme you just created.

OpenID Connect (OAuth 2.0)

OpenID Connect 1.0 is a simple identity layer on top of the OAuth 2.0 protocol. It allows clients to verify the identity of the end-user based on the authentication performed by an Authorization Server, as well as to obtain basic profile information about the end-user.

For more information, visit http://openid.net/connect.

To set OpenID Connect (or any non-Microsoft based authentication), more information is required to complete the verification of the authentication scheme.

Note: To use non-Microsoft authentication, your team needs to set up additional endpoints to provide the Reporting Hub with group and individual user information. This is used in a number of places within the application.

Client ID: OAuth 2.0 Client Identifier valid at the Authentication Provider.

Client Secret: OAuth 2.0 secret provided by the Authentication Provider.

Authentication Endpoint: Where the Reporting Hub requests the authentication code.

Token Endpoint: Where the Reporting Hub requests the token.

Token Require Basic Auth: Some of the OpenId connect token requests require Basic auth for token requests. If your token endpoint needs that info, then turn this flag on.

Authorization Code (with PKCE): If your OpenId connect is set up with PKCE (Proof Key for Code Exchange) required, then turn this flag on. When you select Authorization Code (With PKCE), two additional fields will become available for Code Challenge Method and Code Verifier. The Reporting Hub uses SHA-256 for generating Code-challenge.

Use Custom Id Field: If enabled, you will be prompted to enter the Custom Id Field.

Callback Path: The URL that the authentication provider redirects to (with the code) after successful authentication. It's an intermediate step. Once the user is redirected here, we can then take the user into the Reporting Hub. This is always set to: /authentication/getcode

Signed Out Callback Path: When a user logs out, this is sent to OpenId to complete the log out process. Then OpenId will then redirect back to the Reporting Hub sign out page. This is always set to: /authentication/rhsignout

API Key: The key we use to authenticate the Reporting Hub request.

For more information, go to: https://openid.net/specs/openid-connect-basic-1_0.html#CodeRequest

What's listed below defines additional information needed by the Reporting Hub to provide the correct authorization to create additional endpoints.

Groups Query Endpoint: to get a list of all groups that exist on the Authentication provider. This endpoint is called when the Sync Groups button is clicked on the Manage Groups page.

The request from the Reporting Hub:

Get https://GroupsQueryEndPoint
header{Authorization : Bearer Access Token}

The endpoint should return:

{  
    "groups": [
        {
            "id": "bdd920b6-048b-4942-914e-f75e301054d2",
            "GroupName": "groupname1",
            "description": "group description"
        }, 
        {
            "id": "86553db-0b0f-11df-a8c9-3dafbda932cb",
            "GroupName": "groupname2",
            "description": "group description"
        }
    ]
}

Group Claims Name: This configuration is to handle the claim name so we know which part of the token to use as the Group name. For example, this could be "GroupName" in others "RoleName".

User Info Endpoint: To get the user's profile information such as display name and group membership(s).

The request from the Reporting Hub:

Get https://UserInfoEndpoint
header{Authorization : Bearer Access Token}

The endpoint should return:

{
    "user": {
        "id": "bdd305b6-048b-4942-914e-f75e111111d2",
        "email": "emailtest@email.local",
        "fullname": "FirstName LastName"
    }
}

User Email Query Endpoint: To validate the user's email address (used when adding an individual user to a report).

The request from the Reporting Hub:

Get https://User-EmailQueryEndPoint/{EmailAddress}
header{Authorization : Bearer Access Token}

The endpoint should return:

{
    "user": {
        "id": "bdd305b6-048b-4942-914e-f75e111111d2",
        "email": "emailtest@email.local",
        "fullname": "FirstName LastName"
    }
}

OpenID Connect Password

It is not recommended that this authentication scheme be used. It will be deprecated in the near future.

In this auth scheme, the Reporting Hub application collects the user's password and sends it to their organization's OpenID Connect server for authorization. It is not recommended that this scheme be used. This authentication scheme will be deprecated in the near future.

Client ID: OAuth 2.0 Client Identifier valid at the Authentication Provider.

Client Secret: OAuth 2.0 secret provided by the Authentication Provider.

Token Endpoint: Where the Reporting Hub requests the token.

Groups Query Endpoint: to get a list of all groups that exist on the Authentication provider. This endpoint is called when the Sync Groups button is clicked on the Manage Groups page.

The request from the Reporting Hub:

Get https://GroupsQueryEndPoint
header{Authorization : Bearer Access Token}

The endpoint should return:

{  
    "groups": [
        {
            "id": "bdd920b6-048b-4942-914e-f75e301054d2",
            "GroupName": "groupname1",
            "description": "group description"
        }, 
        {
            "id": "86553db-0b0f-11df-a8c9-3dafbda932cb",
            "GroupName": "groupname2",
            "description": "group description"
        }
    ]
}

Groups Claim Name: This configuration is to handle the claim name so we know which part of the token to use as the Group name. For example, this could be "GroupName" in others "RoleName".

User Info Endpoint: To get the user's profile information such as display name and group membership(s).

The request from the Reporting Hub:

Get https://UserInfoEndpoint
header{Authorization : Bearer Access Token}

The endpoint should return:

{
    "user": {
        "id": "bdd305b6-048b-4942-914e-f75e111111d2",
        "email": "emailtest@email.local",
        "fullname": "FirstName LastName"
    }
}

User-Email Query Endpoint: To validate the user's email address (used when adding an individual user to a report).

Okta (OAuth 2.0)

Okta is a cloud-based identity and access management (IAM) platform that helps businesses manage user authentication, logins, and access privileges across devices, networks, and apps. To learn more about Okta, visit the link below.

Identity | Okta

Client ID: OAuth 2.0 Client Identifier valid at the Authentication Provider.

Client Secret: OAuth 2.0 secret provided by the Authentication Provider.

Base URL: For Okta, this is where the Reporting Hub queries to get the list of groups. Example: <your domain>.okta.com

Authentication Endpoint: Where the Reporting Hub requests to authenticate the user.

Callback Path: The URL that the authentication provider redirects to after successful authentication. It's an intermediate step. Once the user is redirected here, we can then take the user into the Reporting Hub. Default value: /authentication/getcode

Signed Out Callback Path: When a user logs out, this is sent to Okta to complete the log out process. Okta ends the user's session and redirects back to the Reporting Hub sign out page. Default value: /authentication/rhsignout

API Key: The key we use to authenticate the Reporting Hub request on the Okta service. You'll need to create a new token for the Reporting Hub application.

Auth0 (OAuth2.0)

Auth0 is a flexible identity management platform designed for developers to easily integrate secure authentication and authorization into applications. It supports a wide range of login options, including social logins, single sign-on, and multi-factor authentication. To learn more about Auth0, visit their site linked below.

Auth0: Secure access for everyone. But not just anyone.Auth0

Flow of adding Auth0:

Create Auth0 application.
Create a client grant (see below for the scope and the options to create a grant).
Create a user in your Auth0 application.
Add the authentication scheme to the Reporting Hub and verify.
Apply the new authentication scheme to the tenant.

User Identity

In Auth0, the default user identity field is user_id, which typically looks like auth0|12345abcde67890fghij1234. When reports with security roles are viewed in the Reporting Hub, this identity is passed through. As a result, dynamic RLS or DAX identity functions like USERNAME() will display the user_id. To use a different field as the user identity, enable Use Custom ID Field when configuring the authentication scheme in the Reporting Hub, and enter the desired attribute. This custom ID must be a valid user attribute from your Auth0 connection. For example, to use email as the identity field in the Reporting Hub, enable Use Custom ID Field and enter 'email'.

Create Auth0 Application

In Auth0:

Create a new application in Auth0 with type Regular Web Application.
When you create the application, navigate to the Settings tab to view the Base URL, Client ID and Client Secret you’ll need in the Reporting Hub. These can be found on the Settings tab.
Scroll down to the Application URIs section to complete the following fields: In the Allowed Callback URLs field, enter <reporting hub URL> /authentication/getcode. In the Allowed Logout URLs field, enter <reporting hub URL> /authentication/rhsignout. Replace <reporting hub URL> with the domain of your Reporting Hub application; you can choose to use the one provided by Azure or your custom DNS if you have one. See the screenshot below for examples.
Scroll down and expand Advanced Settings. Select the Grant Types tab and ensure the following Grant Types are enabled:
- Implicit
- Authorization Code
- Refresh Token
- Client Credentials

Create a Client Grant

To create a client grant, you’ll need to generate an Auth0 token. Then you use that token to call the Create client grant API.

Go to your Auth0 Management API Explorer and copy the token.
Then, open Auth0's create client grant API. At the top right, you’ll see a button to Set API Token.
Paste the token you copied in step 1 into the API Token Details modal and select Set Token.
Copy the code from the box below and paste it into the Body form on the Create client grant page. Replace the client_id value with your Auth0 application's client id and replace the audience value with the base URL from your Auth0 application (include the https and keep the /api/v2/). Please remove the comments (everything after and including the //) before running it or you will get an error.
Select Test Endpoint to run the API and create the client grant for your application.

{
    "client_id": "qleYjeauDQBWPhGy3SBBpliKTaifYJQo", // replace between the quotations with your Auth0 application’s clientid
    "audience": "https://application_domain/api/v2/",  // replace application_domain between the quotations with the baseurl from Auth0 (including https) and keep the /api/v2/ as our app is tested to work with Auth0 V2
    "scope": [
        "read:users", 
        "read:user_idp_tokens", 
        "read:roles", 
        "create:roles", 
        "read:role_members", 
        "update:clients", 
        "read:clients"
    ]
}

Create an Auth0 User

You'll need to create a user in Auth0 that you can use to verify in the Reporting Hub. When you reach the verification stage, you will be prompted to log in as an Auth0 user -- these are the credentials you use for that.

On your Auth0 site, under User Management, select Users.
Select Create User.
Fill out the form and select Create. Save the email and password you create; you'll need them to verify the authentication scheme in the next step.

Add the authentication scheme in the Reporting Hub and validate

In the Reporting Hub, select your profile picture to access your Admin Settings menu and select App Settings.
Select the Auth Schemes tab.
Select New Item.
Enter a name for your auth scheme and select Auth0 in the Authentication Scheme dropdown.
Copy the following values from your Auth0 application details page: Domain, Client Id, and Client Secret into the Base URL, Client Id, and Client Secret fields, respectively. More information on each of the fields is provided below.

Client Id: This is called Client ID on the Auth0 basic information page.

Client Secret: This is called Client Secret on the Auth0 basic information page.

Base URL: This is called Domain on the Auth0 basic information page.

Token Require Basic Auth: Some of the Auth0 connect token requests require Basic auth for token requests. If your token endpoint needs that info, then turn this flag on.

Authorization Code (with PKCE): If your Auth0 is set up with PKCE (Proof Key for Code Exchange) required, then turn this flag on. When you select Authorization Code (With PKCE), two additional fields will become available for Code Challenge Method and Code Verifier. The Reporting Hub uses SHA-256 for generating Code-challenge.

Use Custom Id Field: Enable this field to use an attribute other than user_id as the user identity. If enabled, you will be prompted to enter the Custom Id Field.

Callback Path: The URL that Auth0 redirects to after successful authentication. It's an intermediate step. Once the user is redirected here, we can then take the user into the Reporting Hub. Default value: /authentication/getcode

Signed Out Callback Path: When a user logs out, this is sent to Auth0 to complete the log out process. Auth0 ends the user's session and redirects back to the Reporting Hub sign out page. Default value: /authentication/rhsignout

Verifying Your Authentication Scheme

Once you've created a new authentication scheme, you'll see it in your list of available schemes. If not verified, you'll see a red 'Not Verified' badge in the Verified column.

To verify the scheme, you can click the red badge or edit the scheme and click on verify. You will be prompted to log in using any valid credentials for that auth scheme. If the system can process the login successfully, it will mark the scheme as verified.

If the scheme remains unverified, you'll need to edit the details of the scheme.

Applying Your Authentication Scheme

Note: In Essentials, you only have the Reporting Hub authentication scheme. In Business tier, you can change authentication schemes, but the same scheme applies to all tenants. In Enterprise tier or above, each tenant can have a different authentication scheme.

Once the scheme is verified, go to Organization Setup > Tenant Admin. You can edit an existing tenant or create a new tenant and apply the authentication scheme to the tenant.

Warning: When you change the authentication scheme, all group assignments to all reports will be removed. An administrator will need to go to Manage Groups and click on the sync groups button to retrieve all new security groups from the new authentication scheme. Then the administrator will need to Manage Navigation and add users and security groups to each report. When switching to a Non-Entra authentication, inheritance or nesting of security groups does not exist. A user has to explicitly belong to a group/role in your authentication scheme. For a user to be directed to a sub-tenant, the user has to be assigned the sub-tenant parent group/role and any other group/role to be able to access a navigation item. So at a minimum, a user requires two groups/roles: one for the parent and one for the group/role being used to segregate access within the tenant. You can still add a user directly to a report. In this case, they would still need the parent group/role assigned and then their individual user name needs to be added to a navigation item for the item to appear.

PreviousManaging Your Subscription NextLanguage Admin

Last updated 19 days ago