Cognite Data Fusion
The IOTA Cognite Driver provides seamless connectivity between IOTA Vue and Cognite Data Fusion (CDF). This driver enables browsing assets, searching time series, and retrieving real-time and historical data from your Cognite projects.
Supported Object Types
| IOTA Type | Supported? | Cognite Type |
|---|---|---|
| Tag | 🟢 | Time Series |
| Asset | 🟢 | Asset (via Data Models) |
Features
- Asset Hierarchy Browsing: Navigate the asset tree using Cognite Data Models
- Time Series Search: Search and filter time series by name and data source
- Snapshot Data: Retrieve latest datapoints for real-time monitoring
- Historical Data: Query historical time series data with aggregation support
- Data Sources: Enumerate available datasets in your Cognite project
- OAuth2 Authentication: Secure authentication via Azure AD client credentials
- Data Models Support: Automatic discovery of views implementing CogniteAsset and CogniteTimeSeries
- Location Filters: Support for Cognite location filters to scope data access
Architecture
Technical Specification
| Description | Value |
|---|---|
| Development Language | GoLang |
| Processor Architecture | 64-bit |
| Supported Operating Systems | Windows/Linux/macOS |
| Data Modes | Read |
| Request/Response Pattern | Asynchronous |
| Source Communication | Cognite REST API |
| Back-end Communication | NATs message bus |
| Message Bus Driver Type | cognite |
| Near Real-Time Data Updates | Yes |
| Multiple Projects | Yes (via connections) |
Connection Configuration
Adding a Connection
To add a Cognite Data Fusion connection:
- Navigate to the Data Sources menu
- Select the appropriate Region and Site
- Select the "Cognite" driver tab
- Click the "Add" icon to create a new connection
Connection Settings
| Setting | Required | Description |
|---|---|---|
| Name | 🟢 | Display name for the connection (prefixes search results) |
| URL | ⚫ | Full Cognite API URL (auto-constructed from Cluster if omitted) |
| Cluster | ⚫ | Cognite cluster name (e.g., az-eastus-1, westeurope-1) |
| Project | 🟢 | Cognite project name |
| Tenant | 🟢 | Azure AD tenant ID (GUID format) |
| Client ID | 🟢 | Azure AD application (client) ID |
| Client Secret | 🟢 | Azure AD application secret |
| Token URL | ⚫ | OAuth2 token endpoint (auto-constructed from Tenant if omitted) |
| Scopes | ⚫ | OAuth2 scopes (auto-constructed from URL/Cluster if omitted) |
| Timeout | ⚫ | HTTP request timeout in seconds (default: 30) |
Automatic Configuration
The driver automatically constructs missing values:
- Token URL: If not provided, constructed from Tenant as
https://login.microsoftonline.com/{Tenant}/oauth2/v2.0/token - Base URL: If URL not provided, constructed from Cluster as
https://{Cluster}.cognitedata.com - Scopes: If not provided, constructed from URL/Cluster as
https://{cluster}.cognitedata.com/.default
Configuration Example
Full URL configuration
{
"nam": "My Cognite Connection",
"host": "[https://az-eastus-1.cognitedata.com/api/v1/projects/my-project]",
"tenant": "0d2dda-95eb-43cd-9d87-fca178450",
"client_id": "5fcbd87d-fc1a-46de-abc5-z62d0",
"secret": "your-client-secret"
}OAuth2 Authentication
The driver uses OAuth2 client credentials flow for authenticating with Cognite Data Fusion via Azure AD.
Setting Up Azure AD Application
- Register an application in Azure Active Directory
- Create a client secret for the application
- Grant the application access to your Cognite project
- Configure the required API permissions for Cognite Data Fusion
Scope and Audience Matching
The OAuth2 token audience must match the Cognite API cluster you're calling:
| API Endpoint | Token Scope |
|---|---|
az-eastus-1.cognitedata.com | https://az-eastus-1.cognitedata.com/.default |
westeurope-1.cognitedata.com | https://westeurope-1.cognitedata.com/.default |
The driver handles this automatically by extracting the cluster from your URL or Cluster setting.
Token Management
The driver automatically handles:
- Token Acquisition: Fetches access token from Azure AD on first request
- Token Caching: Reuses valid tokens to reduce authentication overhead
- Token Refresh: Automatically refreshes expired tokens
- Token Injection: Adds
Authorization: Bearer <token>header to all API requests
Data Models
The Cognite driver automatically discovers data models configured in your project via Location Filters. It resolves views that implement:
- CogniteAsset: For asset hierarchy browsing
- CogniteTimeSeries: For time series queries
This allows the driver to work with custom data models while maintaining compatibility with the standard Cognite Data Model (CDM).
Dependencies
The Cognite Driver is installed alongside the main IOTA Vue service within a containerized environment such as Kubernetes, Docker, or Podman.
Security
Source Security
The driver uses OAuth2 client credentials flow with Azure AD for secure API authentication. All communication with Cognite Data Fusion uses HTTPS.
IOTA API (Back-end) Security
The Cognite Driver uses NATs message bus to communicate with the IOTA Vue Cluster. The two-way data traffic is encrypted using Transport Layer Security (TLS) on port 443. In addition, the message bus communication security model uses a public-key signature system based on Ed25519 called NKeys. With NKeys, the server can verify identities without ever storing or seeing private keys.
Troubleshooting
Common Issues
| Error | Cause | Solution |
|---|---|---|
| 401 Unauthorized | Token audience mismatch or invalid credentials | Verify cluster in URL matches scope |
| Invalid client | Wrong ClientID or ClientSecret | Check Azure AD application credentials |
| Invalid tenant | Wrong Tenant ID | Verify tenant ID is a valid GUID |
| OAuth2 scope configuration missing | Cannot determine scopes | Provide explicit URL, Cluster, or Scopes |
Debug Mode
Enable debug logging to see detailed OAuth2 flow and API requests:
DEBUG=true ./iota.cogniteThis shows:
- Token URL and scope construction
- Token request/response details
- Full API request/response with headers
- Pretty-printed JSON request/response bodies