Web Services Access Control

You can add access control to your web service by turning on Authentication in your project settings and configuring "Roles" there. This allows you to prevent unauthorized access to your web service and control your web client’s access to the methods and resources of your web service. Roles are optional, but using roles gives you more granular access control.

Authentication

Authentication is switched on by setting the Require Authentication option to ‘Yes’ in the project settings of your web service project.

 
When Require Authentication is on, the web service client must provide its authentication details via the HTTP-authorization header to identify itself and gain access to the web service.

The system supports two authentication methods:

• Basic authentication
• Token-based authentication

Basic Authentication

Basic authentication requires an active, local-user account to pass a base64-encoded string in the format '<username>:<password>' as the authorization string in the HTTP-authorization header. Therefore, you must create a user account in Access Management for the web client on the LogicNets server that is running your web service. Typically, this user account type should be set to the type "server". For “server”-type user accounts, the system will automatically generate a unique client id (username) and one-time client secret (password) that can be copied for the web service client to use.

 

Token-Based Authentication

Token-based authentication requires that a base64-encoded, signed JSON Web Token (https://jwt.io/) is passed as the bearer string in the HTTP-authorization header.

LogicNets verifies the signature of the token. The system also verifies that the token issuer is defined in the system configuration as an identity provider (a concept referred to as whitelisting) or listed as public key in a server-user account. In this case, the sub-claim in the JSON Web Token must be the same as the client id of the server user account. When both of these checks pass, LogicNets uses the information from the token to authenticate and authorize the web client.

For token-based authentication to work the following must be true:

• The token must be signed with a RSA256 public/private key pair. The header of the token must contain the id of the key pair.
• The provider of the token must support the standard OAuth2 API, so LogicNets can use this interface to retrieve the public key for the verification of the signature of the token. The configuration of the token provider must be added to the system. OR
• The sub-claim in the JWT token must correspond with the client id of a server-user. The server user must configure a RSA key pair for authentication AND the public key must be registered with a server user-account (see also https://www.ibm.com/blogs/security-identity-access/oauth-client-authentication-using-jwt/).

 
The corresponding private key must exist on the client instance and be used to sign the JWT token. 

Upon receiving a JWT token, the system takes the issuer URL from the “iis” field in the payload of the token and looks up the corresponding configuration of the token provider. The next figure shows an example of the payload of the token and the token provider configuration on the LogicNets server:

 

 

Note: Some identity providers have multiple issuers, depending on the logged-in user. In these cases, wild cards can be used (e.g. {tenantid}) to map multiple issuer URLs to the same configuration.

Once the matching token provider configuration has been looked up, the system uses the "open-id configuration URI" to obtain the public key to verify the token signature. A token provider can issue multiple keys, and the system will use the "kid" field in the token header to retrieve the correct key.

Basic Authentication vs Token-Based Authentication

Although the basic authentication method is technically simpler and easier to set up, the token-based authentication method is safer and provides the following advantages:

• The lifetime of a JWT token is limited, so a stolen token cannot be re-used indefinitely.
• Since all the necessary user information is included in the token, there is no need to store user information locally on the LogicNets server.

User Profile

Once the system authenticates the web client, it generates a user profile data object based on the authentication information. You can use the information from the user profile to control the web client’s access to the functionality of your web-service.

• For basic authentication, the user profile is generated from the information loaded from the local user database.
• For token-based authentication the user profile is generated from the information from the token. By default, the following mapping takes place:

User Profile	Token
user_email	email or preferred_username or upn or unique_name
user_id	preferred_username or upn or unique_name or email
user_name	name or email or upn or unique_name
company	company

It is possible to override this mapping in the configuration of the token provider and use the $() notation to dynamically resolve the fields using information from the token.

   

Group and Roles

For token-based authorization, groups are added to the user profile based on matching the group names in the token to the names of the locally configured user groups on the LogicNets server. The next example illustrates this. The token specifies the groups "basic_users" and "admin_users". And since those groups are also configured on the server, they will be added to the user profile. Consequently, "reader" and "writer" roles are added to the user profile.

 

Alternatively, you can use group assignments in the configuration of your token provider to assign groups. Group assignments give you the flexibility to map different group names to the groups defined on your LogicNets server, but also the ability to use other user information from the token to do the group assignments. The example below shows that, by default, each web client will be assigned the group "logicnets.company.user". However, if the user's email ends with "logicnets.com", it will also be assigned the group "logicnets.company.admins".

 

Though it is possible to assign roles to individual user accounts, LogicNets recommends that you only assign roles to user groups and let each individual user account implicitly inherit roles from the user groups. This improves user management but also allows the uniform handling of access control to your web services for web clients authenticated through basic authentication or token-based authentication.

Role-Based Authorization

Having implemented the configurations above, you have secured the web service so it is only accessible by web clients with an active local user account on the server or web clients passing in valid JWTs. You can further enhance the access control to your web service by adding roles to it in the project settings. Once you have added roles to your web service, only web clients have access your web service when they have at least one of the defined roles.

 

Within the logicnets of your web service you can now use the information from the user profile to model conditions to control the access.

 

System Administrator Notes

For authentication and authorization to work, user accounts and/or user groups for the web-service clients must be configured on the LogicNets server. This can be performed in the Access Management module.

For token-based authentication, the token-provider configuration must be added to the "_session.OAUTH.MODES" section of the company- or installation- configuration file of the LogicNets server. Please use the following template for the token provider configuration:

<token provider alias> = {
           issuers = {
                     -- Add your list of issuer URLs here
                     "<issuer URL>"
          },
         client_id = "<username for the logicnets server for accessing the token provider>",
         client_secret = "<pw for the logicnets server for accessing the token provider>",
         openid_configuration_uri = "",
         group_assignments = { -- optional
                          {
                               action = "include", -- include to include this group, exclude to exclude this group
                               group_guid = "", -- the guid of the group as configured on your logicnets server
                               group_name = "", -- the name of the group as configured on your logicnets server
                               rule = "" -- Optional define your rule here for this group to be assigned
                        },
         },
 }