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
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
/scim
This sets the context path that the SCIM API is mounted at.