PRO TIP - Dynatrace Grail Storage Management API Postman Collection

[DanielS]

A few months ago I shared a Postman collection for the Account management API with the community.

Right now, I share the link to a recently created Postman Collection for the Grail Storage Management API.

I share the steps to get this working in your Postman client.

1. Create an Oauth2 Client in Dynatrace.

For more reference in this step you can take a look at this post from @AgataWlodarczyk with a video from @adam_gardner 

1. Open the User menu and select Account settings (in latest Dynatrace, Account Management).

2. On the top navigation bar, go to Identity & access management > OAuth clients.

3. Select Create client.

4. Provide an email of the user who owns the client.

5. Provide a description for the new client.

6. Select the required token scopes. These are the scopes that the client will be able to grant. Tokens generated by the client might have different scope sets.

   • Grants permission to read records from the events-table storage:events:read
   • Grants permission to read timeseries from the metrics-table storage:metrics:read
   • Grants permission to read records from the logs-table storage:logs:read
   • Grants permission to read records from the entities-table storage:entities:read
   • Grants permission to read records from the bizevents-table storage:bizevents:read
   • Grants permission to read records from all system tables storage:system:read
   • Grants permission to read records from Grail buckets. Required additionally to a table permission. storage:buckets:read
   • Grants permission to read bucket definitions from Grail storage:bucket-definitions:read
   • Grants permission to write bucket definitions to Grail storage:bucket-definitions:write
   • Grants permission to delete bucket definitions from Grail storage:bucket-definitions:delete
   • Grants permission to delete all records from a bucket (not delete the bucket itself) in Grail. storage:bucket-definitions:truncate

7. Select Create client.

8. Copy the generated information to the clipboard. Store it in a password manager for future use.

2. Create an Environment for your Collection in Postman.

Environment

1. Select Environments.
2. Click the + sign.
3. Name your Environment.
4. The environment needs that you define these variables:
   • DT_CLIENT_ID Provided when you create the Oauth2 client in step 1.
   • DT_CLIENT_SECRET Provided when you create the Oauth2 client in step 1.
   • DT_ACCOUNT_URN Provided when you create the Oauth2 client in step 1.
   • DT_UUID Same value of DT_ACCOUNT_URN but stripping the urn:account:
   • DT_SCOPE A list of required scopes separated by a whitespace.
   • DT_TOKEN_URL ⚠️PLEASE DON'T CHANGE THIS VALUE ⚠️The URL https://sso.dynatrace.com/sso/oauth2/token where you need to obtain your Bearer token after create the Oauth2 client.
   • DT_TOKEN_NAME The name for your token.
   • DT_TOKEN In this variable you will store your assigned dynamic token.
   • DT_HOST⚠️PLEASE DON'T CHANGE THIS VALUE⚠️ The URL api.dynatrace.com of the Dynatrace API for Account Management.
   • DT_SaaS_HOST Your Environment ID url for the Latest Dynatrace {your-environment-id}.apps.dynatrace.com
5. Leave this Environment Selected.

3. Import Dynatrace Grail Storage Management API Collection.

Import

1. Download the Dynatrace Grail Storage Management JSON from the repository.
2. Select Collections.
3. Click on Import and choose the previously downloaded JSON.
4. Your Dynatrace Grail Storage Management API v1 Collection has been added to your collection.

4. Get your Bearer Token.

Get your Bearer Token

1. ⚠️DON'T FORGET TO HAVE SELECTED THE ENVIRONMENT CREATED IN STEP 2 ⚠️
   
2. Select your recently imported Dynatrace Grail Storage Management API v1 Collection.
3. Click on the Authorization tab.
4. Click on Get New Access Token.
5. Wait until the token has been collected.
6. Click on Use Token.
7. ⚠️BE SURE TO SELECT ALL YOUR TOKEN ⚠️ And then select Set as variable.
8. Choose the DT_TOKEN variable to store your new Bearer Token.

5. Ready, Set, Go.

Using Collection

1. ⚠️DON'T FORGET TO HAVE SELECTED THE ENVIRONMENT CREATED IN STEP 2 ⚠️
   
2. Select Collections.
3. Then Select the Request you want to use and check the parameters.
4. Click on Send.
5. And if everything goes well you get your Response, but if it didn't go well, continue to the next step.

6. Troubleshooting Grail IAM Permissions.

At this point, if you are receiving Required permissions not met it means that the Oauth  2.0 Token is working, but you are lacking the Dynatrace Identity and Access Management (IAM) framework permissions on the user you assign the Oauth 2.0 Token.

7. Create Grail Storage Admin Policy.

1. Open the User menu and select Account settings (in latest Dynatrace, Account Management).
   On the top navigation bar, go to Identity & access management > Policies.
2. Select Create policy, and set a name.
3. Write the policy statements as seen in the image. Note that for bucket management you only need the storage:bucket-definitions statements (8,9,10,11). But this policy is intended to be used by an Admin so it's a bit more permissive.
4. Save it and you are ready with the policy.

8. Create Storage Manager Group.

1. Open the User menu and select Account settings (in latest Dynatrace, Account Management).
   On the top navigation bar, go to Identity & access management > Groups.
2. Select Create group, and set a name.
3. Under the Policies section click edit and assign the Policy Storage - Admin you created on the previous section Create Grail Storage Admin Policy.
4. Save it and we are ready with the group and policy assignment.

9. Assign Storage Manager Group to your Grail Admin User.

1. Open the User menu and select Account settings (in latest Dynatrace, Account Management).
   On the top navigation bar, go to Identity & access management > People.
2. Search for the same user to which you assign the Oauth 2.0 Token.
3. Edit the user and assign the Storage Manager Group you created in the previous step Create Storage Manager Group.
4. All set.

10. Ready to invoke the API call.

1. Go back to Postman and invoke the API call. You should now get Code 200 and a response like the image.

11. Useful Resources

I also leave the links to great posts from Dynatrace blog and docs. They help to assign user permissions and have all this working.

• Tailored access management, Part 2: Onboard users to Grail and AppEngine 
• Permissions in Grail 
• And this great post from @HansLougas Enhance data management with Grail: Ultimate guide to custom buckets and security policies 

[Mizső]

Hi @DanielS,

WOOOOWWW! Thanks for sharing it! 

Best regards,

Mizső

[DanielS]

👌👌👌👌👌👌👌👌👌

You are welcome. Just my two cents for the community.

[AntonioSousa]

@DanielS,

Have to try it out! Great stuff!

[DanielS]

Let me know if you need something. Thanks.

[radek_jasinski]

@DanielS power🔥

[DenisL]

The level of detail, steps-by-step is impressive for newcomers too!
Thank you for taking the time to create and share this Dan.. it is VERY appreciated!

THANK YOU for sharing your efforts my friend!!!

[gabriel_casella]

@DanielS many thanks for this complete guide on how to do this! Plus the postman collection with the Token refresh is magnific!

I also would like to say that (at least for me on yet Postman v9.31.27),
I had to remove the comma on line 5, at the end of the line. Otherwise the JSON is invalid, and Postman does not import the collection.

Not sure if on Postman v10 it works fine though.

Thanks!

[DanielS · Accepted solution]

Thanks for your feedback @gabriel_casella and the note on Postman versions, I gonna try it on another machine because right now I'm using the web version of Postman. I'm glad to hear this is helpful because it took some effort to make. Thanks again.

[samgar-kali]

Thank you for this awesome guide. I have one question: "Do we need to update the expired bearer token manually?"

It looks like, currently Dynatrace does not have a "refresh token" and Postman can not auto refresh it. 

https://learning.postman.com/docs/sending-requests/authorization/oauth-20/#requesting-an-oauth-20-to....

[DanielS]

Hello @samgar-kali. Yes, right now,  once expired you need to refresh the token manually.

[Malaik]

Good JOB.

not yet on grail, but should try it once moved.