Application Authorization

Developing your solution on top of Ability Platform requires you to create applications. Depending on the project that you're working on, the things that you need to take into account will vary significantly. However, there is at least one concern that every application needs to cover, no matter what the app is actually doing. This piece is authorization. In this article you will learn what Ability Platform has to offer in this regard.

TIP

This article is suited for development of apps that run on servers, PCs, tables, smartphones, etc. If your intention is to develop a directly connected device or an Ability Edge module, this article is not going to provide any useful information for you.

In this article, we will assume that you have a good knowledge about OAuth 2.0 protocols. You will learn what types of applications are supported, and what are the use cases for each of them.

Open Standards

The ABB Ability™ Platform makes use of the OpenID Connect (OIDC) and OAuth 2.0 standards. It's mandatory for anyone developing authentication for an Ability™ application to be familiar with these standards. Additionally, since the Ability Platform relies on the Azure Active Directory B2C for identity management needs, we recommend you have a look at the MSDN docs of this service.

Practical Example

If you want to learn in practice about the application development on top of Ability Platform, we recommend you to go through the Getting Started Tutorial. If you do not have access to the Ability Platform yet, you may always request an Ability Sandbox access.

Application Types

There are four application types that can be built on the Ability™ Platform and each manages security in a unique way. The platform accomplishes this through an Azure AD B2C instance which can be configured to work with multiple identity providers (like Azure AD) for authentication. This information is combined along with the authorization information to issue access tokens. The various schemes for managing security are described below.

The available application types:

• Single Page App
• Native
• Web
• Background

The types were listed in the way as you can find it in the Admin Portal of Ability Platform:

These names might be a bit confusing and require some explanation. As you will see for example, the "Single Page App" option in the Admin Portal is not actually the best choice when building a single page app.

For each of the application types, we recommend you have a look at the MSDN documentation (linked under "References" section of each type) to understand how to use it in practice. You will find some Ability Platform-specific details in the Authorization Parameters article.

Single Page Application

This option refers to the usage of Implicit Flow of the OAuth 2.0 specification. In the past, this was the preferred way of authorizing single page applications. However, nowadays it should not be used due to various security concerns. If your goal is to build a single page app (or any app that runs on client side), it's recommended to use the Authorization Code with PKCE

• or, in Ability terminology, a Native app.

WARNING

As the tokens are returned to the client instead of a server (unlike web application), it's possible that the tokens may be exposed to the applications and/or users that have access to the user-agent (browser). It's strongly recommended that the SPA applications do not access the Ability™ Platform APIs directly from the browser and instead have a middle tier with a web application being the proxy or orchestrating the flows.

References

JS SPA Example

MSDN B2C Implicit Flow

Native Application

This option refers to the usage of Authorization Code with PKCE Auth 2.0 flow. This is a recommended flow for the following scenarios:

• a single page app
• a native app (desktop or mobile)
• web APIs

Authorization Code with PKCE protocol was designed in a way that it does not require any secrets to be stored in the application itself. Instead, the secret is generated dynamically during the runtime. This makes it a perfect choice for any application that has the source code available for user's inspection. Since the secret cannot be stolen, the application's identity is safe.

References

The Getting Started Tutorial goes through building a single page app in Vue.js that uses the Native app identity. The app's source code can be found at Codebits.

The MSDN article describes the Authorization Code flow (and its PKCE alternative).

Web Application

This is a pattern of building a web application where most of the application logic is performed on the server side, and the access token is not visible to the client. It uses the Auth 2.0's Authorization Code flow. This is a recommended flow for the following scenarios:

• web APIs
• server-side web applications (i.e., ASP.NET, Spring Boot, Django, etc.)

TIP

OAuth 2.0 Authorization Code with PKCE (Native app) could also be used in place of the "classic" Authorization Code flow. It's up to you, which authorization type you want to use in your server-side application.

Building a web application will require access to the Client ID and Client Secret of the application created as part of the solution. It's highly recommended that the application is configured to read the Client Secret from a key vault so that it is not compromised.

References

NodeJS Web Application Example

ASP.NET Core Web Application Example

Background Application

This is a pattern where the application uses the Client Credentials Grant of OAuth 2.0. These applications are not user-facing, like a web or single page application. Instead, they are supposed to run on their own, like a daemon or a service. An example of usage of such an app could be a scheduled calculation procedure that is triggered to do some analytics on the data periodically. Such a use case needs authorization to use Ability Platform APIs without any user being logged in. Application needs to have its own Client ID and Client Secret pair to obtain an access token for itself.

In all other application types, an authenticated user can only access data belonging to their own tenancy. In contrast, background applications are by default considered tenant agnostic (i.e., they have access to all data in an instance) and can only be created by an Ability Administrator role. If an operation executed in the platform requires tenant to be specified (e.g. for object creation), then the request made by the background application shall be decorated with Application-Tenant-Id: {your-tenant-id} header.

IMPORTANT

Even though Azure Active Directory B2C does not support the client credentials flow on its own, the flow is supported via a custom authorization proxy, which is implemented following the OAuth 2.0 client credentials specifications. To obtain an access token, create a POST request to your instance's Proxy service with content type application/x-www-form-urlencoded. The message body should contain the following key-value pairs:

• grant_type : client_credentials
• client_id : {your-app-client-id}
• client_secret : {your-app-client-secret}
• scope : {your-scope} (additional information here)

References

NodeJS Background Application Example

.NET Core Background Application Example

App Identities

To create application identities in the Admin Portal, follow the instructions in the Admin Portal User Guide