Device Management

A registered mobile device is more than a single credential. It carries one or more FIDO UAF credentials, one for each account that was onboarded on it, and one or more dispatch targets, which are the addresses that push notifications are sent to. Over the lifetime of an installation these change: the user renames the device, the operating system issues a new push token, the user removes one of several accounts, or a pending out-of-band operation has to be picked up while no push notification arrived.

Device management is the set of endpoints that let the mobile application keep that state correct without going through a full authentication. In nevisAdmin 4 they are exposed by the nevisFIDO UAF Device Service pattern.

These endpoints are a Nevis extension. They are not part of the FIDO UAF specification, and they are consumed by the Nevis Mobile Authentication SDK and by the Nevis Access App only. Do not build a third-party client against them.

Do you need this pattern

The Device Service exposes two path groups, and both are already exposed by other mobile authentication patterns. Before adding the pattern, check whether the paths are covered on the virtual host that your mobile clients use.

Path group	Also exposed by
/nevisfido/devices/credentials/*	Out-of-band Mobile Onboarding, Mobile Deregistration Service
/nevisfido/devices/oobOperations/*	Out-of-band Mobile Authentication, Usernameless Out-of-band Mobile Authentication

Add the nevisFIDO UAF Device Service pattern when one of the following applies:

• Your project uses in-band mobile authentication only, so none of the out-of-band patterns above are present and neither path group is exposed.
• Your mobile clients reach Nevis on a different virtual host than the one those patterns are assigned to. Paths are exposed per virtual host, so a pattern on the web virtual host does not help the mobile virtual host.
• You want device management to keep working independently of the use case patterns, so that removing an out-of-band step from the project does not silently take the fetch channel down with it.

Adding the pattern when the paths are already exposed is harmless. The paths are identical and are simply mapped twice.

Configuring the pattern

The pattern has two fields:

• Virtual Host(s): assign the virtual host that the mobile clients connect to.
• nevisFIDO: assign the nevisFIDO UAF Instance pattern that holds the credentials, or a nevisFIDO UAF Connector pattern if nevisFIDO runs outside this project.

There is no Authentication Realm field and no Application Access Token field, and this is deliberate rather than an oversight. The device endpoints are public APIs. They are not protected by a session, by a realm, or by a service access token. See How the endpoints are protected for what does protect them.

Services exposed

The pattern maps the following paths on the assigned virtual host:

Path	Method	Purpose
/nevisfido/devices/credentials/{deviceId}	GET	Return the FIDO UAF credentials and dispatch targets registered on the device.
/nevisfido/devices/credentials/{deviceId}	PATCH	Update or delete parts of the device state.
/nevisfido/devices/credentials/{deviceId}	DELETE	Remove the device completely.
/nevisfido/devices/oobOperations/{deviceId}	GET	Return the out-of-band operations that are pending for the device.

The PATCH endpoint carries the operation name in the request payload rather than in the path. Three operations are defined:

Operation	Effect
DispatchTargetUpdate	Set a new name, a new push token, or both, on every dispatch target of the device. This is what the application calls after the operating system rotates the push token, and after the user renames the device.
Delete	Remove the listed FIDO UAF credentials and the listed dispatch targets. Both lists are optional, so the same operation can remove an account, remove a stale push address, or remove both together.
DeviceIdUpdate	Move the listed credentials and dispatch targets to a new device identifier.

For the full request and response format, see the Device Service reference.

How the endpoints are protected

The paths are exposed as public in nevisProxy. If the mobile clients are on the internet, so are these endpoints, and there is no realm in front of them to challenge the caller.

What protects them is the key material of the device itself. Every request carries a Device-Signature header, a JWS signed with the private key of one of the dispatch targets of the device. nevisFIDO checks that signature against the public key it stored when the dispatch target was created:

• The dispatch target that signed the request must belong to the device named in the path. If it does not, nevisFIDO answers 403, even though the request reached the endpoint unauthenticated.
• Successful responses are returned as JWE, encrypted to the encryption key of the signing dispatch target. A caller that intercepts the response without that private key cannot read it.
• Each payload carries a request identifier and a creation timestamp, which nevisFIDO uses to reject replayed requests.

The practical consequence is that a device can only ever manage itself. There is no call in this API that lets one device read or change the state of another, and there is no administrative view. Do not reach for these endpoints when building a self-service portal or a helpdesk tool. Those need nevisIDM.

It also means the security of the API rests entirely on the private keys in the secure hardware of the device. Treat the endpoints as internet-facing and let the platform rate limits apply to them, but do not attempt to place a realm in front of them. The mobile clients cannot authenticate against one.

Relationship to deregistration

Device management and deregistration touch the same records, and it is easy to assume that one covers the other. It does not.

The Mobile Deregistration Service removes FIDO UAF credentials. It leaves the Generic credential that makes the device a dispatch target in place, so the backend keeps dispatching push notifications to a device that can no longer authenticate. The device endpoints are where that is cleaned up: the Delete operation of the PATCH endpoint takes a list of key identifiers and a list of dispatch target identifiers, so the client can remove both in one call.

The two are correlated by the deviceId attribute. A dispatch target and a FIDO UAF credential created on the same device carry the same value, which is what makes it possible to find the leftover dispatch target after a deregistration. See Deregistration and Dispatch Target Management.

Endpoints that sound similar

Three different endpoints return information about a user or a device, and they are not interchangeable.

Endpoint	Exposed by	Called by	Answers
/nevisfido/devices/credentials/{deviceId}	nevisFIDO UAF Device Service	The application on the device itself	What is registered on this device
/nevisfido/token/dispatch/targets	Token Dispatch Targets Query Endpoint of the Transaction Confirmation Service	The web application, on behalf of a logged-in user	Which devices this user has, so a transaction can be dispatched to one of them
/nevisfido/uaf/1.1/request/deregistration/	Mobile Deregistration Service	The application, after authenticating	Nothing. It removes a FIDO UAF credential

The middle one is the one most often confused with device management. It is user scoped rather than device scoped, it requires an authenticated caller, and exposing it publicly leaks which devices a given user has registered. It belongs to Transaction Confirmation, not here.

What the client does with these endpoints

The endpoints exist because the mobile clients call them. Which behavior they back depends on the client.

The Nevis Access App uses them for:

• Device name, which the user can change and which is pushed to every dispatch target of the device through DispatchTargetUpdate.
• Fetch, the channel that polls /nevisfido/devices/oobOperations/{deviceId} for pending operations when no push notification arrived. If this path is not exposed, fetch silently stops working while push still appears healthy. See Not receiving push notifications.
• Removing a single account from a device that carries several, which maps to the Delete operation. See Understanding the nevisIDM credentials for how the entries relate to what an administrator sees.
• Listing the authenticators that are enrolled.

An application built with the Nevis Mobile Authentication SDK calls the same endpoints through the SDK API:

• Device management for the overall concept.
• Change device information to set a new device name or push token.
• Check and synchronize device information to reconcile what the device believes with what nevisFIDO stored, which is the operation that repairs a device after a restore from backup.

Only operations that were dispatched with a dispatch target belonging to the device are returned by the out-of-band operations endpoint. An operation dispatched without one, such as a QR code shown on a screen for a usernameless flow, is not associated with any device and cannot be fetched. That is a property of the dispatch, not a configuration error.

Verifying the deployment

After deploying, check the following on the mobile virtual host:

1. GET /nevisfido/devices/credentials/{deviceId} without a Device-Signature header returns an error from nevisFIDO rather than an authentication challenge or a 404. A 404 means the path is not mapped on this virtual host.
2. GET /nevisfido/devices/oobOperations/{deviceId} behaves the same way. Check this one explicitly. It is the path most often missing, because it is not exposed by the onboarding and deregistration patterns.
3. Rename the device in the client and confirm that a push notification still arrives. This exercises DispatchTargetUpdate end to end.
4. Trigger an out-of-band operation, dismiss the push notification, and pull to refresh in the client. The operation should appear through the fetch channel.