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. 

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 Tenant associated with the account.
  3. Select a Tenant from the dropdown if you have more than one associated with your account.
  4. Click Create to create a new service principal for that Tenant. 
    Create Service Principals
  5. Enter a meaningful Name that represents the intended use.
  6. Enter a meaningful Description.
  7. 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. 
  8. Click Create to obtain a Client ID and Secret

    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 has become compromised, you can revoke the secret or delete the Service Principal which prevents the generation of a new token with that secret.

  9. Select either to Download a secret.csv file or Copy the Client ID and Secret.  
  10. 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"
}
CODE


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 Tenant. In other words, 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.

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

  1. Select a [Tenant Name]Drop down menu to view a list of Service Principals for that Tenant. 
  2. (Optionally) Search for a Service Principal within the Tenant selected.
  3. Check the box for the preferred Service Principal.

To View:

Click View to view:

  • Name
  • Description
  • Authentication Type
  • Client ID

To Edit:

  1. Click Editto open the Details page.
  2. Edit the Name and/or Description.
  3. 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. 
  4. Click Save.

To Delete:

  1. Select the row of a Service Principal to reveal actionable options.
  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 old one. The old secret remains viable for 30 days unless you revoke it prior to that time period.

  1. Select a [Tenant Name]Drop down menu to view a list of Service Principals for that Tenant. 
  2. Check the box for the preferred Service Principal.
  3. Click View.
    • Click Rotate to generate and display a new secret for copy or download.

      Rotating a secret does not disable the older one. An old secret remains active for up to 30 days unless you revoke it prior to that time period.

    • Click Revoke Old Secret to revoke the secret.
      Calls using revoked access tokens fail to authenticate with a '401 Unauthorized error' HTTP status code. 

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 allow 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.