Device registration

Prev Next

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.

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

~/.local/share/appgatesdp-service/application.data

Android

/AppGate/settings.xml: adb shell cat storage/self/primary/AppGate/settings.xml

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 (Three circular shapes stacked vertically on a dark background, selected to access a menu.) 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.