Skip to content

Additional Features

Jump to bottom
Pascal Knüppel edited this page Jan 11, 2024 · 13 revisions

this project comes with some additional features not directly defined by RFC7643 or RFC7644.

default-values (@since 1.20.0)

It is now possible to add default values to SchemaAttributes:

{
      "name": "preferredLanguage",
      "type": "string",
      "description": "Indicates the User's preferred written or\nspoken language.  Generally used for selecting a localized user interface; e.g., 'en_US' specifies the language English and country",
      "mutability": "readWrite",
      "returned": "default",
      "uniqueness": "none",
      "multiValued": false,
      "required": false,
      "caseExact": false,
      "defaultValue": "EN"    <-- default value
    }

you can also set the default value during runtime:

resourceType = resourceEndpoint.registerEndpoint(new UserEndpointDefinition(userHandler));
SchemaAttribute schemaAttribute = resourceType.getSchemaAttribute("preferredLanguage");
schemaAttribute.setDefaultValue("EN");

You can then control when the default value should be set by using the ServiceProvider object:

serviceProvider.setUseDefaultValuesOnRequest(true);
serviceProvider.setUseDefaultValuesOnResponse(true);

by default both values are set to true.

the attributes and excludedAttributes parameter

the attributes parameter can be used to define attributes that must be returned by the service provider. This must e.g. be used if a schema definition defines attributes that have a returned value of request. These attributes will only be returned if the client directly asks for them. But defining the attributes parameter just to get the attributes with the returned value of request would lead the service provider into the position that only the minimal set should be returned which are all attributes with a returned value of always plus the attributes defined in the attributes parameter. To make this problem easier for you it is possible to add the resource-uri into the attributes parameter which will then return the full dataset, e.g.: urn:ietf:params:scim:schemas:core:2.0:User

Change of Behaviour (@since 1.21.0)

SCIM defines the attributes and the excludedAttribute parameters as mutually exclusive. The SCIM SDK has removed this limitation due to a specific feature that was added with version 1.21.0. It is possible to use the schema-URIs of a specific resource (this includes schema-extensions) to request the whole attribute-set of a schema. Why should I do this?

  • In some cases you have specific attributes with a returned-value of request. Such attributes are only returned if explicitly requested by the attributes parameter. But if you do so, attributes with a returned-value of default will not be returned anymore. If you want to get the whole resource including the attributes that were just requested you can now use the schemas URI as identifier that will be resolved into the whole attributes-set of the resource.
  • With this feature the excludedAttributes becomes more interesting. You can now access the whole set of a resource and exclude specific attributes. The excludedAttributes-parameter gets precedence before the attributes-parameter if both are used together.

There is one more change in behaviour. If you use the attributes-parameter non requested attributes with a returned-value of default will not be returned anymore except for attributes that are required. An example would be the userName of the users schema. In previous versions the userName was removed from the response if the attributes-parameter was used and did not contain the userName-attribute. To remove required-attributes from the response you will need to use the excludedAttributes-parameter

Auto filtering

normally a framework like this will not be able to filter your resources because the resources are stored within a database and if this is the case you are discouraged to use this feature. But if you may have simple resource set that does not exceed a certain size and is kept in an in memory map or something similiar you may activate the autoFiltering feature. autoFiltering is a feature that can be enabled per resource type. If you called the registration method resourceEndpoint.registerEndpoint(endpointDefinition) you will receive a ResourceType instance on which you may enable this feature.

Please note that autoFiltering will only work if the ServiceProvider configuration instance has set its support for filtering to true

Auto sorting

auto sorting works the same way as auto filtering. It is possible to enable this feature for a specific resource type causing the application to execute sorting automatically if the client provided a "sortBy" parameter in the request. Auto sorting is executed directly after the filtering process and requires the sort-feature in the service provider configuration to be set to supported.

singleton endpoints

this feature can be enabled per resource type. it does nothing else but delegating all requests that would normally trigger the list-resources method to the get-resources method. This feature is by default activated on the /ServiceProviderConfig endpoint. But lets say you got different realms with different service provider configurations and you want to provide the possibility to read all service provider configurations with the list-resource request. Than simply deactivate the feature on the ResourceType object or override the resource type schema with a new json document in which this feature is disabled.

example of resource type with features

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:ResourceType"
  ],
  "schema": "urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig",
  "id": "ServiceProviderConfig",
  "name": "ServiceProviderConfig",
  "description": "the service providers configuration",
  "endpoint": "/ServiceProviderConfig",
  "urn:gold:params:scim:schemas:extension:url:2.0:ResourceTypeFeatures": {
    "singletonEndpoint": true,
    "autoFiltering": false,
    "autoSorting": false
  },
  "meta": {
    "resourceType": "ResourceType",
    "created": "2019-10-18T14:51:11+02:00",
    "lastModified": "2019-10-18T14:51:11+02:00",
    "location": "/ResourceTypes/ServiceProviderConfig"
  }
}

disable single endpoints on resource types (@since 1.2.0)

You can disable specific methods for a resource type. So you are able to set either one, several or all of the following methods to disabled:

  • create
  • get
  • list
  • update (includes patch)
  • delete

this can be achieved by accessing the class EndpointControlFeature of a ResourceType in the following way: resourceType.getFeatures().getEndpointControlFeatures().

NOTE:

if you set all methods to disabled the application reacts the same way as if you would have disabled the whole resource type

Alternatively you can disable the endpoints directly within the resource-type.json file:

{
  "schemas" : [ "urn:ietf:params:scim:schemas:core:2.0:ResourceType", "urn:gold:params:scim:schemas:extension:url:2.0:ResourceTypeFeatures" ],
  "id" : "ServiceProviderConfig",
  "name" : "ServiceProviderConfig",
  "description" : "the service providers configuration",
  "endpoint" : "/ServiceProviderConfig",
  "schema" : "urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig",
  "urn:gold:params:scim:schemas:extension:url:2.0:ResourceTypeFeatures" : {
    ...
    "endpointControl" : {
      "disableCreate" : true,
      "disableGet" : true,
      "disableList" : true,
      "disableUpdate" : true,
      "disableDelete" : true
    }
  }
}

disable resource types (@since 1.2.0)

You can disable single resource types during runtime and enable them again. All you need to do for this is to either use the setDisabled(Boolean) on the ResourceType class or to disable any single endpoint for the given resource type by setting all methods to disabled within the EndpointControlFeature.

You can even start the application with the endpoints disabled by having the feature set within the resource-type.json file:

{
  "schemas" : [ "urn:ietf:params:scim:schemas:core:2.0:ResourceType", "urn:gold:params:scim:schemas:extension:url:2.0:ResourceTypeFeatures" ],
  "id" : "ServiceProviderConfig",
  "name" : "ServiceProviderConfig",
  "description" : "the service providers configuration",
  "endpoint" : "/ServiceProviderConfig",
  "schema" : "urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig",
  "urn:gold:params:scim:schemas:extension:url:2.0:ResourceTypeFeatures" : {
    ...
    "disabled" : true
  }
}
Clone this wiki locally