Create Service Principals

This page describes how to create and use Service Principals to provide secure access to Cisco Cloud Observability 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 Cisco AppDynamics public APIs on your Observability Platform tenant. Service Principals have read-only privileges by default. You must assign the Service Principal to a Observability Platform tenant role to escalate privileges on that Observability Platform tenant. See Assign Tenant Roles.

Create Service Principals

To create a Service Principal you must be a Company Administrator and own a Observability Platform tenant.

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 Observability Platform tenant associated with the account.
3. Select a Observability Platform tenant from the dropdown if you have more than one associated with your account.
4. Click to create a new Service Principal specific to the chosen Observability Platform tenant. 
   
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 Assign Role Access to assign a role to a Service Principal.
8. Select roles from the Default Roles and Custom Roles for the Service Principal. See Manage Custom Roles for Cisco Cloud Observability.
9. Click Save.

10. Click Create to obtain the Tenant ID, Token URL, Client ID, and Secret. 

    

11. Select to Copy all information at once, Download a secret.json file, or click 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.

12.  Click Close.

Get an Access Token

You use the client ID and client secret from your Service Principal to make calls to the Cisco AppDynamics OAuth API to generate an access token. With the access token, you can make calls to Cisco AppDynamics APIs. 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.

Manage Service Principals

Service Principals are Observability Platform tenant-specific. Any management you perform on a chosen Observability Platform tenant will not convey to another Observability Platform tenant. Therefore, if you have multiple Observability Platform tenants and want to write code that can act on each one, you must create and maintain a Service Principal and Secret per Observability Platform 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 Observability Platform tenant.

View, Edit, and Delete Service Principals

Select a [Tenant Name] to view a list of Service Principals for that Observability Platform tenant. 

To View and Edit:

1. Click on a Service Principal Name link or highlight a row and click to open the Details panel.
2. Click  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] to view a list of Service Principals for that Observability Platform tenant. 
2. Click on a Service Principal Name link or highlight a row and click 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 Observability Platform 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 Observability Platform tenant Service Principal Details page and now you see that you are able to revoke the Secret.