Tutorial¶

The scim command allows you to interact with a SCIM server.

Tip

If you want to test scim2-cli with a real SCIM server, you can install and run scim2-server:

$ pip install scim2-server
$ scim2-server

Then you have a functional SCIM server available at http://127.0.0.1:8080 that you can use to test the different commands.

Basic parameters¶

In order to connect to a SCIM server you will need to pass the --url parameter. You can also pass additional headers, such as authentication ones, with --header.

$ scim2 --url https://auth.example --header "Authorization: Bearer 12345" create user --user-name "bjensen@example.com"
{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "id": "2819c223-7f76-453a-919d-413861904646",
    "userName": "bjensen@example.com",
    "meta": {
        "resourceType": "User",
        "created": "2010-01-23T04:56:22Z",
        "lastModified": "2011-05-13T04:42:34Z",
        "version": 'W\\/"3694e05e9dff590"',
        "location": "https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646",
    },
}

However passing those parameters each time you use the command can be annoying. To make commands shorter, you can set those parameters once for all by using the SCIM_CLI_URL and SCIM_CLI_HEADERS environment vars.

$ export SCIM_CLI_URL="https://auth.example"
$ export SCIM_CLI_HEADERS="Authorization: Bearer 12345"
$ scim2 create user --user-name "bjensen@example.com"
{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "id": "2819c223-7f76-453a-919d-413861904646",
    "userName": "bjensen@example.com",
    "meta": {
        "resourceType": "User",
        "created": "2010-01-23T04:56:22Z",
        "lastModified": "2011-05-13T04:42:34Z",
        "version": 'W\\/"3694e05e9dff590"',
        "location": "https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646",
    },
}

Server configuration¶

Before doing anything, the CLI needs to reach the server configuration to find out which features are available, which resource schemas are available, and where they are located.

By default the CLI will automatically discover those resources on the server, before each command is run.

However you might find too time consuming to achieve all those network requests. You can store those data locally and reuse them for future command runs thanks to the --schemas, --resource-types and --service-provider-config (and their corresponding environment vars SCIM_CLI_SCHEMAS, SCIM_CLI_RESOURCE_TYPES and SCIM_CLI_SERVICE_PROVIDER_CONFIG)

Save the configuration resources¶

$ scim query schema > /tmp/schemas.json
$ scim query resourcetype > /tmp/resource-types.json
$ scim query serviceproviderconfig > /tmp/service-provider-config.json

Load the cached resources¶

$ export SCIM_SCHEMAS=/tmp/schemas.json
$ export SCIM_RESOURCE_TYPES=/tmp/resource-types.json
$ export SCIM_SERVICE_PROVIDER_CONFIG=/tmp/service-provider-config.json
$ scim2 query ...

Query and search resources¶

The query and search commands can be used to look for resources. query performs ag GET request on the resources endpoint, while search performs a POST request on the /.search endpoint. Both commands take similar options such as --count or --attributes. An exhaustive list of options can be found on the Reference. query can also take a RESOURCE_TYPE and a ID parameters.

If none are set, all the resources of the server are queried.

Querying all the resources from the server.¶

$ scim query
{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "totalResults": xx,
    "startIndex": 1,
    "itemsPerPage": 50,
    "Resources": [...]
}

If RESOURCE_TYPE is set and ID is unset, all the resource of the kind passed in parameter are returned.

Querying all the users from the server.¶

$ scim query user
{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "totalResults": xx,
    "startIndex": 1,
    "itemsPerPage": 50,
    "Resources": [...]
}

If both options are set, the very resource with the ID are returned.

Querying the user with the ID 38b044dd95624c4186f5614fca30305d¶

$ scim query user 38b044dd95624c4186f5614fca30305d
{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
    ],
    "id": "38b044dd95624c4186f5614fca30305d",
    "meta": {
        "resourceType": "User",
        "created": "2024-12-05T16:08:51.896646Z",
        "lastModified": "2024-12-05T16:08:51.896646Z",
        "location": "http://scim.example/v2/Users/38b044dd95624c4186f5614fca30305d",
        "version": "W/\"637b1ce03c010cd55fe45b6f7be2247b5159b135\""
    },
    "userName": "bjensen@example.com"
}

Create and replace resources¶

The create and replace commands can be used to edit resources.

Options for those commands are dynamically generated, depending on the resource attributes available on the server. For instance, for the User resource, you have a --user-name option. You can have a look at the exhaustive list of options by running scim create user --help.

Creation of an user.¶

$ scim create user --user-name bjensen@example.com
{
     "schemas": [
         "urn:ietf:params:scim:schemas:core:2.0:User",
         "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
     ],
     "id": "38b044dd95624c4186f5614fca30305d",
     "meta": {
         "resourceType": "User",
         "created": "2024-12-05T16:08:51.896646Z",
         "lastModified": "2024-12-05T16:08:51.896646Z",
         "location": "http://scim.example/v2/Users/38b044dd95624c4186f5614fca30305d",
         "version": "W/\"637b1ce03c010cd55fe45b6f7be2247b5159b135\""
     },
     "userName": "bjensen@example.com"
 }

Delete resources¶

The delete command allows you to delete resources.

Deletion of an user.¶

$ scim delete user 38b044dd95624c4186f5614fca30305d

Perform a SCIM compliance test¶

The test command runs a series of resource creation, edition and deletions to check that your server complies with the SCIM specifications. See the scim2-tester documentation for more details on which tests are performed.

SCIM compliance test¶

 $ scim test
 Performing a SCIM compliance check on http://localhost:8080 ...
 SUCCESS check_service_provider_config_endpoint
 SUCCESS check_query_all_resource_types
 SUCCESS check_query_resource_type_by_id
   Successfully accessed the /ResourceTypes/User endpoint.
 SUCCESS check_query_resource_type_by_id
   Successfully accessed the /ResourceTypes/Group endpoint.
 SUCCESS check_access_invalid_resource_typ
 ...

JSON input¶

scim2-cli will also read input data from the standard input. This can be used to send custom payloads to the SCIM server.

When user with query and search, the input value must be a JSON representation of a SearchRequest object:

Search of an user by passing a custom payload.¶

$ echo '{"startIndex": 50, "count": 10}' | scim query user
{
     "schemas": [
         "urn:ietf:params:scim:api:messages:2.0:ListResponse"
     ],
     "totalResults": xx,
     "startIndex": 50,
     "itemsPerPage": 10,
     "Resources": [...]
 }

When used with create and replace, no subcommand is needed and the endpoint is guessed from the payload.

Creation of an user by passing a custom payload.¶

$ echo '{"userName": "bjensen@example.com", "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"]}' | scim create
{
     "schemas": [
         "urn:ietf:params:scim:schemas:core:2.0:User",
         "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
     ],
     "id": "38b044dd95624c4186f5614fca30305d",
     "meta": {
         "resourceType": "User",
         "created": "2024-12-05T16:08:51.896646Z",
         "lastModified": "2024-12-05T16:08:51.896646Z",
         "location": "http://scim.example/v2/Users/38b044dd95624c4186f5614fca30305d",
         "version": "W/\"637b1ce03c010cd55fe45b6f7be2247b5159b135\""
     },
     "userName": "bjensen@example.com"
 }