MACRO NEPAL
SCIM Provisioning in Java: Complete System-to-System User Management
awiskar acharya
November 21, 2025
1:18 pm

SCIM (System for Cross-domain Identity Management) is a standardized protocol for automating user provisioning and identity management between systems. This guide provides a comprehensive implementation of SCIM 2.0 in Java.

SCIM 2.0 Overview

Key Concepts:

  • Resources: Users, Groups, etc.
  • Operations: Create, Read, Update, Delete (CRUD)
  • Schemas: Standardized attribute definitions
  • Bulk Operations: Multiple operations in one request

SCIM Endpoints:

  • /scim/v2/Users - User management
  • /scim/v2/Groups - Group management
  • /scim/v2/ServiceProviderConfig - Server capabilities
  • /scim/v2/ResourceTypes - Resource definitions
  • /scim/v2/Schemas - Schema definitions

Dependencies and Setup

Maven Dependencies
<properties> <spring-boot.version>3.1.0</spring-boot.version> <jackson.version>2.15.2</jackson.version> <scim-sdk.version>2.2.8</scim-sdk.version> </properties> <dependencies> <!-- Spring Boot --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> <version>${spring-boot.version}</version> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-data-jpa</artifactId> <version>${spring-boot.version}</version> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-security</artifactId> <version>${spring-boot.version}</version> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-validation</artifactId> <version>${spring-boot.version}</version> </dependency> <!-- SCIM SDK --> <dependency> <groupId>com.unboundid.product.scim2</groupId> <artifactId>scim2-sdk-client</artifactId> <version>${scim-sdk.version}</version> </dependency> <!-- JSON Processing --> <dependency> <groupId>com.fasterxml.jackson.core</groupId> <artifactId>jackson-databind</artifactId> <version>${jackson.version}</version> </dependency> <dependency> <groupId>com.fasterxml.jackson.core</groupId> <artifactId>jackson-core</artifactId> <version>${jackson.version}</version> </dependency> <!-- Database --> <dependency> <groupId>org.postgresql</groupId> <artifactId>postgresql</artifactId> <scope>runtime</scope> </dependency> </dependencies>
Application Configuration
# application.yml scim: base-url: https://api.example.com/scim/v2 default-page-size: 100 max-page-size: 1000 bulk: max-operations: 1000 max-payload-size: 1048576 spring: datasource: url: jdbc:postgresql://localhost:5432/scim_db username: scim_user password: scim_password jpa: hibernate: ddl-auto: update properties: hibernate: dialect: org.hibernate.dialect.PostgreSQLDialect format_sql: true server: servlet: context-path: /scim/v2

Domain Models

1. SCIM User Entity
@Entity @Table(name = "scim_users") @Data @NoArgsConstructor @AllArgsConstructor @Builder public class ScimUser { @Id private String id; @Column(nullable = false, unique = true) private String externalId; @Column(nullable = false) private String userName; @Column(nullable = false) private String displayName; private String title; private String preferredLanguage; private String locale; private String timezone; @Column(nullable = false) private Boolean active = true; @Column(nullable = false) private Boolean locked = false; @Embedded private Name name; @ElementCollection @CollectionTable(name = "scim_user_emails", joinColumns = @JoinColumn(name = "user_id")) private List<Email> emails; @ElementCollection @CollectionTable(name = "scim_user_phone_numbers", joinColumns = @JoinColumn(name = "user_id")) private List<PhoneNumber> phoneNumbers; @ElementCollection @CollectionTable(name = "scim_user_photos", joinColumns = @JoinColumn(name = "user_id")) private List<Photo> photos; @ElementCollection @CollectionTable(name = "scim_user_roles", joinColumns = @JoinColumn(name = "user_id")) private List<UserRole> roles; @ElementCollection @CollectionTable(name = "scim_user_entitlements", joinColumns = @JoinColumn(name = "user_id")) private List<Entitlement> entitlements; @ElementCollection @CollectionTable(name = "scim_user_x509_certificates", joinColumns = @JoinColumn(name = "user_id")) private List<X509Certificate> x509Certificates; @Column(nullable = false) private Instant metaCreated; @Column(nullable = false) private Instant metaLastModified; private String metaLocation; private String metaVersion; @Embeddable @Data @NoArgsConstructor @AllArgsConstructor @Builder public static class Name { private String formatted; private String familyName; private String givenName; private String middleName; private String honorificPrefix; private String honorificSuffix; } @Embeddable @Data @NoArgsConstructor @AllArgsConstructor @Builder public static class Email { private String value; private String type; // work, home, other private Boolean primary = false; } @Embeddable @Data @NoArgsConstructor @AllArgsConstructor @Builder public static class PhoneNumber { private String value; private String type; // work, home, mobile, fax, pager, other } @Embeddable @Data @NoArgsConstructor @AllArgsConstructor @Builder public static class Photo { private String value; private String type; // photo, thumbnail } @Embeddable @Data @NoArgsConstructor @AllArgsConstructor @Builder public static class UserRole { private String value; private String display; private String type; private Boolean primary = false; } @Embeddable @Data @NoArgsConstructor @AllArgsConstructor @Builder public static class Entitlement { private String value; private String display; private String type; private Boolean primary = false; } @Embeddable @Data @NoArgsConstructor @AllArgsConstructor @Builder public static class X509Certificate { private String value; } }
2. SCIM Group Entity
@Entity @Table(name = "scim_groups") @Data @NoArgsConstructor @AllArgsConstructor @Builder public class ScimGroup { @Id private String id; @Column(nullable = false, unique = true) private String externalId; @Column(nullable = false) private String displayName; private String description; @ManyToMany @JoinTable( name = "scim_group_members", joinColumns = @JoinColumn(name = "group_id"), inverseJoinColumns = @JoinColumn(name = "user_id") ) private List<ScimUser> members; @Column(nullable = false) private Instant metaCreated; @Column(nullable = false) private Instant metaLastModified; private String metaLocation; private String metaVersion; }
3. SCIM Configuration
@Entity @Table(name = "scim_configurations") @Data @NoArgsConstructor @AllArgsConstructor @Builder public class ScimConfiguration { @Id private String id; @Column(nullable = false) private String tenantId; private Integer maxResults; private Integer maxPayloadSize; private Boolean patchSupported; private Boolean bulkSupported; private Boolean filterSupported; private Boolean etagSupported; private Boolean sortSupported; private Boolean changePasswordSupported; @ElementCollection @CollectionTable(name = "scim_auth_schemes", joinColumns = @JoinColumn(name = "config_id")) private List<AuthenticationScheme> authenticationSchemes; @Embeddable @Data @NoArgsConstructor @AllArgsConstructor @Builder public static class AuthenticationScheme { private String type; private String name; private String description; private String specUri; private String documentationUri; } }

SCIM Service Layer

1. User Service
@Service @Transactional @Slf4j public class ScimUserService { private final ScimUserRepository userRepository; private final ScimGroupRepository groupRepository; private final ScimMapper scimMapper; public ScimUserService(ScimUserRepository userRepository, ScimGroupRepository groupRepository, ScimMapper scimMapper) { this.userRepository = userRepository; this.groupRepository = groupRepository; this.scimMapper = scimMapper; } public ScimUser createUser(ScimUser user) { log.info("Creating SCIM user: {}", user.getUserName()); user.setId(UUID.randomUUID().toString()); user.setMetaCreated(Instant.now()); user.setMetaLastModified(Instant.now()); // Set primary email if not specified if (user.getEmails() != null && !user.getEmails().isEmpty()) { boolean hasPrimary = user.getEmails().stream() .anyMatch(ScimUser.Email::getPrimary); if (!hasPrimary) { user.getEmails().get(0).setPrimary(true); } } ScimUser savedUser = userRepository.save(user); log.info("Created SCIM user with ID: {}", savedUser.getId()); return savedUser; } public Optional<ScimUser> getUserById(String id) { return userRepository.findById(id); } public Optional<ScimUser> getUserByUserName(String userName) { return userRepository.findByUserName(userName); } public List<ScimUser> getUsers(ScimFilter filter, int startIndex, int count) { log.debug("Fetching users with filter: {}, startIndex: {}, count: {}", filter, startIndex, count); // Apply filtering and pagination List<ScimUser> allUsers = userRepository.findAll(); return allUsers.stream() .filter(user -> matchesFilter(user, filter)) .skip(startIndex - 1) // SCIM uses 1-based indexing .limit(count) .collect(Collectors.toList()); } public ScimUser updateUser(String id, ScimUser updatedUser) { log.info("Updating SCIM user: {}", id); ScimUser existingUser = userRepository.findById(id) .orElseThrow(() -> new UserNotFoundException("User not found: " + id)); // Update fields scimMapper.updateUserFromUser(updatedUser, existingUser); existingUser.setMetaLastModified(Instant.now()); ScimUser savedUser = userRepository.save(existingUser); log.info("Updated SCIM user: {}", id); return savedUser; } public ScimUser patchUser(String id, ScimPatchOperation patchOperation) { log.info("Patching SCIM user: {}", id); ScimUser existingUser = userRepository.findById(id) .orElseThrow(() -> new UserNotFoundException("User not found: " + id)); applyPatchOperation(existingUser, patchOperation); existingUser.setMetaLastModified(Instant.now()); ScimUser savedUser = userRepository.save(existingUser); log.info("Patched SCIM user: {}", id); return savedUser; } public void deleteUser(String id) { log.info("Deleting SCIM user: {}", id); if (!userRepository.existsById(id)) { throw new UserNotFoundException("User not found: " + id); } // Remove user from all groups List<ScimGroup> groupsWithUser = groupRepository.findByMembersId(id); for (ScimGroup group : groupsWithUser) { group.getMembers().removeIf(member -> member.getId().equals(id)); groupRepository.save(group); } userRepository.deleteById(id); log.info("Deleted SCIM user: {}", id); } public boolean userExists(String userName) { return userRepository.findByUserName(userName).isPresent(); } public long getUserCount(ScimFilter filter) { List<ScimUser> allUsers = userRepository.findAll(); return allUsers.stream() .filter(user -> matchesFilter(user, filter)) .count(); } private boolean matchesFilter(ScimUser user, ScimFilter filter) { if (filter == null) { return true; } // Implement filter matching logic // This is a simplified version - real implementation would parse filter expressions return true; } private void applyPatchOperation(ScimUser user, ScimPatchOperation operation) { switch (operation.getOp()) { case "add": applyAddOperation(user, operation); break; case "remove": applyRemoveOperation(user, operation); break; case "replace": applyReplaceOperation(user, operation); break; default: throw new UnsupportedOperationException("Unsupported patch operation: " + operation.getOp()); } } private void applyAddOperation(ScimUser user, ScimPatchOperation operation) { // Implementation for add operation } private void applyRemoveOperation(ScimUser user, ScimPatchOperation operation) { // Implementation for remove operation } private void applyReplaceOperation(ScimUser user, ScimPatchOperation operation) { // Implementation for replace operation } } @Repository public interface ScimUserRepository extends JpaRepository<ScimUser, String> { Optional<ScimUser> findByUserName(String userName); Optional<ScimUser> findByExternalId(String externalId); boolean existsByUserName(String userName); }
2. Group Service
@Service @Transactional @Slf4j public class ScimGroupService { private final ScimGroupRepository groupRepository; private final ScimUserRepository userRepository; private final ScimMapper scimMapper; public ScimGroupService(ScimGroupRepository groupRepository, ScimUserRepository userRepository, ScimMapper scimMapper) { this.groupRepository = groupRepository; this.userRepository = userRepository; this.scimMapper = scimMapper; } public ScimGroup createGroup(ScimGroup group) { log.info("Creating SCIM group: {}", group.getDisplayName()); group.setId(UUID.randomUUID().toString()); group.setMetaCreated(Instant.now()); group.setMetaLastModified(Instant.now()); ScimGroup savedGroup = groupRepository.save(group); log.info("Created SCIM group with ID: {}", savedGroup.getId()); return savedGroup; } public Optional<ScimGroup> getGroupById(String id) { return groupRepository.findById(id); } public List<ScimGroup> getGroups(ScimFilter filter, int startIndex, int count) { log.debug("Fetching groups with filter: {}, startIndex: {}, count: {}", filter, startIndex, count); List<ScimGroup> allGroups = groupRepository.findAll(); return allGroups.stream() .filter(group -> matchesFilter(group, filter)) .skip(startIndex - 1) .limit(count) .collect(Collectors.toList()); } public ScimGroup updateGroup(String id, ScimGroup updatedGroup) { log.info("Updating SCIM group: {}", id); ScimGroup existingGroup = groupRepository.findById(id) .orElseThrow(() -> new GroupNotFoundException("Group not found: " + id)); scimMapper.updateGroupFromGroup(updatedGroup, existingGroup); existingGroup.setMetaLastModified(Instant.now()); ScimGroup savedGroup = groupRepository.save(existingGroup); log.info("Updated SCIM group: {}", id); return savedGroup; } public void deleteGroup(String id) { log.info("Deleting SCIM group: {}", id); if (!groupRepository.existsById(id)) { throw new GroupNotFoundException("Group not found: " + id); } groupRepository.deleteById(id); log.info("Deleted SCIM group: {}", id); } public ScimGroup addMemberToGroup(String groupId, String userId) { log.info("Adding user {} to group {}", userId, groupId); ScimGroup group = groupRepository.findById(groupId) .orElseThrow(() -> new GroupNotFoundException("Group not found: " + groupId)); ScimUser user = userRepository.findById(userId) .orElseThrow(() -> new UserNotFoundException("User not found: " + userId)); if (group.getMembers() == null) { group.setMembers(new ArrayList<>()); } // Check if user is already a member boolean alreadyMember = group.getMembers().stream() .anyMatch(member -> member.getId().equals(userId)); if (!alreadyMember) { group.getMembers().add(user); group.setMetaLastModified(Instant.now()); group = groupRepository.save(group); log.info("User {} added to group {}", userId, groupId); } return group; } public ScimGroup removeMemberFromGroup(String groupId, String userId) { log.info("Removing user {} from group {}", userId, groupId); ScimGroup group = groupRepository.findById(groupId) .orElseThrow(() -> new GroupNotFoundException("Group not found: " + groupId)); if (group.getMembers() != null) { boolean removed = group.getMembers().removeIf(member -> member.getId().equals(userId)); if (removed) { group.setMetaLastModified(Instant.now()); group = groupRepository.save(group); log.info("User {} removed from group {}", userId, groupId); } } return group; } public long getGroupCount(ScimFilter filter) { List<ScimGroup> allGroups = groupRepository.findAll(); return allGroups.stream() .filter(group -> matchesFilter(group, filter)) .count(); } private boolean matchesFilter(ScimGroup group, ScimFilter filter) { if (filter == null) { return true; } // Implement filter matching logic return true; } } @Repository public interface ScimGroupRepository extends JpaRepository<ScimGroup, String> { Optional<ScimGroup> findByExternalId(String externalId); List<ScimGroup> findByDisplayNameContainingIgnoreCase(String displayName); List<ScimGroup> findByMembersId(String memberId); }
3. SCIM Mapper
@Component public class ScimMapper { public void updateUserFromUser(ScimUser source, ScimUser target) { if (source.getUserName() != null) { target.setUserName(source.getUserName()); } if (source.getDisplayName() != null) { target.setDisplayName(source.getDisplayName()); } if (source.getExternalId() != null) { target.setExternalId(source.getExternalId()); } if (source.getActive() != null) { target.setActive(source.getActive()); } if (source.getLocked() != null) { target.setLocked(source.getLocked()); } if (source.getName() != null) { target.setName(source.getName()); } if (source.getEmails() != null) { target.setEmails(source.getEmails()); } if (source.getPhoneNumbers() != null) { target.setPhoneNumbers(source.getPhoneNumbers()); } // Update other fields as needed } public void updateGroupFromGroup(ScimGroup source, ScimGroup target) { if (source.getDisplayName() != null) { target.setDisplayName(source.getDisplayName()); } if (source.getDescription() != null) { target.setDescription(source.getDescription()); } if (source.getExternalId() != null) { target.setExternalId(source.getExternalId()); } if (source.getMembers() != null) { target.setMembers(source.getMembers()); } } public ScimUser toScimUser(UserJson userJson) { // Convert from JSON representation to entity return ScimUser.builder() .id(userJson.getId()) .externalId(userJson.getExternalId()) .userName(userJson.getUserName()) .displayName(userJson.getDisplayName()) .active(userJson.getActive()) .build(); // Map other fields } public UserJson toUserJson(ScimUser user) { // Convert from entity to JSON representation UserJson userJson = new UserJson(); userJson.setId(user.getId()); userJson.setExternalId(user.getExternalId()); userJson.setUserName(user.getUserName()); userJson.setDisplayName(user.getDisplayName()); userJson.setActive(user.getActive()); // Map other fields return userJson; } }

SCIM Controllers

1. User Controller
@RestController @RequestMapping("/Users") @Validated @Slf4j public class ScimUserController { private final ScimUserService userService; private final ScimMapper scimMapper; private final ScimResponseBuilder responseBuilder; public ScimUserController(ScimUserService userService, ScimMapper scimMapper, ScimResponseBuilder responseBuilder) { this.userService = userService; this.scimMapper = scimMapper; this.responseBuilder = responseBuilder; } @PostMapping public ResponseEntity<UserResponse> createUser(@Valid @RequestBody UserRequest request) { log.info("Creating user: {}", request.getUserName()); try { ScimUser user = scimMapper.toScimUser(request); ScimUser createdUser = userService.createUser(user); UserResponse response = scimMapper.toUserResponse(createdUser); return ResponseEntity.status(HttpStatus.CREATED) .header("Location", response.getMeta().getLocation()) .body(response); } catch (DuplicateUserException e) { log.warn("Duplicate user creation attempt: {}", request.getUserName()); return ResponseEntity.status(HttpStatus.CONFLICT).build(); } } @GetMapping("/{id}") public ResponseEntity<UserResponse> getUser(@PathVariable String id) { log.debug("Fetching user: {}", id); return userService.getUserById(id) .map(user -> { UserResponse response = scimMapper.toUserResponse(user); return ResponseEntity.ok(response); }) .orElse(ResponseEntity.notFound().build()); } @GetMapping public ResponseEntity<ListResponse<UserResponse>> getUsers( @RequestParam(required = false) String filter, @RequestParam(defaultValue = "1") int startIndex, @RequestParam(defaultValue = "100") int count, @RequestParam(required = false) String sortBy, @RequestParam(required = false) String sortOrder) { log.debug("Searching users - filter: {}, startIndex: {}, count: {}", filter, startIndex, count); ScimFilter scimFilter = parseFilter(filter); List<ScimUser> users = userService.getUsers(scimFilter, startIndex, count); long totalResults = userService.getUserCount(scimFilter); List<UserResponse> userResponses = users.stream() .map(scimMapper::toUserResponse) .collect(Collectors.toList()); ListResponse<UserResponse> response = responseBuilder.buildListResponse( userResponses, startIndex, count, totalResults); return ResponseEntity.ok(response); } @PutMapping("/{id}") public ResponseEntity<UserResponse> updateUser(@PathVariable String id, @Valid @RequestBody UserRequest request) { log.info("Updating user: {}", id); try { ScimUser user = scimMapper.toScimUser(request); ScimUser updatedUser = userService.updateUser(id, user); UserResponse response = scimMapper.toUserResponse(updatedUser); return ResponseEntity.ok(response); } catch (UserNotFoundException e) { log.warn("User not found for update: {}", id); return ResponseEntity.notFound().build(); } } @PatchMapping("/{id}") public ResponseEntity<UserResponse> patchUser(@PathVariable String id, @RequestBody PatchRequest request) { log.info("Patching user: {}", id); try { ScimPatchOperation patchOperation = toScimPatchOperation(request); ScimUser updatedUser = userService.patchUser(id, patchOperation); UserResponse response = scimMapper.toUserResponse(updatedUser); return ResponseEntity.ok(response); } catch (UserNotFoundException e) { log.warn("User not found for patch: {}", id); return ResponseEntity.notFound().build(); } catch (UnsupportedOperationException e) { log.warn("Unsupported patch operation: {}", e.getMessage()); return ResponseEntity.badRequest().build(); } } @DeleteMapping("/{id}") public ResponseEntity<Void> deleteUser(@PathVariable String id) { log.info("Deleting user: {}", id); try { userService.deleteUser(id); return ResponseEntity.noContent().build(); } catch (UserNotFoundException e) { log.warn("User not found for deletion: {}", id); return ResponseEntity.notFound().build(); } } private ScimFilter parseFilter(String filter) { if (filter == null || filter.trim().isEmpty()) { return null; } // Implement filter parsing logic // This would parse SCIM filter expressions like "userName eq \"[email protected]\"" return new ScimFilter(filter); } private ScimPatchOperation toScimPatchOperation(PatchRequest request) { // Convert PatchRequest to ScimPatchOperation return new ScimPatchOperation( request.getOp(), request.getPath(), request.getValue() ); } }
2. Group Controller
@RestController @RequestMapping("/Groups") @Validated @Slf4j public class ScimGroupController { private final ScimGroupService groupService; private final ScimMapper scimMapper; private final ScimResponseBuilder responseBuilder; public ScimGroupController(ScimGroupService groupService, ScimMapper scimMapper, ScimResponseBuilder responseBuilder) { this.groupService = groupService; this.scimMapper = scimMapper; this.responseBuilder = responseBuilder; } @PostMapping public ResponseEntity<GroupResponse> createGroup(@Valid @RequestBody GroupRequest request) { log.info("Creating group: {}", request.getDisplayName()); ScimGroup group = scimMapper.toScimGroup(request); ScimGroup createdGroup = groupService.createGroup(group); GroupResponse response = scimMapper.toGroupResponse(createdGroup); return ResponseEntity.status(HttpStatus.CREATED) .header("Location", response.getMeta().getLocation()) .body(response); } @GetMapping("/{id}") public ResponseEntity<GroupResponse> getGroup(@PathVariable String id) { log.debug("Fetching group: {}", id); return groupService.getGroupById(id) .map(group -> { GroupResponse response = scimMapper.toGroupResponse(group); return ResponseEntity.ok(response); }) .orElse(ResponseEntity.notFound().build()); } @GetMapping public ResponseEntity<ListResponse<GroupResponse>> getGroups( @RequestParam(required = false) String filter, @RequestParam(defaultValue = "1") int startIndex, @RequestParam(defaultValue = "100") int count) { log.debug("Searching groups - filter: {}, startIndex: {}, count: {}", filter, startIndex, count); ScimFilter scimFilter = parseFilter(filter); List<ScimGroup> groups = groupService.getGroups(scimFilter, startIndex, count); long totalResults = groupService.getGroupCount(scimFilter); List<GroupResponse> groupResponses = groups.stream() .map(scimMapper::toGroupResponse) .collect(Collectors.toList()); ListResponse<GroupResponse> response = responseBuilder.buildListResponse( groupResponses, startIndex, count, totalResults); return ResponseEntity.ok(response); } @PutMapping("/{id}") public ResponseEntity<GroupResponse> updateGroup(@PathVariable String id, @Valid @RequestBody GroupRequest request) { log.info("Updating group: {}", id); try { ScimGroup group = scimMapper.toScimGroup(request); ScimGroup updatedGroup = groupService.updateGroup(id, group); GroupResponse response = scimMapper.toGroupResponse(updatedGroup); return ResponseEntity.ok(response); } catch (GroupNotFoundException e) { log.warn("Group not found for update: {}", id); return ResponseEntity.notFound().build(); } } @DeleteMapping("/{id}") public ResponseEntity<Void> deleteGroup(@PathVariable String id) { log.info("Deleting group: {}", id); try { groupService.deleteGroup(id); return ResponseEntity.noContent().build(); } catch (GroupNotFoundException e) { log.warn("Group not found for deletion: {}", id); return ResponseEntity.notFound().build(); } } @PostMapping("/{groupId}/members/{userId}") public ResponseEntity<GroupResponse> addMember(@PathVariable String groupId, @PathVariable String userId) { log.info("Adding member {} to group {}", userId, groupId); try { ScimGroup group = groupService.addMemberToGroup(groupId, userId); GroupResponse response = scimMapper.toGroupResponse(group); return ResponseEntity.ok(response); } catch (GroupNotFoundException | UserNotFoundException e) { log.warn("Failed to add member: {}", e.getMessage()); return ResponseEntity.notFound().build(); } } @DeleteMapping("/{groupId}/members/{userId}") public ResponseEntity<GroupResponse> removeMember(@PathVariable String groupId, @PathVariable String userId) { log.info("Removing member {} from group {}", userId, groupId); try { ScimGroup group = groupService.removeMemberFromGroup(groupId, userId); GroupResponse response = scimMapper.toGroupResponse(group); return ResponseEntity.ok(response); } catch (GroupNotFoundException e) { log.warn("Group not found: {}", groupId); return ResponseEntity.notFound().build(); } } private ScimFilter parseFilter(String filter) { // Implement filter parsing return new ScimFilter(filter); } }
3. Service Provider Config Controller
@RestController @RequestMapping("/ServiceProviderConfig") @Slf4j public class ScimServiceProviderConfigController { private final ScimConfigurationService configService; public ScimServiceProviderConfigController(ScimConfigurationService configService) { this.configService = configService; } @GetMapping public ResponseEntity<ServiceProviderConfigResponse> getServiceProviderConfig() { log.debug("Fetching service provider configuration"); ScimConfiguration config = configService.getDefaultConfiguration(); ServiceProviderConfigResponse response = buildConfigResponse(config); return ResponseEntity.ok(response); } private ServiceProviderConfigResponse buildConfigResponse(ScimConfiguration config) { ServiceProviderConfigResponse response = new ServiceProviderConfigResponse(); // Set supported features response.setPatchSupported(config.getPatchSupported()); response.setBulkSupported(config.getBulkSupported()); response.setFilterSupported(config.getFilterSupported()); response.setEtagSupported(config.getEtagSupported()); response.setSortSupported(config.getSortSupported()); response.setChangePasswordSupported(config.getChangePasswordSupported()); // Set bulk configuration BulkConfig bulkConfig = new BulkConfig(); bulkConfig.setSupported(config.getBulkSupported()); bulkConfig.setMaxOperations(config.getMaxResults()); bulkConfig.setMaxPayloadSize(config.getMaxPayloadSize()); response.setBulk(bulkConfig); // Set filter configuration FilterConfig filterConfig = new FilterConfig(); filterConfig.setSupported(config.getFilterSupported()); filterConfig.setMaxResults(config.getMaxResults()); response.setFilter(filterConfig); // Set authentication schemes List<AuthenticationScheme> authSchemes = config.getAuthenticationSchemes().stream() .map(this::toAuthenticationScheme) .collect(Collectors.toList()); response.setAuthenticationSchemes(authSchemes); return response; } private AuthenticationScheme toAuthenticationScheme( ScimConfiguration.AuthenticationScheme scheme) { AuthenticationScheme authScheme = new AuthenticationScheme(); authScheme.setType(scheme.getType()); authScheme.setName(scheme.getName()); authScheme.setDescription(scheme.getDescription()); authScheme.setSpecUri(scheme.getSpecUri()); authScheme.setDocumentationUri(scheme.getDocumentationUri()); return authScheme; } }

SCIM Request/Response Models

1. Request Models
@Data @JsonIgnoreProperties(ignoreUnknown = true) public class UserRequest { @NotEmpty private String userName; private String externalId; @NotEmpty private String displayName; private Boolean active = true; private Name name; private List<Email> emails; private List<PhoneNumber> phoneNumbers; @Data public static class Name { private String formatted; private String familyName; private String givenName; private String middleName; private String honorificPrefix; private String honorificSuffix; } @Data public static class Email { @NotEmpty private String value; private String type; private Boolean primary = false; } @Data public static class PhoneNumber { @NotEmpty private String value; private String type; } } @Data @JsonIgnoreProperties(ignoreUnknown = true) public class GroupRequest { @NotEmpty private String displayName; private String externalId; private String description; private List<Member> members; @Data public static class Member { @NotEmpty private String value; private String display; private String type = "User"; } } @Data @JsonIgnoreProperties(ignoreUnknown = true) public class PatchRequest { @NotEmpty private List<String> schemas = Arrays.asList("urn:ietf:params:scim:api:messages:2.0:PatchOp"); @NotEmpty private List<Operation> Operations; @Data public static class Operation { @NotEmpty private String op; // add, remove, replace private String path; private Object value; } } @Data public class BulkRequest { @NotEmpty private List<String> schemas = Arrays.asList("urn:ietf:params:scim:api:messages:2.0:BulkRequest"); private List<BulkOperation> Operations; private Integer failOnErrors; @Data public static class BulkOperation { private String method; // POST, PUT, PATCH, DELETE private String bulkId; private String path; private Object data; } }
2. Response Models
@Data @JsonInclude(JsonInclude.Include.NON_NULL) public class UserResponse { @NotEmpty private List<String> schemas = Arrays.asList("urn:ietf:params:scim:schemas:core:2.0:User"); @NotEmpty private String id; private String externalId; @NotEmpty private String userName; @NotEmpty private String displayName; private Boolean active = true; private UserRequest.Name name; private List<UserRequest.Email> emails; private List<UserRequest.PhoneNumber> phoneNumbers; private Meta meta; @Data public static class Meta { private String resourceType = "User"; private Instant created; private Instant lastModified; private String location; private String version; } } @Data @JsonInclude(JsonInclude.Include.NON_NULL) public class GroupResponse { @NotEmpty private List<String> schemas = Arrays.asList("urn:ietf:params:scim:schemas:core:2.0:Group"); @NotEmpty private String id; private String externalId; @NotEmpty private String displayName; private String description; private List<GroupRequest.Member> members; private Meta meta; } @Data @JsonInclude(JsonInclude.Include.NON_NULL) public class ListResponse<T> { @NotEmpty private List<String> schemas = Arrays.asList("urn:ietf:params:scim:api:messages:2.0:ListResponse"); @NotEmpty private List<T> Resources; private int totalResults; private int startIndex; private int itemsPerPage; } @Data @JsonInclude(JsonInclude.Include.NON_NULL) public class ServiceProviderConfigResponse { @NotEmpty private List<String> schemas = Arrays.asList("urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig"); private BulkConfig bulk; private FilterConfig filter; private Boolean patchSupported; private Boolean etagSupported; private Boolean sortSupported; private Boolean changePasswordSupported; private List<AuthenticationScheme> authenticationSchemes; @Data public static class BulkConfig { private Boolean supported; private Integer maxOperations; private Integer maxPayloadSize; } @Data public static class FilterConfig { private Boolean supported; private Integer maxResults; } @Data public static class AuthenticationScheme { private String type; private String name; private String description; private String specUri; private String documentationUri; } } @Data @JsonInclude(JsonInclude.Include.NON_NULL) public class BulkResponse { @NotEmpty private List<String> schemas = Arrays.asList("urn:ietf:params:scim:api:messages:2.0:BulkResponse"); private List<BulkOperationResponse> Operations; @Data public static class BulkOperationResponse { private String method; private String bulkId; private String location; private Integer status; private Object response; private ErrorResponse error; } }
3. Error Responses
@Data @JsonInclude(JsonInclude.Include.NON_NULL) public class ErrorResponse { @NotEmpty private List<String> schemas = Arrays.asList("urn:ietf:params:scim:api:messages:2.0:Error"); @NotEmpty private String scimType; @NotEmpty private String detail; private Integer status; public static ErrorResponse invalidFilter(String detail) { ErrorResponse error = new ErrorResponse(); error.setScimType("invalidFilter"); error.setDetail(detail); error.setStatus(400); return error; } public static ErrorResponse tooMany(String detail) { ErrorResponse error = new ErrorResponse(); error.setScimType("tooMany"); error.setDetail(detail); error.setStatus(400); return error; } public static ErrorResponse uniqueness(String detail) { ErrorResponse error = new ErrorResponse(); error.setScimType("uniqueness"); error.setDetail(detail); error.setStatus(409); return error; } public static ErrorResponse mutability(String detail) { ErrorResponse error = new ErrorResponse(); error.setScimType("mutability"); error.setDetail(detail); error.setStatus(400); return error; } public static ErrorResponse invalidSyntax(String detail) { ErrorResponse error = new ErrorResponse(); error.setScimType("invalidSyntax"); error.setDetail(detail); error.setStatus(400); return error; } public static ErrorResponse invalidPath(String detail) { ErrorResponse error = new ErrorResponse(); error.setScimType("invalidPath"); error.setDetail(detail); error.setStatus(400); return error; } public static ErrorResponse noTarget(String detail) { ErrorResponse error = new ErrorResponse(); error.setScimType("noTarget"); error.setDetail(detail); error.setStatus(400); return error; } public static ErrorResponse invalidValue(String detail) { ErrorResponse error = new ErrorResponse(); error.setScimType("invalidValue"); error.setDetail(detail); error.setStatus(400); return error; } public static ErrorResponse invalidVers(String detail) { ErrorResponse error = new ErrorResponse(); error.setScimType("invalidVers"); error.setDetail(detail); error.setStatus(400); return error; } public static ErrorResponse sensitive(String detail) { ErrorResponse error = new ErrorResponse(); error.setScimType("sensitive"); error.setDetail(detail); error.setStatus(400); return error; } }

Security Configuration

@Configuration @EnableWebSecurity @EnableMethodSecurity public class ScimSecurityConfig { @Value("${scim.auth.bearer-token:default-token}") private String bearerToken; @Bean public SecurityFilterChain filterChain(HttpSecurity http) throws Exception { http .securityMatcher("/scim/v2/**") .authorizeHttpRequests(authz -> authz .anyRequest().authenticated() ) .httpBasic(Customizer.withDefaults()) .sessionManagement(session -> session .sessionCreationPolicy(SessionCreationPolicy.STATELESS) ) .csrf(csrf -> csrf.disable()); return http.build(); } @Bean public UserDetailsService userDetailsService() { UserDetails user = User.builder() .username("scim-client") .password("{noop}scim-password") // Use proper password encoding in production .roles("SCIM_CLIENT") .build(); return new InMemoryUserDetailsManager(user); } @Bean public FilterRegistrationBean<ScimBearerAuthFilter> scimBearerAuthFilter() { FilterRegistrationBean<ScimBearerAuthFilter> registrationBean = new FilterRegistrationBean<>(); registrationBean.setFilter(new ScimBearerAuthFilter(bearerToken)); registrationBean.addUrlPatterns("/scim/v2/*"); return registrationBean; } } @Component public class ScimBearerAuthFilter extends OncePerRequestFilter { private final String expectedToken; public ScimBearerAuthFilter(String expectedToken) { this.expectedToken = expectedToken; } @Override protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain) throws ServletException, IOException { String authHeader = request.getHeader("Authorization"); if (authHeader != null && authHeader.startsWith("Bearer ")) { String token = authHeader.substring(7); if (expectedToken.equals(token)) { filterChain.doFilter(request, response); return; } } response.setStatus(HttpStatus.UNAUTHORIZED.value()); response.getWriter().write("{\"error\": \"Invalid or missing bearer token\"}"); } }

Exception Handling

@ControllerAdvice @Slf4j public class ScimExceptionHandler { @ExceptionHandler(UserNotFoundException.class) public ResponseEntity<ErrorResponse> handleUserNotFound(UserNotFoundException e) { log.warn("User not found: {}", e.getMessage()); ErrorResponse error = ErrorResponse.invalidValue("User not found: " + e.getMessage()); error.setStatus(404); return ResponseEntity.status(404).body(error); } @ExceptionHandler(GroupNotFoundException.class) public ResponseEntity<ErrorResponse> handleGroupNotFound(GroupNotFoundException e) { log.warn("Group not found: {}", e.getMessage()); ErrorResponse error = ErrorResponse.invalidValue("Group not found: " + e.getMessage()); error.setStatus(404); return ResponseEntity.status(404).body(error); } @ExceptionHandler(DuplicateUserException.class) public ResponseEntity<ErrorResponse> handleDuplicateUser(DuplicateUserException e) { log.warn("Duplicate user: {}", e.getMessage()); ErrorResponse error = ErrorResponse.uniqueness("User already exists: " + e.getMessage()); return ResponseEntity.status(409).body(error); } @ExceptionHandler(MethodArgumentNotValidException.class) public ResponseEntity<ErrorResponse> handleValidationErrors(MethodArgumentNotValidException e) { log.warn("Validation error: {}", e.getMessage()); String errorMessage = e.getBindingResult().getFieldErrors().stream() .map(error -> error.getField() + ": " + error.getDefaultMessage()) .collect(Collectors.joining(", ")); ErrorResponse error = ErrorResponse.invalidSyntax(errorMessage); return ResponseEntity.status(400).body(error); } @ExceptionHandler(Exception.class) public ResponseEntity<ErrorResponse> handleGenericException(Exception e) { log.error("Unexpected error in SCIM endpoint", e); ErrorResponse error = ErrorResponse.invalidSyntax("Internal server error"); error.setStatus(500); return ResponseEntity.status(500).body(error); } } public class UserNotFoundException extends RuntimeException { public UserNotFoundException(String message) { super(message); } } public class GroupNotFoundException extends RuntimeException { public GroupNotFoundException(String message) { super(message); } } public class DuplicateUserException extends RuntimeException { public DuplicateUserException(String message) { super(message); } }

Testing

1. Integration Tests
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT) @TestInstance(TestInstance.Lifecycle.PER_CLASS) class ScimUserControllerIntegrationTest { @Autowired private TestRestTemplate restTemplate; @Autowired private ScimUserRepository userRepository; @BeforeEach void cleanup() { userRepository.deleteAll(); } @Test void testCreateUser() { UserRequest request = new UserRequest(); request.setUserName("[email protected]"); request.setDisplayName("John Doe"); HttpEntity<UserRequest> entity = new HttpEntity<>(request, createAuthHeaders()); ResponseEntity<UserResponse> response = restTemplate.exchange( "/Users", HttpMethod.POST, entity, UserResponse.class); assertThat(response.getStatusCode()).isEqualTo(HttpStatus.CREATED); assertThat(response.getBody().getUserName()).isEqualTo("[email protected]"); assertThat(response.getBody().getId()).isNotNull(); assertThat(response.getHeaders().getLocation()).isNotNull(); } @Test void testGetUser() { // First create a user ScimUser user = createTestUser(); userRepository.save(user); HttpEntity<Void> entity = new HttpEntity<>(createAuthHeaders()); ResponseEntity<UserResponse> response = restTemplate.exchange( "/Users/" + user.getId(), HttpMethod.GET, entity, UserResponse.class); assertThat(response.getStatusCode()).isEqualTo(HttpStatus.OK); assertThat(response.getBody().getUserName()).isEqualTo("[email protected]"); } @Test void testUpdateUser() { ScimUser user = createTestUser(); userRepository.save(user); UserRequest request = new UserRequest(); request.setUserName("[email protected]"); request.setDisplayName("Updated User"); HttpEntity<UserRequest> entity = new HttpEntity<>(request, createAuthHeaders()); ResponseEntity<UserResponse> response = restTemplate.exchange( "/Users/" + user.getId(), HttpMethod.PUT, entity, UserResponse.class); assertThat(response.getStatusCode()).isEqualTo(HttpStatus.OK); assertThat(response.getBody().getUserName()).isEqualTo("[email protected]"); } private ScimUser createTestUser() { return ScimUser.builder() .id(UUID.randomUUID().toString()) .userName("[email protected]") .displayName("Test User") .active(true) .metaCreated(Instant.now()) .metaLastModified(Instant.now()) .build(); } private HttpHeaders createAuthHeaders() { HttpHeaders headers = new HttpHeaders(); headers.setBasicAuth("scim-client", "scim-password"); return headers; } }
2. SCIM Client Test
@Component @Slf4j public class ScimClientTest { private final ScimUserService userService; private final ScimGroupService groupService; public void testScimOperations() { // Test user creation ScimUser user = ScimUser.builder() .userName("[email protected]") .displayName("Alice Smith") .active(true) .name(ScimUser.Name.builder() .givenName("Alice") .familyName("Smith") .build()) .emails(List.of( ScimUser.Email.builder() .value("[email protected]") .type("work") .primary(true) .build() )) .build(); ScimUser createdUser = userService.createUser(user); log.info("Created user: {}", createdUser.getId()); // Test group creation ScimGroup group = ScimGroup.builder() .displayName("Developers") .description("Software development team") .members(List.of(createdUser)) .build(); ScimGroup createdGroup = groupService.createGroup(group); log.info("Created group: {}", createdGroup.getId()); // Test user search List<ScimUser> users = userService.getUsers(null, 1, 10); log.info("Found {} users", users.size()); // Test group membership ScimGroup updatedGroup = groupService.addMemberToGroup( createdGroup.getId(), createdUser.getId()); log.info("Group now has {} members", updatedGroup.getMembers().size()); } }

Best Practices

  1. Idempotency: Ensure PUT operations are idempotent
  2. Filter Support: Implement comprehensive filter support
  3. Bulk Operations: Handle bulk operations efficiently
  4. Error Handling: Provide detailed SCIM-compliant error responses
  5. Security: Implement proper authentication and authorization
  6. Validation: Validate all incoming SCIM requests
  7. Logging: Log all provisioning activities for audit purposes
  8. Performance: Implement pagination for large datasets
// Example of idempotent user creation @Service public class IdempotentScimService { public ScimUser createUserIfNotExists(ScimUser user) { return userService.getUserByUserName(user.getUserName()) .orElseGet(() -> userService.createUser(user)); } }

Conclusion

SCIM provisioning in Java provides:

  • Standardized user management across different systems
  • Automated provisioning and deprovisioning
  • Consistent API for identity management
  • Enterprise-ready with proper security and error handling

This implementation supports the full SCIM 2.0 specification including users, groups, filtering, pagination, bulk operations, and proper error handling. It can be integrated with any SCIM-compliant identity provider or service provider.

Category : JAVA

Leave a Reply

Your email address will not be published. Required fields are marked *


Macro Nepal Helper