On-Premises SCIM API

The PactFlow On-Premises SCIM API can be added as a surface to your 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 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:2.0.0
    depends_on:
      - postgres
      - redis
    environment:
      # This is set to localhost for this example but in a real deployment, this needs to be set to the actual URL of the application
      - PACTFLOW_BASE_URL=http://localhost
      # Insecure setting only for the purposes of this demo! Not to be used in production.
      - PACTFLOW_DATABASE_SSLMODE=disable
      # Insecure setting only for the purposes of this demo! Not to be used in production.
      - PACTFLOW_REQUIRE_HTTPS=false
      # Demo auth should only be used for demo purposes. Not to be used in production.
      - PACTFLOW_DEMO_AUTH_ENABLED=true
      # 'Allow all' for the webhook host whitelist should only be used for demo purposes. See docs for configuring this in production.
      - PACTFLOW_WEBHOOK_HOST_WHITELIST=/.*/
      - PACTFLOW_HTTP_PORT=9292
      # Link to the postgres database
      - PACTFLOW_DATABASE_URL=postgres://postgres:password@postgres/postgres
      - PACTFLOW_LOG_LEVEL=info
      - PACTFLOW_ADMIN_API_KEY=admin
      - PACTFLOW_MASTER_ENCRYPTION_KEY=thisissomerandombytes
      - PACTFLOW_COOKIE_SECRET=at-least-64-char-secret---------at-least-64-char-secret---------
      - PACT_BROKER_ADMIN_API_KEY=admin 
      - PACTFLOW_HTTP_LOGGING_ENABLED=true
      # Link to the redis cache
      - REDIS_URL=redis://redis:6379
      # SAML settings
      - 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      
    ports:
      - "80:9294"
    healthcheck:
      test: ["CMD", "supervisorctl", "status", "haproxy", "marko", "pactflow"]
      interval: 30s
      timeout: 10s
      retries: 3
    volumes:
      - ./pactflow-onprem.lic:/home/pactflow-onprem.lic
    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"
  
  redis:
    image: redis:latest

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.

Publication date: