Security Domain

The holibob API and the holibob administration system (Hub) require authentication in order to perform most operations.

All authentication relies on either the direct or indirect authentication of a security principal:

Direct authentication is only available to the API and required the passing of an HMAC signature that is created using the API Key and Secret provided to the principal by Holibob.
Indirect authentication is available on both the API and all user interfaces. Indirect authentication requires a user account that is attached to the SecurityPrincipal.

A principal can be any one of the following:

Partner - A viewer authenticated at the level of a partner will typically be able to see and may be able to manage data relating to all their PartnerChannels.
PartnerChannel - This also implies an indirect link to a Partner.
Supplier - Any supplier of product. A supplier may be permissioned to manage their own product or to view certain financial summary information pertaining to their interaction with Holibob.
Company - A member of the internal staff of Holibob including contractors.

The entity resulting from successful authentication is known as the viewer. The viewer will have a combined security context made up of properties and permission from both the security principal and the user. It is the permissions of the viewer that control the screens and menu options available in user interfaces and the operations that can be performed on the API.

It is important to also be aware that, for a given query, the data returned to one viewer may be different than that returned to another as a result of SecurityRules

Authentication to user interfaces is always achieved as a user by providing a username and password. They system also permits users, when configured to do so, to authenticate with any of their email address, phone number or ID and their given password. The passwords of users are not known to holibob. Administrators have the facility to reset a user password to a known default but upon first use the user will be required to change the password to one only known to themself. Where a user has been configured with an email address and/or phone number it is possible for the user to follow a self-serve password reset process that include the transmission of a one time code to their email or via SMS to their phone.

Authentication to the API can be either by a secure HMAC process that uses a SecurityPrincipal`s holibob-api-key and holibob-api-secret or by authenticating as a user that is attached to a SecurityPrincipal.

Database Tables

The following tables are defined in the domain:

Table Name	Purpose
SecurityPrincipal	Details a primaryKey for any entity that has been granted a security context. This table contains `type` and `foreignId`. The type can be any of "COMPANY", "PARTNER", "PARTNER_CHANNEL", "SUPPLIER"
SecurityPrincipalHmac	Details the `key` and `secret` that are commonly referred to as `holibob-api-key` and `holibob-api-secret` and used in validation of any direct call to the API when using HMA
SecurityPrincipalUser	Details the primaryKey for any user that has been created. This table includes `preferredUserName` and `email` and each of these fields must be unique in the context of the entire table. It is either one of these that a user must enter on the initial signing screen in order to begin the user authentication flow. This table also includes `authenticationMethod` that can be any one of "COGNITO", "SSO_MICROSOFT", this informs the system which to contact in order to get an authentication token.
SecurityPrincipalUserSso	Details any information relevant to authenticate the given user via single-sign-on (SSO)
SecurityPrincipalUserCognito	Details any information relevant to authenticate the given user via Cognito. This includes the `cognitoSub` the authentication will be carried out using the `SecurityUser.id` as the username passed to cognito.
SecurityPermission	A record of the permissions that may be associated in via the following tables”
SecurityPermissionPrincipalAssociation	Applies permission to a Principal.
SecurityPermissionPrincipalUserAssociation	Applies permission to a User.
SecurityRule	A record of domain rules that will be applied at runtime to determine record level permission and may be associated via the following tables:
SecurityRulePrincipalAssociation