Authentication

Some end-points are protected and require authentication information to allow access. If the required authentication information is not present, then the API will indicate this with a 400 Bad Request response, with the reason stated as invalid_grant.

Authentication is performed using OpenID Connect which when complete enables the calling client to request OAuth2 access tokens to use the API. The client should be prepared to respond to a invalid_grant response at any point, and in particular both Enumeration and Launch requests may require the client to obtain fresh authentication information.

When building your own application, it is recommended to use a session-based Token Management Service, which would manage duration of and access to OAuth 2.0 access tokens. See our provided example here.

To find out more about OAuth, the flows and core concepts, visit the official RFC.

Citrix Authorization Server

The Citrix Authorization Server endpoint configuration can be found in your customer discovery configurations document as shown in the getting started guide, under clientSettings - oidcConfiguration - oidc_discovery_endpoint.

Performing a get request on the oidc_discovery_endpoint will provide you with the authorization server configuration, specifically this authentication guide we are interested in the authorization_endpoint and the token_endpoint.

For the purposes of this document we will use the following values:

• authorization_endpoint: https://accounts.cloud.com/core/connect/authorize
• token_endpoint: https://accounts.cloud.com/core/connect/token

Obtaining an Access Token

Once you’ve created your client, you can then try to obtain the Access Token to use in the Unified Workspace APIs to perform actions such as resource enumeration, launching and favoriting.

Your client application should perform an OAuth Authorization Code Flow with Proof Key for Code Exchange (PKCE) as described below. You can refer to our client examples to see how we’ve achieved that in .NET. There any many client libraries in your language of choice for performing the OAuth flow. We also support the standard OAuth Authorization Code Flow but only for Private Clients.

Citrix’s access token is valid only for 30 minutes for security reasons. If you’d like to get a new one without user interaction, see Refresh Tokens.

Refresh tokens (offline access)

Conditions for getting a Refresh Token:

1. The client being used has Offline Access enabled, configured during client creation
2. During the Authorization Code Flow with PKCE the scope offline_access is sent

If the conditions are met, a Refresh Token will be provided alongside an Access Token.

The Refresh Token can be used to get a new Access Token without user interaction:

1. The client application makes a POST request to the Citrix Authorization Server token endpoint https://accounts.cloud.com/core/connect/token with the following information in the request body, and a Content Type set to application/x-www-form-urlencoded:

   Form Field	Form Value	Description
   client_id	Your client ID	See Client Management
   client_secret	Your client secret	Optional, only required for Private clients
   grant_type	refresh_token	Indicates that a refresh request is in progress
   refresh_token	Your refresh token	The refresh token that is generated during the Authorization Code Flow

   Raw example:

    POST https://accounts.cloud.com/core/connect/token
    Content-Type: application/x-www-form-urlencoded
    client_id={CLIENT_ID}&client_secret={CLIENT_SECRET}&grant_type=refresh_token&refresh_token={REFRESH_TOKEN}
    <!--NeedCopy-->
   

2. The Citrix Authorization Server will respond with a new Access Token and Refresh Token.

The lifetime of Citrix’s refresh token is 24 hours.

Example of OAuth Authorization Code Flow

To perform the standard Authorization Code Flow, refer to the example for Authorization Code Flow with PKCE and ignore the code_verifier, code_challenge and code_challenge_method specific steps and properties from API calls.

We recommend using the Authorization Code Flow with PKCE for the highest level of security.

Example of OAuth Authorization Code Flow with Proof Key for Code Exchange (PKCE)

For this example, we are going to use the sample WebClient application.

This is the recommended flow for the highest level of security.

1. The user enters their customer URL in the login box and clicks ‘Login’

   

2. The client SDK creates a one-time cryptographically random 128-byte code_verifier and uses this to generate a code_challenge (Base64 URL encoded string containing the SHA-256 digested form of the code_verifier)

3. The client SDK redirects the user to Citrix Authorization Server via a GET request to https://accounts.cloud.com/core/connect/authorize and sends various bits of information in the QueryString:

   Query Field	Query Value	Description
   client_id	Your client ID	See Client Management
   redirect_uri	https://localhost:7182/callback	This is the callback of the locally running WebClient example
   response_type	code	Specifies that we are using the Authorization Code Flow
   scope	openid wsp spa leases offline_access	The values ‘openid wsp spa leases’ are required, if you selected Offline Access during client creation also include ‘offline_access’
   code_challenge	Your Code Challenge	As mentioned above, encoded SHA-256 digested form of the code_verifier
   code_challenge_method	S256	Must be S256 to indicate we are using PKCE SHA-256 Signature
   prompt	Login	Indicates to the Authorization Server we should prompt the end user for re-authentication.
   response_mode	form_post	Indicates that the response parameters are encoded in the body using application/x-www-form-urlencoded format.
   acr_values	Customer ACR Values	Citrix specific value for additional validation purposes, can be obtained via the customer discovery configuration
   state	Your State Value	Randomly generated string, used to prevent CSRF attacks.

   Note: The WebClient C# library also adds a cryptographic number-used-only-once (nonce) value, along with a state.

   Raw example:

    GET https://accounts.cloud.com/core/connect/authorize?client_id={CLIENT_ID}&redirect_uri={REDIRECT_URI}&response_type=code&prompt=Login&scope=openid%20wsp%20spa%20leases%20offline_access&code_challenge={CODE_CHALLENGE}&code_challenge_method=S256&response_mode=form_post&acr_values={ACR_VALUES}&state={STATE}
    <!--NeedCopy-->
   

4. Citrix Authorization Server redirects the user to the login screen, the previous request will result in a 302 Found response with the Location header set to the login screen:
5. After authentication, the end user might see a consent page depending on the OAuth Client configuration
6. Upon successful login, Citrix Authorization Server stores the code_challenge and redirects the user back to the application (WebClient example) with an authorization code valid for one-time use
7. The state value provided during the authorization call will be returned in the /callback?... query string and body, which must be compared against the sent state to protect from CSRF attacks

8. The client SDK then calls the token endpoint (https://accounts.cloud.com/core/connect/token) and sends the authorization code and code_verifier created in step 2 along with client information with the Content Type application/x-www-form-urlencoded:

   Form Field	Form Value	Description
   client_id	Your client ID	See Client Management
   client_secret	Your client secret	Optional, only required for Private clients
   code	Your authorization code	The authorization code sent back to the client in step 6
   grant_type	authorization_code	Tells the server we are performing the authorization code flow
   redirect_uri	https://localhost:7182/callback	This is the callback of the locally running WebClient example
   code_verifier	Your code verifier	The code_verifier created in step 2

   Raw example:

    POST https://accounts.cloud.com/core/connect/token
    Content-Type: application/x-www-form-urlencoded
    client_id={CLIENT_ID}&client_secret={CLIENT_SECRET}&code={AUTHORIZATION_CODE}&grant_type=authorization_code&redirect_uri={REDIRECT_URI}&code_verifier={CODE_VERIFIER}
    <!--NeedCopy-->
   

9. Citrix Authorization Server validates the code_challenge and code_verifier
10. Citrix Authorization Server responds with the access token (and optionally a refresh token if your client has Offline Access and you sent offline_access in the scopes during step 3)
11. The WebClient application can then call Unified Workspace APIs such as Resources

Authentication Errors

400 Bad Request

There are some potential errors that could occur during the authentication flows and while making requests to the APIs. We closely follow the OAuth RFC error responses and a 400 Bad Request error will be returned and include more details in the response body.

For example, a 400 response will be returned when trying to call an API without a valid Access Token:

{
    "error": "invalid_grant",
    "error_description": "Access token is invalid."
}
<!--NeedCopy-->

Possible reason for the 400 Bad Request response:

• Missing Access Token
• Invalid or expired Access/ Refresh token
• Client is invalid
• Scope is invalid

Unable to Process Your Request

The following error page could be returned by the Citrix Authorization Server during the authentication flows:

Likely reasons for this page being shown:

• Client is disabled
• The redirect URI being sent during the authorization code flow is not configured as an ‘Allowed redirect URI’ on the client
• The client is trying to send an offline_access scope during the authorization code flow and offline access was not configured on the client

If the error persists, please contact Citrix Support and provide the Transaction ID.