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 settingsSettings Writer
: grants permission to write Dynatrace settings
To verify that you have these policies
- Go to the Policy management page:
- Dynatrace SaaS: in the user menu, go to Account settings and select Identity management > Policy management.
- Dynatrace Managed: in the Cluster Management Console, select User authentication > Policy management.
- Find
Settings Reader
andSettings 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.
Dynatrace SaaS
For Dynatrace SaaS deployments, the APIs must be accessed using an OAuth2 client.
To generate an OAuth2 client
- Sign in to Dynatrace using an account with the
account-user-management
permission set. - Go to Account management API and select Create new client.
- Describe the client.
Be sure to select Allow IAM policy configuration for environments. - Select Generate client.
- Copy and paste the generated fields (Client ID, Client secret, and Your account URN) to a secure location.
Caution
Client secret is revealed only once and cannot be regenerated!
- 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 athttps://sso.dynatrace.com/sso/oauth2/token
. Any OAuth or HTTP client can be used to request the token. Sample HTTP request:
Now, complete the fields for thePOST /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}
/oauth2/token
endpoint using data obtained in the previous step as shown below:grant_type: client_credentials client_id: ${your client id} client_secret: ${your client secret} scope: iam-policies-management resource: urn:dtaccount:${your account UID}
- Execute the request.
- 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.
Dynatrace Managed
Dynatrace Managed deployments use token-based authentication for the PAP REST API. To generate it
- Open Cluster Management Console (CMC).
- Go to Settings > API tokens.
- In the Cluster tokens section, select Generate token.
- Give the token any name you want
- Turn on Service provider API
- Select Save.
- Select Copy to copy the token.
- Add an
Authorization
header to your request with the valueApi-Token [generated token goes here]
.
Example 1: read and write permission
Suppose you have the following teams in your organization:
- The IT team, which is responsible for configuring the Dynatrace environment and making sure everything works.
- The sales team, which should only be able 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
To add a group named IT
- Go to the Group management page:
- Dynatrace SaaS: Identity management > Group management.
- Dynatrace Managed: User authentication > User groups.
- Select Add group.
- Enter the Group name (
IT
) and Group description, and then select Save.
Repeat the procedure for the Sales
user group.
Now that you have the two user groups, you need to grant each group the correct permissions. You can use either the Dynatrace web UI or the REST API.
Bind policies via Dynatrace web UI
Let's start by assigning the correct permissions to the IT
group.
If you're going to use the REST API, skip to Bind policies via REST API below.
- Go to the Group management page:
- Dynatrace SaaS: Identity management > Group management.
- Dynatrace Managed: User authentication > User groups.
- 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. - Expand the environment for which you want to make changes and select the Policies tab.
- In the Select policies to bind filter box:
- Find and select the
Settings Writer
policy - Find and select the
Settings Reader
policy
- Find and select the
- Select the Bind policies button on the right to bind the policies.
- Select the Save button that is displayed on a ribbon at the bottom of the page.
Congratulations, you've bound your first policies! The IT
group in the selected environment has read and write access to Dynatrace settings.
Now repeat the above procedure for the Sales
team, but bind only the Settings Reader
policy to it. The sales team in this example does not need write access to Dynatrace settings.
Bind policies via REST API
This procedure uses the REST API to do the same things we did above in Bind policies via Dynatrace web UI.
To bind a policy to a group, 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 IDsettings_reader_id
- The
Settings writer
policy has IDsettings_writer_id
- The
Sales
group ID issales_group_id
- The
IT
group ID isit_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:
- Bind the
Settings Reader
policy to both of our groups (IT
andSales
). - Bind the
Settings Writer
policy only to theIT
group.
The first request should then be sent on the /repo/environment/my_environment_id/bindings/settings_reader_id
endpoint with the following body:
{
"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:
{
"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 therefore 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
-
Go to the Policy management page:
- Dynatrace SaaS: Identity management > Policy management.
- Dynatrace Managed: User authentication > Policy management.
-
Select Add policy.
-
Describe the policy:
- Policy name
Any useful name. - Policy description
Any useful description. - Organization level
Select the appropriate level for this policy. Let's assume that it will apply to the same environment as in the previous example (withmy_environment_id
). - Policy statements
Copy the following statement to the Policy statements box.
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: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";
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";
- Policy name
-
Select the Save button that is displayed on a ribbon at the bottom of the page.
The policy is now ready to be used in the next step.
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:
{
"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:
{
"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.