From d3a2f614bebfcb6849b73f64b8e8408530d3c000 Mon Sep 17 00:00:00 2001 From: Dilshan Senarath Date: Wed, 11 Nov 2026 22:18:27 +0530 Subject: [PATCH] Add device activation and deactivation to the device management API --- .../server/device/mgt/common/Constants.java | 4 + .../api/server/device/mgt/v1/DevicesApi.java | 8 +- .../device/mgt/v1/DevicesApiService.java | 2 +- .../mgt/v1/model/DevicePatchRequest.java | 70 +++++++++++-- .../v1/core/DeviceManagementApiService.java | 97 ++++++++++++++----- .../mgt/v1/impl/DevicesApiServiceImpl.java | 4 +- .../src/main/resources/device-mgt.yaml | 17 +++- 7 files changed, 160 insertions(+), 42 deletions(-) diff --git a/components/org.wso2.carbon.identity.api.server.device.mgt/org.wso2.carbon.identity.api.server.device.mgt.common/src/main/java/org/wso2/carbon/identity/api/server/device/mgt/common/Constants.java b/components/org.wso2.carbon.identity.api.server.device.mgt/org.wso2.carbon.identity.api.server.device.mgt.common/src/main/java/org/wso2/carbon/identity/api/server/device/mgt/common/Constants.java index 04b3f140a4..45232a0da6 100644 --- a/components/org.wso2.carbon.identity.api.server.device.mgt/org.wso2.carbon.identity.api.server.device.mgt.common/src/main/java/org/wso2/carbon/identity/api/server/device/mgt/common/Constants.java +++ b/components/org.wso2.carbon.identity.api.server.device.mgt/org.wso2.carbon.identity.api.server.device.mgt.common/src/main/java/org/wso2/carbon/identity/api/server/device/mgt/common/Constants.java @@ -62,6 +62,10 @@ public enum ErrorMessage { "Invalid device name.", "Device name must be a non-blank string of at most 255 characters."), + ERROR_CODE_INVALID_PATCH_REQUEST("60103", + "Invalid device update request.", + "At least one of 'deviceName' or 'status' must be provided."), + ERROR_CODE_ERROR_LISTING_DEVICES("65101", "Unable to list devices.", "Server encountered an error while listing devices."), diff --git a/components/org.wso2.carbon.identity.api.server.device.mgt/org.wso2.carbon.identity.api.server.device.mgt.v1/src/gen/java/org/wso2/carbon/identity/api/server/device/mgt/v1/DevicesApi.java b/components/org.wso2.carbon.identity.api.server.device.mgt/org.wso2.carbon.identity.api.server.device.mgt.v1/src/gen/java/org/wso2/carbon/identity/api/server/device/mgt/v1/DevicesApi.java index 7d9fd87214..65f3ee44a8 100644 --- a/components/org.wso2.carbon.identity.api.server.device.mgt/org.wso2.carbon.identity.api.server.device.mgt.v1/src/gen/java/org/wso2/carbon/identity/api/server/device/mgt/v1/DevicesApi.java +++ b/components/org.wso2.carbon.identity.api.server.device.mgt/org.wso2.carbon.identity.api.server.device.mgt.v1/src/gen/java/org/wso2/carbon/identity/api/server/device/mgt/v1/DevicesApi.java @@ -113,7 +113,7 @@ public Response getDevice(@ApiParam(value = "UUID of the registered device",requ @ApiResponse(code = 403, message = "Forbidden", response = Void.class), @ApiResponse(code = 500, message = "Server Error", response = Error.class) }) - public Response listDevices( @Valid @Min(1) @Max(100)@ApiParam(value = "Maximum number of records to return.", defaultValue="30") @DefaultValue("30") @QueryParam("limit") Integer limit, @Valid @Min(0)@ApiParam(value = "Number of records to skip for pagination.", defaultValue="0") @DefaultValue("0") @QueryParam("offset") Integer offset, @Valid@ApiParam(value = "Filter devices by the ID of the user who registered them. Returns devices of any status. Pagination applies as usual.") @QueryParam("userId") String userId) { + public Response listDevices( @Valid @Min(1) @Max(100)@ApiParam(value = "Maximum number of records to return.", defaultValue="30") @DefaultValue("30") @QueryParam("limit") Integer limit, @Valid @Min(0)@ApiParam(value = "Number of records to skip for pagination.", defaultValue="0") @DefaultValue("0") @QueryParam("offset") Integer offset, @Valid@ApiParam(value = "Filter devices by the ID of the user who registered them. Returns devices of any status. Pagination applies as usual. In an organization, a shared user gets the devices it inherits from its resident organization.") @QueryParam("userId") String userId) { return delegate.listDevices(limit, offset, userId ); } @@ -123,7 +123,7 @@ public Response listDevices( @Valid @Min(1) @Max(100)@ApiParam(value = "Maxim @Path("/{device-id}") @Consumes({ "application/json" }) @Produces({ "application/json" }) - @ApiOperation(value = "Rename a registered device.", notes = "This API provides the capability to update the display name of a registered device. Scope (Permission) required: ``internal_device_mgt_update`` ", response = DeviceResponse.class, authorizations = { + @ApiOperation(value = "Update a registered device.", notes = "This API provides the capability to rename, activate or deactivate a registered device. At least one of 'deviceName' or 'status' must be provided. Scope (Permission) required: ``internal_device_mgt_update`` ", response = DeviceResponse.class, authorizations = { @Authorization(value = "BasicAuth"), @Authorization(value = "OAuth2", scopes = { @@ -137,9 +137,9 @@ public Response listDevices( @Valid @Min(1) @Max(100)@ApiParam(value = "Maxim @ApiResponse(code = 404, message = "Not Found", response = Error.class), @ApiResponse(code = 500, message = "Server Error", response = Error.class) }) - public Response updateDeviceName(@ApiParam(value = "UUID of the registered device",required=true) @PathParam("device-id") String deviceId, @ApiParam(value = "" ,required=true) @Valid DevicePatchRequest devicePatchRequest) { + public Response updateDevice(@ApiParam(value = "UUID of the registered device",required=true) @PathParam("device-id") String deviceId, @ApiParam(value = "" ,required=true) @Valid DevicePatchRequest devicePatchRequest) { - return delegate.updateDeviceName(deviceId, devicePatchRequest ); + return delegate.updateDevice(deviceId, devicePatchRequest ); } } diff --git a/components/org.wso2.carbon.identity.api.server.device.mgt/org.wso2.carbon.identity.api.server.device.mgt.v1/src/gen/java/org/wso2/carbon/identity/api/server/device/mgt/v1/DevicesApiService.java b/components/org.wso2.carbon.identity.api.server.device.mgt/org.wso2.carbon.identity.api.server.device.mgt.v1/src/gen/java/org/wso2/carbon/identity/api/server/device/mgt/v1/DevicesApiService.java index 53d1e2d5fc..8238127426 100644 --- a/components/org.wso2.carbon.identity.api.server.device.mgt/org.wso2.carbon.identity.api.server.device.mgt.v1/src/gen/java/org/wso2/carbon/identity/api/server/device/mgt/v1/DevicesApiService.java +++ b/components/org.wso2.carbon.identity.api.server.device.mgt/org.wso2.carbon.identity.api.server.device.mgt.v1/src/gen/java/org/wso2/carbon/identity/api/server/device/mgt/v1/DevicesApiService.java @@ -39,5 +39,5 @@ public interface DevicesApiService { public Response listDevices(Integer limit, Integer offset, String userId); - public Response updateDeviceName(String deviceId, DevicePatchRequest devicePatchRequest); + public Response updateDevice(String deviceId, DevicePatchRequest devicePatchRequest); } diff --git a/components/org.wso2.carbon.identity.api.server.device.mgt/org.wso2.carbon.identity.api.server.device.mgt.v1/src/gen/java/org/wso2/carbon/identity/api/server/device/mgt/v1/model/DevicePatchRequest.java b/components/org.wso2.carbon.identity.api.server.device.mgt/org.wso2.carbon.identity.api.server.device.mgt.v1/src/gen/java/org/wso2/carbon/identity/api/server/device/mgt/v1/model/DevicePatchRequest.java index 7b3b5bf3bb..f6e79396e5 100644 --- a/components/org.wso2.carbon.identity.api.server.device.mgt/org.wso2.carbon.identity.api.server.device.mgt.v1/src/gen/java/org/wso2/carbon/identity/api/server/device/mgt/v1/model/DevicePatchRequest.java +++ b/components/org.wso2.carbon.identity.api.server.device.mgt/org.wso2.carbon.identity.api.server.device.mgt.v1/src/gen/java/org/wso2/carbon/identity/api/server/device/mgt/v1/model/DevicePatchRequest.java @@ -24,16 +24,53 @@ import io.swagger.annotations.ApiModelProperty; import javax.validation.constraints.*; +/** + * Fields to update. At least one of 'deviceName' or 'status' must be provided. + **/ import io.swagger.annotations.*; import java.util.Objects; import javax.validation.Valid; import javax.xml.bind.annotation.*; - +@ApiModel(description = "Fields to update. At least one of 'deviceName' or 'status' must be provided.") public class DevicePatchRequest { private String deviceName; +@XmlType(name="StatusEnum") +@XmlEnum(String.class) +public enum StatusEnum { + + @XmlEnumValue("ACTIVE") ACTIVE(String.valueOf("ACTIVE")), @XmlEnumValue("INACTIVE") INACTIVE(String.valueOf("INACTIVE")); + + + private String value; + + StatusEnum(String v) { + value = v; + } + + public String value() { + return value; + } + + @Override + public String toString() { + return String.valueOf(value); + } + + public static StatusEnum fromValue(String value) { + for (StatusEnum b : StatusEnum.values()) { + if (b.value.equals(value)) { + return b; + } + } + throw new IllegalArgumentException("Unexpected value '" + value + "'"); + } +} + + private StatusEnum status; + /** * The new display name for the device. **/ @@ -43,11 +80,9 @@ public DevicePatchRequest deviceName(String deviceName) { return this; } - @ApiModelProperty(example = "My Work Phone", required = true, value = "The new display name for the device.") + @ApiModelProperty(example = "My Work Phone", value = "The new display name for the device.") @JsonProperty("deviceName") - @Valid - @NotNull(message = "Property deviceName cannot be null.") - @Size(min=1,max=255) + @Valid @Size(min=1,max=255) public String getDeviceName() { return deviceName; } @@ -55,6 +90,25 @@ public void setDeviceName(String deviceName) { this.deviceName = deviceName; } + /** + * The new status of the device. An inactive device cannot be used for device-based login checks. + **/ + public DevicePatchRequest status(StatusEnum status) { + + this.status = status; + return this; + } + + @ApiModelProperty(example = "INACTIVE", value = "The new status of the device. An inactive device cannot be used for device-based login checks.") + @JsonProperty("status") + @Valid + public StatusEnum getStatus() { + return status; + } + public void setStatus(StatusEnum status) { + this.status = status; + } + @Override @@ -67,12 +121,13 @@ public boolean equals(java.lang.Object o) { return false; } DevicePatchRequest devicePatchRequest = (DevicePatchRequest) o; - return Objects.equals(this.deviceName, devicePatchRequest.deviceName); + return Objects.equals(this.deviceName, devicePatchRequest.deviceName) && + Objects.equals(this.status, devicePatchRequest.status); } @Override public int hashCode() { - return Objects.hash(deviceName); + return Objects.hash(deviceName, status); } @Override @@ -82,6 +137,7 @@ public String toString() { sb.append("class DevicePatchRequest {\n"); sb.append(" deviceName: ").append(toIndentedString(deviceName)).append("\n"); + sb.append(" status: ").append(toIndentedString(status)).append("\n"); sb.append("}"); return sb.toString(); } diff --git a/components/org.wso2.carbon.identity.api.server.device.mgt/org.wso2.carbon.identity.api.server.device.mgt.v1/src/main/java/org/wso2/carbon/identity/api/server/device/mgt/v1/core/DeviceManagementApiService.java b/components/org.wso2.carbon.identity.api.server.device.mgt/org.wso2.carbon.identity.api.server.device.mgt.v1/src/main/java/org/wso2/carbon/identity/api/server/device/mgt/v1/core/DeviceManagementApiService.java index b4fbe7f641..313b7f49d3 100644 --- a/components/org.wso2.carbon.identity.api.server.device.mgt/org.wso2.carbon.identity.api.server.device.mgt.v1/src/main/java/org/wso2/carbon/identity/api/server/device/mgt/v1/core/DeviceManagementApiService.java +++ b/components/org.wso2.carbon.identity.api.server.device.mgt/org.wso2.carbon.identity.api.server.device.mgt.v1/src/main/java/org/wso2/carbon/identity/api/server/device/mgt/v1/core/DeviceManagementApiService.java @@ -43,7 +43,8 @@ import javax.ws.rs.core.Response; /** - * Core service for Device Management API — handles listing, renaming and deleting devices. + * Core service for Device Management API — handles listing, renaming, activating, deactivating and deleting + * devices. */ public class DeviceManagementApiService { @@ -208,12 +209,7 @@ public DeviceResponse getDevice(String deviceId) { String tenantDomain = ContextLoader.getTenantDomainFromContext(); Device device = deviceManagementService.getDeviceById(deviceId, tenantDomain); if (device == null) { - throw new APIError(Response.Status.NOT_FOUND, new ErrorResponse.Builder() - .withCode(Constants.ErrorMessage.ERROR_CODE_DEVICE_NOT_FOUND.code()) - .withMessage(Constants.ErrorMessage.ERROR_CODE_DEVICE_NOT_FOUND.message()) - .withDescription(String.format( - Constants.ErrorMessage.ERROR_CODE_DEVICE_NOT_FOUND.description(), deviceId)) - .build(LOG, "Device not found for id: " + deviceId)); + throw buildDeviceNotFoundError(deviceId); } return DeviceResponseBuilder.buildDeviceResponse(device); } catch (DeviceMgtException e) { @@ -221,40 +217,95 @@ public DeviceResponse getDevice(String deviceId) { } } + private APIError buildDeviceNotFoundError(String deviceId) { + + return new APIError(Response.Status.NOT_FOUND, new ErrorResponse.Builder() + .withCode(Constants.ErrorMessage.ERROR_CODE_DEVICE_NOT_FOUND.code()) + .withMessage(Constants.ErrorMessage.ERROR_CODE_DEVICE_NOT_FOUND.message()) + .withDescription(String.format( + Constants.ErrorMessage.ERROR_CODE_DEVICE_NOT_FOUND.description(), deviceId)) + .build(LOG, "Device not found for id: " + deviceId)); + } + /** - * Updates the display name of a device. + * Updates a device. Renames the device when a device name is given and activates or deactivates it when a + * status is given. Both can be applied in the same request. * * @param deviceId Device UUID. - * @param patchRequest Request body containing the new name. - * @return Updated DeviceResponse. + * @param patchRequest Fields to update. + * @return DeviceResponse reflecting the updated device. */ - public DeviceResponse updateDeviceName(String deviceId, DevicePatchRequest patchRequest) { + public DeviceResponse updateDevice(String deviceId, DevicePatchRequest patchRequest) { validateApiEnabled(); - validateDeviceName(patchRequest); + validatePatchRequest(patchRequest); try { String tenantDomain = ContextLoader.getTenantDomainFromContext(); - Device updated = deviceManagementService.updateDeviceName( - deviceId, patchRequest.getDeviceName(), tenantDomain); - return DeviceResponseBuilder.buildDeviceResponse(updated); + Device device = deviceManagementService.getDeviceById(deviceId, tenantDomain); + if (device == null) { + throw buildDeviceNotFoundError(deviceId); + } + + if (patchRequest.getDeviceName() != null) { + device = deviceManagementService.updateDeviceName( + deviceId, patchRequest.getDeviceName(), tenantDomain); + } + if (patchRequest.getStatus() != null) { + device = updateDeviceStatus(device, patchRequest.getStatus(), tenantDomain); + } + return DeviceResponseBuilder.buildDeviceResponse(device); } catch (DeviceMgtException e) { throw handleException(e, Constants.ErrorMessage.ERROR_CODE_ERROR_UPDATING_DEVICE); } } - private void validateDeviceName(DevicePatchRequest patchRequest) { + /** + * Activates or deactivates the device. Nothing is changed when the device already has the requested status. + * + * @param device Device to update. + * @param status Requested status. + * @param tenantDomain Tenant domain. + * @return Device reflecting the requested status. + * @throws DeviceMgtException If the status update fails. + */ + private Device updateDeviceStatus(Device device, DevicePatchRequest.StatusEnum status, String tenantDomain) + throws DeviceMgtException { + + Device.Status requestedStatus = Device.Status.valueOf(status.value()); + if (requestedStatus == device.getStatus()) { + if (LOG.isDebugEnabled()) { + LOG.debug("The device: " + device.getId() + " is already " + requestedStatus + + ". Skipping the status update."); + } + return device; + } + if (requestedStatus == Device.Status.ACTIVE) { + return deviceManagementService.activateDevice(device.getId(), tenantDomain); + } + return deviceManagementService.deactivateDevice(device.getId(), tenantDomain); + } - String deviceName = patchRequest != null ? patchRequest.getDeviceName() : null; - if (StringUtils.isBlank(deviceName) || deviceName.length() > DEVICE_NAME_MAX_LENGTH) { - throw new APIError(Response.Status.BAD_REQUEST, new ErrorResponse.Builder() - .withCode(Constants.ErrorMessage.ERROR_CODE_INVALID_DEVICE_NAME.code()) - .withMessage(Constants.ErrorMessage.ERROR_CODE_INVALID_DEVICE_NAME.message()) - .withDescription(Constants.ErrorMessage.ERROR_CODE_INVALID_DEVICE_NAME.description()) - .build(LOG, "Invalid device name.")); + private void validatePatchRequest(DevicePatchRequest patchRequest) { + + if (patchRequest == null || (patchRequest.getDeviceName() == null && patchRequest.getStatus() == null)) { + throw buildBadRequestError(Constants.ErrorMessage.ERROR_CODE_INVALID_PATCH_REQUEST); + } + String deviceName = patchRequest.getDeviceName(); + if (deviceName != null && (StringUtils.isBlank(deviceName) || deviceName.length() > DEVICE_NAME_MAX_LENGTH)) { + throw buildBadRequestError(Constants.ErrorMessage.ERROR_CODE_INVALID_DEVICE_NAME); } } + private APIError buildBadRequestError(Constants.ErrorMessage error) { + + return new APIError(Response.Status.BAD_REQUEST, new ErrorResponse.Builder() + .withCode(error.code()) + .withMessage(error.message()) + .withDescription(error.description()) + .build(LOG, error.message())); + } + /** * Deletes a device by ID. * diff --git a/components/org.wso2.carbon.identity.api.server.device.mgt/org.wso2.carbon.identity.api.server.device.mgt.v1/src/main/java/org/wso2/carbon/identity/api/server/device/mgt/v1/impl/DevicesApiServiceImpl.java b/components/org.wso2.carbon.identity.api.server.device.mgt/org.wso2.carbon.identity.api.server.device.mgt.v1/src/main/java/org/wso2/carbon/identity/api/server/device/mgt/v1/impl/DevicesApiServiceImpl.java index b80be418f5..b4db00da14 100644 --- a/components/org.wso2.carbon.identity.api.server.device.mgt/org.wso2.carbon.identity.api.server.device.mgt.v1/src/main/java/org/wso2/carbon/identity/api/server/device/mgt/v1/impl/DevicesApiServiceImpl.java +++ b/components/org.wso2.carbon.identity.api.server.device.mgt/org.wso2.carbon.identity.api.server.device.mgt.v1/src/main/java/org/wso2/carbon/identity/api/server/device/mgt/v1/impl/DevicesApiServiceImpl.java @@ -50,9 +50,9 @@ public Response getDevice(String deviceId) { } @Override - public Response updateDeviceName(String deviceId, DevicePatchRequest patchRequest) { + public Response updateDevice(String deviceId, DevicePatchRequest patchRequest) { - return Response.ok().entity(service.updateDeviceName(deviceId, patchRequest)).build(); + return Response.ok().entity(service.updateDevice(deviceId, patchRequest)).build(); } @Override diff --git a/components/org.wso2.carbon.identity.api.server.device.mgt/org.wso2.carbon.identity.api.server.device.mgt.v1/src/main/resources/device-mgt.yaml b/components/org.wso2.carbon.identity.api.server.device.mgt/org.wso2.carbon.identity.api.server.device.mgt.v1/src/main/resources/device-mgt.yaml index 403fb49b76..de2178ea5b 100644 --- a/components/org.wso2.carbon.identity.api.server.device.mgt/org.wso2.carbon.identity.api.server.device.mgt.v1/src/main/resources/device-mgt.yaml +++ b/components/org.wso2.carbon.identity.api.server.device.mgt/org.wso2.carbon.identity.api.server.device.mgt.v1/src/main/resources/device-mgt.yaml @@ -127,9 +127,10 @@ paths: patch: tags: - Device Management - summary: Rename a registered device. - operationId: updateDeviceName - description: "This API provides the capability to update the display name of a registered device.\n\n + summary: Update a registered device. + operationId: updateDevice + description: "This API provides the capability to rename, activate or deactivate a registered device. + At least one of 'deviceName' or 'status' must be provided.\n\n Scope (Permission) required: ``internal_device_mgt_update``\n\n" parameters: - name: device-id @@ -288,8 +289,7 @@ components: example: "2026-04-27T10:00:00.000Z" DevicePatchRequest: type: object - required: - - deviceName + description: Fields to update. At least one of 'deviceName' or 'status' must be provided. properties: deviceName: type: string @@ -297,6 +297,13 @@ components: maxLength: 255 description: The new display name for the device. example: "My Work Phone" + status: + type: string + enum: + - ACTIVE + - INACTIVE + description: The new status of the device. An inactive device cannot be used for device-based login checks. + example: "INACTIVE" Error: type: object properties: