Get started with Citrix Cloud APIs - Service Principals Preview

Citrix Cloud services streamline the delivery and management of Citrix technologies, allowing you to extend existing on-premises deployments or fully transition to the cloud.

Get Access to Citrix Cloud

Sign up for a free Citrix Cloud account, or log in to Citrix Cloud.

Citrix Cloud API Access with Service Principals

A service principal acts as an API client to Citrix Cloud APIs and have the following characteristics:

• Service principals have their own roles and permissions. These roles and permissions are distinct from the creator’s roles and permissions.
• Service principals are scoped to a single Citrix Cloud customer. To access more than one customer, you must create a distinct service principal within each customer.
• Service principals are not associated with an email.
• Service principals’ secrets expire on an expiration date of your choosing. A secret management standard operating procedure is provided below here.
• Service principals management, like CRUD operations, require full access administrator privileges.
• Service principals in tech preview will only support custom access. Full access will be available as soon as all resource provider services are supported.
  • The following services are currently unavailable for Service Principals: Netscaler Console, Secure Private Access

Automation integrations in applications and scripts can leverage service principals for access to Citrix Cloud APIs.

This document will highlight 3 steps to set up a service principal and make an authorized request to a Citrix Cloud API endpoint.

1. Create a Service Principal

1. In the Citrix Cloud console, click the menu in the upper left corner.

   

2. Select Identity and Access Management > API Access > Service principals (Preview) > Create service principal and follow the steps to completion.

   If these options do not appear, you may not have sufficient permissions to manage service principals. Contact your administrator to get the required full access permission.

   

3. Add the credentials to your secret management tool as the secret will only appear once.

   

2. Generate a Bearer Token

Using the clientId and secret from the previous step, obtain a bearer token using a standard OAuth 2.0 Client Credential Grant (IETF RFC 6749 Section 4.4).

Call POST https://api.cloud.com/cctrustoauth2/{customerid}/tokens/clients

Note:

Use https://api.citrixcloud.jp if your Citrix Cloud account is set to the Japan region.

Request sample:

POST https://api.cloud.com/cctrustoauth2/customer123/tokens/clients HTTP/2
Accept: application/json
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id={client_id}&client_secret={client_secret}
<!--NeedCopy-->

Response sample:

HTTP/2 200 OK
Content-Type: application/json
...

{
    "token_type": "bearer",
    "access_token": "ey1..",
    "expires_in": "3600"
}
<!--NeedCopy-->

3. Make an Authorized Request

You may use this bearer token to make authorized calls to Citrix Cloud APIs. Pass in an HTTP Authorization Header in the following format using the access_token value.

Authorization: CwsAuth Bearer={access_token}
<!--NeedCopy-->

Browse the portal to learn about all available Services and their APIs.

You may get access to additional Citrix Cloud Services using the following:

• Trials
• Purchases

Service Principal Secret Management

Service principals may have a primary and secondary secret where both secrets may be functional and valid at any given time. Service principal secrets include secret expiration for better security practices. You may rotate a secret with zero downtime through the UI. Secret Rotation automation via APIs will be available after full access service principals are supported.

Creating a new secret will effectively “rotate” secrets — the primary is set to the new secret, secondary is set to the old primary, and the existing secondary is deleted if it exists.

Example 1

Before rotation: PrimarySecret = "secret1", SecondarySecret = null

After rotation: PrimarySecret = "secret2", SecondarySecret = "secret1"

Example 2

Before rotation: PrimarySecret = "secret2", SecondarySecret = "secret1"

After rotation: PrimarySecret = "secret3", SecondarySecret = "secret2"

Rotating Secrets via the UI

1. Create a New Secret

Navigate to Manage secret > Create new secret and follow the prompts.

2. Update Automations, Integrations, and Deployments

Update automations, integrations, deployments, secret servers, etc. to use the new primary secret.

3. Delete Secondary Secret

Delete the secondary secret to maintain only one functioning secret at a given time.

Secret Management Best Practices

Here are some best practices for managing your service principal secret:

• Avoid Hardcoding Secrets: Hardcoding secrets directly in code, configuration files, or version control is a significant security risk. If these files are accidentally exposed or compromised, the secrets within them can be readily accessible. Avoid embedding sensitive information in source code whenever possible.
• Use Secrets Management Tools: Dedicated secret management tools provide secure storage, management, and access control for secrets. These tools automate secret encryption, access management, and secure retrieval, enhancing security and reducing manual management.
• Use Environment Variables: Storing secrets in environment variables is a secure and convenient alternative to hardcoding. Environment variables keep secrets separate from code, reducing the risk of accidental exposure in code repositories. When possible, use environment-specific configuration files to manage secrets securely.
• Regularly Rotate Secrets: Rotating secrets at regular intervals reduces the risk of exposure if a secret is compromised. Implement an automatic rotation policy, where feasible, to change secrets periodically without manual intervention. Ensure your application or system can handle regular rotations and updates without disruptions.

Manual API: Developer Portal Flow

For manual API interactions, use the Developer Portal UI to generate bearer tokens.

1. Navigate to any Citrix Cloud service on the developer portal. On the API Exploration tab, click on any API from the list. Click on the Invoke API button.

2. In the request Authorization header parameter description, click Generate here. The Set Authentication window appears.

3. Enter a service principal Client ID and Secret. Click Generate. A bearer token is generated using the Client ID and Secret and populated in the Authorization header field.