2: Security - bruno-beloff/scs_analysis GitHub Wiki
docs > software repositories > scs_analysis
The South Coast Science security regime is designed to protect both historical data stored in the cloud, and the IoT devices which generate that data. The security system is imposed on the South Coast Science cloud APIs, and therefore also on the command-line utilities in the scs_analysis package.
The fundamentals of the security system are:
- Organisations have ownership of devices
- Agents are members of one or more organisation
- A device is visible to an agent when the device is owned by an organisation to which they belong
- A data topic is visible to an agent if the topic receives data from a device owned by an organisation they belong to
- An agent must be authenticated before attempting to perform any operation
Further restrictions on the visibility of topics for individual users are also available. For example, it is possible to restrict visibility to specific projects, rather than to all topics within the organisation.
The Amazon Web Services (AWS) Cognito security regime is used throughout. Agents authenticate themselves by means of an email address and a password. Both the email address and the password may be changed at any time.
The same regime is applied to both the APIs and the command-line utilities. Although the actions described below can all be performed using the APIs, it is recommended that the command-line utilities are used at least initially, because this simplifies and guides the activity.
In order for an agent to engage with the security regime, the following workflow should be used:
1. Registration
1.1 Existing users
If the user is already registered on live.southcoastscience.com then the registration stage can be skipped.
1.2 New users
For New users, registration is performed by creating a Cognito user:
cognito_user_identity.py -C
An interactive dialogue follows. Note that the chosen password must include lower and upper case, numeric and punctuation characters.
More information on the command-line utility: cognito_user_identity.
2. Confirmation
2.1 Existing users
If the user is already registered on live.southcoastscience.com then their email will already be registered on Cognito, but their password will not have been copied across. In this scenario, confirmation is performed with:
cognito_email.py -e [email protected]
An email will be sent with a temporary password. Respond to this email with:
cognito_email.py -s [email protected]
An interactive dialogue follows. Note that the chosen password must include lower and upper case, numeric and punctuation characters. Once this is done, the Cognito account is active.
2.2 New users
Newly-registered users will have received an email with a confirmation code when registration was performed in step 1.2 above. The confirmation code should be presented with:
cognito_email.py -c [email protected]
An interactive dialogue follows. Once this is completed, the Cognito account is active.
More information on the command-line utility: cognito_email.
3. Credentials management
Data acces and other dependent command-line utilities require that the email address and password are stored (in a strongly-encrypted form) on the user's computer. Credentials are stored with:
cognito_user_credentials.py -s
An interactive dialogue follows. If the user wishes to store multiple sets of credentials, this can be done with:
cognito_user_credentials.py -c ID1 -s
cognito_user_credentials.py -c ID2 -s
With this facility, it is easy for the user to administer multiple organisations. The "retrieval password" can be the same in the two cases, even though the stored password is different in each case.
The credentials can be tested with:
cognito_user_credentials.py -t
This reports whether the used is authorised by the Cognito system. Note that this only confirms that the user is valid and active, not that they have rights to access resources belonging to a specific organisation.
More information on the command-line utility: cognito_user_credentials.
4. Joining an organisation
4.1 Existing users
If the user was already registered on live.southcoastscience.com then this stage can be skipped.
4.2 New users
The user can only be enrolled into the organisation by an organisation administrator (or by a super-user at South Coast Science). This is done with, for example:
organisation_users.py -i4 -C -e [email protected] -l "The Organisation"
More information on the command-line utility: organisation_users.
5. Accessing data
Topic data can now be accessed. For example:
aws_topic_history.py -s 2024-04-30T00:00:00Z -e 2024-04-30T00:10:00Z south-coast-science-dev/cube/device/praxis-opcube-000001/status
If the user wishes to access data in a particular role, this can be done with, for example:
aws_topic_history.py -c ID1 -s 2024-04-30T00:00:00Z -e 2024-04-30T00:10:00Z south-coast-science-dev/cube/device/praxis-opcube-000001/status
In the above case, the stored credentials named ID1 are used.
Note that in both cases, a password will be requested - this is the "retrieval password" specified when using the cognito_user_credentials utility in step 3 above. If numerous operations are to be performed, it may be convenient to store the retrieval password as a shell environmental variable. This can be done as follows:
export SCS_CREDENTIALS_RETRIEVAL=MyRetrievalPassword
Note that this does compromise the security of the password. The environmental variable may be deleted with:
unset SCS_CREDENTIALS_RETRIEVAL
More information on the command-line utility: aws_topic_history.