SCIMSEARCH   = scimEndpoint [scimSearch] ["/" UUID] ["?" query]

scimEndpoint = "https://" authority [path-absolute] [scimVers] 
               [scimResType] ["/" UUID]
        
scimSearch   = "/.search"

authority    = [ userinfo "@" ] host [ ":" port ]

scimVers     = "/V" 1*DIGIT

scimResType  = "/Users" / "/Groups" / "/" 1*extResChar

extResChar   = "-" / "." / "_" / DIGIT / ALPHA

Figure 1: ABNF for SCIM Search Endpoints

[Discussion: since a search within a "/Users" endpoint could be confused with a resource, do we want to have something more jarring like "xsearch" or ".search" (as in well-known urls)?]

Where:

scimSearch

Is a special path qualifier that indicates the operation is related to a search. When used with HTTP GET, scimSearch is OPTIONAL.

authority, path-absolute, userinfo, host, port

Are defined as per URI Syntax ABNF [RFC3986]

query

Is any SCIM query term as specified in section 3.2 of the SCIM Core API [I-D.ietf-scim-api].

scimVers

Is the SCIM Service Provider API version.

scimResType

Is a SCIM resource type such as "Users", "Groups" or any other schema extended resource supported by the service provider.

UUID

Identifies a unique SCIM resource or SCIM search result that is retrievable from the SCIM Service Provider (see [RFC4122]).

Example SCIM Search endpoints include:

http://example.com/scim/v2/.search

for server-wide searches

http://example.com/scim/v2/Users/.search

for searches of User resources only

http://example.com/scim/v2/Groups/.search

for searches of Group resources only

http://example.com/scim/v2/.search?searchId=607dac9b24a2;startIndex=20

to return results from a previously executed query

Token search is initiated by using either an HTTP POST or HTTP GET command (see next sections) to pass search parameters AND by setting the parameter "stateful" to "true". The server responds and returns results in a JSON result set along with a searchId token if stateful results are available.

2.1. Search Tokens

From the clients perspective, as with any HTTP is a stateless protocol. When performing searches requiring several pages of results to be returned, there is always the possibility to have inconsistent results should the underlying data change between requests. SCIM Service Providers MAY optionally maintain a stateful representation of search results that may be accessed by the client using a token.

Once a search result "searchId" token has been created, a client may peform GET requests using the parameter "searchId" and "startIndex" to return additional result pages. Any other parameters and path are IGNORED when "searchId" is present. The searchId token allows the service provider to respond with consistent stateful results, using pagination commands as defined in section 3.2.2.3 of the SCIM Core API.

[Discussion: Can an existing search result be used in combination with a new search or ordering request to sub-search within an existing set of results? E.g. would it make sense to allow a PUT against an existing search result?]

2.2. Filter Processing Across Multiple Resource Types

When the SCIM Extended Search specification is supported, Filtering, as defined in the SCIM Core API, section 3.2.2.1 is REQUIRED.

When processing search operations across endpoints that MAY include more than one SCIM resource type (e.g. a search from the server root endpoint), filters MUST be processed in the same fashion as outlined in 3.2.2.1 of the SCIM Core API. For filtered attributes that are not part of a particular resource type, the service provider SHALL treat the attribute as if there is no attribute value. For example, a presence or equality filter for an undefined attribute evaluates as FALSE.

2.3. Search Request Using HTTP POST

To create a new search result set, clients send an HTTP POST request to the desired SCIM resource endpoint (see Figure 1). The body of the POST request MAY include any of the parameters as defined in section 3.2 of the SCIM Core API.

An additional parameter "stateful" MAY be set to "true" in order to request stateful results from the server. Note that the presence of this parameter DOES NOT require that the server produce a stateful result set. Detection of stateful results is described in Section 2.5.1.

After receiving a HTTP POST request, a response is returned as specified in Section 2.5.

POST /.search
Host: example.com
Accept: application/json
Content-Type: application/json
Authorization: Bearer h480djs93hd8
Content-Length: ...

{
  "schemas": ["urn:scim:schemas:core:1.0"],
  "attributes":["displayName","username"],
  "filter":"displayName sw \"smith\"",
  "stateful":"true",
  "count":10
}

GET /.search?attributes="displayName,username"
    &filter=displayName sw "smith"&count=10&stateful="true"
Host: example.com
Accept: application/json
Authorization: Bearer h480djs93hd8

HTTP/1.1 201 Created
Content-Type: application/json
Location: https://example.com/.search
{
  "totalResults":100,
  "itemsPerPage":10,
  "startIndex":1,
  "searchId":"131dc0667e20"
  "schemas":["urn:scim:schemas:core:1.0"],
  "Resources":[
    {
      "meta":{
        "location":
          "https://example.com/Users/2819c223-7f76-413861904646",
        "resourceType":"User",
        "lastModified": ...
      }
      "username":"jsmith",
      "displayName":"Smith, James"
    },
    {
      "meta":{
        "location":
          "https://example.com/Groups/c8596b90-7539-4f20968d1908",
        "resourceType":"Group",
        "lastModified": ...
      }
      "displayName":"Smith Family"
    },
     ...
  ]
} 

GET /v2/.search?startIndex=11&count=10
      &searchId=2a7229cc-d9dc-4153-131dc0667e20
HOST: example.com
Accept: application/json
Content-Type: application/json
Authorization: Bearer h480djs93hd8

DELETE /Users/.search?searchId=64b6efd7-6598-4dbc-ab3a-af38dad71493
Host: example.com
Authorization: Bearer h480djs93hd8


HTTP/1.1 200 OK