Reporting & Analytics - Last Updated: July 19, 2023
The Open Data Protocol (OData) is a standardized protocol for consuming data APIs. It builds on core protocols like HTTP and commonly accepted methodologies like REST, resulting in a uniform way to expose full-featured data APIs. OData provides both a standard for representing data and a metadata method for describing the structure of data and the operations available in your API. This document focuses on Onit OData version 4.0.
OData applies web technologies such as HTTP and JavaScript Object Notation (JSON) to provide access to information from various programs. OData provides the following benefits:
- It lets developers interact with data by using RESTful web services.
- It provides a simple and uniform way to share data in a discoverable manner.
- It enables broad integration across products.
- It enables integration by using the HTTP protocol stack.
The Onit OData API is a Web Service API feature based on the OData protocol version 4. It's intended to enable access to reporting data from the data warehouse.
Overview of OData Service
The below diagram provides a high-level overview of the Onits OData Service architecture.
Onit's OData provides the following benefits:
- It lets authorized users interact with the data warehouse by using RESTful web services.
- It provides a simple and uniform way to share data in a discoverable manner.
- It enables broad integration across products (Tableau, PowerBI, Microsoft Excel, etc.) in the customer's environment.
- It enables integration by using the HTTP protocol stack.
OData Service Deployment
- Only HTTPS requests are allowed to the OData service.
- All the HTTPS requests to the application load balancer are routed from Cloudflare DNS.
- All data for the warehouse is stored in a secured RDS (Postgres) service.
- All data in the RDS service is encrypted using Amazon Key Management Service (KMS).
- OData Service is deployed as part of the auto-scaling group in the private subnet.
- Each node is further secured with CrowdStrike Falcon and Elastic SIEM.
- All the requests to the OData Service are routed via the application load balancer.
- All data is encrypted in transit.
- All data is encrypted at rest.
- The connection to DaaS endpoint uses a valid, trusted server certificate
- Algorithm: SHA-256 with RSA Encryption
- Key Size: 2,048 bits Data as a Service 5 Architecture Guide
- TLS version: 1.3
- The connection to the DaaS endpoint is encrypted and authenticated using TLS 1.3, X25519, and AWS_128_GCM
- OData Service layer does not store any data locally.
- OData service uses DataDog as a cloud monitoring service.
- All the logs are stored in secured Amazon CloudWatch Logs.
- Administrators can secure access to Onit Data As a Service by implementing IP address whitelists.
- Supports external authentication mechanisms so that enterprises can verify users against their in-house authentication systems SAML or OpenID Connect (OIDC) or any other authentication service.
Pre-Requisites
- Onit data warehouse needs to be in place, including all the default applications and fields from App builder and Billing Points systems.
- Any additional applications or fields required in the Onit data warehouse must be marked reportable within the App Builder application.
Before You Begin
Before you start accessing the OData endpoints, we recommend changing the password for the user/useradmin. Please follow the below steps to change the password.
Steps to Change the Password
1. To change the password, use your web browser to open the below OData endpoint. https://odata.onit.com/hdpui/login.jsp
2. Enter the username and password for your OData user/useradmin, shared by Onit through the OData Welcome Provision mail.
3. Click on the authenticate button, and a change password screen will appear to set the new password.
4. Enter the Current Password and new password, confirm the new password, and click Save to change the password.
Create a New User for a Tenant
This section describes how to add a new user for a tenant. For this, we will use the useradmin credentials, as the useradmin will be responsible for adding new users.
1. Login to the below OData endpoint using the useradmin credentials. https://odata.onit.com/hdpui/login.jsp
If the useradmin is logging in for the first time, the useradmin needs to reset the password. Refer to the Steps section of the document to change the password.
Once logged in, the Manage User page of the OData endpoint will open. This page contains a list of this tenant's available users.
2. Click on the + New User button. This will open the Create User page.
3. In Create User page, there are two sections to fill:
- General
- Authentication Setup
On the General tab, enter your username in the User Name field and select the appropriate role from the Role dropdown. There are three roles available in the Role dropdown.
- User Role: Users with this role can access the data from the OData endpoint.
- UserAdmin Role: Users with this role can create a user for a tenant.
- Tenant Administration Role: Users with this role can manage the tenant. Currently, Onit manages this role.
Here, we will be creating a new user named onituser for awsustau tenant, and the role for this user will be User Role.
In the Authentication Setup tab, enter the new user's password and click the Save button, as shown in the screenshot below. After clicking the Save button, the user will be redirected to the Manage User page.
4. The useradmin should now be able to see the newly created user added in the Manage User page. The useradmin needs to share the credentials with the new user.
5. The new user needs to log in to the OData endpoint and change the password. The guide to changing the password for a user is provided in the document's Steps to Change the Password section.
6. Once the password is changed, the user can connect to the OData endpoints using any of the methods mentioned in the later sections of the document.
Note: Once the password has been set, useradmin will not have the permissions to reset the password.
IP Whitelisting
Onit administrators can secure access to Onit Data as a Service endpoint by implementing IP address whitelists for individual IP or IP ranges at the tenant or user level. When an IP whitelist is enabled for the endpoint, any user attempting to reach the resource from an invalid IP address will be denied access, and a 403 access-denied error will be returned.
Contact your account manager or Onit support to enable IP Whitelisting.
Authentication
Onit Data as a Service supports internal and external authentication. When the default internal authentication system is used, end-user credentials are checked against a hash of the password stored in the Data as a Service account database. When external authentication is used, end-user credentials are checked against an external authentication service. External authentication services may be supported through a SAML or OIDC servers.
The following topics provide details and procedures for implementing authentication services.
Integrating a SAML authentication service
SAML authentication services can be integrated with Onit Data as a Service. The following general steps apply to integrating a SAML service.
- The SAML service must be registered as an external authentication service.
- Onit Data as a Service user accounts must be configured to use the SAML service.
- The identity provider (IdP) for SAML must be configured to use Onit Data as a Service.
Important: To log in using SAML, enter the URL of your Onit Data as a Service instance followed by SSO and the authentication service name.
For example, https://odata.onit.com/hdpui/sso/authservice.
IdP requirements: To configure SAML, an Assertion Consumer Service (ACS) URL is required. The ACS URL is an endpoint on the Onit Data as a Service server. The identity provider redirects authentication responses to the ACS URL. When setting up your account with the identify provider, you must specify a unique relying party entity ID. A relying party entity ID is a URL that identifies Onit Data as a Service.
Before a user account can be configured to use SAML, a SAML service must be registered with Onit Data as a Service.
As described in the following sections, you can register a SAML plugin authentication service through the Web UI.
Registering a SAML Authentication Aervice
Take the following steps to register a SAML service via the Web UI.
- Navigate to the Manage Authentication view by clicking the Manage Authentication icon.
- Select the tenant for which you are registering the service from the Select Tenant dropdown.
3. Click + New Service. You will be directed to the Create Authentication Service screen.
4. Provide the following information.
a. The name and description of the service
b. The service type
c. Asserting Party SSO URL (The URL used to access the SAML server of the identity provider)
d. Asserting Party Entity ID (The entity ID of the identity provider)
e. Asserting Party Certificate Location (The certificate location of the identity provider required to authenticate against the SAML server. For example, /common/test/example/samlcerts/onelogin.pem)
f. Relying Party Entity Id (Optional. A valid string or URL identifying the entity ID of the Onit Data as a Service server)
g. Assertion Consumer Service Path (Optional. The URL to which the identity provider redirects after authentication)
h. Onit Data as a Service Username Identifier (Optional. A valid SAML attribute containing the authenticated user name)
5. Click Save.
Configuring User Accounts for SAML Authentication
Once a SAML service has been registered, user accounts can be configured to use the service. As described in the following sections, user accounts can be configured through the Web UI.
To create a new user account, take the following steps.
1. Navigate to the Manage Users view by clicking the Manage Users icon.
2. Click + New User.
3. Under the General tab, provide tenant, user name, and user role information.
4. Click the Authentication Setup tab.
Option 1. If you add the SAML service as an additional authentication type for the user account, click + Add Authentication Service.
Option 2. If you want to use only the SAML service, modify the properties of the current authentication type.
5. Select the SAML service from the Authentication Type dropdown.
6. In the External Usernames field, specify the user or users you want to associate with the Onit Data as a Service user account. Any user name provided should correspond to a user name persisted by the authentication service.
7. Click Save.
To modify a current user account, take the following steps:
1. Navigate to the Manage Users view by clicking the Manage Users icon.
2. From the list of user accounts, click the user account you want to modify.
3. Click the Authentication Setup tab.
Option 1. If you add the SAML service as an additional authentication type for the user account, click + Add Authentication Service.
Option 2. If you want to use only the SAML service, modify the properties of the current authentication type.
6. Select the SAML service from the Authentication Type dropdown.
7. In the External Usernames field, specify the user or users you want to associate with the Onit Data as a Service user account. The user name provided should correspond to one persisted by the authentication service.
8. Click Update to save your changes to the user account.
To log in using SAML, you can just enter the URL of Onit Data as a Service instance followed by SSO and the authentication service name you created.
For example, https://odata.onit.com/hdpui/sso/authservice.
Note: If you are not logged into your identity provider, the URL will take you to your identity provider's login page.
Integrating an OpenID Connect (OIDC) Authentication Service
OIDC authentication services can be integrated with Onit Data as a Service. The following general steps apply to integrating an OIDC service.
The OIDC service must be registered as an external authentication service.
- Onit Data as a Service user accounts must be configured to use the OIDC service.
- The identity provider (IdP) for OIDC must be configured to access Onit Data as a Service.
- For all configurations, you must define the scope as api.access.odata for accessing the Onit Data as a Service OData endpoint. Refer to the IdP's documentation for other configuration details
NOTES:
- The OIDC authentication method is only supported for OData connectivity.
- The Onit Data as a Service server supports JSON Web Token (JWT) and Introspect methods for token validation.
- Microsoft Azure only supports the JWT method for token validation
Registering an OpenID Connect (OIDC) Authentication Service
Before a user account can be configured to use OIDC, an OIDC service must be registered with Onit Data as a Service. As described in the following sections, you can register an OIDC authentication service through the Web UI.
Take the following steps to register an OIDC service via the Web UI:
1. Navigate to the Manage Authentication view by clicking the Manage Authentication icon.
2. Select the tenant for which you are registering the service from the Select Tenant dropdown.
3. Click + New Service. You will be directed to the Create Authentication Service screen.
4. Provide the following information.
- The name and description of the service
- The service type (OIDC)
- Issuer URL (The URL of the OpenID provider used to access and validate the token)
- HDP Username Identifier (Optional. The specific key in the token which contains the authenticated user name)
- Token Validation method (Specifies the method used to validate a token. The valid values are JSON Web Token (JWT) and Introspect)
- Claims to validate (Optional. A JSON object which contains the claims to be validated against the token)
5. Click Save.
Configuring User Accounts for OpenID Connect (OIDC) Authentication
Once an OIDC service has been registered, user accounts can be configured to use the service. As described in the following sections, user accounts can be configured through the Web UI.
To create a new user account, take the following steps:
1. Navigate to the Manage Users view by clicking the Manage Users icon.
2. Click + New User.
3. Under the General tab, provide tenant, user name, and user role information.
4. Click the Authentication Setup tab.
Option 1. To add the OIDC service as an additional authentication type for the user account, click + Add Authentication Service.
Option 2. If you want to use only the OIDC service, modify the properties of the current authentication type.
5. Select the OIDC service from the Authentication Type dropdown.
6. In the External Usernames field, specify the user or users you want to associate with the Onit Data as a Service user account. Any user name provided should correspond to a user name persisted by the authentication service.
7. Click Save.
To modify a current user account, take the following steps:
1. Navigate to the Manage Users view by clicking the Manage Users icon.
2. From the list of user accounts, click the user account you want to modify.
3. Click the Authentication Setup tab.
Option 1. To add the OIDC service as an additional authentication type for the user account, click + Add Authentication Service.
Option 2. If you want to use only the OIDC service, modify the properties of the current authentication type.
4. Select the OIDC service from the Authentication Type dropdown.
5. In the External Usernames field, specify the user or users you want to associate with the Onit Data as a Service user account. The user name provided should correspond to one persisted by the authentication service.
6. Click Update to save your changes to the user account.