Skip to main content

On-Premises SCIM API

The PactFlow SCIM API can be added as a façade to your on-premises PactFlow instance. It runs in its own docker container and access the PactFlow APIs using a system account API token.

For details on the PactFlow SCIM API, refer to the main SCIM documentation.

Installation

First

Before running the SCIM API, you must have a correctly running PactFlow 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 instance as the PACTFLOW_URL environment variable to the running container.

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

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

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

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

PactFlow URL (Required)

Variable: PACTFLOW_URL

This sets the URL that the PactFlow 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: Setting the log level to DEBUG will cause all HTTP interactions between the SCIM API and PactFlow 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.