Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision 		Previous revision
Next revision Both sides next revision
devel:documentation:modules_scim [2019/08/16 09:14]
tomiskar [SCIM standard resources] 		devel:documentation:modules_scim [2020/03/22 11:52]
poulm grammar
Line 1: Line 1:
-<- .:modules_sms |  ^ .:start | Documentation ^  .:conventions | ->+<- .:modules_sms |  ^ .:start | Documentation ^  .:modules_tool | ->
  
 {{tag> scim}} {{tag> scim}}
Line 12: Line 12:
 ==== Dependencies ==== ==== Dependencies ====
  
-We are using third party library [[https://github.com/pingidentity/scim2|scim2-sdk-common]] under LGPLv2 license. This library contains very useful DTOs (scim standard resources) and filter parser. Rest endpoints are exposed by our devstack.+We are using a third party library [[https://github.com/pingidentity/scim2|scim2-sdk-common]] under LGPLv2 license. This library contains very useful DTOs (scim standard resources) and filter parser. Rest endpoints are exposed by our devstack.
  
 Module can be installed both ways: Module can be installed both ways:
Line 18: Line 18:
 ==== Maven ==== ==== Maven ====
  
-This way is mainly for developer, when CzechIdM is opened in your favorite IDE. You can add maven dependency into **idm-app** pom.xml (or into other project specific (and used) module pom.xml):+This way is mainly for a developer, when CzechIdM is opened in your favorite IDE. You can add maven dependency into **idm-app** pom.xml (or into other project-specific (and used) module pom.xml):
  
 <code xml> <code xml>
Line 28: Line 28:
 </code> </code>
  
-Third party dependencies will be included automatically.+Third-party dependencies will be included automatically.
  
-Note: module has to be built locally - available in [[https://git.bcvsolutions.eu/modules/scim|gitlab]] or access to our [[https://nexus.bcvsolutions.eu/#browse/browse/components:maven-modules-releases|nexus]] has to be granted and repository included in the same pom.xml:+Note: the module has to be built locally - available in [[https://git.bcvsolutions.eu/modules/scim|gitlab]] or access to our [[https://nexus.bcvsolutions.eu/#browse/browse/components:maven-modules-releases|nexus]] has to be granted and repository included in the same pom.xml:
  
 <code xml> <code xml>
Line 54: Line 54:
 ===== Architecture ===== ===== Architecture =====
  
-Module is separated to two libraries - api and implementation. Api contains useful DTOs, which can be used for the client implementation:+The module is separated into two libraries - API and implementation. API contains useful DTOs, which can be used for client implementation:
  
 <code xml> <code xml>
Line 116: Line 116:
   * ''phoneNumbers'' - only one phone number (primary) can be given   * ''phoneNumbers'' - only one phone number (primary) can be given
  
-This attributes are not implemented on the CzechIdM side by default, so when client try to save this attributes, exception with filled unsupported attribute name will be thrown. Custom module extension can be created, when attributes should be supported and saved in CzechIdM (with ''ScimUserService'' extension - override ''toDto'' and ''toResource'' methods and save attribute e.g. to custom extended attributes or into custom entity).+These attributes are not implemented on the CzechIdM side by default, so when the client tries to save these attributes, an exception with filled unsupported attribute name will be thrown. Custom module extension can be created, when attributes should be supported and saved in CzechIdM (with ''ScimUserService'' extension - override ''toDto'' and ''toResource'' methods and save attribute e.g. to custom extended attributes or into custom entity). 
 + 
 +Group resource property ''displayName'' is mapped to CzechIdM attributes ''code'' and ''name''. If ''displayName'' is changed, then both properties are changed (since 1.2.0 version, previous version modified ''name'' attribute only, ''code'' was unmodifiable).
  
 Implemented filter and sort properties on standard scim resources: Implemented filter and sort properties on standard scim resources:
   * ''User'' - ''externalId'', ''userName'', ''name.familyName''   * ''User'' - ''externalId'', ''userName'', ''name.familyName''
-  * ''Group'' - ''externalId'', ''displayName'' (mapped to both - code and name)+  * ''Group'' - ''externalId'', ''displayName''
  
-Filter supports equals (''eq'') operator and ''AND'' clause only. When other operator or clause is used, then unsupported operation will be thrown. Pagination ''startIndex'' and ''count'' parameter can be used. ''startIndex'' parameter is he 1-based index of the first query result. Start index has to be the first index on the page (n * count + 1), exception with code ''FIND\_START\_INDEX\_INVALID'' is thrown otherwise (CzechIdM can paginate by the whole page only). Filter parameter has to be url encoded.+Filter supports equals (''eq'') operator and ''AND'' clause only. When other operator or clause is used, then the unsupported operation will be thrown. Pagination ''startIndex'' and ''count'' parameter can be used. ''startIndex'' parameter is the 1-based index of the first query result. Start index has to be the first index on the page (n * count + 1), exception with code ''FIND\_START\_INDEX\_INVALID'' is thrown otherwise (CzechIdM can paginate by the whole page only). The filter parameter has to be URL encoded.
  
 Standard CzechIdM filter properties can be used too, this is not in SCIM standard - e.g. ''<server>/api/v1/scim/Users?username=testOne'' is alias to SCIM standard ''<server>/api/v1/scim/Users?filter%3DuserName%20eq%20%22testOne%22''. Standard CzechIdM filter properties can be used too, this is not in SCIM standard - e.g. ''<server>/api/v1/scim/Users?username=testOne'' is alias to SCIM standard ''<server>/api/v1/scim/Users?filter%3DuserName%20eq%20%22testOne%22''.
Line 146: Line 148:
  
 and extensions: and extensions:
-  * Extended form values - namespace ''urn:ietf:params:scim:schemas:CzechIdM:8.1:Form''. Extended form values can be added to standard and custom resources. Resources, which supports extended forms can be listed on schemes endpoint.+  * Extended form values - namespace ''urn:ietf:params:scim:schemas:CzechIdM:8.1:Form''. Extended form values can be added to standard and custom resources. Resources, which support extended forms can be listed on schemes endpoint.
  
-Available form definitions (and their attributes) for saving extended attribute values can be listed by ''FormDefinition'' resource type endpoint. Then extended form values can be saved together with resource (Resource has to implement ''FormableResource'' interface):+Available form definitions (and their attributes) for saving extended attribute values can be listed by ''FormDefinition'' resource type endpoint. Then extended form values can be saved together with the resource (Resource has to implement ''FormableResource'' interface):
 <code json> <code json>
 { {
Line 171: Line 173:
 </code> </code>
  
-As you can see, you don't need to know exact form definition and attributes uuid identifiers - code can be given instead, but uuid identifier can be used too (alias). When request with resource is sent (POST / PUT / PATCH), then uuid identifiers are returned for saved resources. Saved value identifier has to be used, when value has to be updated, otherwise value will be recreated (=> drop and create). +As you can see, you don't need to know exact form definition and attributes uuid identifiers - code can be given instead, but uuid identifier can be used too (alias). When request with the resource is sent (POST / PUT / PATCH), then uuid identifiers are returned for saved resources. Saved value identifier has to be used when the value has to be updated, otherwise, the value will be recreated (=> drop and create). 
  
 ==== Swagger ==== ==== Swagger ====
Line 185: Line 187:
 Then swagger documentation will be available at url ''<server>/swagger-ui.html''. Then swagger documentation will be available at url ''<server>/swagger-ui.html''.
  
-This property is configured in test and production profile by default.+This property is configured in the test and production profile by default.
  
  
  • by poulm