This page describes how to create and use Service Principals to provide secure access to AppDynamics Cloud Tenants using the provided REST APIs. 

Service Principals can consume all APIs except data ingest. Agent Principals can only ingest data. 

Service Principals allow code to securely connect to AppDynamics public APIs on your Cloud Tenant. Service Principals have read-only privileges by default. You must assign the Service Principal to a Cloud Tenant role to escalate privileges on that Cloud Tenant. See Assign Cloud Tenant Roles.

Create Service Principals

To create a Service Principal you must be a Company Administrator and own a Cloud Tenant.
You must create a Service Principal for use in generating OAuth2 tokens. 

  1. Log in to the Account Management Portal as a Company Administrator.
  2. Navigate to Access Management > Service Principals. This option displays only if you have a Cloud Tenant associated with the account.
  3. Select a Cloud Tenant from the dropdown if you have more than one associated with your account.
  4. Click Create to create a new Service Principal specific to the chosen Cloud Tenant. 
    Create Service Principals
  5. Enter a meaningful Name and Description that represents the intended use.
  6. Select an Authentication Type
    1. Basic—credentials pass in the basic authorization header as part of the token request.
    2. Post—credentials pass in the request body as part of the token request. 
  7. Click Create to obtain the Tenant ID, Token URL, Client ID, and Secret

  8. Select to CopyCopy all information at once, DownloadDownload a JSON file a secret.json file, or click Copy to ClipboardCopy to clipboard to copy just that element.  

    This is the only time you can view, copy, or download the Secret. If you close the modal, you must rotate the Secret to generate a new one.

    If you believe that your Secret is no longer secure, you can revoke the Secret or delete the Service Principal which prevents the generation of a new token with that Secret.

  9. Close the dialog.

Get an Access Token

You generate and use an access token for API access calls into your Cloud Tenant. Access tokens are valid for one hour and are reusable during the validity period. Access tokens use the JSON Web Tokens (JWT) open industry standard, therefore decoding them will not show sensitive information.

You cannot view or revoke issued access tokens through the UI or REST API.

Generate a Token

Application principal token requests, for your application, adhere to a standard OAuth2 request format. The authentication method you select when creating the application principal determines the method you supply the client credentials in the token request.

You can use this URL to obtain your tenantId, where tenantName is the name of your Cloud Tenant. 

curl "https://observe-tenant-lookup-api.saas.appdynamics.com/tenants/lookup/{tenantName}.observe.appdynamics.com" 
CODE


For a client configuration using Basic authentication, the client credentials are sent in the basic authorization header. For example:

curl -X "POST" "https://{tenantName}.observe.appdynamics.com/auth/{tenantId}/default/oauth2/token" \
     -H 'Content-Type: application/x-www-form-urlencoded; charset=utf-8' \
     -u '{client_id}:{client_secret}' \
     --data-urlencode "grant_type=client_credentials"
CODE


If the client configuration uses Post authentication, the client credentials are sent in the request body. For example:

curl -X "POST" "https://{tenantName}.observe.appdynamics.com/auth/{tenantId}/default/oauth2/token" \
     -H 'Content-Type: application/x-www-form-urlencoded; charset=utf-8' \
     --data-urlencode "grant_type=client_credentials" \
     --data-urlencode "client_id={client_id}" \
     --data-urlencode "client_secret={client_secret}"
CODE


Any method you use to pass the credentials returns a standard OAuth 2 token response. For example:

{
  "access_token": "{JWT accessToken}",
  "expires_in": 3599,
  "scope": "introspect_tokens revoke_tokens",
  "token_type": "bearer"
}
JSON


You can use the returned access token in your requests to the permitted APIs in the authorization header as a Bearer type. For example:

curl "https://{tenantName}.observe.appdynamics.com/{someAPI}" \
     -H 'Authorization: Bearer {accessToken}'
CODE

Manage Service Principals

Service Principals are Cloud Tenant-specific. Any management you perform on a chosen Cloud Tenant will not convey to another Cloud Tenant. Therefore, if you have multiple Cloud Tenants and want to write code that can act on each one, you must create and maintain a Service Principal and Secret per Cloud Tenant in your system code to perform the desired functions. 

Service Principals provide 

To create a Service Principal you must be a Company Administrator and own a Cloud Tenant.
Log in to the Account Management Portal as a Company Administrator and navigate to Access Management > Service Principals

Service Principals

View, Edit, and Delete Service Principals

Select a [Tenant Name]Drop down menu to view a list of Service Principals for that Cloud Tenant. 

To View and Edit:

  1. Click on a Service Principal Name link or highlight a row and clickEdit to open the Details panel.
  2. Click Copy to Clipboard to copy the information.
  3. Edit the Name and Description.
  4. Update the Authentication Type
    1. Basic—credentials pass in the basic authorization header as part of the token request.
    2. Post—credentials pass in the request body as part of the token request. 
  5. Click Save.

To Delete:

  1. Select the row of a Service Principal.
  2. Click .
  3. Click Delete to confirm.

Deleting a Service Principle causes any integration using it to fail immediately and cannot be reversed. You must create a new Client ID and Secret to reinstate the integration.

Rotate or Revoke a Secret

Rotating a Secret keeps two Secrets valid for a period of time. When you rotate the Secret, the system sends a call to the authentication server which provides a new Secret and deprecates the current one. The deprecated Secret remains viable for no more than 30 days to provide you time to configure the new Secret in your code without disrupting existing integrations. You can select to revoke the Secret prior to 30 days.

  1. Select a [Tenant Name]Drop down menu to view a list of Service Principals for that Cloud Tenant. 
  2. Click on a Service Principal Name link or highlight a row and clickEdit to open the Details panel.
  3. Click Revoke Secret.
    Calls using revoked access tokens fail to authenticate with a '401 Unauthorized error' HTTP status code. 
  4. Select a time range to revoke the previous Secret.
  5. Click Rotate Secret.

Use Case 

As a DevOps engineer, you implement an application for creating cloud connections. The integration has been running on your system for several weeks and has created several successful connections. The company security policy requires you to rotate integration Secrets every 90 days. You want to ensure that the current Secret is not usable by an outside party yet still allows the integration to continue working.

You immediately access the Cloud Tenant Service Principal Details page through Account Management and rotate the Secret to generate a new one. You replace the old Secret in the integration with the new Secret and restart the application. Since you no longer need the old Secret, you want to revoke it. You go back to the Cloud Tenant Service Principal Details page and now you see that you are able to revoke the Secret.