Registration and authentication

Terrascope services are available to all users, with some services requiring authentication. Users can freely explore and visualize the data and services offered by Terrascope, but registration and authentication are required to access more advanced features.

Why Register?

Registering with Terrascope grants access to advanced services and tools that enhance the user experience. Some key examples include:

  • Explore and Download Data: The Terrascope Viewer allows users to explore and visualize data without registering. However, users must sign up to download data, save specific areas of interest, or obtain time series data for those areas.
  • Join the Community: To participate in discussions, post messages or ask questions on the forum, a user needs a Terrascope account.
  • Use Jupyter Notebooks: Registered users can access interactive Jupyter Notebooks for more advanced data analysis. This powerful tool enables a more profound exploration of the available data.
  • Access Virtual Machines: Users requiring additional computing power can request a virtual machine. Registration is necessary to access and utilize these virtual machines, providing a more robust environment for their work.

Therefore, this page provides detailed instructions on the registration and authentication process, including how to create a Terrascope account, use an external identity provider, and update a user profile.

Note

To access protected Terrascope services, users can create a new account or utilize an existing one from a supported external identity provider. For openEO services, registration through the external identity provider EduGAIN & social logins is necessary, separate from the initial registration for other Terrascope services.

Logging in to Terrascope

The following options are available for logging in to Terrascope:

Figure 1: Terrascope login dialog.

Option-1: Register a new account

To create a new Terrascope account, users can click on the register link located at the bottom of the login page. This opens the Terrascope registration box, where users must provide a Terrascope username and password, among other details.

Figure 2: Terrascope registration dialog.

Upon (un)checking the ‘Keep me posted’ checkbox, users can choose whether to (un)subscribe from the Terrascope mailing list. After filling out the registration page, sign in using the credentials entered in the form.

However, if users want to access openEO services, they must also register through EduGAIN & social logins. This is a separate registration process, as described in the next section.

Option-2: Registering through external identity provider

Terrascope supports external identity providers, allowing users to sign in using accounts from supported providers. This includes immediate access using one of these providers.

Through EduGAIN & social logins, users can sign in using an EduGAIN account or one of the supported social login providers (such as Google, Facebook, etc.).

Additionally, as previously mentioned, users must register using EduGAIN & social logins to access processes and services offered by openEO. Registration through EduGAIN & social logins is also required for services provided in EOplaza.

Terrascope also supports the Copernicus Data Space Ecosystem as an external identity provider. It is possible to sign in and register an account on Terrascope using a Copernicus Data Space Ecosystem account.

Using an external identity provider simplifies the login process. A Terrascope account is created automatically without users noticing. They only need to provide additional information by submitting the form shown in the figure below:

Figure 3: Terrascope external registration dialog.
Note

If the user wants to start using a Terrascope Virtual Machine, a password must be set for an auto-generated Terrascope account. Therefore, in this case, “Option-1” is recommended.

Updating your profile

Personal info

The user can update their Terrascope profile on the update profile page. On this page, they can modify their Terrascope profile properties.

Figure 4: Update profile properties.

Password

To update your password you need to visit the account security - signing in page.

Figure 5: Update password.

Linked accounts

Users can also view and manage the external login accounts linked to their Terrascope account.

Figure 6: Manage federated identities.
Important

For those interested in using openEO services, ensure that EduGAIN & social logins are available under the ‘Federated Identities’ tab.

Securing Your Account with Multi-Factor Authentication (MFA)

To enhance the security of your Terrascope account, we strongly recommend enabling Multi-Factor Authentication (MFA). Terrascope uses Keycloak, an open-source identity and access management platform, which supports TOTP (Time-based One-Time Password) as a secure authentication method.

What is TOTP MFA?

TOTP MFA adds an extra layer of security to your account by requiring two factors for authentication:

  1. Something you know: Your username and password
  2. Something you have: A time-based one-time password (TOTP) generated by an authenticator app

Even if someone obtains your password, they cannot access your account without the second factor. TOTP uses an authenticator application on your device that generates a new six-digit code every 30 seconds, making it extremely difficult for attackers to gain unauthorized access.

Why Enable TOTP MFA?

  • Enhanced Security: Protects against common attacks such as password brute force, phishing and credential theft
  • Compliance: Meets security best practices and regulatory requirements for protecting sensitive data
  • Access to Sensitive Services: Some Terrascope services may require MFA for accessing critical resources

How to Enable TOTP MFA on Terrascope

Follow these steps to configure TOTP MFA for your Terrascope account:

  1. Access Your Account Settings
  2. Configure Authenticator App
    • Go to the “Account security > Signing in” tab
    • Look for the “Two-factor authentication” option
    • Click on “Set up authenticator application” button
  3. Install an Authenticator App
    • If you haven’t already, install one of the following authenticator apps on your device:
      • Google Authenticator (iOS, Android)
      • FreeOTP (iOS, Android) - Open source alternative
      • Microsoft Authenticator (iOS, Android, Windows)
    • These apps generate TOTP codes required for MFA
  4. Scan the QR Code
    • Open your authenticator app and select the option to add a new account
    • Scan the QR code displayed on the Terrascope account page
    • Alternatively, if the app doesn’t support QR scanning, you can manually enter the secret key provided
  5. Verify Configuration
    • Enter the 6-digit code currently shown in your authenticator app
    • Click “Submit” to complete the setup
    • Your TOTP MFA is now active

Using TOTP MFA When Logging In

Once TOTP MFA is enabled:

  1. Enter your username and password on the login page
  2. When prompted, enter the 6-digit code from your authenticator app
  3. Click “Submit” to complete the login

Best Practices for MFA Security

  • Use a Reliable Authenticator: Choose an authenticator app from a trusted provider
  • Don’t Share Codes: Never share your TOTP codes with anyone
  • Update Regularly: If you change devices, update your authenticator configuration promptly
  • Sync Device Time: Ensure your device’s clock is synchronized with network time for TOTP to work correctly

Need Help?

If you encounter issues enabling or using TOTP MFA:

  • Check that your device’s date and time settings are correct (TOTP depends on time synchronization)
  • Verify you’re entering the current code from your authenticator app (codes change every 30 seconds)
  • Contact Terrascope Support for additional assistance
Tip

We recommend enabling TOTP MFA on all accounts, especially if you have access to sensitive data or plan to use Terrascope’s advanced services like Virtual Machines or Jupyter Notebooks.

Access and refresh tokens

Certain Terrascope services require token authentication. Users can request an access token to access these services. The OpenID Connect (OIDC) Direct Access Grant, also known as the OAuth2 Resource Owner Password Credentials Grant, enables users to obtain an access token by providing their username and password.

Request token

To get an access token, send a POST request to the token endpoint: https://sso.terrascope.be/auth/realms/terrascope/protocol/openid-connect/token.

The request should contain the following parameters:

  • grant_type: password
  • client_id: public
  • username: your Terrascope username
  • password: your Terrascope password

This will result in the following HTTP request:

curl --location 'https://sso.terrascope.be/auth/realms/terrascope/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'client_id=public' \
--data-urlencode 'username=<username>' \
--data-urlencode 'password=<password>'

The response will look like the example below:

{
    "access_token": "eyJhb...",
    "expires_in": 300,
    "refresh_expires_in": 3600,
    "refresh_token": "eyJhb...",
    "token_type": "Bearer",
    "not-before-policy": 0,
    "session_state": "...",
    "scope": "profile email"
}

The provided access token can now be used to access supported services. The access token is included in the Authorization header of the request to the service, for example, for downloading WorldCover data:

curl --location 'https://services.terrascope.be/download/WORLDCOVER/ESA_WORLDCOVER_10M_2020_V100/MAP/ESA_WorldCover_10m_2020_v100_N00E006_Map/ESA_WorldCover_10m_2020_v100_N00E006_Map.tif' \
--header 'Authorization: Bearer eyJhb...' \

Refresh token

The token obtained previously expires after a certain period. To avoid repeatedly requesting a new access token with user credentials, it is possible to refresh the token using the refresh token provided in the response.

This can be achieved by sending a POST request to the token endpoint with different parameters:

  • grant_type: refresh_token
  • client_id: public
  • refresh_token: the refresh token provided in the previous call to the token endpoint

This generates the following HTTP request:

curl --location 'https://sso.terrascope.be/auth/realms/terrascope/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'client_id=public' \
--data-urlencode 'refresh_token=eyJhb...'

The response to this request includes both an access token and a refresh token.

Back to top