Skip to content

Commit 858782d

Browse files
committed
chore: documentation and release notes for 2.0.0 release
PACT-4181
1 parent 12dcd75 commit 858782d

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

87 files changed

+4877
-57
lines changed
Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
---
2+
title: PactFlow On-Premises Architecture
3+
sidebar_label: Architecture
4+
---
5+
6+
## System architecture
7+
8+
### Minimum requirements
9+
10+
* An application server capable of running Docker
11+
* PostgreSQL database
12+
* Redis Serialization Protocol (RESP)-compatible key/value cache
13+
* SAML IDP for SSO
14+
* PactFlow license file
15+
16+
### Recommended architecture
17+
18+
* Deploy to a service designed for Docker container orchestration (ECS, Fargate, Kubernetes etc.)
19+
20+
### Example AWS deployment using ECS
21+
22+
![System architecture](/img/on-prem-architecture-2x.png)
23+
24+
## Internal architecture
25+
26+
The PactFlow On-Premises application is distributed as a Docker image. It is based on the open source [Pact Broker](https://github.com/pact-foundation/pact_broker), which is a Ruby application.
27+
28+
### Application user requirements
29+
30+
You can run the application without elevated privileges. It runs under the user `app`.
31+
32+
### Application port
33+
34+
The PactFlow application runs on port `9292` by default. This can be configured by setting the [PACTFLOW_HTTP_PORT](/docs/on-premises/environment-variables#pactflow_http_port) environment variable.
35+
36+
### Healthcheck endpoint
37+
38+
There's a healthcheck endpoint at `http://<HOST>/diagnostic/status/heartbeat` meant for Docker container management tools.
39+
40+
- It doesn't need authentication.
41+
- It doesn't touch the database.
42+
- You can use it to check if load balancer targets are working properly.
43+
44+
If you're running the healthcheck from inside the container, be sure to use the port specified by the `$PACTFLOW_HTTP_PORT` environment variable (defaults to `9292` if not set).
45+
46+
You can use `supervisorctl` to send the healthcheck request.
47+
48+
An example healthcheck configuration for Docker Compose:
49+
50+
```yaml
51+
healthcheck:
52+
test: ["supervisorctl", "status", "haproxy", "marko", "pactflow"]
53+
interval: 30s
54+
timeout: 10s
55+
retries: 3
56+
```
57+
58+
To check the connection to the database, use the endpoint `/diagnostic/status/dependencies`. This endpoint should not be used by Docker container managment services, as unrelated database issues might cause the Docker container to churn.
59+
60+
### License file
61+
62+
PactFlow on-premises version requires a license file to run. [Contact us](https://support.smartbear.com/pactflow/message/) if you have not
63+
received one when your account was setup. See the [section on licenses for installation instructions](/docs/on-premises/license).
Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
---
2+
title: Authentication
3+
---
4+
5+
## User interface
6+
7+
The PactFlow On-Premises application currently supports single sign for SAML identity providers. It supports both IDP and SP initiated log in.
8+
9+
Any user who is able to authenticate to the configured IDP is allowed access to PactFlow.
10+
11+
The SAML IDP is configured via [environment variables](environment-variables#saml-authentication).
12+
13+
## API
14+
15+
The API is accessed using a bearer token that is set in the HTTP header of the request (eg. `Authorization: Bearer <your token here>`). The tokens are administered on a per user basis in the [settings page](/docs/user-interface/settings/api-tokens) of the PactFlow application.
16+
Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
---
2+
title: Demo Auth
3+
---
4+
5+
To allow experimentation with PactFlow without the need to configure an external identity provider, the "demo" authentication provider can be enabled. With demo auth enabled, any user can log in to PactFlow by providing a name and email address. No password is used to authenticate the user.
6+
7+
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+
After a user has logged in, they may perform all the actions their role allows, as if they were a user created via a real identify provider.
10+
11+
:::caution
12+
13+
This method of authentication is NOT secure and should not be used in production.
14+
15+
:::
16+
17+
Demo auth replaces the basic auth capability that was previously used for this purpose.
18+
19+
## Configuration
20+
21+
See the [Demo](/docs/on-premises-2x/environment-variables#demo_auth_enabled) section of the environment variables page. Demo auth cannot be enabled at the same time as any other method of authentication (ie. SAML).
22+
23+
## Converting to a production IDP
24+
25+
Demo authentication cannot be enabled at the same time as a real authentication provider (eg. SAML). We recommend starting with a clean database when installing PactFlow for production use. This will ensure no demo users remain in the system.
26+
27+
## Docker Compose example
28+
29+
This [Docker Compose example](/docs/on-premises-2x/docker-compose-example) is configured using Demo Auth.
Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
---
2+
title: OAuth2
3+
---
4+
5+
## Configuration
6+
7+
An OAuth2 identify provider is configured by a set of environment variables prefixed with `PACTFLOW_TEST_OAUTH2_`, or using the `test_oauth2` key in a YAML configuration file. See the [Test OAuth2](/docs/on-premises-2x/environment-variables/1.14-beta) section of the environment variables page for the full list.
8+
9+
## Callback URL
10+
11+
The callback URL is `https://<your PactFlow host>/auth/oauth2/callback`. This must be configured in the settings for the PactFlow client in your Identify Provider.
12+
13+
## Authorize params
14+
15+
The following parameters are sent to the Identity Provider's configured [`authorize_url`](/docs/on-premises-2x/environment-variables/1.14-beta#pactflow_test_oauth2__authorize_url) during the request phase.
16+
17+
| Parameter | Description |
18+
|-----------|-------------|
19+
| scope | `openid profile email` |
20+
| response_type | `code` |
21+
| response_mode | `form_post` |
22+
| state | A randomly generated hex string |
23+
| client_id | The configured [client_id](/docs/on-premises-2x/environment-variables/1.14-beta#pactflow_test_oauth2__client_id) |
24+
| redirect_uri | The [callback URL](#callback-url) as documented above |
25+
26+
The parameters configured in the [`custom_authorize_params`](/docs/on-premises-2x/environment-variables/1.14-beta#pactflow_test_oauth2__custom_authorize_params__key) are also merged into these default parameters.
27+
28+
## Token params
29+
30+
The following parameters are sent to the Identity Provider's configured [`token_url`](/docs/on-premises-2x/environment-variables/1.14-beta#pactflow_test_oauth2__token_url).
31+
32+
| Parameter | Description |
33+
|-----------|-------------|
34+
| code | The `code` returned by the IDP during the callback phase. |
35+
| grant_type | `authorization_code` |
36+
| client_id | The configured [client_id](/docs/on-premises-2x/environment-variables/1.14-beta#pactflow_test_oauth2__client_id) |
37+
| client_secret | The configured [client_secret](/docs/on-premises-2x/environment-variables/1.14-beta#pactflow_test_oauth2__client_secret) |
38+
| redirect_uri | The [callback URL](#callback-url) as documented above |
39+
40+
The parameters configured in the [`custom_token_params`](/docs/on-premises-2x/environment-variables/1.14-beta#pactflow_test_oauth2__custom_token_params__key) are also merged into these default parameters.
41+
42+
## Custom Auth handler
43+
44+
At the end of the OAuth2 login flow, a JWT is retrieved by PactFlow from the customer's Identify Provider. A custom Ruby auth handler configuration file will be supplied by PactFlow to map claims from the JWT to PactFlow roles and teams. The auth handler configuration file must be mounted as a volume on the PactFlow container, in the directory `/home/pactflow/extensions/` eg. `/home/pactflow/extensions/auth_ext_script.rb`.
45+
46+
## Debugging
47+
48+
The URLs and headers of the HTTP interactions with the Identity Provider will be logged at `info` level in the PactFlow logs. To see the request and response bodies, set the `PACTFLOW_LOG_LEVEL` to `debug`. Note that this will log sensitive information, so do not leave the logging at this level permanently.
Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
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+
```
Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
---
2+
title: Database
3+
---
4+
5+
A PostgreSQL database is required for storage of the application data.
6+
7+
:::info
8+
If you would like to migrate an existing PostgreSQL database, skip this section and instead follow the guide [**here**](/docs/on-premises-2x/installation/migrating).
9+
:::
10+
11+
## Supported versions
12+
13+
PostgreSQL version 10.6 and later are supported.
14+
15+
## Database creation
16+
17+
Log in as your database administrator, and execute the following statements in an SQL session.
18+
19+
```sql
20+
CREATE USER pactflow_user WITH PASSWORD '<password>';
21+
CREATE DATABASE pactflow;
22+
GRANT ALL PRIVILEGES ON DATABASE pactflow TO pactflow_user;
23+
REVOKE ALL ON DATABASE pactflow FROM PUBLIC;
24+
```
25+
26+
## SSL
27+
28+
The application's PostgreSQL SSL mode is set to `require` by default, which means it requires the connection to the database to be encrypted, but does not verify the server's certificate. See the documentation for the [PACTFLOW_DATABASE_SSLMODE](environment-variables#pactflow_database_sslmode) environment variable for more options. It is not recommended to use any option weaker than `require`.
29+
30+
## Authentication
31+
32+
## Username/password authentication
33+
34+
Database access between the PactFlow application and Postgres instance can be secured using a [username](/docs/on-premises-2x/environment-variables#pactflow_database_username) and [password](/docs/on-premises-2x/environment-variables#pactflow_database_password), configured via environment variables.
35+
36+
## AWS IAM authentication
37+
38+
When deploying PactFlow on AWS Cloud infrastructure, database access between the PactFlow application and the RDS Postgres instance can be secured using IAM. Please see the [AWS RDS IAM documentation](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAM.html) for more information.
39+
40+
The following environmet variables must be set for the PactFlow application:
41+
42+
* [`PACTFLOW_DATABASE_ADAPTER="postgresiam"`](/docs/on-premises-2x/environment-variables#pactflow_database_adapter)
43+
* [`PACTFLOW_DATABASE_USERNAME`](/docs/on-premises-2x/environment-variables#pactflow_database_username)
44+
* [`PACTFLOW_DATABASE_HOST`](/docs/on-premises-2x/environment-variables#pactflow_database_host)
45+
* [`PACTFLOW_DATABASE_PORT`](/docs/on-premises-2x/environment-variables#pactflow_database_port)
46+
* [`PACTFLOW_DATABASE_NAME`](/docs/on-premises-2x/environment-variables#pactflow_database_name)
47+
* [`PACTFLOW_DATABASE_SSLMODE="require"`](/docs/on-premises-2x/environment-variables#pactflow_database_sslmode)
48+
* [`AWS_REGION`](/docs/on-premises-2x/environment-variables#aws_region)
49+
50+
## Schema migrations
51+
52+
The database schema migrations will be run automatically on start up. See the documentation on [Database migrations](upgrading/database-migrations) for more information.
53+
54+
### Migrating from OSS Pact Broker to PactFlow
55+
56+
If you have been hosting your own instance of the open source Pact Broker, you can point the new PactFlow On-Premises application at the same database, and the missing migrations will be applied.
57+
58+
## Schema
59+
60+
![Database schema](/on-premises/schema.png)

0 commit comments

Comments
 (0)