On-Premises SCIM API

Warning

PactFlow On-Premises 1.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 PactFlow On-Premises SCIM API can be added as a façade to your on-premises PactFlow On-Premises instance. It runs in its own docker container and access the PactFlow On-Premises APIs using a system account API token.

Installation

First

Before running the SCIM API, you must have a correctly running PactFlow On-Premises instance that is version 1.26.0 or later. Follow the PactFlow On-Premises 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 PactFlow On-Premises instance as the PACTFLOW_URL environment variable to the running container.

Note

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

For instance, if your PactFlow 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 PactFlow On-Premises instance and create a system account with the SCIM role and then copy the system account API token.

For instance, assuming your PactFlow 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 PactFlow On-Premises Docker Compose example) to show how the SCIM API can be setup alongside the PactFlow On-Premises instance. Run through the PactFlow 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 PactFlow 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 PactFlow On-Premises license file correctly as per 2. PactFlow 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 PactFlow 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": "[email protected]",
          "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

PactFlow On-Premises URL (Required)

Variable: PACTFLOW_URL

This sets the URL that the PactFlow 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 PactFlow 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: