User authentication and authorization in the GeoSpock database

The Geospock database supports the authentication using the following Identity Providers (IdP):

For each of the IdPs listed above, these must exist with appropriate users in advance of deploying GeoSpock DB.

Authorisation is performed by the GeoSpock Authorisation service; refer to User Management. In each of the cases below, a root account needs to be assigned to have starting administrative access; refer to Setting up the Root account.

Using Amazon Cognito as an Identity Provider

For GeoSpock to be able to authenticate users to your IdP, you will need to set up an App client. To do this:

  1. In your Cognito User Pool, click on "App clients" and click on "Add another app client"
  2. Add a suitable name, and make sure "Generate client secret" is not ticked. Then click "Create app client."
  3. Make a note of the Client ID.

Alternatively, if using Terraform to deploy your architecture, something similar to the below can be used, with appropriate values completed for the user_pool_id and the identity_provider_callback_urls:

resource "aws_cognito_user_pool_client" "user_pool_web_client" {
  #This corresponds to the app used for authorising GeoSpock CLI and Presto
  name                                 = "test_user_pool_web_client"
  user_pool_id                         = var.user_pool_id
  generate_secret                      = false
  callback_urls                        = var.identity_provider_callback_urls
  allowed_oauth_flows                  = ["code"]
  allowed_oauth_scopes                 = ["phone", "email", "openid", "profile", "aws.cognito.signin.user.admin"]
  supported_identity_providers         = ["COGNITO"]
  allowed_oauth_flows_user_pool_client = true
}

When deploying the GeoSpock DB, the Enterprise Authentication section of your tfvars file should have relevant values provided for the cognito_user_pool and cognito_web_app variables, respectively, for example:

# (Optional) Cognito User Pool ID of the pool to authenticate against if using Cognito authentication (string)
# default: ""
cognito_user_pool = "us-east-1_1abcdEFGH"

# (Optional) Cognito App Client ID corresponding to the LDAP facade if using Cognito authenication (string)
# default: ""
cognito_web_app = "123456789ABCDEFGH"

Refer to Set Up External Authentication Examples for further details.

Using LDAPS as an Identity Provider

You will need to know the host address and port of your LDAPS server, alongside the bind pattern for users. The Enterprise Authentication section of your tfvars file should have relevant values provided for these, for example:

# (Optional) Bind pattern of LDAPS users - multiple DNs are separated by colons, for example: uid=${USER},ou=presto,dc=geospock,dc=com:uid=${USER},ou=query,dc=geospock,dc=com (string)
# default: ""
ldaps_bind_pattern = "uid=$${USER},ou=corporate,dc=example,dc=com"

# (Optional) Host of LDAPS server if using LDAPS authentication (string)
# default: ""
ldaps_server_host = "ec2-3-4-5-6.compute-1.amazonaws.com"

# (Optional) Port used by LDAPS server if using LDAPS authentication (string)
# default: "1389"
ldaps_server_port = "636"

Refer to Set Up External Authentication Examples for further details.

Using OpenID as an Identity Provider

To be able to log in using an OpenID Identity Provider (IdP), you will need to supply the URL of the JSON Web Key Sets (JWKS) when deploying the GeoSpock DB. This JWKS will then be used to verify the JSON Web Token (JWT) used to log in.

The JWT you provide must have a field in that corresponds to your username - for example the sub field may have this information in, or you may have to add a custom claim to your your JWTs.

The Enterprise Authentication section of your tfvars file should have a relevant values provided for the JWKS URL and the field name in the JWT containing your username, for example:

# (Optional) URL of the JWKS to verify JWTs if using OpenID authentication (string)
# default: ""
jwks_address = "https://login.example.com/.well-known/jwks.json"

# (Optional) Username field in JWTs if using OpenID authentication (string)
# default: ""
jwt_username_field = "sub"

When using this authentication route, you will need to use your OpenID username as the --user argument and a JWT from your OpenID IdP as the --password argument when logging in using the GeoSpock CLI; refer to The GeoSpock CLI.