Multitenant authentication

Edit online

IBM® IoT Connected Vehicle Insights supports the following types of authentication mechanisms for REST API access. These authentication mechanisms can be used in all of IBM IoT Connected Vehicle Insights REST APIs, Vehicle API, Dynamic Map API, and Driver Behavior API.

  • Public Authentication. Access all tenants, which include the public tenant. This function is for compatibility with a version earlier than V3.0.

  • Basic Tenant Authentication. Access each tenant per token. Built on HTTP Basic Authentication and is able to issue multiple tokens from IBM Maximo®Asset ManagementGUI or API. Supports token invalidation, never access APIs with revoked tokens.

  • Advanced Authentication. Access each tenant per token with extra capabilities. Built on JWT-based authentication to support stateless token management and token expiration. Supports token invalidation, never access APIs with revoked tokens.

The types of authentication mechanisms

The following table shows characteristics and capabilities of each authentication mechanism.

Characteristics and Capabilities Public Authentication Basic Tenant Authentication Advanced Authentication
Based on HTTP Basic Authentication HTTP Basic Authentication JWT Authentication
Support tenant isolation No Yes Yes
Can issue multiple tokens No Yes Yes
Can support token invalidation No Yes Yes
Can access public tenant Yes No No
Can expire tokens No No Yes
Can change password Yes No No

Authentication flow for the Basic Tenant Authentication

Basic Tenant Authentication uses HTTP Basic Authentication protocol. To access IBM IoT Connected Vehicle Insightss APIs with Basic Tenant Authentication, you must add Authorization: Basic <your token ID> into HTTP request headers. You can issue Basic Tenant Authentication tokens by using Maximo Asset Management API or GUI.

Sequence diagram of issuing a token for Basic Tenant Authentication.
Sequence diagram of revoking a token for Basic Tenant Authentication.

Authentication flow for the JWT-based advanced authentication

Advanced Authentication uses JWT (JSON Web Token) authentication protocol. To access IBM IoT Connected Vehicle Insights APIs with JWT authentication, you must add Authorization: Bearer < your token ID> into HTTP request headers. You can issue JWT tokens via Maximo Asset Management API or GUI.

Maximo Asset Management supports HMAC SHA512 algorithm only. A randomized HMAC secret key is stored in Maximo. You cannot change the secret key by yourself.

Sequence diagram of issuing a token for Advanced Authentication.
Sequence diagram of revoking a token for Advanced Authentication.

Considerations of Vehicle Data Hub Custom Plug-ins

By default, tenant authentication enables VDH REST API only. If you want to enable tenant authentication in other VDH Custom Plug-in protocols, contact your IBM representatives.