Device registration occurs after a user with a valid client profile authenticates.
A device is registered the first time the system encounters it. At that time, an onboarding cookie is sent to the client and saved for use at sign-in. Standard clients save the cookie in the user space. Headless and Windows SSO clients save the cookie in the system space.
Device registration and MFA at sign-in
NOTE
To configure MFA at sign-in, see the Sign-in Settings in the General IdP Settings section.
MFA at sign-in controls device registration. Device registration prevents unauthorized access when valid credentials are used from a new device.
AppGate ZTNA creates a cookie at sign-in that is stored by both the Controller and the AppGate client. This cookie is presented during future connection attempts. The Controller then checks the device registration limit. If the device registration limit has not been exceeded, MFA can be enforced based on the configured MFA mode.
MFA modes
There are three modes available:
Not required (automatically register all devices).
Once (MFA required to register all new devices). Requires MFA to register each new device, provided the device registration limit has not been exceeded.
Always (MFA required at every sign-in). Requires MFA at every login, provided the device registration limit has not been exceeded.
IMPORTANT
The Always mode can interfere with background operations such as automatic sign-in, token renewal, and browser launches when SAML tokens expire. Consider overall system behavior before enabling this option.
Removing the onboarding cookie
If needed, you can remove the onboarding cookie from a device. Onboarding cookies are stored in the following locations:
Operating System | Location |
|---|---|
Windows | Credential Manager > Generic Credentials > “OnBoardingCookie” |
macOS | Keychain > Passwords > “Appgate SDP Client” with Kind “OnBoardingCookie…” |
Linux |
|
Android |
|
Onboarding issues with cloning client instances
Because the onboarding cookie relates to both the user and device, users might not be able to onboard in some situations. This can happen on a single machine, but it can also occur when you clone client instances.
Originally onboarded | Device | Current PC user | AppGate ZTNA user | Result |
|---|---|---|---|---|
By PC user A | Original PC | Logged in as B | Signed in as A | Not OK. A has no access to the cookie in B's user space |
No one (before clone) | VM clone of original PC | Logged in as A | Signed in as A | OK in first clone only. A has no access to the cookie from other clones. |
By PC user A (before clone) | VM clone of original PC | Logged in as A | Signed in as A | OK on all clones until the cookie changes on a clone. |
The Registered Devices page
The Registered Devices page (Usage > Registered Devices) lists all registered devices and lets you remove a device from the system. The most recently seen devices appear first. By default, registered devices are purged 90 days after they were last seen by the Collective. You can change this in Global Settings.
Managing registered devices
On the Registered Devices page, you can use bulk actions to renew claims, administrator, and entitlement tokens. A confirmation dialog appears in which you can enter the reason for the renewal. Token renewal is limited to 6.66 per second, so renewing 1,200 users might take about three minutes.
You can also use the action button—the three dots icon (
) to the right of each line item—to access the following options:
Renew Tokens. Refreshes tokens or this device, such as after you change a user’s entitlements. A confirmation dialog lets you enter the reason for renewal.
Remove. Deletes the device record from the Controller. The next time the user signs in from that device, it is treated as a new device. Depending on how onboarding is configured in the user's identity provider, the Controller either blocks the device or requires onboarding cookie verification before allowing the device to connect. Removing a device revokes the user's tokens, terminating all sessions on that device.
Add User to Denylist. Removes access from all devices for this user by revoking all related tokens and prevents the user from signing in again. If a user was added to the denylist accidentally, restore the user's status from the Denylist page.