|
| 1 | +--- |
| 2 | +title: SAML |
| 3 | +--- |
| 4 | + |
| 5 | +PactFlow supports single sign on using the SAML authentication protocol. |
| 6 | + |
| 7 | +Once SAML has been configured, if the database contains no users, the first user to log in will be assigned the [Administrator](/docs/permissions/predefined-roles#administrator) role, and every user thereafter will receive the default ([User](/docs/permissions/predefined-roles#user)) role. |
| 8 | + |
| 9 | +## Configuration |
| 10 | + |
| 11 | +A SAML provider is configured by a set of environment variables prefixed with `PACTFLOW_SAML_`. See the [SAML](/docs/on-premises-2x/environment-variables#saml-authentication) section of the environment variables page for the full list. |
| 12 | + |
| 13 | +## Assertion Consumer URL |
| 14 | + |
| 15 | +This is the endpoint to which the IDP will post the SAML assertion after the user is authenticated. It is also called the "sign on URL", "reply URL", and "callback URL", depending on your IDP. You will need to configure this value in your IDP when you set up the PactFlow service provider. |
| 16 | + |
| 17 | +The URL is `https://<your PactFlow host>/auth/saml/callback`. |
| 18 | + |
| 19 | +## Metadata URL |
| 20 | + |
| 21 | +The PactFlow SAML service provider metadata URL is available at `https://<your PactFlow host>/auth/saml/metadata`. |
| 22 | + |
| 23 | +## Configuring multiple SAML providers |
| 24 | + |
| 25 | +In PactFlow 1.7.0 and later, multiple SAML providers may be configured. To configure a second SAML provider, create another set of the [SAML environment variables](/docs/on-premises-2x/environment-variables#saml-authentication) with the prefix `PACTFLOW_SAML_2_` (and `PACTFLOW_SAML_3_` for the third, etc). The `PACTFLOW_SAML_ISSUER` does not need to be specified again, as it is shared between all SAML providers. |
| 26 | + |
| 27 | +The callback path for the second provider is `/auth/saml/2/callback`, and for the third `/auth/saml/3/callback` etc. The path for the metadata for subsequent SAML providers will be `/auth/saml/2/metadata`, `/auth/saml/3/metadata` etc. |
| 28 | + |
| 29 | +## Configuring Azure Active Directory |
| 30 | + |
| 31 | +### Create a non gallery application |
| 32 | + |
| 33 | +* Follow the [Microsoft documentation](https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/add-non-gallery-app) for creating a non gallery application. |
| 34 | + * Choose `Non-gallery application` at the `Add your own app` screen. |
| 35 | + * Set the name to `PactFlow On-Premesis` when prompted. |
| 36 | + |
| 37 | +* When the application has been created, assign the users that should be allowed to login to PactFlow. |
| 38 | + |
| 39 | +* Once the users have been assigned, select the `Single sign-on` tab. Select `SAML`. |
| 40 | + |
| 41 | +* Set the Identifier (Entity ID) to `https://pactflow.<your company domain>` eg. `https://pactflow.mycompany.com`. This field must match the [PACTFLOW_SAML_ISSUER]../(environment-variables#pactflow_saml_issuer) environment variable. |
| 42 | + |
| 43 | +* Set the Reply URL to `https://<your PactFlow host>/auth/saml/callback` |
| 44 | + |
| 45 | +* Leave the Sign On URL, Relay State and Logout Url fields blank. |
| 46 | + |
| 47 | +### Configure the PactFlow environment variables |
| 48 | + |
| 49 | +You can find a template for the required environment variables [here](/docs/on-premises-2x/environment-variables/templates#azure-active-directory). |
| 50 | + |
| 51 | +* Set the [PACTFLOW_SAML_ISSUER](/docs/on-premises-2x/environment-variables#pactflow_saml_issuer) to the `Identifier (Entity ID)`. |
| 52 | +* Set the [PACTFLOW_SAML_IDP_SSO_TARGET_URL](/docs/on-premises-2x/environment-variables#pactflow_saml_idp_sso_target_url) to the `Login URL`. |
| 53 | +* Set the [PACTFLOW_SAML_IDP_ENTITY_ID](/docs/on-premises-2x/environment-variables#pactflow_saml_idp_entity_id) to the `Azure AD Identifier` |
| 54 | +* Set the [PACTFLOW_SAML_IDP_CERT_FINGERPRINT](/docs/on-premises-2x/environment-variables#pactflow_saml_idp_cert_fingerprint) to the `Thumbprint` |
| 55 | +* Set the [PACTFLOW_SAML_IDP_NAME](/docs/on-premises-2x/environment-variables#pactflow_saml_idp_name) to your choice - this is a display name for the login button. |
| 56 | +* Set the identifier, email and name attributes as per the [template](/docs/on-premises-2x/environment-variables#/templates#azure-active-directory). |
| 57 | + |
| 58 | + |
| 59 | +## Docker Compose Example |
| 60 | + |
| 61 | +Follow [steps 1 and 2](/docs/on-premises-2x/docker-compose-example) from the Docker Compose example that uses Demo Auth, then use the following `docker-compose.yml` file to run your services. |
| 62 | + |
| 63 | +``` |
| 64 | +version: "3" |
| 65 | +
|
| 66 | +services: |
| 67 | + simplesaml: |
| 68 | + image: kristophjunge/test-saml-idp |
| 69 | + logging: |
| 70 | + driver: none # comment out the logging config to see the SAML server logs |
| 71 | + ports: |
| 72 | + - "8080:8080" |
| 73 | + - "8443:8443" |
| 74 | + environment: |
| 75 | + - SIMPLESAMLPHP_SP_ENTITY_ID=https://pactflow.io |
| 76 | + - SIMPLESAMLPHP_SP_ASSERTION_CONSUMER_SERVICE=http://localhost/auth/saml/callback |
| 77 | +
|
| 78 | + pactflow: |
| 79 | + image: quay.io/pactflow/enterprise |
| 80 | + depends_on: |
| 81 | + - postgres |
| 82 | + environment: |
| 83 | + - PACTFLOW_HTTP_PORT=9292 |
| 84 | + - PACTFLOW_BASE_URL=http://localhost |
| 85 | + - PACTFLOW_DATABASE_URL=postgres://postgres:password@postgres/postgres |
| 86 | + # insecure settings only for the purposes of this demo! Not to be used in production. |
| 87 | + - PACTFLOW_DATABASE_SSLMODE=disable |
| 88 | + - PACTFLOW_REQUIRE_HTTPS=false |
| 89 | + - PACTFLOW_LOG_FORMAT=short # normally this would be set to json, use short for demo only |
| 90 | + - PACTFLOW_ADMIN_API_KEY=admin |
| 91 | + - PACTFLOW_MASTER_SECRETS_ENCRYPTION_KEY=thisissomerandombytes |
| 92 | + - PACTFLOW_SAML_AUTH_ENABLED=true |
| 93 | + - PACTFLOW_SAML_IDP_NAME=Simple SAML |
| 94 | + - PACTFLOW_SAML_IDP_SSO_TARGET_URL=http://localhost:8080/simplesaml/saml2/idp/SSOService.php |
| 95 | + - 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 |
| 96 | + - PACTFLOW_SAML_IDP_ID_ATTRIBUTE=uid |
| 97 | + - PACTFLOW_SAML_EMAIL_ATTRIBUTE=email |
| 98 | + - PACTFLOW_COOKIE_SECRET=at-least-64-char-secret---------at-least-64-char-secret--------- |
| 99 | + - PACT_BROKER_ADMIN_API_KEY=admin |
| 100 | + - PACTFLOW_WEBHOOK_HOST_WHITELIST=/.*/ |
| 101 | + ports: |
| 102 | + - "80:9292" |
| 103 | + healthcheck: |
| 104 | + test: ["CMD", "wget", "-nv", "-t1", "--spider", "http://localhost:9292/diagnostic/status/heartbeat"] |
| 105 | + interval: 30s |
| 106 | + timeout: 10s |
| 107 | + retries: 3 |
| 108 | + entrypoint: dockerize |
| 109 | + command: -wait tcp://postgres:5432 docker-entrypoint |
| 110 | + volumes: |
| 111 | + - ./pactflow-onprem.lic:/home/pactflow-onprem.lic |
| 112 | +
|
| 113 | + postgres: |
| 114 | + image: postgres:13-alpine |
| 115 | + healthcheck: |
| 116 | + test: psql postgres --command "select 1" -U postgres |
| 117 | + ports: |
| 118 | + - "5432:5432" |
| 119 | + volumes: |
| 120 | + - postgres-volume:/var/lib/postgresql/data |
| 121 | + environment: |
| 122 | + POSTGRES_USER: postgres |
| 123 | + POSTGRES_PASSWORD: password |
| 124 | + POSTGRES_DB: postgres |
| 125 | +
|
| 126 | +volumes: |
| 127 | + postgres-volume: |
| 128 | +``` |
0 commit comments