Bosch IoT Insights

External data source: on-behalf-of (OBO) flow

Concept

The on-behalf-of (OBO) flow is a feature of Microsoft Azure Active Directory for middle-tier services to make authenticated requests to downstream services on behalf of the user. This feature allows us to pass a user's identity and permissions through the request chain by requesting a new access token from Azure AD.

For more information, refer to the on-behalf-of documentation.

Benefits

  • You can use widgets to communicate (get, post, put, delete) with external services without the need of technical users.
    The actual user's identity is passed to the downstream services enabling you to have a fine-grained authorization.

  • Reuse your Microsoft Azure's Active Directory for authentication and authorization of REST requests sent by Bosch IoT Insights users.

  • Have the flexibility to configure claims needed for your downstream service.
    All incoming requests from Bosch IoT Insights will contain a bearer token which is generated exclusively for your application.

  • This approach is more secured as there is no need to configure any Client Id or client secrets in the widget.

Limitations

  • This feature only works for Bosch employee login and Azure Active Directory applications that belong to the Bosch tenant.
    Its possible to integrate other Microsofts Tenants, but this requires additional coordination with the Admin of this Tenant and can not be done out the box.
    The feature does also not work when logged in with other Identity Providers like SingleKey ID.

    images/confluence/download/attachments/3223097616/image-2023-7-6_15-19-32-version-1-modificationdate-1690270223000-api-v2.png
  • Applications with custom signing keys cannot be used as middle-tier APIs in the OBO flow.
    This includes enterprise applications configured for single sign-on.
    If the middle-tier API uses a custom signing key, the downstream API will not be able to validate the signature of the access token that is passed to it.

How to set up the Azure AD app on your side

To access your own API from Bosch IoT Insights with Azure AD user context, you need to set up the Azure AD app that represents your API.

Proceed as follows

  1. Create a new App Registration in the Bosch Group Active Directory.

  2. Navigate to Expose an API and define the Application ID URI.

    images/confluence/download/attachments/3223097616/image-2023-7-6_13-39-11-version-1-modificationdate-1690270224000-api-v2.png



    images/confluence/download/attachments/3223097616/image-2023-7-6_13-39-55-version-1-modificationdate-1690270224000-api-v2.png
  3. Define your application scopes, e.g., read, write.

    images/confluence/download/attachments/3223097616/image-2023-7-6_13-40-22-version-1-modificationdate-1690270224000-api-v2.png
  4. Authorize the "Bosch IoT Insights" application.

    1. In the Authorized client applications section, click the Add a client application button.

    2. Add a9812fa5-5f4f-45d1-940f-c60e80e26178 as Client ID.

    3. Assign the scopes that you want to access from a Rest Request within "Bosch IoT Insights".

      images/confluence/download/attachments/3223097616/image-2023-7-6_13-41-20-version-1-modificationdate-1690270224000-api-v2.png
  5. Once the above steps are completed, the application scopes can be used while configuring an external data source for widgets,
    like the Action Button widget, Table widget or any other widget supported by Bosch IoT Insights.

    For this, the external data source authorization type must be OAuth 2.0.

    1. In the example below, the REST endpoint https://my-server.com/api/v1/test is configured as an external data source. This is the REST endpoint of the application.

      images/confluence/download/attachments/3223097616/image-2023-7-6_15-9-53-version-1-modificationdate-1690270224000-api-v2.png
    2. The scope configured in the Azure Active Directory application is provided in the Scope field of the OAuth 2.0 configuration settings.

      images/confluence/download/attachments/3223097616/image-2023-7-6_15-10-31-version-1-modificationdate-1690270224000-api-v2.png
    3. To complete the configuration , click the Save button.
      → When the widget is rendered, the REST endpoint https://my-server.com/api/v1/test receives a get request. And the request header contains an "Authorization" key with the bearer access token representing the user's on-behalf-of token.

Refer to the "External Data Source" configuration section for Widget types on how to set up external data sources for widgets.

Troubleshooting / Known Problems

Errors

Possible reasons and solutions

Illegal char(s) in description, see RFC 6749, section 5.2

This might happen for the following reasons:

  • The provided API in the scope does not exist anymore.

  • There is a wildcard character used in the scopes, for example api://my-app/*

  • The Bosch IoT Insights App ID is not part of the authorized client applications.

  • The Bosch IoT Insights App ID is part of the authorized client applications, but does not have the necessary scopes assigned to it.

I do not see the provided apps in the audience.

Azure AD does not support scopes containing multiple application APIs. So if we have api://my-app-one/read and api://my-app-two/read, the audience contains the application Id of my-app-one. However, it is possible to have api://my-app-one/read and api://my-app-one/write in the scopes as it belongs to the same application.

AADSTS65001: The user or administrator has not consented to use the application with ID '5b68ed38-2104-4c0b-904b-19e26b976d67' named 'insights-oidc-login-test-api'. Send an interactive authorization request for this user and resource.

  • The targeted scope is not in the list of API Permissions of the requesting app.

  • The administrator has not consented to the requested API Permissions.

Run an Auth Code Flow from the requesting App with the scope of the targeted app and request consent from an admin.

AADSTS500011: The resource principal named api://5b36333e-ad1a-402b-971c-6ed2e605bb9a was not found in the tenant named 0ae51e19-07c8-4e4b-bb6d-648ee58410f4.

  • Application has not been installed by the administrator of the tenant or consented to by any user in the tenant. You might have sent your authentication request to the wrong tenant.

  • The scope in the token request for the targeted app does not exist.

You need to add a scope under "Expose an API" on the targeted app and request it as scope.