Using Entra ID B2B with Citrix Cloud

In a recent project, I designed an environment for a client who offers a published application to a substantial customer base. They expressed their desire to incorporate the use of Entra ID. I recommended the adoption of Entra ID B2B accounts for this purpose. Entra ID B2B accounts enable access to external partners for applications and resources within the organizational environment.

About Entra ID B2B

Entra ID B2B, short for Business-to-Business, is a Microsoft cloud service that facilitates secure collaboration among organizations. It permits organizations to extend invitations to external entities, such as partners, suppliers, or customers, granting them access to resources hosted within their Entra ID environment (formerly Azure AD). This approach eliminates the necessity for external users to establish new accounts, streamlining the collaborative process. Entra ID B2B bolsters security by implementing conditional access policies and multi-factor authentication for guest users, ensuring that only authorized individuals can access shared resources. Read here for more about Entra ID B2B.

Issues during implementation

While implementing this solution within the Citrix Cloud using the default Entra ID connect option, I encountered issues during the sign-in process with B2B accounts. After asking around, Julian Jakob directed me to an article highlighting an issue related to the default Entra ID connection in conjunction with Citrix FAS (Federated Authentication Service).

Upon reaching out to Citrix for support, it was revealed that there had been a modification to their SAML 2.0 configuration. This change now offers the option to utilize UPN (User Principal Name) or SID (Security Identifier) for authentication, whereas both were previously required. Please refer to the screenshot below for visual reference to this configuration option.

Based on the information provided, we successfully implemented Entra ID B2B accounts. However, this implementation necessitated certain modifications to our On-Premises Active Directory. Specifically, to grant B2B access to individual users, updating their User Principal Name (UPN) to align with their respective email addresses was imperative. While this approach was effective, it may not be ideal, especially considering the potential complexities of managing multiple DNS suffixes within the environment. As such, I dedicated some time to exploring alternative solutions that would obviate the need for such changes within the Active Directory.

Earlier in the project, I had come across an article from Citrix that introduced the concept of a ClaimsMappingPolicy. This approach leverages Azure AD Preview modules and a SAML Tech preview. It is worth noting that I refrained from testing this solution previously due to its preview status. Please refer to the provided article link for detailed information on this alternative approach.

Configuring the Entra ID as IdP

To initiate the configuration of Entra ID as the Identity Provider (IdP), the following key steps must be taken:

1. Enterprise Application Setup: The first step involves the configuration of the Enterprise Application within the designated environment.
2. Microsoft Graph Integration: Integrating with Microsoft Graph services is essential to facilitate the required functionalities.
3. Claims Policy Mapping: Mapping of claims policies is necessary to define and manage the assertion of identity attributes.
4. SAML 2.0 Connection in Citrix Cloud: Establishing a SAML 2.0 connection within the Citrix Cloud infrastructure enables secure authentication and authorization processes.

Enterprise Application Setup

To initiate the setup and configuration of a custom Entra ID Enterprise SAML application, please follow the provided steps. I have followed the guide created by Citrix, which can be accessed.

1. Azure Portal Sign-In:
   • Sign in to the Azure portal.
2. Navigate to Entra ID:
   • In the portal menu, select “Entra ID.
3. Access Enterprise Applications:
   • From the left pane, under “Manage,” select “Enterprise Applications.”
4. Create New Application:
   • In the working pane’s command bar, select “New Application.”
5. Choose Custom Application:
   • Select “Create your own application” from the command bar. Avoid using the Citrix Cloud SAML SSO enterprise application template, as it restricts modifications to the list of claims and SAML attributes.
6. Application Name and Integration:
   • Enter a name for the application.
   • Select “Integrate any other application you don’t find in the gallery (Non-gallery).”
   • Click “Create.” This action will lead you to the application overview page.
7. Configure Single Sign-On (SSO):
   • From the left pane, select “Single sign-on.”
   • In the working pane, choose “SAML.”
8. Basic SAML Configuration:
   • In the “Basic SAML Configuration” section, select “Edit” and configure the following settings:
     • In the “Identifier (Entity ID)” section, select “Add identifier” and input the value associated with the region in which your Citrix Cloud tenant is located:
       • For European Union, United States, and Asia-Pacific South regions, enter: https://saml.cloud.com.    
       • For the Japan region, enter: https://saml.citrixcloud.jp.         
       • For the Citrix Cloud Government region, enter: https://saml.cloud.us.
     • In the “Reply URL (Assertion Consumer Service URL)” section, select “Add reply URL” and enter the value associated with your Citrix Cloud tenant’s region.
       • For European Union, United States, and Asia-Pacific South regions, enter: https://saml.cloud.com/saml/acs.
       • For the Japan region, enter: https://saml.citrixcloud.jp/saml/acs.
       • For the Citrix Cloud Government region, enter: https://saml.cloud.us/saml/acs.
     • In the “Logout URL (Optional)” section, enter the value associated with your Citrix Cloud tenant’s region:
       • For European Union, United States, and Asia-Pacific South regions, enter: https://saml.cloud.com/saml/logout/callback.   
       • For the Japan region, enter: https://saml.citrixcloud.jp/saml/logout/callback.
       • For the Citrix Cloud Government region, enter: https://saml.cloud.us/saml/logout/callback.
   • After configuring these settings, select “Save” from the command bar.
9. User and Group Assignment:
   • From the left pane, select “Users and Groups.”
     • In the top bar, select “Add user/group.”
     • Under “Users,” select “None Selected.”
     • Choose the user you wish to test with, and click “Select.”
   • Click “Assign.” This action allows the designated user to be used for testing purposes.

These steps will enable creating and configuring a custom Entra ID Enterprise SAML application for your specific requirements.

Microsoft Graph Integration

The Citrix article I came across relies on Azure AD PowerShell modules, which have been planned for deprecation. To conduct effective testing, I needed to use something that was officially supported to ensure reliable functionality. Consequently, I embarked on a transition journey, migrating all the Azure AD commands to Microsoft Graph. Fortunately, I stumbled upon an informative article outlining the Microsoft Graph commands, which are direct replacements for the deprecated Azure AD Commands. This migration strategy aligns with industry best practices and guarantees continued operational effectiveness by leveraging the Microsoft Graph framework while circumventing the challenges posed by deprecated Azure AD PowerShell modules.

Modules

After migrating all Azure AD commands to Microsoft Graph, I comprehensively understood the requisite modules. Below, you’ll find an enumeration of all the essential commands, complete with their corresponding modules and the associated permissions indispensable for their execution:

To initiate work with Microsoft Graph, the first step involved the installation of the necessary modules. To achieve this, an Elevated PowerShell session needs to be opened, and the following commands need to be executed:

Install-Module Microsoft.Graph.Users
Install-Module Microsoft.Graph.Identity.SignIns
Install-Module Microsoft.Graph.Applications

You can append- force to each command if you prefer to streamline the installation process without individual prompts.

Permissions

When establishing a connection to Microsoft Graph, it is essential to define the scope, which dictates the permissions granted for that session. As illustrated in the table above, a comprehensive set of permissions is required, which can be summarized as follows:

• Policy.Read.All
• Application.ReadWrite.All
• Policy.ReadWrite.ApplicationConfiguration
• User.ReadWrite.All

With these permissions delineated, we can proceed to connect to Microsoft Graph. To initiate this process, follow these steps:

1. Open an Elevated PowerShell window.
2. Connect to Microsoft Graph using the following command:

Connect-MgGraph -Scopes Policy.Read.All, Application.ReadWrite.All,Policy.ReadWrite.ApplicationConfiguration, User.ReadWrite.All

3. A popup window will appear upon executing the command, prompting you to authenticate and grant Microsoft Graph the specified permissions, as detailed in the command above.

This authentication step ensures the session has the necessary privileges to interact with Microsoft Graph effectively.

Configuring Claims Policy Mapping

Now that we are ready to configure the necessary settings for the Claims Mapping Policy, we continue from the PowerShell window we previously used to connect to Microsoft Graph.

Claims Mapping Policies are used in identity management to map and transform attributes (claims) exchanged between identity providers and service providers during authentication. They enable customization of how user attributes are processed, ensuring proper handling and alignment of user data between systems for secure access control.

Preparing the Application

To utilize the Claims Mapping Policy for Entra ID B2B users, where the User Principal Name (UPN) and Security Identifier (SID) do not align with the On-Premises Active Directory, we need to edit Entra ID with specific Extensions and bind them to the application. In this context, we will require the name of the previously created application, which, for this demonstration, is referred to as “CTX-DaaS-B2B.”

1. Retrieve the application using the following command:

$MGApp = Get-MgApplication -Filter "displayname eq 'CTX-DaaS-B2B' "

2. Next, we need to add the Extensions, both of which are set to target User objects:
   • guestUserOnPremSID
   • guestShadowUPN

New-MgApplicationExtensionProperty -ApplicationId $MGApp.id -Name "guestUserOnPremSID" -TargetObjects User

New-MgApplicationExtensionProperty -ApplicationId $MGApp.id -Name "guestShadowUPN" -TargetObjects User

3. Note down the names of these Extensions by executing the following command:

Get-MgApplicationExtensionProperty -ApplicationId $mgapp.Id | fl *

4. Add the Claims Mapping Policy by providing the policy in JSON format. Before doing so, replace the ExtensionIDs with the Extension names obtained in step 3. Take note of the following names:
   • Variable = $params
   • displayName = “CitrixCustomClaims“

$params = @{
	definition = @(
		'{"ClaimsMappingPolicy":
            {"Version":1,
            "IncludeBasicClaimSet":"true",
            "ClaimsSchema": [
                {
                "Source":"user",
                "ID":"displayname",
                "name": "displayName",
                "SamlClaimType":"displayName"
                },
                {
                "Source":"user",
                "ID":"givenname",
                "name": "givenName",
                "SamlClaimType":"givenName"
                },
                {
                "Source":"user",
                "ID":"userprincipalname",
                "name": "cip_upn",
                "SamlClaimType":"cip_upn",
                "AppliesToUserType": "members"
                },
                {
                "Source":"user",
                "ExtensionID":"extension_c8ef4d2cb6694d76974c5a05be13affa_guestShadowUPN",
                "name": "cip_upn",
                "SamlClaimType": "cip_upn",
                "AppliesToUserType": "allGuests"
                },
                {
                "Source":"user",
                "ID":"objectid",
                "name": "cip_oid",
                "SamlClaimType":"cip_oid"
                },
                {
                "Source":"user",
                "ID":"userprincipalname",
                "name": "cip_email",
                "SamlClaimType":"cip_email"
                },
                {
                "Source":"user",
                "ID":"onPremiseSecurityIdentifier",
                "name": "cip_sid",
                "SamlClaimType":"cip_sid",
                "AppliesToUserType": "members"
                },
                {
                "Source":"user",
                "ExtensionID":"extension_c8ef4d2cb6694d76974c5a05be13affa_guestUserOnPremSID",
                "name": "cip_sid",
                "SamlClaimType": "cip_sid",
                "AppliesToUserType": "allGuests"
                }
            ]
            }
        }'
	)
	displayName = "CitrixCustomClaims"
}

This process ensures the application has the necessary Extensions and Claims Mapping Policy to handle Entra ID B2B user scenarios where UPNs and SIDs do not correspond to the On-Premises Active Directory.

5. Obtain the Service Principal
   Proceed by retrieving the Service Principal with the following command, where Displayname is the name of the app, in this case CTX-DaaS-B2B:

$ServicePrincipal = Get-MgServicePrincipal -Filter "Displayname eq 'CTX-DaaS-B2B' "

6. Create the Claims Mapping Policy
   Now, create the Claims Mapping Policy, utilizing the $Params variable, which represents the variable name assigned to the Policy when pasting the JSON code. Execute the following command to establish the policy:

New-MgPolicyClaimMappingPolicy -BodyParameter $params

7. Map the Claims Policy to the Service Principal
   A Graph body parameter must be created using the OData protocol to map the Claims policy to the Service Principal. Follow these steps:
   • Execute the command below, replacing “CitrixCustomClaims” with the name you assigned to your Claims Policy (found in the JSON command. In this case, it’s “CitrixCustomClaims“):

Get-MgPolicyClaimMappingPolicy -Filter "Displayname eq 'CitrixCustomClaims'"| select DisplayName,Description, Id

• Retrieve the ID and modify the following URL, replacing the ID at the end with the one obtained in the previous step:
  • https://graph.microsoft.com/beta/policies/claimsMappingPolicies/<ID from previous step>
• Create a variable in PowerShell with the modified URL, like so:

$odata = @{
	"@odata.id" = "https://graph.microsoft.com/beta/policies/claimsMappingPolicies/37720c4a-bb51-43ee-aae0-afa5eece4805"
}

• Finally, link the Odata to the Service Principal using the following command:

New-MgServicePrincipalClaimMappingPolicyByRef -ServicePrincipalId $servicePrincipal.id -BodyParameter $odata

These steps facilitate the establishment of the Claims Mapping Policy and its connection to the Service Principal, ensuring proper configuration for your desired scenario.

Configuring the User

To configure the test user, follow the steps outlined below:

1. Retrieve Current UPN and SID:
   Execute the following command to obtain the current User Principal Name (UPN) and Security Identifier (SID). Replace “[email protected]” with the Entra ID UPN you are configuring (for this test, it’s “[email protected]“):

$user = get-mguser -UserId Sjoerd@lab.newyard.online -Property Id,DisplayName,UserPrincipalName, OnPremisesSecurityIdentifier

2. Update User Extensions:
   Now, proceed to update the user’s Extension with the appropriate values. Replace the Extension name with the one you acquired earlier and execute the following commands:

• Update User’s On-Premises Security Identifier (SID):

Update-mguser -UserId $user.id -AdditionalProperties @{'extension_dcf32e98a0de4910ba50bd486eef0335_guestUserOnPremSID' = $user.OnPremisesSecurityIdentifier}

• Update User’s Shadow User Principal Name (UPN):

Update-mguser -UserId $user.id -AdditionalProperties @{'extension_dcf32e98a0de4910ba50bd486eef0335_guestShadowUPN' = $user.UserPrincipalName}

These steps ensure the test user’s proper configuration, including updating relevant Extensions with the required values, effectively facilitating the Entra ID B2B user scenario.

Configuring the SAML 2.0 Connection in Citrix Cloud

With Entra ID prepared, let’s proceed to configure Citrix Cloud. To initiate this process, follow these steps:

1. Sign in to the Citrix Cloud administration console and navigate to the Single Sign-On settings of the previously created Enterprise App.

1. Access the Citrix Cloud Console, and under “Identity and Access Management,” click on “Connect” within the SAML 2.0 option.
2. Create a Custom Administrator URL.

1. In the SAML configuration, populate the following settings using the Single Sign-On URLs obtained from Entra ID within the Enterprise App:
   • Identity Provider Entity ID = Microsoft Entra ID Identifier.
   • SSO Service URL = Login URL.
   • Logout URL (optional) = Logout URL.
   • Refer to the screenshot below for reference. On the “Set up single sign-on with SAML” page, in the SAML Signing Certificate section, locate “Certificate (PEM)” and select “Download” to save the certificate to your computer. Upload this certificate to the X.509 section of the SAML configuration within Citrix Cloud.
   • Proceed by clicking “Test and Finish.”

2. Now that SAML 2.0 has been configured, it is necessary to update the Workspace Configuration to employ the newly created authentication method:
   • Within the Citrix Cloud Administration Console, navigate to “Workspace Configuration.”
   • Proceed to the “Authentication” tab.
   • Select “SAML 2.0” and confirm your selection by clicking “OK” in the pop-up dialog.
     Allow a brief moment (approximately 1 minute) before proceeding, as immediate functionality may not always be observed.

By following these steps, you configure the SAML 2.0 connection in Citrix Cloud, enabling seamless integration with Entra ID for authentication and access management.

Testing

Now that we have configured all required settings, we can start with the test.

1. Visit the Workspace URL and sign in using the test user employed previously:
   1. After launching the desktop, open a command prompt or PowerShell and run the “whoami” command. You will observe that the sign-in is performed using the local Active Directory (AD) account.

Conclusion

After an extensive search and engagement with Citrix support, a functional Entra ID B2B scenario has been successfully resolved. While the initial solution relied on outdated information, it has been updated with current PowerShell commands, resulting in a functional setup. Consequently, organizations can seamlessly integrate Entra ID B2B and regular Entra ID users into their Citrix Cloud deployments, enhancing their access and identity management capabilities.

Please feel free to comment or ask questions regarding this solution. I am working on another article to guide you on using Azure Automation to update all B2B users with the new extension. So, stay tuned.
UPDATE: As mentioned earlier, I would create a blog post about using Azure Automation to automate this. You can read it here.