Entra ID authentication via OIDC and single sign-on to VDA
StoreFront Entra ID integration with NetScaler Gateway
This article describes how to set up remote StoreFront access using a NetScaler Gateway virtual server with AAA Entra ID and OIDC. This configuration provides Microsoft Entra ID SSO for users who use Citrix Workspace app or a web browser.
Prerequisites
- NetScaler
- StoreFront 2507 CU1 or higher
- Microsoft Entra ID and account with one of the following permissions:
- Cloud Application Administrator
- Application Administrator
- Global Administrator
- DaaS subscription with connectors
- Published desktops and/or apps
- For launches from a web browser into Citrix Workspace app, to enable SSO to VDAs, Citrix web extension.
Azure application registration
Create a Microsoft Azure Entra ID application
An App Registration in Microsoft Entra ID defines your application so that Entra ID recognizes it—in this case, NetScaler OIDC. This registration also manages the application’s authentication and authorization requests. Because OAuth requires a trusted Identity Provider (IdP) to authenticate users and issue tokens, registering your app tells Entra ID: “This application uses you as its IdP for OAuth flows.”
- Sign in to the Azure portal for the Entra ID tenant that you use for NetScaler or StoreFront authentication.
- Go to Microsoft Entra ID resource > Manage > App registrations, then select New registration.
- Name the application, for example, NetScaler StoreFront Authentication.
- Under Supported account types, select Accounts in this organizational directory only.
-
Under Redirect URI, select Web for the type of application you want to create. Enter the URI where the access token is sent. Use the format <NetScaler Virtual Server URL>/oauth/login, for example
https://netscalerentra.customer.com/oauth/login.
Create client secret
To create client secret:
- After you register the application, go to Manage > Certificates & Secrets.
- Select Client secrets, and then select New client secret. Your app uses these credentials to securely communicate with the IdP and request tokens.
- Provide a description of the secret and a duration.
- After you create the secret, record the secret value because you need it later in the setup process and it’s only visible during this stage of creation.
Configure application permissions
To configure app permissions:
- Go to Manage > App registrations, then select your application.
- Select Manage > API Permissions.
- The User.Read permission is already added by default.
- Add openid and profile.
- Select Grant admin consent for <tenant name> and accept.
“Grant admin consent for” in API permissions in Microsoft Entra ID means that an administrator gives approval, on behalf of all users in the organization, for an application to access specific resources or APIs with the requested permissions.
Configure Citrix DaaS
Configure XML trust and optional service keys
XML trust for Citrix DaaS (Desktop as a Service) allows StoreFront to pass the relevant Microsoft Entra ID user credentials. You need XML trust if you use authentication methods like pass-through authentication, smart cards, SAML (Single Sign-On), or OIDC that don’t rely on a password.
- Sign in to Citrix Cloud and go to the DaaS console.
- Go to Settings.
-
Turn on XML trust.
- (Optional step) For added security you can enable security keys between DaaS and StoreFront. For more information, see Manage security keys in the Citrix DaaS™ documentation.
Configure Citrix NetScaler
Configure NetScaler Gateway with StoreFront
Complete steps 1, 2, and 4 from Integrate NetScaler Gateway with StoreFront.
- Create a session policy for web browser-based access.
-
Create a session policy for Citrix Workspace app-based access.
a. Setting up a CWA session also requires a profile, so you must include the following steps that are missing in the document for the CWA session.
i. In the **Session Policies** tab, click **Add**. The session policy is required for NetScaler to differentiate between the web browser-based and Citrix Workspace app-based connections. This policy is applied to web browser-based connections. ii. In **Name**, assign a name to session policy. iii. In **Profile**, select the session profile that you created. iv. Click the **Advanced Policy** option and enter the following syntax under **Expression**: ```HTTP.REQ.HEADER("User-Agent").CONTAINS("CitrixReceiver")<!--NeedCopy--> ``` v. Click **Create**. - See Configure Authentication ICA Proxy virtual server in the upcoming sections.
-
Create a NetScaler Gateway virtual server.
a. The ICA Proxy virtual server name is required for the additional Entra ID configuration described as follows.
Configure authentication
Create the OAuth action and policy to set up the Authentication virtual server as an OIDC Relying Party for Microsoft Entra ID. This configuration tells the ADC how to redirect users to an external OAuth IdP (like Microsoft Entra ID) for sign-in and how to handle the OAuth tokens received after authentication. It specifies endpoints, client credentials, scopes, and how the ADC extracts user information from tokens.
You need the client secret from the previous steps and the Microsoft Entra ID authentication endpoints. You can find the authentication endpoints in the Azure portal by going to your App Registration Overview and clicking the Endpoints tab.
Create authentication virtual server
The authentication virtual server handles authentication for users before they access backend resources (like StoreFront, web apps, VPN, and so on).
Run these commands on the NetScaler command line with line breaks removed (breaks are added for readability).
add authentication vserver EntraId_Authentication_VirtualServer SSL <IP Address> 443
-state ENABLED
-authentication ON
-td 0 -appflowLog ENABLED
-noDefaultBindings NO
bind ssl vserver EntraId_Authentication_VirtualServer
-certkeyName <Certificate Key Name>
<!--NeedCopy-->
Create OAuth action
The OAuth action specifies how NetScaler ADC interacts with an OAuth IdP (like Microsoft Entra ID, Okta, or Google). This action allows ADC to redirect users to the IdP for sign-in and handle the OAuth token returned. It facilitates single sign-on (SSO) for applications published through Citrix Gateway.
You need the Client ID and Client secret from the previous steps.
add authentication OAuthAction EntraId_Oauth_Server
-authorizationEndpoint "https://login.microsoftonline.com/<TenantId>/oauth2/v2.0/authorize?prompt=login"
-tokenEndpoint "https://login.microsoftonline.com/<TenantId>/oauth2/v2.0/token"
-clientID <ClientId>
-clientSecret <ClientSecret>
-Attribute1 email
-Attribute2 family_name
-Attribute3 given_name
-Attribute4 upn
-CertEndpoint "https://login.microsoftonline.com/<TenantId>/discovery/v2.0/keys"
-userNameField oid
-allowedAlgorithms HS256 RS256 RS512
-PKCE ENABLED
-tokenEndpointAuthMethod client_secret_post
-OAuthType GENERIC
-grantType CODE
-refreshInterval 1440
<!--NeedCopy-->
The authorizationEndpoint includes the query string parameter prompt=login so that users are forced to reauthenticate when they attempt to access StoreFront through the NetScaler.
Create OAuth policy
Create a policy used to trigger the preceding OAuth Action
add authentication Policy EntraId_Authentication_Policy
-rule true
-action EntraId_Oauth_Server
<!--NeedCopy-->
Bind the authentication policy to the virtual server
bind authentication vserver EntraId_Authentication_VirtualServer
-policy EntraId_Authentication_Policy
-priority 100
-gotoPriorityExpression END
<!--NeedCopy-->
Add authentication profile to Auth virtual server
add authentication authnProfile EntraId_Auth_Profile
-authnVsName EntraId_Authentication_VirtualServer
-AuthenticationLevel 0
<!--NeedCopy-->
Bind AAA authentication server to StoreFront virtual server
Bind the configured AAA authentication server to your ICA Proxy virtual server. When you bind at the StoreFront virtual server level, authentication occurs directly when users access the StoreFront endpoint.
Running this command replaces the existing authentication profile bound to the ICA Proxy/StoreFront virtual server with EntraId_Auth_Profile. It doesn’t remove other unrelated bindings, but it does override whatever authentication profile was previously in use.
Consider backing up the existing ICA Proxy virtual server configuration before you run this command so that you can revert the changes if necessary.
set vpn vserver <StoreFront ICA Proxy vServer>
-authentication ON
-authnProfile EntraId_Auth_Profile
<!--NeedCopy-->
Entra ID token injection configuration for SSO
When you pass the Entra ID token, users authenticated through Azure AD/OAuth on NetScaler Gateway don’t need to enter credentials again at StoreFront. The rewrite rule takes the Entra ID token received at NetScaler Gateway and inserts it into the authentication HTTPS requests sent to StoreFront. StoreFront recognizes and validates the token, then signs in the user based on its claims.
The NetScaler rewrite policy requires that you enable the feature.
enable ns feature Rewrite
add rewrite action EntraId_Oauth_Insert_AccessToken_Header insert_http_header X-Citrix-OIDC-Access-Token "AAA.USER.ATTRIBUTE(\"accesstoken\")"
-comment "A rewrite policy to add the OAUTH access_token to subsequent user authentication requests"
add rewrite policy EntraId_Oauth_Insert_AccessToken_Policy "HTTP.REQ.URL.TO_LOWER.ENDSWITH(\"gatewayauth/login\") || HTTP.REQ.URL.TO_LOWER.ENDSWITH(\"citrixagbasic/authenticate\")" EntraId_Oauth_Insert_AccessToken_Header
-comment "A rewrite policy to add the OAUTH access_token to subsequent user authentication requests"
bind vpn vserver <StoreFront ICA Proxy vServer>
-policy EntraId_Oauth_Insert_AccessToken_Policy
-priority 100
-gotoPriorityExpression END
-type REQUEST
<!--NeedCopy-->
Configure NetScaler content switcher
You have two options for configuring content switching.
You need a NetScaler content switching policy to route requests to the unauthenticated /Citrix/<StoreWeb>/Tickets/RedeemStoreTicket endpoint on the StoreFront server. This ensures that the Microsoft Entra ID SSO flow completes successfully, because requests to this URL originate from the Citrix Entra ID client page and must be specially routed.
Add backend server for content switching
Replace storefront.fqdn.com with the FQDN that you use as the StoreFront host base URL.
This service represents the backend StoreFront server, accessible through HTTP on port 80. You can use it in load balancing or other traffic management configurations on NetScaler.
add server storefront1 storefront.fqdn.com
add service srv storefront1 HTTP 80
<!--NeedCopy-->
The SSL backend service represents a backend server accessible through HTTPS on port 443. NetScaler can use this service for load balancing, content switching, or other traffic management. Change the private IP address srv_ssl IP Address to represent your network.
add service srv_ssl <srv_ssl Ip Address> SSL 443
<!--NeedCopy-->
HTTP load balancing virtual server
You have two options here: forward requests to StoreFront on port 80 HTTP or port 443 (SSL).
Create a server that listens on all IPs/ports with no persistence. Use this in a content switching setup where the virtual server itself doesn’t need a dedicated IP/port.
add lb vserver lb_vs HTTP 0.0.0.0 0 -persistenceType NONE -cltTimeout 180
<!--NeedCopy-->
Create an SSL load balancing virtual server on a specific IP and port with no persistence. This sets up an SSL virtual server to handle HTTPS traffic on IP
add lb vserver lb_ssl SSL <lb_ssl Ip Address> 443 -persistenceType NONE -cltTimeout 180
<!--NeedCopy-->
Bind service to load balancing virtual server where the protocol type is HTTP
Bind the server storefront.fqdn.com represented by srv to a load balancer. At this point, you can bind multiple StoreFront servers that are used for the final step of the Microsoft Entra ID single sign-on.
bind lb vserver lb_vs srv
<!--NeedCopy-->
Bind SSL service to load balancing virtual server where the protocol type is HTTPS
This enables the lb_ssl virtual server to route incoming SSL (HTTPS) traffic to the backend server or service defined as srv_ssl. Without this binding, the virtual server has no backend servers to send client requests to.
bind lb vserver lb_ssl srv_ssl
<!--NeedCopy-->
Create SSL content switching virtual server
Create an SSL content switching virtual server to handle client requests.
This content switching virtual server listens for HTTPS traffic on port 443 and routes requests to the appropriate backend services or load balancers.
Note:
Content Switching isn’t enabled by default on NetScaler and you must explicitly configure it.
enable feature CS
add cs vserver cs_vs SSL <cs_vs Ip Address> 443 -cltTimeout 180 -persistenceType NONE
bind ssl vserver cs_vs -certkeyName <Certificate Name>
<!--NeedCopy-->
Define content switching action (VPN)
Define a content switching action to redirect matching traffic to the ICA Proxy virtual server. Create the action with the name cs_vpn_vs, configured to route matching requests to the target virtual server. The exact virtual server name varies depending on what was specified in the earlier StoreFront virtual server configuration steps.
add cs action cs_vpn_vs -targetVserver <StoreFront ICA Proxy vServer>
<!--NeedCopy-->
Define content switching action (LB)
Define a content switching action to redirect matching traffic to the ICA Proxy virtual server. Create the action with the name cs_vpn_vs, configured to route matching requests to the target virtual server. The exact virtual server name varies depending on what was specified in the earlier StoreFront virtual server configuration steps.
If the backend server is configured to communicate over the HTTPS protocol
add cs action cs_lb_vs -targetLBVserver lb_ssl
<!--NeedCopy-->
Or if the backend server is configured to communicate over the HTTP protocol
add cs action cs_lb_vs -targetLBVserver lb_vs
<!--NeedCopy-->
Create content switching policy
Create a content switching policy for load balancing based on a URL containing a StoreFront ticket redemption path. Replace “StoreEntraWeb” with the name of the StoreFront website from the StoreFront virtual server web policy.
This policy matches requests when the URL contains /Citrix/StoreEntraWeb/Tickets/RedeemStoreTicket. Action: Routes those matching requests to the content switching action cs_lb_vs (which, in turn, sends them to the appropriate backend, such as a load balancing virtual server). This ensures that requests for the StoreFront Entra ID ticket redemption endpoint are properly routed to the backend StoreFront virtual server.
add cs policy cs_lb_vs_pol -rule "HTTP.REQ.URL.CONTAINS(\"/Citrix/StoreEntraWeb/Tickets/RedeemStoreTicket\")" -action cs_lb_vs
<!--NeedCopy-->
Catch-all policy
Create a catch-all content switching policy to send all other StoreFront traffic to VPN virtual server.
add cs policy cs_vpn_pol -rule TRUE -action cs_vpn_vs
<!--NeedCopy-->
Bind content switching policies
Bind content switching policies to content switching virtual server with explicit priorities. This binds different content switching policies to cs_vs, which allows it to evaluate incoming requests and route them according to the rule above.
bind cs vserver cs_vs -policyName cs_lb_vs_pol -priority 100
bind cs vserver cs_vs -policyName cs_vpn_pol -priority 110
<!--NeedCopy-->
Configure StoreFront
Configure Citrix Gateway
-
Add a NetScaler Gateway instance on StoreFront.
Set up the gateway as though it does domain authentication and ensure that you specify a working callback URL because it isn't optional when you use Entra ID with StoreFront. -
Configure the gateway for remote access for the Store aggregating the Citrix DaaS resources.
-
Enable and configure Entra ID authentication from NetScaler Gateway. Replace the Tenant ID with the ID from your Entra ID tenant.
$store = Get-STFStoreService /Citrix/EntraStore
$authenticationService = Get-STFAuthenticationService -Store $store
Set-STFEntraIdSettings -AuthenticationService $authenticationService -TenantId "<Your tenant id>" -Enabled $true
<!--NeedCopy-->
Configure VDA Entra ID single sign-on
Single sign-on enables users to authenticate once when they sign in to the Citrix Gateway—and then access their virtual desktops and applications without having to re-enter their credentials to the VDA.
$store = Get-STFStoreService /Citrix/EntraStore
Set-STFStoreLaunchOptions -StoreService $store -EntraIdSsoEnabled $true
<!--NeedCopy-->
Considerations for enabling or disabling Entra ID SSO
-
Only enable single sign-on if you configure the Azure Entra ID Enterprise Application and update StoreFront with the tenant. If you enable this setting for stores currently using Entra ID with SAML without these settings, it potentially breaks existing single sign-on if you’re using FAS.
-
If you enable the setting for existing stores using Entra ID with SAML where the VDAs don’t currently have SSO, launch might be delayed and or you might see errors related to Entra ID authentication settings.