Try it free

ActiveGate security

  • Latest Dynatrace
  • 8-min read

Custom certificate for ActiveGate

We recommend using custom certificates for ActiveGates to increase security.

See Custom SSL certificate for ActiveGate.

Tokens

ActiveGates authenticate to Dynatrace using dedicated ActiveGate tokens.

ActiveGate token types

ActiveGate tokens come in two types:

  • Seed token—An ActiveGate seed token is automatically customized into the ActiveGate installer when you download the installer via the Dynatrace web UI or Dynatrace API.
  • Individual token—During the first ActiveGate connection to the Dynatrace Cluster, the initial ActiveGate seed token is replaced with an automatically generated, individual ActiveGate token. The same installer can be used multiple times; the initial ActiveGate seed token is allowed to create multiple individual ActiveGate tokens.

ActiveGate token structure

The format of an ActiveGate token consists of three parts separated by dots (.).

Example:

dt0g02.4KWZO5EF.XT47R5DRADJIZUFOX4UDNOKTSUSABGLN7XSMJG7UXHRXKNY4WLORH4OF4T75MG7E

PartNameDescription

1

prefix

The first part (dt0g02 in the example above) is the token prefix. It identifies the token type.

2

public

The second part (4KWZO5EF in the example above) is the 8-character public portion of the token.

Together, the prefix and the public portion comprise the token identifier.

You can safely display the token identifier in the web UI and use it for logging purposes.

3

secret

The third part (XT47R5DRADJIZUFOX4UDNOKTSUSABGLN7XSMJG7UXHRXKNY4WLORH4OF4T75MG7E in the example above) is the 64-character secret portion of the token.

Treat the secret portion like a password. It shouldn't be displayed in Dynatrace (following initial creation) or stored in log files.

ActiveGate token enforcement

To check which of your ActiveGates have ActiveGate tokens enabled:

  1. Go to Fleet Management Fleet Management > ActiveGate, Synthetic Engine, or zRemote.
  2. In the filter sidebar, select Alert type > Token and select Apply.
    • For more information about alert types, see ActiveGate health overview.

ActiveGate token status

If your ActiveGates don't use valid ActiveGate tokens, an ActiveGate token alert is raised so you can check why the tokens are invalid. Depending on the status, you may be required to perform some actions to transition to ActiveGate token-based network security.

An ActiveGate token can have one of the following statuses:

Absent

The ActiveGate version supports ActiveGate tokens, but it's still using the tenant token for communication. Generate and configure a new ActiveGate token.

Expiring

The ActiveGate token is set to expire in 30 or fewer days. If your environment has ActiveGate tokens enforced, your ActiveGate will lose its connection after the token expires.

Invalid

The ActiveGate is configured to use an ActiveGate token, but the format is invalid. Generate and configure a new ActiveGate token.

Unknown

The ActiveGate is configured to use an ActiveGate token and the token format is valid, but the token isn't recognized by the Dynatrace Cluster. Generate and configure a new ActiveGate token.

Valid

The ActiveGate is using a valid ActiveGate token to authenticate.

Unsupported

The ActiveGate is version 1.223 or earlier; ActiveGate token-based network security is supported for ActiveGate version 1.225+.

Generate and configure ActiveGate token

  • If your ActiveGate is deployed as a StatefulSet, you need to generate an ActiveGate token and add it to your configuration.

    • An ActiveGate seed token can't be used for containerized ActiveGates.
    • An ActiveGate token can be shared among ActiveGates within the same environment.

  • If your ActiveGate is deployed by using Dynatrace Operator, Dynatrace Operator handles the authorization token. Starting with Dynatrace Operator version 0.9.0+, you must enable the Create ActiveGate tokens (activeGateTokenManagement.create) scope. For details, see Tokens and permissions.

    For issues with your ActiveGate token, see Problem with ActiveGate token in Dynatrace Community.

  • All host-based ActiveGates installed via the Dynatrace web UI or Dynatrace API already have an automatically generated ActiveGate token. However, you may sometimes need to generate an ActiveGate token and configure it in the authorization.properties file.

Generate ActiveGate token

  1. Generate an API token. Select one of the following token scopes to limit access for security reasons:

    • Create ActiveGate tokens
    • Write ActiveGate tokens

  2. Save the token.

    It's displayed only once.

  3. Use the ActiveGate tokens API - POST a token endpoint to create the token. Authorize your call with the API token you just created. For example, the following command will generate an ActiveGate token with the following parameters:

    • ActiveGate type: ENVIRONMENT
    • ActiveGate token expires in: 6 months
    • ActiveGate token type: individual ActiveGate token (seedToken is false).

    Starting with Dynatrace version 1.293+, you must ensure that the expirationDate field is not set in the past and does not exceed two years from the moment of creation.

    Command:

    curl -X POST "https://{your-environment-id}.live.dynatrace.com/api/v2/activeGateTokens" \
    -H 'Authorization: Api-Token {api-token}' \
    -H 'Accept: application/json; charset=utf-8' \
    -H 'Content-Type: application/json; charset=utf-8' \
    -d '{
         "name": "myToken",
         "expirationDate": "now+6M",
         "seedToken": false,
         "activeGateType": "ENVIRONMENT"
        }'

    Replace:

    • {your-environment-id} with your Environment ID
    • {api-token} with an API token set to one of the following scopes: Create ActiveGate tokens or Write ActiveGate tokens.

    Response body example:

    {
      "id": "dt0g02.4KWZO5EF",
      "token": "dt0g02.4KWZO5EF.XT47R5DRADJIZUFOX4UDNOKTSUSABGLN7XSMJG7UXHRXKNY4WLORH4OF4T75MG7E",
      "expirationDate": "2020-11-24T08:15:30.144Z"
    }

Configure token on host-based ActiveGate

  1. In the ActiveGate configuration directory, locate the authorization.properties file.
  2. Edit the file to add the ActiveGate token you generated as the value of the authToken property. For example: 
    authToken = dt0g02.4KWZO5EF.XT47R5DRADJIZUFOX4UDNOKTSUSABGLN7XSMJG7UXHRXKNY4WLORH4OF4T75MG7E     # present, if required
  3. Restart the ActiveGate main service

ActiveGate token expiry notifications

Fleet Management Fleet Management surfaces a Warning alert when a token is close to expiring. No changes to the token generation process are required—when you see this warning, rotate the token to prevent the ActiveGate from losing its connection.

In Health state conditions see Token row.

Automatic ActiveGate token cleanup

Dynatrace version 1.272+

Dynatrace performs an automatic cleanup of unused ActiveGate tokens. The token is considered unused after two years from the last usage. You can check your tokens via the GET all tokens request of the Tokens API—look for the lastUsedDate field.

Sample API payload
{
  "activeGateTokens": [
    {
      "id": "dt0g02.abc123",
      "name": "system:installer",
      "owner": "max.mustermann@company.com",
      "creationDate": "2021-11-22T11:39:29.797Z",
      "seedToken": true,
      "activeGateType": "ENVIRONMENT"
    },
    {
      "id": "dt0g02.321cba",
      "name": "system:installer",
      "owner": "john.smith@company.com",
      "creationDate": "2021-11-30T14:11:40.913Z",
      "seedToken": true,
      "activeGateType": "ENVIRONMENT"
    },
    {
      "id": "dt0g02.123abc",
      "name": "system:initial-setup",
      "owner": "mary.brown@company.com",
      "creationDate": "2021-10-22T13:48:00.135Z",
      "expirationDate": "2021-12-02T11:52:17.201Z",
      "lastUsedDate": "2020-11-24T08:15:30.144Z",
      "seedToken": false,
      "activeGateType": "ENVIRONMENT"
    }
  ],
  "nextPageKey": "AAAAAAAAAAAAAABOAAAAAAAAAAAAAAA6ACQAEAAAABgACgAITFdXQk1BRzYAAAhtZXRhZGF0YQB___-bf___m3iIYxfF7xVQvY72rwblQkcAAwAAAAAAAADHAAAAZA==",
  "pageSize": 100,
  "totalCount": 1000
}