Skip to content

Authentication & Authorization

Jump to bottom
Geir Arne Rødde edited this page Dec 5, 2023 · 22 revisions

Authentication & Authorization

Introduction

The Omnia Timeseries API uses OAuth 2.0 and Azure AD as identity provider. The following OAuth 2.0 flows have been tested and verified towards the API:

The client can be a web app or a native app. A client secret cannot be used in a native app (public client), because client secrets cannot be reliably stored on devices. It is required for web apps and web APIs (all confidential clients), which have the ability to store the client secret securely on the server side.

The Microsoft Authentication Library (MSAL) enables developers to authenticate users and applications to Omnia Plant Platform, and obtain tokens for using the Omnia Timeseries API. An overview of Microsoft-supported MSAL client libraries is found here: https://docs.microsoft.com/en-us/azure/active-directory/develop/msal-overview

A token can also be obtained through Azure AD REST API, without using MSAL. Example for a service-to-service request: https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-client-creds-grant-flow#service-to-service-access-token-request

The access token received from Azure AD has an expiration time (e.g. 1 hour), and it is the client's responsibility to renew the token before it expires.

We support the following access control in our authorization layer:

  • Grant read and write access to specific timeseries objects (only for service-to-service).
  • Grant read access to all timeseries from a specific source across facilities, for example grant access to all timeseries originating from on-premises Historians across facilities (both for service-to-service and user impersonation).
  • Grant read access to all timeseries from a specific source on a specific facility, for example grant access to all timeseries originating from the on-premises Historian on Åsgard B (both for service-to-service and user impersonation).
  • All Equinor employees have read access to metadata from all timeseries across sources and facilities (only for user impersonation).
  • A client creating a new timeseries object automatically gets read and write access to it (only for service-to-service). A person accessing the API using user impersonation cannot create new timeseries objects.

Service-to-service using a shared secret

The overall process

  1. Send an e-mail to OmniaIndIoT@equinor.com or create a request here (link), describing your project, what you need access to and why.
  2. Customers will be registered in the platform and be assigned the appropriate roles and API permissions. To read timeseries, the API permission Timeseries.Read must be provided for omnia-iiot-timeseries-api-production API. Omnia Ind IoT will provide that.
  3. A customer can have one or many client applications that want to access the API, and each client application will be registered in Omnia Plant Platform and automatically be assigned a client id and client secret (for web apps and service-to-service). These credentials will be provided to the customer in a secure channel, and the customer must take necessary actions to secure the secret in their application. This client secret should never be stored in clear text at any time. Use a secure storage, e.g. Azure Key Vault.
  4. The customer client application must ask for an access token from Azure AD by providing the required parameters (i.e. client id, client secret, resource id and tenant id of the Omnia Timeseries API for Client Credentials Grant Flow using shared secret).
  5. The access token must be included in the Authorization header when sending requests to the Omnia Timeseries API.
  6. The authorization layer will check this access token to make sure the client is allowed to perform the requested operation.

Authenticating by user impersonation without any shared secret (For people with Equinor accounts)

  1. You need to apply for the role "Omnia Plant Timeseries Read" in AccessIT.
  2. You need to apply for the appropriate Historian (IMS) role in AccessIT, i.e. if you have read access to timeseries data in the IMS Grane system you will also have access to the same data in Omnia Timeseries API.

Example:

  • You request to read a timeseries from Grane, but you only have the Omnia Timeseries API Read role = Access Denied
  • You request to read a timeseries from Grane, but you only have the Read role for IMS Grane = Access Denied
  • You request to read a timeseries from Grane, and you have both access to IMS Grane and the Omnia Timeseries API Read Role = Access granted.
  1. In your software, you need to do user impersonation in context of an application/client, and we have created a public client for that (see below). You can also use your own client, but that client need to be granted a "user_impersonation" permission to Omnia Timeseries API, and to be connected to a defined customer (to be done by IIoT team).
  • plant-timeseries-api-public-plant-production with clientId = 67da184b-6bde-43fd-a155-30ed4ff162d2 for Omnia Timeseries API in production with resource id = 141369bd-3dca-4b55-825b-56ad4a69b1fc
  • plant-timeseries-api-public-plant-non-production with clientId = 675bd975-260f-498e-82cd-65f67b34fe7d for Omnia Timeries API in beta with resource id = 32f2a909-8a98-4eb8-b22d-1208d9350cb0

Managed Service Identity (For Equinor applications in Azure)

If you have a system in Equinor tenant in Azure that supports Managed Service Identity, this identity can be granted access to the Omnia Timeseries API.

To request this

  1. Send an e-mail to OmniaIndIoT@equinor.com or create a request here (link) to apply for timeseries access for your identity. Describe the use case, and which identity to use. This must be a Managed Service Identity. It cannot be an app registration.
  2. Omnia IIoT Team will review request and request the required roles for the identity
  3. The identity can now be used to request access tokens for accessing the API

Code examples

The MSAL documentation has code examples for multiple programming languages and scenarios. These can easily be adapted to the client application obtained through the registration process. Keep in mind though that the only supported flows are client credentials and user impersonation. A few Timeseries API specific examples follows

C#

using Microsoft.Identity.Client;

 // Use the resource id for the environment you wish to access, as described above
var resource = "<resource-id>";
// Substitute below values with values received from Omnia IIoT Team when registering your project
var clientId = "<client-id>";
var clientSecret = "<client-secret>"; // IMPORTANT: The client secret must NOT be checked into source code version control system
var tenantId = "<tenant-id>";

var scope = new string[] { $"{resource}/.default" };
var clientApp = ConfidentialClientApplicationBuilder
                    .Create(clientId)
                    .WithTenantId(tenantId)
                    .WithClientSecret(clientSecret)
                    .Build();

// To obtain an access token
var accessToken =  await clientApp.AcquireTokenForClient(scope).ExecuteAsync();

Python

For python, there is an official SDK. Using the SDK, authentication and token aquisition is handled internally. Examples are provided here

Clone this wiki locally