Managing users

You use the GeoSpock CLI to manage GeoSpock database user accounts. This command line tool enables you to invite new database users to create an account. For instructions on how to set up and use this command line interface, see The GeoSpock CLI.

Using the GeoSpock CLI to manage the GeoSpock database users, you can:

To manage accounts, you need a GeoSpock database account with an ADMINISTRATOR role.

Be aware that the first Geospock database account, created automatically during the deployment of the database, will be unable to access the SQL cluster

Using custom identity providers

If your deployment is using either AWS Cognito or LDAP to manage the user accounts that can access the Geospock database, you should only create accounts for those users that require access to the GeoSpock CLI. Access to the GeoSpock CLI enables a user to manage access to the database and its datasets, as well controlling which users can access that data. For more information about using custom identity providers, see User authentication and authorization in the GeoSpock database.

Roles

You can assign one of the following roles to a GeoSpock database account:

  • ADMINISTRATOR: this role has full access to the GeoSpock CLI, including the ability to:
    • create, update and delete user accounts
    • ingest, update and delete datasets
    • grant and remove a user's access to datasets
  • USER: this role has access limited access to the GeoSpock CLI, including the ability to:
    • list all Geospock database user accounts (account-list)
    • get the status of a dataset (dataset-status)
    • get the history of a dataset (dataset-operations)
    • list the datasets (dataset-list)
    • create a data source description for your dataset (data-source-description)
    • list the groups and associated user (group-list)

Inviting GeoSpock database users

If your deployment uses:

  • custom identity provision (AWS Cognito or LDAP), users can get access to the GeoSpock CLI by using the get-credentials command; refer to The GeoSpock CLI for instructions on how to use this command. This gives them USER access to the CLI. If they require ADMINISTRATOR access, another GeoSpock CLI user with ADMINISTRATOR access can use the account-update-role to change their access level
  • built-in identity provision (Auth0), you need to create a Geospock database account for each user, using the account-invite command, as this controls access to both the GeoSpock CLI and the SQL cluster (Presto CLI). You create a GeoSpock database user account by using the CLI to send an invitation email, that contains the instructions for setting up the account. This invitation remains valid for a short period of time (a day), after which the link in the email no longer works. If the user still requires a Geospock database user account, you can resend the invitation; see Resending an invitation email.

See User authentication and authorization in the GeoSpock database for more details about each of the identity provision models.

Use the account-invite command in the GeoSpock CLI to create an new account (built-in identity provision only) and send an invitation email to that user:

geospock account-invite --email <email address of new user> --full-name <value> --role <ROLE> 

Say, for example, that you want to create a new account with User role permissions for new.user@example.com, you would use the following command:

$ geospock account-invite --email new.user@example.com --full-name "New User" --role USER 
{
    "newAccount": {
        "id": "usr-auth0|5e2ad9b79809280cb25b1eb5",
        "email": "new.user@example.com",
        "fullName": "New User",
        "role": "USER"
    }
}

For more information about this command, use the GeoSpock CLI's help command.

You should avoid creating accounts such as geospock_presto and geospock_geospatial_table_reader, as these usernames are used internally by the Geospock database. Whilst these user accounts will still be able to ingest data and run queries, you will be unable to track the actual queries submitted by these users in the logs because the activity of the services with these usernames is also recorded.

Resending an invitation email

You create a GeoSpock database user account by using the CLI to send an invitation email, that contains the instructions for setting up the account. This invitation remains valid for a short period of time (a day), after which the link in the email no longer works. If the user still requires a Geospock database user account, you can resend the invitation using the following command:

geospock account-resend-invite --account-id <user ID> --email <email address of new user>

For more information about this command, use the GeoSpock CLI's help command.

Listing all user accounts

To list all the GeoSpock database user accounts, use the account-list command. Use this command to find the id of a user account, so that you can update its role or delete it.

$ geospock account-list --page-index <value> --page-size <value> 

You can specify the page index (starting with page 0) and/or the number of accounts per page. By default, the CLI returns page 0 with 100 accounts listed per page. For example:

$ geospock account-list --page-size 2 
{
    "listInfo": {
        "totalItemCount": 92,
        "pageCount": 1
    },
    "accounts": [
        {
            "id": "usr-auth0|5d7aefeaa1b3c90e19815d61",
            "fullName": "A Username",
            "email": "a.username@example.com",
            "role": "USER"
        },
...
    ]
}

For more information about this command, use the GeoSpock CLI's help command.

Note that if you are using a custom identity provider, this command only lists those accounts which have a Geospock database account, so that they can access the GeoSpock CLI.

Updating a user account's role

To change the role of the specified user account, use the account-update-role command. You can use the account-list command to search for the relevant user.

$ geospock account-update-role --account-email <email_address> --role <new role> 

For example, to change the role for the account belonging to another.user@example.com, your command would look like this:

$ geospock account-update-role --email "another.user@example.com" --role ADMINISTRATOR 
{
    "updatedAccount": {
        "id": "usr-auth0|5e2ad9b79809280cb25b1eb5",
        "email": "another.user@example.com",
        "fullName": "Another User",
        "role": "ADMINISTRATOR"
    }
}

Alternatively, you can use the user ID (account-ID) instead of the email address to specify the Geospock database user.

For more information about this command, use the GeoSpock CLI's help command.

Deleting a user account

To remove a users access to both the GeoSpock CLI and the SQL cluster, use the account-delete command. You can use the account-list command to search for the relevant user.

$ geospock account-delete --email <email_address> 

For example, to delete the role for the account belonging to another.user@example.com, your command would look like this:

$ geospock account-delete --email "another.user@example.com" 
{
    "deletedAccount": "another.user@example.com"
}

Alternatively, you can use the user ID (account-ID) instead of the email address to specify the Geospock database user.

Note, this command is only available if your deployment uses built-in identity provision.

For more information about this command, use the GeoSpock CLI's help command.