--- title: "Configuring client profiles and client profile groups" slug: "configure-client-profiles-v7-0" description: "Create and manage client profiles for different IdPs, assign policies, and streamline onboarding with AppGate ZTNA's comprehensive profile settings." tags: ["Client profile Configuration", "Client Profile Groups", "Client Profiles", "Client Profile Management"] updated: 2026-10-05T18:49:06Z published: 2026-10-05T18:49:06Z canonical: "support.appgate.com/configure-client-profiles-v7-0" --- > ## Documentation Index > Fetch the complete documentation index at: https://support.appgate.com/llms.txt > Use this file to discover all available pages before exploring further. # Configuring client profiles and client profile groups You can create multiple client profiles—typically to support different IdPs or differently named profiles, which can then be used to assign different policies. You cannot edit key components within a profile; instead, you can clone or delete profiles from within the profile form. > [!NOTE] > **NOTE** > > You do not need to create client profiles for Connectors or k8s service clients—these are created and installed automatically. A client profile group can contain multiple client profiles from any Collective. Each profile added to the group is assigned a weighting similar to Gateway weightings. When none of the Controllers for a given profile are available, the client tries the Controllers for the next profile according to the set weighting. Profiles with the same weighting distribute users equally across Collectives. Before configuring a client profile, check the global [client profile DNS name](/v1/docs/global-settings-v7-0) configured in Global Settings (Settings > Global Settings). --- ## Configuring a client profile Client profiles include the profile name, SPA details, the identity provider (IdP), and the Controllers' profile DNS name and CA fingerprints. To add a client profile: 1. Go to **Client Profiles** (Identity > Client Profiles). 2. Select **+Add** and then select *Client Profile*. 3. Complete the following fields: - ***Name***. The name of the profile as it appears in the client. Use a name that is meaningful to users. Only a limited number of characters appear in the client, so keep names to 20 characters. Use tags if you need to organize profiles for admin users. - ***Notes***. Optional. Enter any notes for the profile. - ***Tags***. Select **+Add** to add tags to the profile. - ***DNS Name***. Clients use DNS round-robin to find a Controller, so the DNS name is shared across all Controllers. Select from the following: - *Use global*. The global DNS name generated when you created your first Controller. This can be changed in Global Settings if required. - *Set custom.* Enter a custom DNS name. This is used only for this client profile. See [Controller and Gateway HA mechanisms](/v1/docs/high-availability-ha-v7-0#controller-and-gateway-ha-mechanisms) for more details about profile DNS names. - ***Identity Provider.*** Select the IdP the users authenticate against. > [!NOTE] > **NOTE** > > You can check which keys are in use because all connected clients return the `spaKey` device claim, which contains the SPA key name. 1. Save the profile. --- ## Configuring a client profile group Client profile groups are a list of client profiles from this and other Collectives. They are treated like client profiles within the system. > [!NOTE] > **NOTE** > > Client profile groups can only be used within device policies and cannot be distributed out-of-band. To add a client profile group: 1. Go to **Client Profiles** (Identity > Client Profiles). 2. Select **+Add** and then select *Client Profile Group*. 3. Complete the following fields: - ***Name***. Enter a name for the profile group as it appears in the client. Use a name that is meaningful to users. Because users may have more than one profile, make the name clear about which profile or Collective this refers to. - ***Notes***. Optional. Enter any notes for the profile group. - ***Tags***. Select **+Add** to add tags to the profile group. - ***Profile Links***. Select **+Add** to add profile links with a *Weighting Factor*. The weighting factor sets the order in which Collectives are tried. 4. Save the profile group. --- ## Distributing client profiles Profiles can be distributed directly to Portal users, but new clients and devices require profiles exported from the **Client Profiles** page using the action button (![Three circular shapes stacked vertically on a dark background, selected to access a menu.](https://cdn.us.document360.io/e7482ce5-acfa-4c3b-b76c-b6c32472644a/Images/Documentation/three_dots.png?sv=2026-02-06&spr=https&st=2026-11-21T21%3A39%3A54Z&se=2026-11-21T22%3A39%3A54Z&sr=b&sp=r&sig=bgYBLECF5vKH9%2Fk7H094SXMQeTzQ99Ae1Tu2CqTBAAA%3D)) on the right side of the screen. Several export options streamline distribution. In all cases, handle distribution carefully—client profiles contain confidential data such as the SPA key. Subsequent profile updates can be pushed directly to clients and devices as part of a device policy. The client profile export options are: - ***Copy Profile*** ***Link***. The copy profile link lets you distribute the client profile for use with any type of client or Portal not part of this Collective. The `appgate://` prefix used in the client profile is recognized by most operating systems after the client is installed. > [!NOTE] > **NOTE** > > Do not create desktop shortcuts in Windows for client profiles. Some Windows tools do not support strings longer than 255 characters. Because profile links can exceed this length, the shortcut can break. - ***Copy Email Template (contains the profile link)***. The email template is designed for desktop users and includes instructions for using the included profile link. This template assumes your users already have the AppGate ZTNA client installed. Paste the text into a new email and send it to your user community. Users only need to click the link. Exercise care at the point of distribution—some operating systems and email apps may try to handle the profile link by replacing the `appgate://` prefix or by recognizing only part of the profile link as clickable. Test your distribution method to confirm that what arrives is exactly what was sent. - ***Download Profile Link as QR Code*** ***(encoded profile link)***. After the client is installed, mobile apps include the option to scan a QR code as an alternative to clicking a profile link. The QR code is the exact equivalent of the profile link. - ***Download Client Onboarding Web Page (contains the profile link)***. The onboarding web page is designed to help with desktop client installation and includes the profile link, giving users everything they need in one place. ![](https://cdn.us.document360.io/e7482ce5-acfa-4c3b-b76c-b6c32472644a/Images/Documentation/image(112).png?sv=2026-02-06&spr=https&st=2026-11-21T21%3A39%3A54Z&se=2026-11-21T22%3A39%3A54Z&sr=b&sp=r&sig=qt15vk5Ur2nDjx5qsfYkwGTsj8%2BOZe6a5vscj1nav30%3D) Download the single file `AppgateSDPOnboardingPage.html`. Click the file to view it in your browser. This onboarding page is automatically seeded with the profile link for your Controller and works immediately for your users. The download links in the HTML file—starting at row 13—point to the latest available client versions in the AppGate download center. Edit these links before distributing the page so you control which version users receive and avoid download speed issues. After editing, host the page on your own web server. The page cannot be deployed on the Controller and cannot be hosted on SharePoint, as SharePoint prevents downloads from simple HTML pages. ![Code snippet showing download links for various operating systems.](https://cdn.us.document360.io/e7482ce5-acfa-4c3b-b76c-b6c32472644a/Images/Documentation/ag511-webpage_urls.png?sv=2026-02-06&spr=https&st=2026-11-21T21%3A39%3A54Z&se=2026-11-21T22%3A39%3A54Z&sr=b&sp=r&sig=h5TGhIROL514x%2B2%2B%2BPRWtGTha6kylHnLzF9F7Od%2Fs5Y%3D) After deployment, the page dynamically presents the correct client to each user and guides new users through the complete onboarding process: installation, configuration, and sign-in. Your profile link is behind the **** button. **Windows lite client**: By default, this page serves the Windows full client. To onboard users of the Windows lite client, use the URL `AppgateSDPOnboardingPage.html?lite`. The lite client then appears instead for Windows users. Because the lite client does not require administrator rights to install, this option is useful for enabling third parties or temporary workers to use AppGate ZTNA. --- ## Installing client profiles The client profile can be provided to the client in several ways: - With the client installation, using the appropriate options. - At run time, using command-line options. - After the client is installed, at first use only. The user can: - Click the `appgate://` link to install the profile. Operating systems and email apps may try to handle the client profile link by replacing the `appgate://` prefix or by recognizing only part of the link as clickable. Test your distribution method to confirm it works as expected. - Scan the QR code (mobile). - From within the client, use the **+ Add Profile** option at the bottom of the profile drop-down on the home screen, then either: - Paste the client profile into the appropriate field. Copy the profile as text, not as a link. If your preferred distribution method does not work with the `appgate://` prefix, the client also accepts links where `appgate://` is replaced with `https://`. Edit the profile link to read: `https://myserver.company.com/eyJzcGEiOn......`. - Scan the QR code (mobile). - Presented to Portal users as a list, configured in the [Portal user access settings](/v1/docs/adding-a-portal-v7-0#user-access-settings). After the profile is installed in the AppGate ZTNA client, the new profile is added to the list and users are taken through the profile acceptance form to the user sign-in form. The `profileHostnames` [device claim](/v1/docs/device-claim-scripts-v7-0) can be used to check which profiles are installed on a user’s device. --- ## Managing client profiles and client profile groups ### Client profile settings Specific client profiles and client profile groups can be selected and imposed on the client for this Collective. After the initial profile is distributed to allow the client to connect to the Collective, client profiles can be centrally managed. All subsequent profile updates are pushed by the system administrator, including the ability to remove all installed profiles for a given Collective. This allows the use of a general onboarding profile—which does not grant any actual access—that is replaced by a permanent profile after the first successful sign-in. Profiles are always created and managed in **Client Profiles** (Identity > Client Profiles). In the device policy, select one or more existing profiles or profile groups and add them to the list. This is how the **Client Profile Settings > Managed by Admin** option works: - The profiles selected in the device policy are applied for this Collective only. - You cannot select two profiles where one is a replacement for another already on the list. - New profiles are received when the entitlement token is renewed and applied at sign-out or when the client next restarts. - If the new profiles include a replacement for the profile currently in use, the user is signed out when the list takes effect. - If no profiles are selected, all profiles for this Collective are removed when the device policy takes effect and the user is signed out. - Use separate device policies for full and headless clients in always-on configurations. #### **For full clients:** - If you push three new profiles, after the device policy takes effect the user will have exactly those three profiles for this Collective. Users cannot add or remove profiles for that Collective. - The Managed by Admin option does not affect users' ability to add or remove profiles for other Collectives. This lets users use a managed corporate Collective while still being able to experiment with a separate test Collective. #### **For headless clients:** - Managed profiles takes precedence over installed ones. - Push only one profile to the headless client. If more than one profile is pushed, the first one in the list is used—unless the current profile is included in the list, in which case that profile continues to be used. - Credentials remain unchanged, so the client can sign in automatically. - To reclaim local control of profile settings after using the Managed by Admin option, run the `configurator reload` command (`reset service` on Windows) or reinstall the client. - If an empty profile list is used, all profiles are removed and the client cannot connect to the Collective. > [!NOTE] > **NOTE** > > Client Profile Settings are not recommended for the k8s service client. The injector itself is not updated, so the new profile is applied only to running container instances when they restart. > [!NOTE] > **NOTE** > > Client Profile Settings do not affect Portal and Connector appliances. ### Example use case—third party users - Set up a device policy with client profile settings managed by admin and no profiles included. Save this as `z-no-profiles-policy`. The system always selects the policy nearest to "a" in the alphabet when more than one policy applies. - Set up access for your third-party user with a temporary onboarding profile. - Set up a device policy with client profile settings managed by admin, with assignment criteria allowing third-party access for the current month only. Include a new "third party" replacement profile. Save this as `third-party-policy`. This policy is initially used by the third party because it is nearest to "a" in the alphabet. - When the user connects using the onboarding profile, the system swaps it out for the "third-party" profile. At this point you can delete the onboarding profile if you want. - After month-end, `z-no-profiles-policy` is automatically selected, the "third party" profile is removed, and the user is signed out. Without a profile, the user can no longer connect to your Collective.