Skip to main content

Introduction

The identity service is probably the first service you will meet - because, you know, you need a users in the system.

Purpose#

The purpose of the service is to authenticate users and for system administrators to manage:

  • Users
  • Teams
  • Roles
  • Permissions

All authenticated users have read permissions to all the data in the identity service but they must have the SYS_ADMIN role to change anything.

Overview#

The Identity service delegates almost all authentication responsibility to external providers (the only exception is for system users):

Federated Gateway

This works by Identity Service redirecting the user to a trusted identity provider (this has to be configured).
When authenticated, the user is redirected back to asset integrity hub, which then issues an access token.

Identity server integrates with two identity providers: Azure Active Directory and Azure Active Directory B2C.

Concepts#

Domain Model

Users#

A user represents an acting entity in the system. This can be one of:

  • Human user.
  • System user.

The only difference between the two types is how they authenticate: The human user will use an external login provider with a GUI to login (which can involve MFA). The system user is an external system that wants to interact with AIH. Since it's hard for external systems (like batch-jobs) to authenticate with GUI and MFA, they can authenticate with client credentials (i.e. username and password).

Teams#

Users can be grouped into teams. A user can be part of none or several teams. The sole purpose of teams, is to enable more person to own objects. This is important if more than one person share responsibility over that object. One scenario could be that data stewards (responsible for managing the asset registry) are divided into regional teams. Each team owns a set of plants, main systems etc. By assigning the plants and main systems to the teams, more than one person can own a power plant. This can be crucial if you don't want one team to be able to update information, owned by another team (this is sometimes the case).

Roles#

To be able to carry out their work, the users or teams must have assigned roles. The roles, assigned to a user or team, tell the system what the user or team is allowed to do. The system comes with only one pre-configured role: SYS_ADMIN (or System administrator). Having this role enables the user to do all the things (use this with care). Besides SYS_ADMIN, the rest of the roles must be defined by the system configurator (the system administrator).

To configure a role, the system administrator must define, what the role is allowed to do. This is done by specifying a set of permissions. After the configuration, the system administrator must assign the role to the relevant users or teams (this can be both human and system users).

Usually, when configuring the roles, it's a good idea to think about what titles your colleagues have; each role usually represents a title (Technician, Supervisor, Back-office, etc.).

To determine the total set of permissions for a team, the system calculates the union of all the permissions in all the assigned roles to the team - then calculates the unique list of permissions.

To determine the total set of permissions for a user, the system calculates the union of all the permissions in all the assigned roles to the user and a team(s) (where the user is part of) - then calculates the unique list of permissions.

Ownership#

Ownership is not, strictly speaking, part of the identity service but it's an important aspect that we need to understand before we dive into the permissions models.

Most objects in the system have a property "Object Owner" that is mandatory and which references a user or a team.
The objects that does not have this property is usually tightly linked to a "parent object" that has this property - and the authorization is thus governed by that ownership.

Ownership is used, combined with permissions, when the system determines whether a user is authorized to carry out an operation (e.g. read information on a power plant).

Permissions#

A permission is representing something the user is allowed to do, according to his/her relationship to that object. A permission is comprised of:

  • Object - The type of object in question (MainSystem, Plant, Schema, etc.).
  • Operation - The operation that the user is allowed to do.
  • Scope - The relationship to that object (All or Owned).

Let's take some examples:

(Main System, Read, All)
The user can read all Main Systems in the system

(Main System, Update, Owned)
The user can update all Main System owned by the user, or owned by a team which the user is part of.

(Main System, Create, Owned)
The user can create Main System that belongs to him/herself or a team which the user is part of.