• Home
  • Manage
  • Access control
  • Manage user permissions with IAM policies
  • Get started with IAM

Get started with IAM

All examples here are based on the Settings 2.0 service. For a complete list of services supporting policy-based authorization, see IAM service reference.

Built-in policies

For every account, administrators have two built-in policies available for Settings 2.0 services:

  • Settings Reader: grants permission to read Dynatrace settings
  • Settings Writer: grants permission to write Dynatrace settings

To verify that you have these policies

  1. In Account Management, go to Identity & and access management > Policies.
  2. Find Settings Reader and Settings Writer in the table.
  1. In the Cluster Management Console, go to User authentication > Policy management.
  2. Find Settings Reader and Settings Writer in the table.

REST API authentication

All IAM features can be accessed via REST API. The complete documentation of all the objects used within the API and all exposed endpoints can be found in the REST API Swagger doc. Here we will only cover the aspects regarding authentication of requests, which differs in Dynatrace SaaS and Dynatrace Managed deployments.

For Dynatrace SaaS deployments, the APIs must be accessed using an OAuth2 client.

To generate an OAuth2 client

  1. Access Dynatrace Account Management at https://myaccount.dynatrace.com and select the account.

  2. Go to Identity & access management > OAuth clients.

    If you don't see this option, you don't have sufficient permissions for this action.

  3. Select Create client.

  4. Enter the email address of the user who owns the client.

  5. optional Enter a description of the new client.

  6. required Select View and manage policies.

  7. Select Create client.

  8. Copy the generated client ID and secret and store them in a safe place.

    You can only access your client secret once upon creation. You can't reveal it afterward.

  9. Once you have a client ID and secret, you can use Dynatrace SSO to request an access token for your client through the client credentials flow. You must include your account UID prefixed with urn:dtaccount in the resource parameter of the request body. For instance:
    urn:dtaccount:12a34567-8901-2bc3-d45e-6f7g8h90123i
    Request a token at https://sso.dynatrace.com/sso/oauth2/token. Any OAuth or HTTP client can be used to request the token. Sample HTTP request:

plaintext
POST /sso/oauth2/token HTTP/1.1
Host: sso.dynatrace.com
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&client_id={your client id}&client_secret={your client secret}&scope=iam-policies-management&resource=urn%3Adtaccount%3A{your account UID}

Now, complete the fields for the /oauth2/token endpoint using data obtained in the previous step as shown below:

plaintext
grant_type: client_credentials
client_id: ${your client id}
client_secret: ${your client secret}
scope: iam-policies-management
resource: urn:dtaccount:${your account UID}

  1. Execute the request.

  2. The required token is returned in the response. This can now be used as a Bearer token to authenticate requests to the Policy Administration Point (PAP) REST API.

    The returned token is valid for 5 minutes and can be reused. If you're making multiple calls to the API, you don't have to create a new token for every call.

Dynatrace Managed deployments use token-based authentication for the PAP REST API.

To generate the token

  1. In the Cluster Management Console, go to Settings > API tokens.
  2. In the Cluster tokens section, select Generate token.
    • Give the token any name you want
    • Turn on Service provider API
  3. Select Save.
  4. Select Copy to copy the token.
  5. Add an Authorization header to your request with the value Api-Token [generated token goes here].

Example 1: read and write permission

Suppose you have the following teams in your organization:

  • The IT team is responsible for configuring the Dynatrace environment and making sure everything works.
  • The Sales team just needs to read the Dynatrace settings, and never modify them.

The IT team needs read and write access, while the sales team needs only read access.

Create two Dynatrace user groups

First, create a group named IT that has policies Settings Writer and Settings Reader.

  1. In Account Management, go to Identity & and access management > Groups.
  2. Select Create group.
  3. In the Set group details step, enter the group Name (IT in this example) and a group Description, and then select Next.
  4. In the Assign permissions step, assign group permissions and then select Next.
  5. In the Assign policies step, under Group policies > Account policies, find and select Settings Writer and Settings Reader, and then select Next.
  6. In the Review group step, verify the group permissions and policies and then select Create group.

To create a group

  1. In the Cluster Management Console, go to User authentication > User groups.
  2. Select Add new group.
  3. Enter the Group name (IT in this example) and Group description, and then select Save.

To bind policies to the group

  1. In the Cluster Management Console, go to User authentication > User groups.
  2. Find the IT group and select the pencil icon in the Edit column to edit that group.
    The edit view includes an Environment permissions section listing all environments you are managing.
  3. Expand the environment for which you want to make changes and select the Policies tab.
  4. In the Select policies to bind filter box:
    • Find and select the Settings Writer policy
    • Find and select the Settings Reader policy
  5. Select the Bind policies button on the right to bind the policies.
  6. Select the Save button that is displayed on a ribbon at the bottom of the page.

Now repeat the above procedure to create a Sales group with read-only access:

  • Set the group name to Sales
  • Bind only the Settings Reader policy to it, because the sales team in this example does not need write access to Dynatrace settings.

Bind policies via web UI

In the previous example for a SaaS deployment, we bound policies to or IT and Sales user groups as we created them, in the Assign policies step, so you can skip this procedure for this example.

But if you wanted to adjust the selection of policies for a group, it's easy.

  1. In Account Management, go to Identity & and access management > Groups.
  2. Find the group you created in the example earlier.
  3. Select Actions > View group.
  4. Scroll down to Policies and select the edit link.
  5. Change the selection of policies for that group.
  6. Scroll down and select the Save.
  7. Review the summary on the Group details page. If you need to make additional changes, scroll down to Policies and select the edit link again.

To bind policies to the group

  1. In the Cluster Management Console, go to User authentication > User groups.
  2. Find the IT group and select the pencil icon in the Edit column to edit that group.
    The edit view includes an Environment permissions section listing all environments you are managing.
  3. Expand the environment for which you want to make changes and select the Policies tab.
  4. In the Select policies to bind filter box:
    • Find and select the Settings Writer policy
    • Find and select the Settings Reader policy
  5. Select the Bind policies button on the right to bind the policies.
  6. Select the Save button that is displayed on a ribbon at the bottom of the page.

Bind policies via REST API

Optionally, you can instead use the REST API to bind policies to a group.

To do so, you need the following values:

  • ID of each policy you want to bind
  • ID of each group to which you want to bind policies
  • ID of the environment for which you want to make changes (for details, see this guide)

In our example, suppose we have the following values:

  • The Settings Reader policy has ID settings_reader_id
  • The Settings writer policy has ID settings_writer_id
  • The Sales group ID is sales_group_id
  • The IT group ID is it_group_id
  • The environment has the ID my_environment_id

Now we need to create a body for the request for binding the policies. You can use either a PUT (for replacing policy bindings) or a POST (for appending policy bindings). Let's assume that we want to append the policies and use a POST.

In this example we use the /repo/{level-type}/{level-id}/bindings/{policy-uuid} endpoint from the PAP REST API. We need to proceed in two steps:

  1. Bind the Settings Reader policy to both of our groups (IT and Sales).
  2. Bind the Settings Writer policy only to the IT group.

The first request should then be sent on the /repo/environment/my_environment_id/bindings/settings_reader_id endpoint with the following body:

plaintext
{
  "groups": [
    "it_group_id",
    "sales_group_id"
  ]
}

This grants read permission to both groups.

To add write permission to the IT group, we need to execute another POST request on the /repo/environment/my_environment_id/bindings/settings_writer_id endpoint with the following body:

plaintext
{
  "groups": [
    "it_group_id"
  ]
}

Congratulations, you've completed the binding of built-in policies via API!

Example 2: allow access to a particular schema

If the built-in policies are not granular enough for your needs, you can manage permissions at the setting level.

Assume that you have a particular Settings 2.0 schema, say settings.apm.my-super-secret-schema, the only one that you want to keep open for the Sales and IT groups.

You want to allow access to the following:

  • Allow reading of schema settings.apm.my-super-secret-schema
  • Allow reading and writing of objects belonging to the schema settings.apm.my-super-secret-schema

As before, we present two ways of obtaining this effect.

Create a policy via Dynatrace web UI

This procedure uses the Dynatrace web UI. To use the REST API instead, skip to Create a policy via REST API.

To create a policy

  1. In Account Management, go to Identity & and access management > Policies.

  2. Select Create policy.

  3. Describe the policy:

    • Name
      Any useful name.

    • Description
      Any useful description.

    • Policy statement
      Copy the following statement to the Policy statements box.

      plaintext
      ALLOW settings:schemas:read WHERE settings:schemaId = "builtin:container.monitoring-rule";
ALLOW settings:objects:read WHERE settings:schemaId = "builtin:container.monitoring-rule";
ALLOW settings:objects:write WHERE settings:schemaId = "builtin:container.monitoring-rule";

      Note that since one can use multiple permissions in one statement, it is possible to merge the first two statements from the above into a single one:

      plaintext
      ALLOW settings:schemas:read, settings:objects:read WHERE settings:schemaId = "builtin:container.monitoring-rule";
ALLOW settings:objects:write WHERE settings:schemaId = "builtin:container.monitoring-rule";

  4. Select Create policy.

  1. In the Cluster Management Console, go to User authentication > Policy management.

  2. Select Add policy.

  3. Describe the policy:

    • Policy name
      Any useful name.

    • Policy description
      Any useful description.

    • Policy statements
      Copy the following statement to the Policy statements box.

      plaintext
      ALLOW settings:schemas:read WHERE settings:schemaId = "builtin:container.monitoring-rule";
ALLOW settings:objects:read WHERE settings:schemaId = "builtin:container.monitoring-rule";
ALLOW settings:objects:write WHERE settings:schemaId = "builtin:container.monitoring-rule";

      Note that since one can use multiple permissions in one statement, it is possible to merge the first two statements from the above into a single one:

      plaintext
      ALLOW settings:schemas:read, settings:objects:read WHERE settings:schemaId = "builtin:container.monitoring-rule";
ALLOW settings:objects:write WHERE settings:schemaId = "builtin:container.monitoring-rule";

  4. Select Save.

The policy is now added to your table of policies that you can bind to groups.

Create a policy via REST API

This procedure uses the REST API to do the same things we did in Create a policy via Dynatrace web UI.

To create a policy using the API, we will use the /repo/{level-type}/{level-id}/policies endpoint and use a POST method to add a policy.

Assume that the policy name we want to add is my_policy_name and the description is My policy description. As before, assume that we want this policy to apply only on the environment level for environment my_tenant_id.

The request body should be the following:

json
{
   "name":"my_policy_name",
   "description":"My policy description",
   "tags":[

   ],
   "statementQuery": "ALLOW settings:schemas:read WHERE settings:schemaId = \"builtin:container.monitoring-rule\"; ALLOW settings:objects:read WHERE settings:schemaId = \"builtin:container.monitoring-rule\"; ALLOW settings:objects:write WHERE settings:schemaId = \"builtin:container.monitoring-rule\";"
}

Equivalently, using multiple permissions in a single statement, the request body should be the following:

json
{
   "name":"my_policy_name",
   "description":"My policy description",
   "tags":[

   ],
   "statementQuery": "ALLOW settings:schemas:read, settings:objects:read WHERE settings:schemaId = \"builtin:container.monitoring-rule\"; ALLOW settings:objects:write WHERE settings:schemaId = \"builtin:container.monitoring-rule\";"
}

Enforce the policy

Important: Remember that a policy does not take effect until you bind it to a group. For this example, you need to bind it to the IT and Sales groups. See Bind policies via Dynatrace web UI or Bind policies via REST API for details.