ActiveGate security

Starting with Dynatrace version 1.225, every ActiveGate uses its own unique ActiveGate token to authorize in the Dynatrace Cluster.

Depending on the state of your deployment, starting with Dynatrace version 1.246, you may be required to perform some actions to migrate to ActiveGate token-based security.

Migrate to ActiveGate tokens

To migrate to ActiveGate token-based security, start by determining the status of your ActiveGate token usage.

In Dynatrace, go to Settings > Preferences > Network security.
Review the messages displayed on the Network security page and address any issues as described below.

No action required

If Dynatrace displays a message like this:

ActiveGate tokens enforced

No action is required. ActiveGate enforcement is on and you're all set.
Only ActiveGates with valid ActiveGate tokens can connect to Dynatrace.

Fix ActiveGate token issues

If Dynatrace displays a message like this:

ActiveGate token issues

ActiveGate tokens are not yet enforced and some of your ActiveGates use invalid tokens.
You need to address the issues based on the status. Otherwise, such ActiveGates will lose connectivity after ActiveGate tokens are enforced.

Enforce ActiveGate tokens immediately

If Dynatrace displays a message like this:

Manual ActiveGate token enforcement

You have the option to enforce ActiveGate tokens immediately. You can do so at any time, regardless of whether your ActiveGates report token issues, but be sure to read Manual ActiveGate token enforcement below first. All ActiveGates with a status other than Valid will lose their connection to Dynatrace.

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

Part Name Description

Part	Name	Description
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.

prefix

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

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.

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

All your ActiveGates have already been gradually migrated to use ActiveGate tokens during the ActiveGate updates starting with ActiveGate version 1.225.

To check which of your ActiveGates have ActiveGate tokens enabled

In Dynatrace, go to Deployment Status and select ActiveGates.
You can filter your ActiveGates by the following ActiveGate token statuses:
- Absent
- Expiring
- Invalid
- Unknown
- Valid
- Unsupported See ActiveGate token status below for more information.

Automatic ActiveGate token enforcement

If all of your ActiveGates are ready for token-based network security for 30 days, your environment will automatically switch to ActiveGate token-based network security.

Manual ActiveGate token enforcement

If you want to speed up the process and you are sure that there are only ActiveGates version 1.225+ in your environment, you can force the switch to ActiveGate tokens whenever you're ready.

In Dynatrace, go to Settings > Preferences > Network security.
Turn on Manually enforce ActiveGate token authentication.

When you turn on Manually enforce ActiveGate token authentication and save your changes, all ActiveGates with a status other than Valid will lose their connection to Dynatrace.
You have a maximum of 30 days after the last invalid token was detected to withdraw from manual enforcement (to turn off Manually enforce ActiveGate token authentication). For example, if the last invalid token was detected 20 days earlier, you still have 10 days to withdraw from enforcement. After the transitional period is over, the switch is disabled (so you can't turn it off).

Transitional period

The transitional period of 30 days is designed to prevent data loss from ActiveGates where new tokens are not implemented in your environment.

During that period, if any attempt to connect without an ActiveGate token is detected:

ActiveGate token enforcement won't be switched on and all ActiveGates will be allowed to connect to the Dynatrace cluster (only tenant tokens will be required).
The transitional period is reset to 30 days—ActiveGate token enforcement will be switched on automatically no sooner than 30 days from that point.

ActiveGate token status

If your ActiveGates don't use valid ActiveGate tokens, you can check to learn why the tokens are invalid.

In Dynatrace, go to Deployment Status and select ActiveGates.
Select Check ActiveGate token statuses.

This option is only available if there are problems with the ActiveGate tokens.

Depending on the status, you may be required to perform some actions to transition to ActiveGate token-based network security.

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 Access 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

Generate an API token. Select one of the following token scopes to limit access for security reasons:
- Create ActiveGate tokens
- Write ActiveGate tokens
Save the token.

It's displayed only once.
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).
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:
```
{
  "token": "dt0g01.4KWZO5EF.
  XT47R5DRADJIZUFOX4UDNOKTSUSABGLN7XSMJG7UXHRXKNY4WLORH4OF4T75MG7E",
  "expirationTimeEpoch": 1607096737302
}
```

Configure token on host-based ActiveGate

In the ActiveGate configuration directory, locate the authorization.properties file.

Edit the file to add the ActiveGate token you generated as the value of the authToken property. For example:

authToken = dt0g01.4KWZO5EF.XT47R5DRADJIZUFOX4UDNOKTSUSABGLN7XSMJG7UXHRXKNY4WLORH4OF4T75MG7E     # present, if required

Restart the ActiveGate main service

ActiveGate token expiry notifications

Besides setting up your internal mechanism for rotating ActiveGate tokens before their expiration date, you can set up notifications about expiring ActiveGate tokens. To do so, create a problem notification integration (for example, Email) using the built-in Default for ActiveGate Token Expiry alerting profile.

For Dynatrace Managed, emergency contacts also receive token expiry notifications.

To stop notifications

In Dynatrace, go to Deployment Status > ActiveGates.
Select More (…), then select ActiveGate token enforcement settings.
Turn off Enable notifications about ActiveGate tokens expiration dates.
Select Save changes.

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.

{
  "totalCount": 3,
  "pageSize": 3,
  "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",
     "lastUsedDate": "2021-12-02T11:52:17.201Z",
     "seedToken": false,
     "activeGateType": "ENVIRONMENT"
   }
 ]
}