OAuth Client Management

Application ID

An application ID is required to make API requests to the Unified Workspace API, in order to obtain one you will need to create an OAuth client as described on this page.

API requests must contain either the Citrix-ApplicationId header, or the ApplicationId query parameter with the value set to the above mentioned application ID.

OAuth Client Registration

To perform the OIDC authentication steps, it will be necessary to request a Client.

Depending on the type of application you want to build, a public client, private (confidential) client will need to be requested.

Public Client

For native applications that will handle the authorization code flow with PKCE and store the access and refresh token in memory, you will need to request a public client as the application won’t be able to securely store the private client secret.

Private Client

For server side web clients - including the example Token Management Service - you should request a private client. The private client will use the standard authorization code flow or the authorization code flow with PKCE.

Creating a Client

1. Login to the Citrix Cloud Admin Portal and select the customer you’d like to register a client for. The account you login with needs to be either be a ‘Full’ admin, or a custom admin with the ‘Workspace OAuth Clients’ permission selected.

   

   Warning:

   It is recommended to assign the Workspace OAuth clients custom role with caution. The access privileges associated with this role might enable administrators to access end user’s resources (VDAs or applications) on the Workspace platform. It is also important to note that administrators with Full access will automatically have access permissions equivalent to that of an administrator with the Workspace OAuth clients permission.

2. Navigate to ‘Identity and Access Management’ - ‘API Access’ - ‘Workspace API’

   

3. Select ‘Create Client’ and fill out the required details, here is an example that will work with the sample applications:

   

4. For a Private Client, once you click ‘Create’ a modal will appear with the Client ID and Secret for you to download and copy:

   

5. You will be able to see all your created clients on the page:

   

Client Validity and Rotation Requirements

For Private Clients only.

Client secrets are valid for a period of 90 days and will need rotating before this elapses. Please see instructions on rotating the client secret below.

Before undertaking development that will rely on your client secret being valid, ensure that you are able to rotate, update applications using, and expire your client secret using the guide.

OAuth 2.0 Client Rotation

OAuth 2.0 private clients are valid for a period of 90 days. The validity period ensures that the owner of the client follows recommended security practices.

An email will be sent to the ‘Owner Contact’ when the client gets close to expiry.

To rotate the client:

Manual Rotation

1. Login to Citrix Cloud Admin Portal and navigate to ‘Identity and Access Management’ - ‘API Access’ - ‘Workspace API’.

2. Find the client you want to rotate in the client list (a warning will be shown when a client is close to expiry), click on the three dots, and select ‘Edit this client’:

   

3. Here you will be able to see the client details and perform a few operations, here we are interested in the ‘Client Secret Expiration date’ and the ‘Rotate Client Secret’ button:

   

4. Clicking the ‘Rotate Client Secret’ button will show you a page giving some more information on client rotation. Once agreeing to the terms, click ‘Rotate’:

   

5. A modal will show you the new Client secret including the Client ID, giving you the ability to download and copy the information:

   

Once the client has been rotated, you can start using the new Client secret in your application, and the old secret will continue to work until it expires, or until you trigger an expiry:

1. Navigate to the client details page by clicking ‘Edit this client’ and you’ll be able to see the new secret Expiration date, alongside the old secret Expiration date:

   

2. Click on the ‘Expire Now’ secret to bring up the confirmation page:

   

3. A confirmation will be displayed showing the old Client secret has been expired and will no longer work:

   

Programmatic Rotation

It is possible to perform the client rotation and secret expiry using the Citrix Cloud API, this might be useful if you want to automate the client rotation.

Before you perform the rotation, consider the following:

• The existing Client Secret will expire automatically after remaining valid days.
• You will need to manually update your app to start using the newly generated Client Secret.

To perform the rotation:

1. Follow the Citrix Cloud API guide to create a secure client and obtain a CC Bearer Token.

2. Perform a web request to find all your customer clients to find the client name which will be used to perform the rotation:

   Request:

    curl https://cws.citrixworkspacesapi.net/{CUSTOMER_ID}/rpclients --header "Authorization: CWSAuth bearer=$token"
    <!--NeedCopy-->
   

   Note: The CUSTOMER_ID can be found on the Citrix Cloud secure client page (see step 1).

   Response:

    [
        {
            "name": "customer-private-305",
            "display_name": "Demo Client",
            "api_key": "api_key",
            "secret_update_time": 1686218219,
            "secret_expiration": 1693958400,
            "secret_update_time_old": null,
            "secret_expiration_old": null,
            "owner": "customer@customer.com",
            ...
        },
        ...
    ]
    <!--NeedCopy-->
   

3. Using the above response, you can determine if you want to rotate the client based upon the secret_expiration value, which is a Unix timestamp.

4. Perform a web request to rotate the client. In the response, you’ll see the secret time values update, and a new secret value which is valid for another 90 days.

   Request:

    curl -X POST https://cws.citrixworkspacesapi.net/{CUSTOMER_ID}/rpclients{CLIENT_NAME}/$rotateSecret --header "Authorization: CWSAuth bearer=$token"
    <!--NeedCopy-->
   

   Response:

    {
        "client": {
            "name": "customer-private-305",
            "display_name": "Demo Client",
            "api_key": "api_key",
            "secret_update_time": 1691151918,
            "secret_expiration": 1698927918,
            "secret_update_time_old": 1691151918,
            "secret_expiration_old": 1693958400,
            "owner": "customer@customer.com",
            ...
        },
        "secret": "{NEW_SECRET}"
    }
    <!--NeedCopy-->
   

Once the client has been rotated, you can start using the new Client secret in your application, and the old secret will continue to work until it expires, or until you trigger an expiry.

To perform an expiry of the old secret:

1. Ensure you have updated your app to use the new Client Secret, as it will not be possible to authenticate using the expired client secret.

2. Perform a web request to expire the old secret:

   Request:

    curl -X POST https://cws.citrixworkspacesapi.net/{CUSTOMER_ID}/rpclients/{CLIENT_NAME}/$expireOldSecret --header "Authorization: CWSAuth bearer=$token"
    <!--NeedCopy-->
   

   Response will be a 200 OK with an empty body, indicating the secret has been expired.

Enable and Disable Clients

Newly created clients are enabled by default. However, it is possible to disable them in the admin portal. This will cause any application using them to stop working until the client is re-enabled.

The status of a client can be seen on the client page:

Clicking on the three dots, you can select ‘Disable this client’ and tick the confirmation box:

Once disabled, the client will now show that on the client page:

It can then be re-enabled following a similar process.

If the client is disabled and an application attempts to use it for the authorization code flows, it will get a 400 Bad Request back from the Citrix Authorization Server as detailed here.

Editing a Client

You can edit the following information for a client:

• Display Name
• Requiring User Consent
• Redirect URIs

1. Login to Citrix Cloud Admin Portal and navigate to ‘Identity and Access Management’ - ‘API Access’ - ‘Workspace API’.

2. Find the client you want to edit in the client list, click on the three dots, and select ‘Edit this client’:

   

3. Click on the Client settings tab:

   

4. Make any changes and click ‘Save’.

Deleting a Client

Deleting a client will mean that any application using the client will stop working.

To delete a client via the dropdown menu:

1. Login to Citrix Cloud Admin Portal and navigate to ‘Identity and Access Management’ - ‘API Access’ - ‘Workspace API’.

2. Find the client you want to delete in the client list, click on the three dots, and select ‘Delete this client’:

   

3. A confirmation will appear. Select the confirmation and click ‘Delete Client’:

   

4. The client will now be deleted and disappear from the client list.

You can also delete the client via the client details page: