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:

  1. Create a new authentication scheme.

  2. Verify the authentication scheme.

  3. Apply the 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:

  1. Select your profile picture to navigate to the Admin Settings menu.

  2. Select App Settings.

  3. Select the Auth Schemes tab.

  4. Select New Item.

  5. Enter a Name for your scheme and select an Authentication Scheme type from the dropdown list.

  6. Fill out the required fields. Each auth scheme type requires different information and each type is described in detail below.

  7. Select Save.

Reporting Hub Authentication

The default Reporting Hub authentication scheme is Azure Active Directory. Users and groups are managed with AAD. 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.

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:

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-AAD based authentication), more information is required to complete the verification of the authentication scheme.

NOTE: To use non-AAD 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)

The Reporting Hub also supports Okta authentication.

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)

Flow of adding Auth0:

  1. Create Auth0 application.

  2. Create a client grant (see below for the scope and the options to create a grant).

  3. Add the authentication scheme to the Reporting Hub and validate.

  4. Apply the new authentication scheme to the tenant.

Create Auth0 Application

In Auth0:

  1. Create a new application in Auth0 with type Regular Web Application.

  2. When you create the application, it’ll provide you with the Base URL, Client ID and Client Secret you’ll need in the Reporting Hub.

  3. The Base URL is the domain of the Reporting Hub application. You can choose to use your new custom DNS or the one provided by Azure.

  4. See the screenshot below for examples of Callback and logout URLs. These will need to be configured to match your URLs.

  5. Ensure the following Grant Types are enabled in the Advanced Settings of Auth0:

    • Implicit

    • Authorization Code

    • Refresh Token

    • Client Credentials

Create a Client Grant

To create a client grant, you’ll need to generate an Auth0 token. To do so, go to: https://auth0.com/docs/api/management/v2#!/Client_Grants/post_client_grants

At the top right, you’ll see a button to “SET API TOKEN”.

Click on this to generate an API token that you’ll need to copy/paste back on the previous page and paste into the “SET MANAGEMENT API TOKEN” modal.

This is the code that goes into the body of the Create client grant page. Please remove the comments (everything after and including the //) before running it or you will get an error.

{
    "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"
    ]
}

Add the authentication scheme in the Reporting Hub and validate

In the Reporting Hub, add a new Authentication Scheme with type Auth0. Copy the following values from the Auth0 application: Base URL, Client Id, Client Secret.

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: 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. The system will process the actual login check as per the setup of the 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 and you can open 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-AAD 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 SubscriptionNextLanguage Admin

Last updated