On-Premises SCIM API

Warning

Swagger Contract Testing On-Premises 1.x.x is now in maintenance mode and receives security updates only. It will no longer be supported after March 11, 2026.

To benefit from the latest features and improvements, upgrade to version 2.x as soon as possible.

The Swagger Contract Testing On-Premises SCIM API can be added as a façade to your Contract Testing On-Premises instance. It runs in its own docker container and access the Contract Testing On-Premises APIs using a system account API token.

Installation

First

Before running the SCIM API, you must have a correctly running Swagger Contract Testing On-Premises instance that is version 1.26.0 or later. Follow the Contract Testing On-Premises installation instructions.

Then

  • Configure the SCIM Docker image to be pulled from Quay. Follow the Docker image registry instructions to get access to the Quay registry and then run docker pull quay.io/pactflow/scim-api to pull down the latest SCIM API image.

  • You can then deploy the docker container to your docker orchestration service (AWS ECS, K8, etc.). You need to provide the external URL of your Contract Testing On-Premises instance as the PACTFLOW_URL environment variable to the running container.

Note

The SCIM API has to access your Contract Testing On-Premises instance using the URL/one of the URLs listed in the PACTFLOW_BASE_URL environment variable used for the Contract Testing On-Premises application. This is due to Contract Testing On-Premises using the HAL media format which uses embedded links in the responses.

For instance, if your Contract Testing On-Premises instance is running as https://pactflow.mycompany.com then you need to the set the PACTFLOW_URL environment variable for the SCIM API to that address.

Next

You can now test the running SCIM API by using a tool like curl. First, login to your Contract Testing On-Premises instance and create a system account with the SCIM role and then copy the system account API token.

For instance, assuming your Contract Testing On-Premises instance is running as https://pactflow.mycompany.com and your SCIM API is running as https://pactflow-scim.mycompany.com with its PACTFLOW_URL environment variable set to https://pactflow.mycompany.com and you have copied the SCIM system account API token, you can then run curl -H 'Authorization: Bearer <PASTE THE SERVICE TOKEN HERE>'; https://pactflow-scim.mycompany.com/Users to fetch the users as a SCIM request.

Docker Compose example

Here is an example docker compose setup (modified from the Swagger Contract Testing On-Premises Docker Compose example) to show how the SCIM API can be setup alongside the Contract Testing On-Premises instance. Run through the Contract Testing On-Premises Docker Compose example first, and when that is working you can use this docker compose file to add SCIM as a façade.

1. Authenticating to Quay.io

Authenticate to Quay.io so that the docker engine is able to fetch our images.

docker login -u="<username>" -p="<password>" quay.io
docker pull quay.io/pactflow/scim-api

2. Startup Swagger Contract Testing On-Premises with SCIM API

Save the below file as docker-compose.yml into a temporary directory and then run docker-compose up. Make sure you have setup the Contract Testing On-Premises license file correctly as per 2. Contract Testing On-Premises license file

version: "3"

services:
  simplesaml:
    image: kristophjunge/test-saml-idp
    logging:
      driver: none # comment out the logging config to see the SAML server logs
    ports:
      - "8080:8080"
      - "8443:8443"
    environment:
      - SIMPLESAMLPHP_SP_ENTITY_ID=https://pactflow.io
      - SIMPLESAMLPHP_SP_ASSERTION_CONSUMER_SERVICE=http://localhost/auth/saml/callback

  pactflow:
    image: quay.io/pactflow/enterprise
    depends_on:
      - postgres
    environment:
      - PACTFLOW_HTTP_PORT=9292
      - PACTFLOW_BASE_URL=http://localhost http://pactflow:9292
      - PACTFLOW_DATABASE_URL=postgres://postgres:password@postgres/postgres
      # insecure settings only for the purposes of this demo! Not to be used in production.
      - PACTFLOW_DATABASE_SSLMODE=disable
      - PACTFLOW_REQUIRE_HTTPS=false
      - PACTFLOW_SECURE_COOKIES=false
      - PACTFLOW_LOG_FORMAT=short # normally this would be set to json, use short for demo only
      - PACTFLOW_ADMIN_API_KEY=admin
      - PACTFLOW_MASTER_SECRETS_ENCRYPTION_KEY=thisissomerandombytes
      - PACTFLOW_SAML_AUTH_ENABLED=true
      - PACTFLOW_SAML_IDP_NAME=Simple SAML
      - PACTFLOW_SAML_IDP_SSO_TARGET_URL=http://localhost:8080/simplesaml/saml2/idp/SSOService.php
      - PACTFLOW_SAML_IDP_CERT_FINGERPRINT=11:9B:9E:02:79:59:CD:B7:C6:62:CF:D0:75:D9:E2:EF:38:4E:44:5F
      - PACTFLOW_SAML_IDP_ID_ATTRIBUTE=uid
      - PACTFLOW_SAML_EMAIL_ATTRIBUTE=email
      - PACTFLOW_COOKIE_SECRET=thisisasecret
      - PACT_BROKER_ADMIN_API_KEY=admin
      - PACTFLOW_WEBHOOK_HOST_WHITELIST=/.*/
    ports:
      - "80:9292"
    healthcheck:
      test: ["CMD", "wget", "-nv", "-t1", "--spider", "http://localhost:9292/diagnostic/status/heartbeat"]
      interval: 30s
      timeout: 10s
      retries: 3
    entrypoint: dockerize
    command: -wait tcp://postgres:5432 docker-entrypoint
    volumes:
      - ./pactflow-onprem.lic:/home/pactflow-onprem.lic

  postgres:
    image: postgres
    healthcheck:
      test: psql postgres --command "select 1" -U postgres
    ports:
      - "5432:5432"
    volumes:
      - postgres-volume:/var/lib/postgresql/data
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: password
      POSTGRES_DB: postgres

  scim-api:
    image: quay.io/pactflow/scim-api
    depends_on:
      - pactflow
    environment:
      PACTFLOW_URL: "http://pactflow:9292"
      LOGGING_LEVEL_ROOT: DEBUG
      LOGGING_LEVEL_ORG_APACHE_HC_CLIENT5_HTTP_WIRE: INFO
    ports:
      - "8100:8080"

volumes:
  postgres-volume:

3. Log in to Swagger Contract Testing On-Premises

Head to http://localhost in your browser, and choose to login with "SIMPLE SAML", with the username user1 and password user1pass. Then go to Settings -> API Tokens and COPY an API token.

4. Use Curl and JQ to test access to the SCIM API

Replace <PASTE TOKEN HERE> below with the API token copied from the last step.

❯ curl -H 'Authorization: Bearer <PASTE TOKEN HERE>'  http://localhost:8100/scim/Users | jq
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  1530  100  1530    0     0   3026      0 --:--:-- --:--:-- --:--:--  3029
{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "totalResults": 2,
  "Resources": [
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
      ],
      "id": "61cfa5ff-1be6-4e7e-a620-7efac4a370df",
      "meta": {
        "created": "2022-12-06T03:49:22Z",
        "lastModified": "2022-12-06T03:49:29Z",
        "resourceType": "User",
        "location": "http://localhost:8100/scim/Users/61cfa5ff-1be6-4e7e-a620-7efac4a370df"
      },
      "name": {
        "formatted": "SCIM"
      },
      "displayName": "SCIM",
      "userType": "System Account",
      "active": true,
      "groups": [
        {
          "value": "4ac05ed8-9e3b-4159-96c0-ad19e3b93658",
          "display": "Default",
          "type": "direct",
          "$ref": "Groups/4ac05ed8-9e3b-4159-96c0-ad19e3b93658"
        }
      ],
      "roles": [
        {
          "value": "c1878b8e-d09e-11ea-8fde-af02c4677eb7",
          "display": "CI/CD",
          "type": "CI/CD"
        },
        {
          "value": "cf75d7c2-416b-11ea-af5e-53c3b1a4efd8",
          "display": "Administrator",
          "type": "Administrator"
        }
      ]
    },
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
      ],
      "id": "aaa3e1a2-3648-4453-b3a6-2195b6822e2d",
      "meta": {
        "created": "2022-12-06T00:25:56Z",
        "lastModified": "2022-12-06T00:25:56Z",
        "resourceType": "User",
        "location": "http://localhost:8100/scim/Users/aaa3e1a2-3648-4453-b3a6-2195b6822e2d"
      },
      "userType": "User",
      "active": true,
      "emails": [
        {
          "value": "user1@example.com",
          "primary": true
        }
      ],
      "groups": [
        {
          "value": "4ac05ed8-9e3b-4159-96c0-ad19e3b93658",
          "display": "Default",
          "type": "direct",
          "$ref": "Groups/4ac05ed8-9e3b-4159-96c0-ad19e3b93658"
        }
      ],
      "roles": [
        {
          "value": "e9282e22-416b-11ea-a16e-57ee1bb61d18",
          "display": "User",
          "type": "User"
        },
        {
          "value": "cf75d7c2-416b-11ea-af5e-53c3b1a4efd8",
          "display": "Administrator",
          "type": "Administrator"
        }
      ]
    }
  ]
}

Configuration

Swagger Contract Testing On-Premises URL (Required)

Variable: PACTFLOW_URL

This sets the URL that the Contract Testing On-Premises instance is accessed from.

Log Level

Variable: LOGGING_LEVEL_ROOT

Default: INFO

Allowed values: DEBUG, INFO, WARN, ERROR

This sets the base log level for the SCIM API container.

Warning

WARNING: Setting the log level to DEBUG will cause all HTTP interactions between the SCIM API and Swagger Contract Testing On-Premises to be be logged, which will include the API tokens in clear text. To disable logging of the HTTP interactions, set LOGGING_LEVEL_ORG_APACHE_HC_CLIENT5_HTTP_WIRE to INFO or greater.

Context Path

Variable: SERVER_SERVLET_CONTEXT_PATH

Default: /scim

This sets the context path that the SCIM API is mounted at.

In this section:
© 2025
Publication date: