How does it work#

Critical Manufacturing Security Portal is an Identity Management System that provides integrated security for client applications.

To understand how it works we need to distinguish two main interactions:

• Between Client Applications and Security Portal (Client <-> Security Portal)
• Between Security Portal and Authentication Sources (Security Portal <-> Authentication Source)

Client Application <-> Security Portal#

The interaction between a client application (example: MES User Interface) and security portal is established using OAuth 2.0 ⧉.

Currently, we support the following OAuth grant types:

• Authorization Code
• Refresh Token
• Client Credentials
• Implicit
• Password

Authorization Code#

An example of how the Authorization Code flow works for the retrieval of the MES interface can be seen below:

Client Credentials#

The Client Credentials Flow is defined in OAuth 2.0 RFC 6749, section 4.4 ⧉. It describes an application request for an access token, giving the Client Id and Client Secret in return.

This should be used on authenticated communications between applications like CLIs, daemons or backend services.

• If the communication is to be made between applications and no user is involved, than the access token used should be created through this flow.
• If a user is necessary, than a PAT should be used.

How to request a Client Credentials Access Token#

To request an access token using the client credentials flow, one should make an HTTP POST request to /SecurityPortal/api/tenant/TenantName/oauth2/token. Notice that the TenantName should be the one configured on the environment. An example of a full URL can be https://mes.prod.criticalmanufacturing.com/SecurityPortal/api/tenant/TenantName/oauth2/token.

The request to the token endpoint is made using the application/x-www-form-urlencoded content-type. Follows a simplified example of such a call:

POST /SecurityPortal/api/tenant/TenantName/oauth2/token HTTP/1.1
Host: mes.prod.criticalmanufacturing.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=MES&client_secret=haWG@daSYYaG&scope=MES%20APP1

As can be seen, the request's body contains several key-values, which are briefly described below:

• grant_type: value must be set to client_credentials.
• client_id: value must be set to the Client Id to which the request is made.
• client_secret: value must be set to the Client Secret to which the request is made.
• scope: the extra scope requested.

A use case for the scope could be when we have a MES installation along with an APP and we want a token that can access both environments. In that situation, instead of making two requests for two different access tokens, a single request should be made with both the MES and the app Client Id on the scope key-value pair. It's important to note that the system will not give access to the extra scopes if the user doesn't have it already.

The response contains a JSON with the access token. Follows an example of such a response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsInRlbmFudE5hbWUiOiJjbWYifQ.eyJzdWIiOiJNRVMiLCJ0ZW5hbnROYW1lIjoiY21mIiwic2NvcGUiOiJNRVMgQVBQMSIsInVzZXJBY2NvdW50IjoiTUVTIiwiaWF0IjoxNzAwNzUxNDcyLCJleHAiOjE3MDQzNTE0NzIsImF1ZCI6WyJNRVMiLCJBUFAxIl0sImlzcyI6IkF1dGhQb3J0YWwifQ==.QvLYMXBjOdZdLp9I17fPX1bCHFFpjLH8sQsWzF3ZbWesPHLBztO7LeEHvPsRMlhyZREhyx",
  "expires_in": 3600000,
  "token_type": "Bearer"
}

Authentication and Authorization#

This section explains how users are authenticated and authorized. This is purely for information purposes, no action is needed on the user side aside from managing the OAuth Roles as desired.

Security Portal authenticates users into the deployed environment while the user OAuth Roles, managed within MES, determine which Apps the user is authorized to access.

When Security Portal successfully authenticates a user it provides a time-sensitive Access Token which serves to identify said user into other Apps and only the Security Portal can generate and provide valid Access Tokens for the users as well as any installed Apps. All tokens are signed/verified using asymmetric encryption, i.e., a public key-private key pair is used to validate and sign all emitted tokens. Any entity that needs to validate tokens must have access to the public key to properly validate the token signature, which was in turn signed with the private key and only available to the Security Portal.

When authenticated into Security Portal your Access Token contains a scope with all the OAuth Roles assigned to you. These roles are solely managed within MES and not inside an App. For more information, see the Roles section. When an App is installed its corresponding OAuth Role is automatically generated. Afterwards, the admin user should assign this Role to any users that should have access to the newly installed App.

Also, in order to connect to the MessageBus, two specific MessageBus Access Tokens are generated by the Security Portal as well. One token serves to authenticate a user on the first connection made between the GUI and the MessageBus, while the second one is sent to the MessageBus as a message containing all the user's Data Groups. This information is then stored by the MessageBus and used for security purposes for subsequent messages.

Security Portal <-> Authentication Source#

The interaction between Security Portal and any Authentication Source will mostly depend on the Authentication Source.

Security Portal implements a plugin system, also called strategies, based on passport.js ⧉ that allows unlimited extensibility opportunities.

To better understand how strategies work please refer to the Strategies section.

Client Configuration hot reload#

Security Portal actively watches a folder (local or other) looking recursively inside all sub-folders for files ending in .config.json that are immediately inside a securityportal folder. For the files found, it loads or updates the Client configuration for a given Tenant. Only these partial configurations are supported, all other are ignored.

For a sample of a partial configuration file, please refer to Partial Configuration Hot Reload sample sub-section.

When the Security Portal finds a file that matches the aforementioned criteria with correct configurations, it creates a new Client with the file's configuration to the specified Tenant.

If a file is deleted which was previously used to load a Client's configuration, the Security Portal will remove that Client's configuration.

The Security Portal also tracks any file content changes, so if the file changes, the Client configuration is updated accordingly. If a file is renamed, the Security Portal treats this differently and assumes the file was deleted and a new one was created, and behaves as described above.

If the file to be loaded isn't a valid configuration file, being it a badly formed JSON or some other type of error, the Security Portal logs an error and changes nothing.

To better understand the Security Portal configuration file, please refer to the Security Portal Base Configuration.

The main use case for this partial load of configuration is an App installation process. During which a partial configuration file is placed on the folder being watched by the Security Portal.

To enable this functionality, the HOT_RELOAD_CONFIG environment variable should be set to true.

There are two other environment variables which affect this functionality:

• HOT_RELOAD_CONFIG_PATH which sets the path to the folder to watch for partial configuration files. It defaults to /var/opt/envmanager/installation, which is the Installation Data folder.
• HOT_RELOAD_POLLING which sets the polling interval, in milliseconds, to look for changes inside the watched folder. It defaults to 10000, 10 seconds.