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
devel:documentation:modules_scim [2019/08/16 09:14]
tomiskar [SCIM standard resources] 		devel:documentation:modules_scim [2020/03/22 21:09] (current)
poulm typos
Line 1: Line 1:
-<- .:modules_sms |  ^ .:start | Documentation ^  .:conventions | ->+<- .:modules_sms |  ^ .:start | Documentation ^  .:modules_tool | ->
  
 {{tag> scim}} {{tag> scim}}
  
-====== Modules - SCIM [scim] - System for Cross-domain Identity Management ======+====== Modules - SCIM [scim] ======
  
-The System for Cross-domain Identity Management ([[http://www.simplecloud.info/|SCIM]]) specification is designed to make managing user identities in cloud-based applications and services easier. The specification suite seeks to build upon experience with existing schemas and deployments, placing specific emphasis on simplicity of development and integration, while applying existing authentication, authorization, and privacy models. Its intent is to reduce the cost and complexity of user management operations by providing a common user schema and extension model, as well as binding documents to provide patterns for exchanging this schema using standard protocols. In essence: make it fast, cheap, and easy to move users in to, out of, and around the cloud.+"scim" module exposes interface in CzechIdM by the [[http://www.simplecloud.info/|SCIM 2.0 specification]]. Thus CzechIdM can be - as a server - connected to clients that implement SCIM 2.0 via its public [[.dev:scim_api| API]].
  
-Scim module exposes interface in CzechIdM by the SCIM 2.0 specification. Read more about SCIM [[http://www.simplecloud.info/| model, operations and endpoints]]. +{{ :devel:documentation:scim_server.jpg | SCIM module}}
-===== Installation =====+
  
-==== Dependencies ====+More about general SCIM specification - [[http://www.simplecloud.info/| model, operations and endpoints]].
  
-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.+====== Read more ======
  
-Module can be installed both ways:+===== Admin tutorials ===== 
 +  * [[ tutorial:adm:modules_scim_installation|Installation tutorial]]
  
-==== Maven ==== +===== Devel guide ===== 
- +  * [[.dev:scim_api| SCIM API description (CzechIdM implementation)]] 
-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): +  * [[.dev:scim_architecture| SCIM architecture]]
- +
-<code xml> +
-<dependency> +
-  <groupId>eu.bcvsolutions.idm</groupId> +
-  <artifactId>idm-scim-impl</artifactId> +
-  <version>1.0.1</version> +
-</dependency> +
-</code> +
- +
-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: +
- +
-<code xml> +
-<repository> +
-  <id>nexus</id> +
-  <name>Nexus private modules</name> +
-  <url>https://nexus.bcvsolutions.eu/repository/maven-modules-releases/</url> +
-</repository> +
-</code> +
- +
-==== Standalone module ==== +
- +
-Module artefact (idm-scim-api, idm-scim-impl) can be downloaded from [[https://nexus.bcvsolutions.eu/#browse/browse/components:maven-modules-releases|nexus]] releases and copied into installed CzechIdM server libraries ''<server>/WEB-INF/lib''. +
- +
-Third party library ''scim2-sdk-common'' in version 2.1.3 has to be copied into CzechIdM server libraries ''<server>/WEB-INF/lib'' too. Library can be built from [[https://github.com/pingidentity/scim2|github]] or downloaded from a public maven repository (e.g. [[http://central.maven.org/maven2/com/unboundid/product/scim2/scim2-sdk-common/2.1.3/scim2-sdk-common-2.1.3.jar|central.maven.org]]). +
- +
-After module is installed, run the CzechIdm and enable module by GUI (Setting -> Modules) or by application properties: +
-<code properties> +
-# enable scim module by default +
-idm.pub.scim.enabled=true +
-</code> +
- +
-===== Architecture ===== +
- +
-Module is separated to two libraries - api and implementation. Api contains useful DTOs, which can be used for the client implementation: +
- +
-<code xml> +
-<dependency> +
-  <groupId>eu.bcvsolutions.idm</groupId> +
-  <artifactId>idm-scim-api</artifactId> +
-  <version>1.0.1</version> +
-</dependency> +
-</code> +
- +
-Note: The same [[https://nexus.bcvsolutions.eu/#browse/browse/components:maven-modules-releases|nexus]] repository has to be configured and access has to be granted as above. +
- +
-===== API ===== +
- +
-Scim base path is available at url ''<server>/api/v1/scim''. To simplify interoperability, SCIM provides three end points to discover supported features and specific attribute details:  +
- +
-  * ''<server>/idm/api/v1/scim/ResourceTypes'' - An endpoint used to discover the types of resources available. +
-  * ''<server>/idm/api/v1/scim/Schemas'' - Introspect resources and attribute extensions. +
-  * ''<server>/idm/api/v1/scim/ServiceProviderConfig'' - Specification compliance, authentication schemes, data models. +
-  *  +
-This endpoints are public - no authentication is needed. +
- +
-Resources are exposed on endpoints by resource types (authentication is needed): +
-  * ''<server>/idm/api/v1/scim/<resource_name>'' - endpoints for resources, uses hateoas standard. +
- +
- +
-==== Security ==== +
- +
-Two authentication schemes is supported now: +
-  * Basic authentication - specification is available [[http://www.rfc-editor.org/info/rfc2617|here]] +
-  * Token authentization - Authentication scheme using the CzechIdM authentication token in ''CIDMST'' header. Documentation and example is available in swagger ''<server>/swagger-ui.html#!/Authentication/loginUsingPOST'' (read more below). +
- +
-=== Permissions === +
-Module defines new permission group: +
-  * ''SCIM\_READ'' - read all resources +
-  * ''SCIM\_CREATE'' - create all resources +
-  * ''SCIM\_UPDATE'' - update all resources +
-  * ''SCIM\_DELETE'' - delete all resources +
- +
-Standard CzechIdM authorization policies are not supported. +
-==== SCIM standard resources ==== +
- +
-<note tip>Read more about SCIM [[http://www.simplecloud.info/| model, operations and endpoints]].</note> +
- +
-Standard scim schemas and resources [[https://tools.ietf.org/html/rfc7643|rfc7643]] are implemented with a few limitations: +
- +
-User resource unsupported properties, which cannot be saved in CzechIdM: +
-  * ''nickName'' +
-  * ''title'' +
-  * ''preferredLanguage'' +
-  * ''locale'' +
-  * ''timeZone'' +
-  * ''addresses'' +
-  * ''ims'' +
-  * ''photos'' +
-  * ''roles'' +
-  * ''entitlements'' +
-  * ''x509Certificates'' +
-  * ''name.middleName'' +
-  * ''emails'' - only one email (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). +
- +
-Implemented filter and sort properties on standard scim resources: +
-  * ''User'' - ''externalId'', ''userName'', ''name.familyName'' +
-  * ''Group'' - ''externalId'', ''displayName'' (mapped to both - code and name) +
- +
-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. +
- +
-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''. +
- +
-If CzechIdM resource implements ''Codeable'' interface (e.g. User, Group, TreeType), then resource can be addressed additivelly by code in url and used in filter properties. E.q. ''<server>/api/v1/scim/Users/testOne'' will get user resource. UUID identifier can be used too. +
- +
-Bulk operation is not supported. +
- +
-Attribute names and values are case sensitive. +
- +
-==== Custom schemas, resources and extensions ==== +
- +
-Module adds custom schema ''urn:ietf:params:scim:schemas:CzechIdM:8.1'' with resources: +
-  * ''Contract'' - ~ ''IdmIdentityContract'', implemented filter properties ''externalId'', ''user'', ''position'', ''main'', ''workPosition'' +
-  * ''ContractGuarantee'' - ~ ''IdmContractGuarantee'', implemented filter properties ''externalId'', ''guarantee'', ''contract'' +
-  * ''UserGroup'' - ~ ''IdmIdentityRole'', implemented filter properties ''externalId'', ''guarantee'', ''contract'' +
-  * ''TreeType'' - ~ ''IdmTreeType'', implemented filter properties ''externalId'', ''code'' +
-  * ''TreeNode'' - ~ ''IdmTreeNode'', implemented filter properties ''externalId'', ''code'', ''parent'', ''treeType'' +
-  * ''Form'' - extended form definitions, attributes and values - just schema without resource +
-  * ''FormDefinition'' - ~ ''IdmFormDefinition'', implemented filter properties ''type'', ''code''. Readonly form definitions. +
-  * ''FormAttribute'' - ~ ''IdmFormAttribute'' - just schema without resource +
-  * ''FormValue'' - ~ ''IdmFormValue'' - just schema without resource +
- +
-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. +
- +
-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): +
-<code json> +
-{ +
-   "schemas": [ +
-     "urn:ietf:params:scim:schemas:core:2.0:User", +
-     "urn:ietf:params:scim:schemas:CzechIdM:8.1:Form" +
-    ], +
-   "userName": "scimOne", +
-   "urn:ietf:params:scim:schemas:CzechIdM:8.1:Form": { +
-   "forms" : [{ +
-    "code": "default", +
-    "attributes": [{ +
-    "code": "extArtrOne", +
-  "values": [{ +
-          "shortTextValue": "test" +
-  }] +
-    } +
-    ] +
-   } +
-   ]} +
-} +
-</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).  +
- +
-==== Swagger ==== +
- +
-To expose swagger documentation endpoints, application property has to be [[.:application_configuration:dev:backend#swagger|configured]]: +
- +
-<code properties> +
-## Swagger config +
-# enable swagger endpoint (can be disabled for development etc.) +
-springfox.documentation.swagger.enabled=true +
-</code> +
- +
-Then swagger documentation will be available at url ''<server>/swagger-ui.html''. +
- +
-This property is configured in test and production profile by default. +
- +
- +
-====== Read more ====== +
- +
-===== Admin guide ===== +
-  * [[.adm:module_scim|SCIM module: Forming groups of users]]+
  
 ===== Devel tutorials ===== ===== Devel tutorials =====
-  * [[ tutorial:dev:scim_user_role ]] +  * [[ tutorial:dev:scim_user_role]] 
-  * [[ tutorial:dev:scim_form_value ]] +  * [[ tutorial:dev:scim_form_value]]
- +
- +
- +
  
  • by tomiskar