Profiles 'seed' the Clients allowing them to connect to the Controllers. They can be installed manually, managed by a device Policy or used in Client Profile Groups.
Profile Groups are used for Cross-Collective HA. The Client will automatically try the next profile when none of the Controllers are available for the current profile.
Use the Client Profile UI to create and distribute Client profiles.
Use the Policies UI to Manage or change Client Profiles.
Client profiles include a profile name plus the minimum set of information required for a Client to be able to connect to an AppGate ZTNA Controller. The resulting elements are:
the DNS name for the Controller(s)
an IdP which the user will authenticate against
the profile name (which appears in the Client)
the SPA details (name and key) which are used to establish a TCP connection to the Controller
the fingerprints of the current CA and next CA as a means to verify the Controller is genuine
The first two underlined items are what defines a unique profile. When a profile is updated (changed name, SPA or CA), then because the underlined items are unchanged it will replace the existing profile. If a new profile is created (with a unique DNS name / IdP), then it will be treated as an additional profile.
So what happens if you need to distribute a replacement profile - maybe the CA has been renewed or the SPA key compromised? Create a new one with a new name but use the same DNS name and IdP. (The new name allows you to easily manage the distribution of the Client profile within your organization.) Once the new profile has been distributed, this will replace the existing profile when installed in Client. Once all Clients have the new profile the obsolete one can be deleted.
Profile elements in detail
DNS name
This resolves to one or more Controller instances. See Controllers for details covering DNS requirements.
IdP
The AppGate ZTNA system can work with many IdPs configured. It is therefore important to set one as the default, so the user is able to use their normal authentication credentials.
Profile name
The friendly name which will be displayed on the main screen of the Client. It is important from a security perspective that this helps a user to understand what Collective they are signing in to.
SPA
Single Packet Authorization (SPA) is designed to prevent external connections to appliances without the correct SPA key. The profile includes the SPA key name and the key. The SPA key name is derived from the profile name; and the SPA key is derived from the SPA key name. So for a given Collective, a Client profile called 'fred' will always generate the same SPA key. This can be useful in the event that a Client profile is accidentally deleted.
Different profiles will have different SPA keys - this can be useful when you have different types of users to cater for. You might want to issue one profile containing one SPA key to your corporate users, and a different one to any third party users. This way you are limiting the distribution of your corporate SPA key and if your third party SPA key was compromised, then your corporate users would not require a replacement profile. The SPA key name can easily be checked (and used to assign Policies) as it is reported as the spaKey device claim when a user is signing in.
NOTE
These specially crafted SPA handshake packet(s) must be received before a TLS/DTLS connection can be established with an appliance. SPA packets on port 53 (UDP) and on port 443 (UDP and/or TCP) are always sent regardless of the Global Settings configuration SPA use. This is done because the connecting device does not know the configuration setting of the receiving device.
For TCP SPA, the packet sent to port 443 (TCP) must be allowed through.
For UDP-TCP SPA, packets are sent to port 53 (UDP) and 443 (UDP), at least one of which must get through. If TLS is being used for the tunnel, the system will subsequently perform TCP SPA, so the packet sent to port 443 (TCP) must also be allowed through.
See Troubleshooting user/device access for more details about SPA's workings.
CA Certificates
To establish TLS connections the Client must trust the Certificate of the Controller. The fingerprint of the Controller's CA is included and this is used to cryptographically verify the authenticity of the Controller. This mitigates the possibilities for a man-in-the-middle attack at first usage.
The next CA Fingerprint is also included to make it easier to perform CA switches when using automation, for example you have an immutable image (k8s or docker Client) that use a hardcoded profile URL. Without this a new image would need to be used at exactly the same moment as the CA was switched!
Inside the Client profile
A Client profile will always look like appgate://<server>/<data-blob>, but the length will vary according to the original configuration. The first part is simply the URL of the Controller(s). The second part comprises the base64 encoded data-blob. Overall it might look like:
appgate://myserver.company.com/eyJzcGEiOnsibW9kZSI6IlRDUCIsIm5hbWUiOi...........
This base64 encoded data-blob can be decoded using standard online decoding tools and will contain:
"profileName":"myprofilename",
"spa":{"name":"mykeyname","key":"cd337b2..........453c98828"},
"caFingerprint":"f917fd6a4b.............0bfb18e6",
"nextCaFingerprint":"044b3e061............2c32bf918"
"identityProviderName":"LDAP"
Creating and managing Client profiles
Multiple Client profiles can be created - these would typically be created to support the use of different IdPs and/or differently named profiles (which could then be used to assign different Policies). However you can't edit the key components within a profile, instead profiles can be cloned or deleted (from within the profile form).
NOTE
You don't need to create Client Profiles for Connectors or K8S service Clients as these are created and installed automagically.
A Client Profile Group can contain multiple Client profiles which can originate from any Collective. Each Client profile added to the group is also assigned a weighting (which behaves similarly to the Gateway weightings). When none of the Controllers for a given Client profile are available, then the Client tries the Controllers for the next profile (according to the set weighting). When Client profiles can have the same weighting, then the users will be distributed across these Collectives equally.
NOTE
Client profile groups can only be used within Device Policies and not distributed out-of-band.
Distributing Client Profiles
Profiles can be distributed to Portal users directly but for new Clients/devices they need to be exported from the Client Profiles UI using the action menu on the right hand side of the screen. There are a number of export options to streamline the process of distributing the Client profiles. In all cases care must be taken with their distribution as the Client profile contains confidential data such as the SPA key.
Subsequent profile updates can be pushed to Clients/devices directly as part of a device Policy.
Copy link to clipboard
The copy profile link allows you distributed the Client profile for use with any type of Client or Portals which are not part of this Collective.
The appgate:// prefix used in the Client profile should be recognized by most operating systems once the Client is installed.
NOTE
Don't create desktop shortcuts in Windows for Client profiles. Some Windows tools are old and do not support strings longer than 255 characters. Since the profile links can exceed this length it will become broken and not work.
Download QR Code (encoded profile Link)
Once the Client is installed, the mobile apps include the option to scan a QR code, as an alternative to clicking on a profile link.
The QR code is the exact equivalent of the profile link.
Download Client On-boarding web page (contains the profile link)
The onboarding web page is designed to help with installation of the desktop Clients and includes the profile link, so users have everything they need all in one place.
| Download the single file However, the download links in the html file that appear from row 13, point to the latest available versions of the Clients available in the AppGate download center.
These download links should therefore be edited before use. This way you get control over which version users get and avoid any download speed issues. Once done, this page needs to be hosted on your own simple web server (it can't be deployed on the Controller). It also can't be hosted on SharePoint because it prevents downloads from simple html pages such as this. Once deployed - this page dynamically presents the correct Client to the user. It then steps new users through the whole on-boarding process including; installation, configuration and sign-in. Your own profile link will be hiding behind the <PROFILE LINK> button that the users will click in order to complete the required profile. Windows lite Client By default this page will serve up the Windows full Client. However, this page can also be particularly useful for on-boarding users of the Windows lite Client. If you plan to use the page for the lite Client then simply use the URL |
Copy email template (contains the profile link)
The email template is designed for desktop users and includes instructions for how to use the included profile link .
| This assumes your users already have the AppGate ZTNA Client installed. This text needs to be pasted into a new email message and sent to your user community. Once sent - all users have to do is to click the link. However care must to be taken at the point of use - some operating systems and/or (email) apps will try to handle the profile link in a clever way because they think they are seeing a conventional URL. They may for instance replace the appgate:// with something else only recognize part of the profile link as being a link you can click. We strongly recommend you try your planned method of distribution to ensure what arrives is the same as you sent. |
Installing Client profiles
The Client profile can be fed to the Client in a number of different ways:
With the Client installation (using the appropriate options)
At run time (using the command line options)
After the Client has been installed, at first use only the user can:
click on the appgate:// link to install the profile to the Client.
NOTE
The Client operating systems and/or (email) apps may try to handle the Client profile link in a clever way because they think they are seeing a conventional URL. They may for instance replace the appgate:// with something else or only recognize part of the Client profile link as being clickable. We strongly recommend you try your planned method of distribution to ensure it operates as you expect!
scan the QR code (mobile).
From within the Client use the + Add Profile option at the bottom of the profile dropdown on the home screen of the Client then:
paste the Client profile into the appropriate field. Ensure that the profile is copied as text NOT as a link.
NOTE
If your preferred distribution model does not work (using the appgate:// prefix), then the Client will happily accept links where the appgate:// has been replaced with https:// so just edit the Client profile to look like: https://myserver.company.com/eyJzcGEiOn.......
scan the QR code (mobile)
Presented to Portal users as a pick list - set in the Portal appliance configuration
Once installed into the AppGate ZTNA Client, the new profile is added to the list and the users are normally taken via the profile acceptance form straight to the user sign-in form.
The profileHostnames device claim can be used to check on which profiles the user has installed.
Managing Client Profiles and Client profile groups
For subsequent connections a device Policy can be used to manage the Client profile settings.
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 (using the normal four export options) Client profiles can be centrally managed, so all subsequent updates of profiles can be pushed by the system administrator. This includes the ability to completely remove all installed profiles relating to a given Collective. This might for instance, allow the use of a generalized on-boarding profile (which does not allow any actual access), which is replaced by a permanent profile after the first successful sign-in.
Profiles are always created and managed in Client profiles. In the device Policy all you need to do, is to select one or more of the existing profiles or profile groups, then add them to the list.
This is how the Client Profile Settings > Managed by Admin option works:
The profiles selected in the device Policy will be imposed for this Collective only.
You cannot select two profiles where one is deemed to be a replacement profile for another already on the list.
The new profile(s) are received when the Entitlement token is renewed and applied at sign-out or when the Client next restarts.
If the new profile(s) contains a replacement profile for the profile currently in use, then when the list goes live, the user will be signed out.
If no profiles were selected then when the device Policy goes live, all profiles for this Collective will be removed and the user will be signed out.
Separate device Policies should be used for full and headless Clients (in the case of always-on)
For full Clients
If you have three new profile(s), then after the device Policy goes live on a user's device they will have exactly those three profiles for this Collective and users will not be able to add or remove profiles relating to that Collective.
The Managed by Admin option does not affect users' ability to add and remove profiles for other Collectives. (This would allow users to use a managed corporate Collective while still having the ability to experiment with a separate test Collective.)
For headless Clients
Managed profiles takes precedence over Installed ones.
It's important to only push one profile to headless (otherwise the first one in the list is used, unless the current profile is included in the list then that will continue to be used.).
The credentials remain as before - so the Client can sign in automatically.
After use of the Managed by Admin option, re-claiming local control of profile settings is done by running the configurator reload (reset service on Windows) command or by un/re-installation.
If empty profile list is used, then all profiles are removed and the Client won't be able to connect to Collective.
NOTE
It is not recommended to use Client Profile Settings for the k8s service Client. The injector itself is not updated - so the new profile will only be applied to running instances (in a Container) and only when they are restarted.
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 include no profiles. Save this as 'z-no-profiles-policy'. The system will always pick the Policy nearest to 'a' in the alphabet when more than one applies.
Set up access for your third party user with a temporary 'on-boarding' profile.
Set up a device Policy with Client profile settings managed by admin with assignment criteria allowing third party access for this month only. Include a new 'third party' replacement profile. Save this as 'third-party-policy'. This Policy will initially be used by the third party because it is the nearest to 'a' in the alphabet.
When the user connects using the 'on-boarding' profile it will be swapped out for 'third-party' profile. At this point you can delete the 'on-boarding' profile if you wish.
After the month-end, the 'z-no-profiles-policy' will be automatically selected; the 'third party' profile will be removed and the user signed out. Without a profile, they will no longer be able to connect to your Collective.