1"use strict";(self.webpackChunkpartners=self.webpackChunkpartners||[]).push([[2765],{15680:(e,n,t)=>{t.d(n,{xA:()=>p,yg:()=>g});var a=t(96540);function o(e,n,t){return n in e?Object.defineProperty(e,n,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[n]=t,e}function r(e,n){var t=Object.keys(e);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);n&&(a=a.filter((function(n){return Object.getOwnPropertyDescriptor(e,n).enumerable}))),t.push.apply(t,a)}return t}function s(e){for(var n=1;n<arguments.length;n++){var t=null!=arguments[n]?arguments[n]:{};n%2?r(Object(t),!0).forEach((function(n){o(e,n,t[n])})):Object.getOwnPropertyDescriptors?Object.defineProperties(e,Object.getOwnPropertyDescriptors(t)):r(Object(t)).forEach((function(n){Object.defineProperty(e,n,Object.getOwnPropertyDescriptor(t,n))}))}return e}function i(e,n){if(null==e)return{};var t,a,o=function(e,n){if(null==e)return{};var t,a,o={},r=Object.keys(e);for(a=0;a<r.length;a++)t=r[a],n.indexOf(t)>=0||(o[t]=e[t]);return o}(e,n);if(Object.getOwnPropertySymbols){var r=Object.getOwnPropertySymbols(e);for(a=0;a<r.length;a++)t=r[a],n.indexOf(t)>=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(o[t]=e[t])}return o}var l=a.createContext({}),c=function(e){var n=a.useContext(l),t=n;return e&&(t="function"==typeof e?e(n):s(s({},n),e)),t},p=function(e){var n=c(e.components);return a.createElement(l.Provider,{value:n},e.children)},d="mdxType",m={inlineCode:"code",wrapper:function(e){var n=e.children;return a.createElement(a.Fragment,{},n)}},u=a.forwardRef((function(e,n){var t=e.components,o=e.mdxType,r=e.originalType,l=e.parentName,p=i(e,["components","mdxType","originalType","parentName"]),d=c(t),u=o,g=d["".concat(l,".").concat(u)]||d[u]||m[u]||r;return t?a.createElement(g,s(s({ref:n},p),{},{components:t})):a.createElement(g,s({ref:n},p))}));function g(e,n){var t=arguments,o=n&&n.mdxType;if("string"==typeof e||o){var r=t.length,s=new Array(r);s[0]=u;var i={};for(var l in n)hasOwnProperty.call(n,l)&&(i[l]=n[l]);i.originalType=e,i[d]="string"==typeof e?e:o,s[1]=i;for(var c=2;c<r;c++)s[c]=t[c];return a.createElement.apply(null,s)}return a.createElement.apply(null,t)}u.displayName="MDXCreateElement"},84187:(e,n,t)=>{t.r(n),t.d(n,{assets:()=>l,contentTitle:()=>s,default:()=>g,frontMatter:()=>r,metadata:()=>i,toc:()=>c});var a=t(58168),o=(t(96540),t(15680));const r={title:"On-Premises SCIM API"},s=void 0,i={unversionedId:"docs/on-premises/scim",id:"docs/on-premises/scim",title:"On-Premises SCIM API",description:"The PactFlow SCIM API can be added as a fa\xe7ade to your on-premises PactFlow instance. It runs in its own",source:"@site/docs/docs/on-premises/scim.md",sourceDirName:"docs/on-premises",slug:"/docs/on-premises/scim",permalink:"/docs/on-premises/scim",draft:!1,editUrl:"https://github.com/pactflow/docs.pactflow.io/edit/master/website/docs/docs/on-premises/scim.md",tags:[],version:"current",lastUpdatedBy:"Voon Siong Wong",lastUpdatedAt:1747030375,formattedLastUpdatedAt:"May 12, 2025",frontMatter:{title:"On-Premises SCIM API"},sidebar:"onprem",previous:{title:"Database",permalink:"/docs/on-premises/maintenance/database"},next:{title:"Security audit report",permalink:"/docs/on-premises/security-audit-report"}},l={},c=[{value:"Installation",id:"installation",level:2},{value:"First",id:"first",level:3},{value:"Then",id:"then",level:3},{value:"Next",id:"next",level:3},{value:"Docker Compose example",id:"docker-compose-example",level:2},{value:"1. Authenticating to Quay.io",id:"1-authenticating-to-quayio",level:3},{value:"2. Startup PactFlow with SCIM API",id:"2-startup-pactflow-with-scim-api",level:3},{value:"3. Login to PactFlow",id:"3-login-to-pactflow",level:2},{value:"4. Use Curl and JQ to test access to the SCIM API",id:"4-use-curl-and-jq-to-test-access-to-the-scim-api",level:2},{value:"Configuration",id:"configuration",level:2},{value:"PactFlow URL (Required)",id:"pactflow-url-required",level:3},{value:"Log Level",id:"log-level",level:3},{value:"Context Path",id:"context-path",level:3}],p=(d="BR",function(e){return console.warn("Component "+d+" was not imported, exported, or provided by MDXProvider as global scope"),(0,o.yg)("div",e)});var d;const m={toc:c},u="wrapper";
1function g(e){let{components:n,...t}=e;return(0,o.yg)(u,(0,a.A)({},m,t,{components:n,mdxType:"MDXLayout"}),(0,o.yg)("p",null,"The PactFlow SCIM API can be added as a fa\xe7ade to your on-premises PactFlow instance. It runs in its own\ndocker container and access the PactFlow APIs using a system account API token."),(0,o.yg)("p",null,"For details on the PactFlow SCIM API, refer to the ",(0,o.yg)("a",{parentName:"p",href:"/docs/scim/main"},"main SCIM documentation"),"."),(0,o.yg)("h2",{id:"installation"},"Installation"),(0,o.yg)("h3",{id:"first"},"First"),(0,o.yg)("p",null,"Before running the SCIM API, you must have a correctly running PactFlow instance that is version 1.26.0 or later. Follow the\n",(0,o.yg)("a",{parentName:"p",href:"/docs/on-premises/installation/checklist"},"PactFlow On-Premises installation instructions"),"."),(0,o.yg)("h3",{id:"then"},"Then"),(0,o.yg)("ul",null,(0,o.yg)("li",{parentName:"ul"},"Configure the SCIM Docker image to be pulled from Quay. Follow the ",(0,o.yg)("a",{parentName:"li",href:"/docs/on-premises/docker-image-registry"},"Docker image registry instructions"),"\nto get access to the Quay registry and then run ",(0,o.yg)("inlineCode",{parentName:"li"},"docker pull quay.io/pactflow/scim-api")," to pull down the latest SCIM API image."),(0,o.yg)("li",{parentName:"ul"},"You can then deploy the docker container to your docker orchestration service (AWS ECS, K8, etc.). You need to provide the external URL of\nyour PactFlow instance as the ",(0,o.yg)("inlineCode",{parentName:"li"},"PACTFLOW_URL")," environment variable to the running container.")),(0,o.yg)("p",null,(0,o.yg)("strong",{parentName:"p"},"NOTE: The SCIM API has to access your PactFlow instance using the URL/one of the URLs listed in the ",(0,o.yg)("a",{parentName:"strong",href:"/docs/on-premises/environment-variables#pactflow_base_url"},"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."),(0,o.yg)("p",null,"For instance, if your PactFlow instance is running as ",(0,o.yg)("inlineCode",{parentName:"p"},"https://pactflow.mycompany.com")," then you need to the set the\n",(0,o.yg)("inlineCode",{parentName:"p"},"PACTFLOW_URL")," environment variable for the SCIM API to that address."),(0,o.yg)("h3",{id:"next"},"Next"),(0,o.yg)("p",null,"You can now test the running SCIM API by using a tool like ",(0,o.yg)("inlineCode",{parentName:"p"},"curl"),". First, login to your PactFlow instance and create ",(0,o.yg)("a",{parentName:"p",href:"/docs/user-interface/settings/users#system-accounts"},"a\nsystem account")," with the ",(0,o.yg)("a",{parentName:"p",href:"/docs/permissions/predefined-roles#scim"},"SCIM role")," and then copy the system account API token."),(0,o.yg)("p",null,"For instance, assuming your PactFlow instance is running as ",(0,o.yg)("inlineCode",{parentName:"p"},"https://pactflow.mycompany.com")," and your SCIM API is\nrunning as ",(0,o.yg)("inlineCode",{parentName:"p"},"https://pactflow-scim.mycompany.com")," with its ",(0,o.yg)("inlineCode",{parentName:"p"},"PACTFLOW_URL")," environment variable set to ",(0,o.yg)("inlineCode",{parentName:"p"},"https://pactflow.mycompany.com")," and\nyou have copied the SCIM system account API token, you can then run ",(0,o.yg)("inlineCode",{parentName:"p"},"curl -H 'Authorization: Bearer <PASTE THE SERVICE TOKEN HERE>' https://pactflow-scim.mycompany.com/Users"),"\nto fetch the users as a SCIM request."),(0,o.yg)("h2",{id:"docker-compose-example"},"Docker Compose example"),(0,o.yg)("p",null,"Here is an example docker compose setup (modified from the ",(0,o.yg)("a",{parentName:"p",href:"/docs/on-premises/docker-compose-example"},"PactFlow Docker Compose example"),")\nto show how the SCIM API can be setup alongside the PactFlow instance. Run through the ",(0,o.yg)("a",{parentName:"p",href:"/docs/on-premises/docker-compose-example"},"PactFlow Docker Compose example"),"\nfirst, and when that is working you can use this docker compose file to add SCIM as a fa\xe7ade."),(0,o.yg)("h3",{id:"1-authenticating-to-quayio"},"1. Authenticating to Quay.io"),(0,o.yg)("p",null,"Authenticate to Quay.io so that the docker engine is able to fetch our images."),(0,o.yg)("pre",null,(0,o.yg)("code",{parentName:"pre"},'docker login -u="<username>" -p="<password>" quay.io\ndocker pull quay.io/pactflow/scim-api\n')),(0,o.yg)("h3",{id:"2-startup-pactflow-with-scim-api"},"2. Startup PactFlow with SCIM API"),(0,o.yg)("p",null,"Save the below file as ",(0,o.yg)("inlineCode",{parentName:"p"},"docker-compose.yml")," into a temporary directory and then run ",(0,o.yg)("inlineCode",{parentName:"p"},"docker-compose up"),". Make sure you\nhave setup the PactFlow license file correctly as per ",(0,o.yg)("a",{parentName:"p",href:"/docs/on-premises/docker-compose-example#2-pactflow-license-file"},"2. PactFlow license file"),"."),(0,o.yg)("pre",null,(0,o.yg)("code",{parentName:"pre",className:"language-yaml"},'version: "3"\n\nservices:\n simplesaml:\n image: kristophjunge/test-saml-idp\n logging:\n driver: none # comment out the logging config to see the SAML server logs\n ports:\n - "8080:8080"\n - "8443:8443"\n environment:\n - SIMPLESAMLPHP_SP_ENTITY_ID=https://pactflow.io\n - SIMPLESAMLPHP_SP_ASSERTION_CONSUMER_SERVICE=http://localhost/auth/saml/callback\n\n pactflow:\n image: quay.io/pactflow/enterprise\n depends_on:\n - postgres\n environment:\n - PACTFLOW_HTTP_PORT=9292\n - PACTFLOW_BASE_URL=http://localhost http://pactflow:9292\n - PACTFLOW_DATABASE_URL=postgres://postgres:password@postgres/postgres\n # insecure settings only for the purposes of this demo! Not to be used in production.\n - PACTFLOW_DATABASE_SSLMODE=disable\n - PACTFLOW_REQUIRE_HTTPS=false\n - PACTFLOW_SECURE_COOKIES=false\n - PACTFLOW_LOG_FORMAT=short # normally this would be set to json, use short for demo only\n - PACTFLOW_ADMIN_API_KEY=admin\n - PACTFLOW_MASTER_SECRETS_ENCRYPTION_KEY=thisissomerandombytes\n - PACTFLOW_SAML_AUTH_ENABLED=true\n - PACTFLOW_SAML_IDP_NAME=Simple SAML\n - PACTFLOW_SAML_IDP_SSO_TARGET_URL=http://localhost:8080/simplesaml/saml2/idp/SSOService.php\n - PACTFLOW_SAML_IDP_CERT_FINGERPRINT=11:9B:9E:02:79
1:59:CD:B7:C6:62:CF:D0:75:D9:E2:EF:38:4E:44:5F\n - PACTFLOW_SAML_IDP_ID_ATTRIBUTE=uid\n - PACTFLOW_SAML_EMAIL_ATTRIBUTE=email\n - PACTFLOW_COOKIE_SECRET=at-least-64-char-secret---------at-least-64-char-secret---------\n - PACT_BROKER_ADMIN_API_KEY=admin\n - PACTFLOW_WEBHOOK_HOST_WHITELIST=/.*/\n ports:\n - "80:9292"\n healthcheck:\n test: ["CMD", "wget", "-nv", "-t1", "--spider", "http://localhost:9292/diagnostic/status/heartbeat"]\n interval: 30s\n timeout: 10s\n retries: 3\n entrypoint: dockerize\n command: -wait tcp://postgres:5432 docker-entrypoint\n volumes:\n - ./pactflow-onprem.lic:/home/pactflow-onprem.lic\n\n postgres:\n image: postgres\n healthcheck:\n test: psql postgres --command "select 1" -U postgres\n ports:\n - "5432:5432"\n volumes:\n - postgres-volume:/var/lib/postgresql/data\n environment:\n POSTGRES_USER: postgres\n POSTGRES_PASSWORD: password\n POSTGRES_DB: postgres\n\n scim-api:\n image: quay.io/pactflow/scim-api\n depends_on:\n - pactflow\n environment:\n PACTFLOW_URL: "http://pactflow:9292"\n LOGGING_LEVEL_ROOT: DEBUG\n LOGGING_LEVEL_ORG_APACHE_HC_CLIENT5_HTTP_WIRE: INFO\n ports:\n - "8100:8080"\n\nvolumes:\n postgres-volume:\n\n')),(0,o.yg)("h2",{id:"3-login-to-pactflow"},"3. Login to PactFlow"),(0,o.yg)("p",null,'Head to http://localhost in your browser, and choose to login with "SIMPLE SAML", with the username ',(0,o.yg)("inlineCode",{parentName:"p"},"user1")," and password ",(0,o.yg)("inlineCode",{parentName:"p"},"user1pass"),".\nThen go to Settings -> API Tokens and COPY an API token."),(0,o.yg)("h2",{id:"4-use-curl-and-jq-to-test-access-to-the-scim-api"},"4. Use Curl and JQ to test access to the SCIM API"),(0,o.yg)("p",null,"Replace ",(0,o.yg)("inlineCode",{parentName:"p"},"<PASTE TOKEN HERE>")," below with the API token copied from the last step. "),(0,o.yg)("pre",null,(0,o.yg)("code",{parentName:"pre",className:"language-console"},'\u276f curl -H \'Authorization: Bearer <PASTE TOKEN HERE>\' http://localhost:8100/scim/Users | jq\n % Total % Received % Xferd Average Speed Time Time Time Current\n Dload Upload Total Spent Left Speed\n100 1530 100 1530 0 0 3026 0 --:--:-- --:--:-- --:--:-- 3029\n{\n "schemas": [\n "urn:ietf:params:scim:api:messages:2.0:ListResponse"\n ],\n "totalResults": 2,\n "Resources": [\n {\n "schemas": [\n "urn:ietf:params:scim:schemas:core:2.0:User"\n ],\n "id": "61cfa5ff-1be6-4e7e-a620-7efac4a370df",\n "meta": {\n "created": "2022-12-06T03:49:22Z",\n "lastModified": "2022-12-06T03:49:29Z",\n "resourceType": "User",\n "location": "http://localhost:8100/scim/Users/61cfa5ff-1be6-4e7e-a620-7efac4a370df"\n },\n "name": {\n "formatted": "SCIM"\n },\n "displayName": "SCIM",\n "userType": "System Account",\n "active": true,\n "groups": [\n {\n "value": "4ac05ed8-9e3b-4159-96c0-ad19e3b93658",\n "display": "Default",\n "type": "direct",\n "$ref": "Groups/4ac05ed8-9e3b-4159-96c0-ad19e3b93658"\n }\n ],\n "roles": [\n {\n "value": "c1878b8e-d09e-11ea-8fde-af02c4677eb7",\n "display": "CI/CD",\n "type": "CI/CD"\n },\n {\n "value": "cf75d7c2-416b-11ea-af5e-53c3b1a4efd8",\n "display": "Administrator",\n "type": "Administrator"\n }\n ]\n },\n {\n "schemas": [\n "urn:ietf:params:scim:schemas:core:2.0:User"\n ],\n "id": "aaa3e1a2-3648-4453-b3a6-2195b6822e2d",\n "meta": {\n "created": "2022-12-06T00:25:56Z",\n "lastModified": "2022-12-06T00:25:56Z",\n "resourceType": "User",\n "location": "http://localhost:8100/scim/Users/aaa3e1a2-3648-4453-b3a6-2195b6822e2d"\n },\n "userType": "User",\n "active": true,\n "emails": [\n {\n "value": "[email protected]",\n "primary": true\n }\n ],\n "groups": [\n {\n "value": "4ac05ed8-9e3b-4159-96c0-ad19e3b93658",\n "display": "Default",\n "type": "direct",\n "$ref": "Groups/4ac05ed8-9e3b-4159-96c0-ad19e3b93658"\n }\n ],\n "roles": [\n {\n "value": "e9282e22-416b-11ea-a16e-57ee1bb61d18",\n "display": "User",\n "type": "User"\n },\n {\n "value": "cf75d7c2-416b-11ea-af5e-53c3b1a4efd8",\n "display": "Administrator",\n "type": "Administrator"\n }\n ]\n }\n ]\n}\n')),(0,o.yg)("h2",{id:"configuration"},"Configuration"),(0,o.yg)("h3",{id:"pactflow-url-required"},"PactFlow URL (Required)"),(0,o.yg)("p",null,(0,o.yg)("strong",{parentName:"p"},"Variable:")," ",(0,o.yg)("inlineCode",{parentName:"p"},"PACTFLOW_URL"),(0,o.yg)(p,{mdxType:"BR"})),(0,o.yg)("p",null,"This sets the URL that the PactFlow instance is accessed from."),(0,o.yg)("h3",{id:"log-level"},"Log Level"),(0,o.yg)("p",null,(0,o.yg)("strong",{parentName:"p"},"Variable:")," ",(0,o.yg)("inlineCode",{parentName:"p"},"LOGGING_LEVEL_ROOT")," ",(0,o.yg)(p,{mdxType:"BR"}),"\n",(0,o.yg)("strong",{parentName:"p"},"Default:")," ",(0,o.yg)("inlineCode",{parentName:"p"},"INFO"),(0,o.yg)(p,{mdxType:"BR"}),"\n",(0,o.yg)("strong",{parentName:"p"},"Allowed values:")," ",(0,o.yg)("inlineCode",{parentName:"p"},"DEBUG"),", ",(0,o.yg)("inlineCode",{parentName:"p"},"INFO"),", ",(0,o.yg)("inlineCode",{parentName:"p"},"WARN"),", ",(0,o.yg)("inlineCode",{parentName:"p"},"ERROR"),(0,o.yg)(p,{mdxType:"BR"})),(0,o.yg)("p",null,"This sets the base log level for the SCIM API container. "),(0,o.yg)("p",null,(0,o.yg)("strong",{parentName:"p"}
1,"WARNING: Setting the log level to ",(0,o.yg)("inlineCode",{parentName:"strong"},"DEBUG")," will cause all HTTP interactions between the SCIM API and PactFlow to be be logged,\nwhich will include the API tokens in clear text.")," To disable logging of the HTTP interactions, set\n",(0,o.yg)("inlineCode",{parentName:"p"},"LOGGING_LEVEL_ORG_APACHE_HC_CLIENT5_HTTP_WIRE")," to ",(0,o.yg)("inlineCode",{parentName:"p"},"INFO")," or greater."),(0,o.yg)("h3",{id:"context-path"},"Context Path"),(0,o.yg)("p",null,(0,o.yg)("strong",{parentName:"p"},"Variable:")," ",(0,o.yg)("inlineCode",{parentName:"p"},"SERVER_SERVLET_CONTEXT_PATH")," ",(0,o.yg)(p,{mdxType:"BR"}),"\n",(0,o.yg)("strong",{parentName:"p"},"Default:")," ",(0,o.yg)("inlineCode",{parentName:"p"},"/scim"),(0,o.yg)(p,{mdxType:"BR"})),(0,o.yg)("p",null,"This sets the context path that the SCIM API is mounted at."))}g.isMDXComponent=!0}}]);
Line numbers count LF bytes from the start of the resource, as the search results do. Vendor segments are library code the classifier recognised; they are stored but not indexed. Bytes are shown as Latin1 characters, one per byte.