diff --git a/docs/config.json b/docs/config.json index 8467cad0049..3ec8d6d8e05 100644 --- a/docs/config.json +++ b/docs/config.json @@ -63,8 +63,9 @@ "title": "Guides", "slug": "/database-access/guides/", "entries": [ - { "title": "PostgreSQL on AWS", "slug": "/database-access/guides/postgres-aws/" }, - { "title": "MySQL on AWS", "slug": "/database-access/guides/mysql-aws/" }, + { "title": "AWS RDS/Aurora PostgreSQL", "slug": "/database-access/guides/postgres-aws/" }, + { "title": "AWS RDS/Aurora MySQL", "slug": "/database-access/guides/mysql-aws/" }, + { "title": "GCP Cloud SQL PostgreSQL", "slug": "/database-access/guides/postgres-cloudsql/" }, { "title": "Self-Hosted PostgreSQL", "slug": "/database-access/guides/postgres-self-hosted/" }, { "title": "Self-Hosted MySQL", "slug": "/database-access/guides/mysql-self-hosted/" }, { "title": "Database GUI Clients", "slug": "/database-access/guides/gui-clients/" } @@ -89,6 +90,7 @@ { "title": "Role Templates", "slug": "/access-controls/guides/role-templates/" }, { "title": "Second Factor - U2F", "slug": "/access-controls/guides/u2f/" }, { "title": "Per-session MFA", "slug": "/access-controls/guides/per-session-mfa/" }, + { "title": "Dual Authorization", "slug": "/access-controls/guides/dual-authz/" }, { "title": "Impersonation", "slug": "/access-controls/guides/impersonation/" } ] }, @@ -177,10 +179,10 @@ "variables": { "version": "7.0", "teleport": { - "version": "6.0.1", + "version": "6.1.0", "golang": "1.16", "plugin": { - "version": "6.0.1" + "version": "6.1.0" }, "latest_oss_docker_image": "quay.io/gravitational/teleport:7.0", "latest_ent_docker_image": "quay.io/gravitational/teleport-ent:7.0" diff --git a/docs/img/access-controls/dual-authz/mattermost-0-enable.png b/docs/img/access-controls/dual-authz/mattermost-0-enable.png new file mode 100644 index 00000000000..3d3e7e915a3 Binary files /dev/null and b/docs/img/access-controls/dual-authz/mattermost-0-enable.png differ diff --git a/docs/img/access-controls/dual-authz/mattermost-1-bot.png b/docs/img/access-controls/dual-authz/mattermost-1-bot.png new file mode 100644 index 00000000000..5c44f426464 Binary files /dev/null and b/docs/img/access-controls/dual-authz/mattermost-1-bot.png differ diff --git a/docs/img/access-controls/dual-authz/mattermost-2-all-permissions@2x.png b/docs/img/access-controls/dual-authz/mattermost-2-all-permissions@2x.png new file mode 100644 index 00000000000..5473af4dfae Binary files /dev/null and b/docs/img/access-controls/dual-authz/mattermost-2-all-permissions@2x.png differ diff --git a/docs/img/access-controls/dual-authz/mattermost-5-request.png b/docs/img/access-controls/dual-authz/mattermost-5-request.png new file mode 100644 index 00000000000..0f8c2d22eec Binary files /dev/null and b/docs/img/access-controls/dual-authz/mattermost-5-request.png differ diff --git a/docs/img/access-controls/dual-authz/teleport-4-bob-request.png b/docs/img/access-controls/dual-authz/teleport-4-bob-request.png new file mode 100644 index 00000000000..1ce44826544 Binary files /dev/null and b/docs/img/access-controls/dual-authz/teleport-4-bob-request.png differ diff --git a/docs/img/access-controls/dual-authz/teleport-6-ivan-approve.png b/docs/img/access-controls/dual-authz/teleport-6-ivan-approve.png new file mode 100644 index 00000000000..55c509aee03 Binary files /dev/null and b/docs/img/access-controls/dual-authz/teleport-6-ivan-approve.png differ diff --git a/docs/img/access-controls/dual-authz/teleport-7-bob-assume.png b/docs/img/access-controls/dual-authz/teleport-7-bob-assume.png new file mode 100644 index 00000000000..ae2d2d42840 Binary files /dev/null and b/docs/img/access-controls/dual-authz/teleport-7-bob-assume.png differ diff --git a/docs/img/database-access/guides/cloudsql/add-user-account@2x.png b/docs/img/database-access/guides/cloudsql/add-user-account@2x.png new file mode 100644 index 00000000000..2da4f3283e8 Binary files /dev/null and b/docs/img/database-access/guides/cloudsql/add-user-account@2x.png differ diff --git a/docs/img/database-access/guides/cloudsql/iam-existing-instance@2x.png b/docs/img/database-access/guides/cloudsql/iam-existing-instance@2x.png new file mode 100644 index 00000000000..caf65c3aa66 Binary files /dev/null and b/docs/img/database-access/guides/cloudsql/iam-existing-instance@2x.png differ diff --git a/docs/img/database-access/guides/cloudsql/iam-new-instance@2x.png b/docs/img/database-access/guides/cloudsql/iam-new-instance@2x.png new file mode 100644 index 00000000000..2c53ace12a3 Binary files /dev/null and b/docs/img/database-access/guides/cloudsql/iam-new-instance@2x.png differ diff --git a/docs/img/database-access/guides/cloudsql/instance-id@2x.png b/docs/img/database-access/guides/cloudsql/instance-id@2x.png new file mode 100644 index 00000000000..91d41199b1f Binary files /dev/null and b/docs/img/database-access/guides/cloudsql/instance-id@2x.png differ diff --git a/docs/img/database-access/guides/cloudsql/instance-public-ip@2x.png b/docs/img/database-access/guides/cloudsql/instance-public-ip@2x.png new file mode 100644 index 00000000000..5a911da379e Binary files /dev/null and b/docs/img/database-access/guides/cloudsql/instance-public-ip@2x.png differ diff --git a/docs/img/database-access/guides/cloudsql/instance-root-ca@2x.png b/docs/img/database-access/guides/cloudsql/instance-root-ca@2x.png new file mode 100644 index 00000000000..302140d95cc Binary files /dev/null and b/docs/img/database-access/guides/cloudsql/instance-root-ca@2x.png differ diff --git a/docs/img/database-access/guides/cloudsql/service-account-db-grant@2x.png b/docs/img/database-access/guides/cloudsql/service-account-db-grant@2x.png new file mode 100644 index 00000000000..61cb2072f26 Binary files /dev/null and b/docs/img/database-access/guides/cloudsql/service-account-db-grant@2x.png differ diff --git a/docs/img/database-access/guides/cloudsql/service-account-db-service-grant@2x.png b/docs/img/database-access/guides/cloudsql/service-account-db-service-grant@2x.png new file mode 100644 index 00000000000..c652bebd066 Binary files /dev/null and b/docs/img/database-access/guides/cloudsql/service-account-db-service-grant@2x.png differ diff --git a/docs/img/database-access/guides/cloudsql/service-account-db-service@2x.png b/docs/img/database-access/guides/cloudsql/service-account-db-service@2x.png new file mode 100644 index 00000000000..76c78999863 Binary files /dev/null and b/docs/img/database-access/guides/cloudsql/service-account-db-service@2x.png differ diff --git a/docs/img/database-access/guides/cloudsql/service-account-db@2x.png b/docs/img/database-access/guides/cloudsql/service-account-db@2x.png new file mode 100644 index 00000000000..5417e77aecc Binary files /dev/null and b/docs/img/database-access/guides/cloudsql/service-account-db@2x.png differ diff --git a/docs/img/database-access/guides/cloudsql/service-account-keys@2x.png b/docs/img/database-access/guides/cloudsql/service-account-keys@2x.png new file mode 100644 index 00000000000..81a0e972ba0 Binary files /dev/null and b/docs/img/database-access/guides/cloudsql/service-account-keys@2x.png differ diff --git a/docs/img/database-access/guides/cloudsql/service-account-new-key@2x.png b/docs/img/database-access/guides/cloudsql/service-account-new-key@2x.png new file mode 100644 index 00000000000..1ada05ac57d Binary files /dev/null and b/docs/img/database-access/guides/cloudsql/service-account-new-key@2x.png differ diff --git a/docs/img/database-access/guides/cloudsql/user-accounts@2x.png b/docs/img/database-access/guides/cloudsql/user-accounts@2x.png new file mode 100644 index 00000000000..791a54db118 Binary files /dev/null and b/docs/img/database-access/guides/cloudsql/user-accounts@2x.png differ diff --git a/docs/pages/access-controls/guides.mdx b/docs/pages/access-controls/guides.mdx index a588a0f90fb..ae85257e228 100644 --- a/docs/pages/access-controls/guides.mdx +++ b/docs/pages/access-controls/guides.mdx @@ -9,3 +9,4 @@ description: Detailed guides for configuring Teleport Access Controls - [Second Factor - U2F](./guides/u2f.mdx) - [Per-session MFA](./guides/per-session-mfa.mdx) - [Create certs for CI/CD using impersonation](./guides/impersonation.mdx) +- [Dual authorization with ChatOps](./guides/dual-authz.mdx) diff --git a/docs/pages/access-controls/guides/dual-authz.mdx b/docs/pages/access-controls/guides/dual-authz.mdx new file mode 100644 index 00000000000..fbabb157895 --- /dev/null +++ b/docs/pages/access-controls/guides/dual-authz.mdx @@ -0,0 +1,287 @@ +--- +title: Dual Authorization +description: Dual Authorization for SSH and Kubernetes +--- + +# Dual Authorization + +You can set up Teleport to require require the approval of multiple team members to perform some critical actions. +Here are the most common scenarios: + +- Improve security of your system and prevent one successful phishing attack from compromizing your system. +- Satisfy FedRamp AC-3 Dual authorization control that requires approval of two authorized individuals. + +Let's set up Teleport's access requests to require approval of +two team members for a privileged role `dbadmin`. + + + This guide requires a commercial edition of Teleport. The open source + edition of Teleport only supports [Github](../../admin-guide.mdx#github-oauth-20) as + an SSO provider. + + +## Prerequisites + +- Installed [Teleport Enterprise](../../enterprise/introduction.mdx) or [Teleport Cloud](../../cloud.mdx) >= (=teleport.version=) +- [Tctl enterprise admin tool](https://goteleport.com/teleport/download) >= (=teleport.version=) +- Mattermost installed. + + + ```bash + docker run --name mattermost-preview -d --publish 8065:8065 --add-host dockerhost:127.0.0.1 mattermost/mattermost-preview + ``` + + +Verify that your Teleport client is connected: + +```bash +$ tctl status +Cluster acme.example.com +Version 6.0.2 +Host CA never updated +User CA never updated +Jwt CA never updated +CA pin sha256:e63c7c44be468d37a5b0276b70e9d10b17f24f4be19d6b579810fc94eaa31783 +``` + +## Setup Teleport Bot + + + + +Enable bot account creation in `System Console -> Integrations`. +Toggle `Enable Bot Account Creation`. + +![Enable bots](../../../img/access-controls/dual-authz/mattermost-0-enable.png) + +Go back to your team settings, navigate to `Integrations -> Bot Accounts`. Press `Add Bot Account`. + +![Enable bots](../../../img/access-controls/dual-authz/mattermost-1-bot.png) + +Add `Post All` permission on the new account. + +![Enable bots](../../../img/access-controls/dual-authz/mattermost-2-all-permissions@2x.png) + +Create the bot and save the access token. + + + + +Create a non-interactive bot `access-plugin` user and role. + +```yaml +kind: user +metadata: + name: access-plugin +spec: + roles: ['access-plugin'] +version: v2 +--- +kind: role +version: v3 +metadata: + name: access-plugin +spec: + allow: + rules: + - resources: ['access_request'] + verbs: ['list', 'read'] + - resources: ['access_plugin_data'] + verbs: ['update'] + # teleport currently refuses to issue certs for a user with 0 logins, + # this restriction may be lifted in future versions. + logins: ['access-plugin-not-used'] +``` + + + Here and below follow along and create yaml resources using `tctl create -f`: + ```bash + $ tctl create -f access.yaml + ``` + + + +**Export access-plugin cert** + +Teleport Plugin uses the `access-plugin` role and user to perform the approval. +We export the identify files, using tctl auth sign. + +```bash +$ tctl auth sign --format=tls --user=access-plugin --out=auth --ttl=720h +``` + +Teleport will generate `auth.crt`, `auth.key`, and `auth.cas` - a certificate, a private key, and a set of CA certs respectively. + +**Install the plugin** + + + + ```bash + $ curl -L https://get.gravitational.com/teleport-mattermost-v(=teleport.version=)-linux-amd64-bin.tar.gz + $ tar -xzf teleport-mattermost-v(=teleport.version=)-linux-amd64-bin.tar.gz + $ cd teleport-mattermost + $ ./install + ``` + + + To install from source you need `git` and `go >= (=teleport.golang=)` installed. + + ```bash + # Checkout teleport-plugins + $ git clone https://github.com/gravitational/teleport-plugins.git + $ cd teleport-plugins/access/mattermost + $ make + ``` + + + + +```bash +$ teleport-mattermost configure > /etc/teleport-mattermost.toml +``` + +Update the config with Teleport address, Mattermost URL and a bot token. + +```toml +# example Mattermost configuration TOML file +[teleport] +# For Teleport Cloud you can point to the proxy: "example.teleport.sh:443" +auth_server = "teleport.example.com:3025" # Teleport Auth Server GRPC API address +client_key = "/var/lib/teleport/plugins/mattermost/auth.key" # Teleport GRPC client secret key +client_crt = "/var/lib/teleport/plugins/mattermost/auth.crt" # Teleport GRPC client certificate +root_cas = "/var/lib/teleport/plugins/mattermost/auth.cas" # Teleport cluster CA certs + +[mattermost] +url = "https://mattermost.example.com" # Mattermost Server URL +token = "api-token" # Mattermost Bot OAuth token + +[log] +output = "stderr" # Logger output. Could be "stdout", "stderr" or "/var/lib/teleport/mattermost.log" +severity = "INFO" # Logger severity. Could be "INFO", "ERROR", "DEBUG" or "WARN". +``` + +## Dual Authorization + +Alice and Ivan are reviewers - they can approve requests for assuming role `dbadmin`. +Bob is a devops and can assume `dbadmin` role if two members of the `reviewer` role +approved the request. + +Create `dbadmin`, `reviewer` and `devops` roles: + +```yaml +kind: role +version: v3 +metadata: + name: reviewer +spec: + allow: + review_requests: + roles: ['dbadmin'] +--- +kind: role +version: v3 +metadata: + name: devops +spec: + allow: + request: + roles: ['dbadmin'] + thresholds: + - approve: 2 + deny: 1 +--- +kind: role +version: v3 +metadata: + name: dbadmin +spec: + allow: + logins: ['root'] + node_labels: + 'env': 'prod' + 'type': 'db' +``` + +Example below creates local users Alice, Ivan and Bob. +Bob does not have a role `dbadmin` assigned to him, but can create an access request for it. + +```bash +$ tctl users add bob@example.com --roles=devops +$ tctl users add alice@example.com --roles=reviewer +$ tctl users add ivan@example.com --roles=reviewer +``` + +## Access Requests Flow + +Bob can create an access request for the `dbadmin` role in the Web UI or CLI: + + + + ![Mattermost-Request](../../../img/access-controls/dual-authz/teleport-4-bob-request.png) + + + ```bash + # Bob has to set valid emails of Alice and Ivan matching in Mattermost. + tsh request create --roles=dbadmin --reviewers=alice@example.com,ivan@example.com + ``` + + + +Chatbot will notify both Alice and Ivan: + +![Mattermost-Request](../../../img/access-controls/dual-authz/mattermost-5-request.png) + +Alice and Ivan can review and approve request using Web UI or CLI: + + + +![Teleport-Approve](../../../img/access-controls/dual-authz/teleport-6-ivan-approve.png) + + + ```bash + $ tsh request list + ID User Roles Created (UTC) Status + ------------------------------------ --------------- ------- ------------------- ------- + 9c721e54-b049-4ef8-a7f6-c777aa066764 bob@example.com dbadmin 03 Apr 21 03:58 UTC PENDING + + $tsh request review --approve --reason="hello" 9c721e54-b049-4ef8-a7f6-c777aa066764 + Successfully submitted review. Request state: APPROVED + ``` + + + +If Bob has created a request using CLI, he will assume it once it has been approved. +Bob can also assume granted access request roles using Web UI: + +![Teleport Assume](../../../img/access-controls/dual-authz/teleport-7-bob-assume.png) + +## Troubleshooting + +**Cert errors** + +You may be getting certificate errors if Teleport's auth server is missing +address in the server certificate: + +```bash +authentication handshake failed: x509: cannot validate certificate for 127.0.0.1 because it doesn't contain any IP SANs +``` + +```bash +x509: certificate is valid for,*.teleport.cluster.local, teleport.cluster.local, not example.com +``` + +To fix the problem, update the auth service with public address and restart Teleport: + +```yaml +auth_service: + public_addr: ['localhost:3025', 'example.com:3025'] +``` diff --git a/docs/pages/database-access.mdx b/docs/pages/database-access.mdx index bcbb6420000..72372fd49d7 100644 --- a/docs/pages/database-access.mdx +++ b/docs/pages/database-access.mdx @@ -50,6 +50,7 @@ guide. - [AWS RDS/Aurora PostgreSQL](./database-access/guides/postgres-aws.mdx) - [AWS RDS/Aurora MySQL](./database-access/guides/mysql-aws.mdx) +- [GCP Cloud SQL PostgreSQL](./database-access/guides/postgres-cloudsql.mdx) - [Self-hosted PostgreSQL](./database-access/guides/postgres-self-hosted.mdx) - [Self-hosted MySQL](./database-access/guides/mysql-self-hosted.mdx) - [GUI clients](./database-access/guides/gui-clients.mdx) diff --git a/docs/pages/database-access/getting-started.mdx b/docs/pages/database-access/getting-started.mdx index f47f8ab0cbc..5b163242611 100644 --- a/docs/pages/database-access/getting-started.mdx +++ b/docs/pages/database-access/getting-started.mdx @@ -179,7 +179,7 @@ psql "service=-aurora user=alice dbname=postgres" For the next steps, dive deeper into the topics relevant to your Database Access use-case, for example: -- Learn in more detail about AWS hosted [PostgreSQL](./guides/postgres-aws.mdx) or [MySQL](./guides/mysql-aws.mdx). +- Learn in more detail about AWS hosted [PostgreSQL](./guides/postgres-aws.mdx), [MySQL](./guides/mysql-aws.mdx), or GCP hosted [PostgreSQL](./guides/postgres-cloudsql.mdx). - Learn how to connect to a self-hosted [PostgreSQL](./guides/postgres-self-hosted.mdx) or [MySQL](./guides/mysql-self-hosted.mdx). - Learn how to configure [GUI clients](./guides/gui-clients.mdx). - Learn about Database Access [role-based access control](./rbac.mdx). diff --git a/docs/pages/database-access/guides.mdx b/docs/pages/database-access/guides.mdx index e3d559ef89e..6b00744fd8a 100644 --- a/docs/pages/database-access/guides.mdx +++ b/docs/pages/database-access/guides.mdx @@ -7,6 +7,7 @@ description: Guides for configuring Teleport Database Access with self-hosted or - [AWS RDS/Aurora PostgreSQL](./guides/postgres-aws.mdx) - [AWS RDS/Aurora MySQL](./guides/mysql-aws.mdx) +- [GCP Cloud SQL PostgreSQL](./guides/postgres-cloudsql.mdx) - [Self-hosted PostgreSQL](./guides/postgres-self-hosted.mdx) - [Self-hosted MySQL](./guides/mysql-self-hosted.mdx) - [GUI clients](./guides/gui-clients.mdx) diff --git a/docs/pages/database-access/guides/mysql-aws.mdx b/docs/pages/database-access/guides/mysql-aws.mdx index 9c93dd89a7d..49152359e1f 100644 --- a/docs/pages/database-access/guides/mysql-aws.mdx +++ b/docs/pages/database-access/guides/mysql-aws.mdx @@ -3,7 +3,7 @@ title: Database Access with MySQL on AWS description: How to configure Teleport Database Access with AWS RDS/Aurora MySQL --- -# MySQL on AWS +# AWS RDS/Aurora MySQL ## Enable IAM Authentication diff --git a/docs/pages/database-access/guides/postgres-aws.mdx b/docs/pages/database-access/guides/postgres-aws.mdx index 1d4e2ed1290..6b00918621e 100644 --- a/docs/pages/database-access/guides/postgres-aws.mdx +++ b/docs/pages/database-access/guides/postgres-aws.mdx @@ -3,7 +3,7 @@ title: Database Access with PostgreSQL on AWS description: How to configure Teleport Database Access with AWS RDS/Aurora PostgreSQL --- -# PostgreSQL on AWS +# AWS RDS/Aurora PostgreSQL ## Enable IAM Authentication diff --git a/docs/pages/database-access/guides/postgres-cloudsql.mdx b/docs/pages/database-access/guides/postgres-cloudsql.mdx new file mode 100644 index 00000000000..08164c6e3aa --- /dev/null +++ b/docs/pages/database-access/guides/postgres-cloudsql.mdx @@ -0,0 +1,348 @@ +--- +title: Database Access with PostgreSQL on GCP Cloud SQL +description: How to configure Teleport Database Access with GCP Cloud SQL PostgreSQL +--- + +# GCP Cloud SQL PostgreSQL + +## Enable Cloud SQL IAM Authentication + +Teleport uses [IAM database authentication](https://cloud.google.com/sql/docs/postgres/authentication) +with Cloud SQL PostgreSQL instances. + +If you're [creating](https://console.cloud.google.com/sql/choose-instance-engine) +a new PostgreSQL instance, make sure to add the `cloudsql.iam_authentication` +database flag under "Customize your instance / Flags" section: + +![Enable IAM Authentication](../../../img/database-access/guides/cloudsql/iam-new-instance@2x.png) + +To check whether IAM authentication is enabled for an existing Cloud SQL instance, +look for the flag on the Configuration panel on the instance's Overview page: + +![Check IAM Authentication](../../../img/database-access/guides/cloudsql/iam-existing-instance@2x.png) + +If it isn't enabled, you can add this flag using the "Edit configuration" dialog +at the bottom of the Configuration panel. Note, changing this setting may +require a database instance reboot. + +## Create Service Account for Database + +Teleport uses service accounts to connect to Cloud SQL databases. + +Go to the IAM & Admin [Service Accounts](https://console.cloud.google.com/iam-admin/serviceaccounts) +page and create a new service account: + +![Create Service Account](../../../img/database-access/guides/cloudsql/service-account-db@2x.png) + +Press "Create". + +On the second step grant this service account the "Cloud SQL Instance User" role +which will allow it to connect to Cloud SQL instances using IAM token for +authentication: + +![Grant Cloud SQL Instance User to Service Account](../../../img/database-access/guides/cloudsql/service-account-db-grant@2x.png) + +Press "Done". + +Now go back to the Users page of your Cloud SQL instance and add a new user +account. In the sidebar, choose "Cloud IAM" authentication type and add the +service account you've just created: + +![Add Cloud SQL User Account](../../../img/database-access/guides/cloudsql/add-user-account@2x.png) + +Press "Add" and your Users table should look similar to this: + +![Cloud SQL User Accounts Table](../../../img/database-access/guides/cloudsql/user-accounts@2x.png) + +See [Creating and managing IAM users](https://cloud.google.com/sql/docs/postgres/create-manage-iam-users) +in Google Cloud documentation for more info. + +## Create Service Account for Teleport Database Service + +The final part of GCP configuration is to create another service account with +"Service Account Token Creator" permission, or modify an existing one to add it. +This will let Teleport Database Service generate an IAM auth token when +connecting to the database as a service account user we created above. + +If creating a new one, go to the [Service Accounts](https://console.cloud.google.com/iam-admin/serviceaccounts) +page and create another service account: + +![Create Service Account](../../../img/database-access/guides/cloudsql/service-account-db-service@2x.png) + +Assign it the "Service Account Token Creator" role: + +![Grant Service Account Token Creator to Service Account](../../../img/database-access/guides/cloudsql/service-account-db-service-grant@2x.png) + +Once created, go to that service account's Keys tab and create a new key: + +![Service Account Keys](../../../img/database-access/guides/cloudsql/service-account-keys@2x.png) + +Make sure to choose JSON format: + +![Service Account New Key](../../../img/database-access/guides/cloudsql/service-account-new-key@2x.png) + +Save the file, your Teleport Database Service will need it to be able to generate +IAM auth tokens. + +## Gather Cloud SQL Instance Information + +To connect a Cloud SQL database to Teleport, you'll need to gather a few pieces +of information about the instance. + +- GCP Project ID. + +You can normally see it in the organization view at the top of the GCP dashboard. + +- Cloud SQL instance ID. + +The instance ID is the name of your Cloud SQL instance shown at the top of the +Overview page: + +![Instance ID](../../../img/database-access/guides/cloudsql/instance-id@2x.png) + +- Cloud SQL instance endpoint. + +You will use the instance's public IP address to connect to it. It can be viewed +on the "Connect to this instance" panel on the Overview page: + +![Instance Public IP](../../../img/database-access/guides/cloudsql/instance-public-ip@2x.png) + +- Cloud SQL instance root certificate. + +The instance's root certificate is required so Teleport can validate the +certificate presented by the database instance. You can download `server-ca.pem` +file from the Connections tab under Security section: + +![Instance Root Certificate](../../../img/database-access/guides/cloudsql/instance-root-ca@2x.png) + +## Setup Teleport Auth and Proxy Services + +Cloud SQL support for Teleport Database Access is available starting from +`6.1` release. Download the appropriate version of Teleport for your platform from +our [downloads page](https://goteleport.com/teleport/download). + +Teleport requires a valid TLS certificate to operate and can fetch one automatically +using Let's Encrypt [ACME](https://letsencrypt.org/how-it-works/) protocol. + +We will assume that you have configured DNS records for `teleport.example.com` +and `*.teleport.example.com` to point to the Teleport node. + +Let's generate a Teleport config with ACME enabled: + +```shell +$ teleport configure --cluster-name=teleport.example.com --acme --acme-email=alice@example.com -o file +``` + + + Teleport uses [TLS-ALPN-01](https://letsencrypt.org/docs/challenge-types/#tls-alpn-01) + ACME challenge to validate certificate requests which only works on port `443`. + As such, in order to use ACME for certificate management, web proxy needs to + be accessible on port `443`. + + +Start the service: + +```sh +$ sudo teleport start +``` + +Generate a short-lived join token for the database service and save it for +example in `/tmp/token`: + +```sh +$ tctl tokens add \ + --type=db \ + --db-name=test \ + --db-protocol=postgres \ + --db-uri=35.1.2.3:5432 +``` + +### Create User + +Create local Teleport user with the built-in `access` role: + +```sh +$ tctl users add --roles=access alice +``` + +The `access` role allows users to see all connected database servers, but +database names and accounts are restricted to the user's `db_names` and +`db_users` traits. Normally, these traits come from the identity provider. For +the local user you've just created you can update them manually to allow it to +connect to the `postgres` database as a `teleport@.iam` database +service account. + +First, export the user resource: + +```sh +$ tctl get users/alice > alice.yaml +``` + +Update the resource to include the following traits: + +```yaml +traits: + # Database account names the user will be allowed to use. + # Note: replace with your GCP project ID. + db_users: + - teleport@.iam + # Database names the user will be allowed to connect to. + db_names: + - postgres +``` + +Update the user: + +```sh +$ tctl create alice.yaml -f +``` + +For more detailed information about database access controls see [RBAC](../rbac.mdx) +documentation. + +## Setup Teleport Database Service + +Below is an example of a database service configuration file that proxies +a single Cloud SQL PostgreSQL database: + +```yaml +teleport: + data_dir: /var/lib/teleport-db + nodename: test + # Proxy address to connect to. Note that it has to be the proxy address + # because database service always connects to the cluster over reverse + # tunnel. + auth_servers: + - teleport.example.com:3080 +db_service: + enabled: "yes" + # This section contains definitions of all databases proxied by this + # service, can contain multiple items. + databases: + # Name of the database proxy instance, used to reference in CLI. + - name: "cloudsql" + # Free-form description of the database proxy instance. + description: "GCP Cloud SQL PostgreSQL" + # Database protocol. + protocol: "postgres" + # Database endpoint. For Cloud SQL use instance's public IP address. + uri: "35.1.2.3:5432" + # Path to Cloud SQL instance root certificate you downloaded above. + ca_cert_file: /path/to/cloudsql/instance/root.pem + # GCP specific configuration when connecting Cloud SQL instance. + gcp: + # GCP project ID. + project_id: "" + # Cloud SQL instance ID. + instance_id: "test" + # Labels to assign to the database, used in RBAC. + static_labels: + env: dev +auth_service: + enabled: "no" +ssh_service: + enabled: "no" +proxy_service: + enabled: "no" +``` + + + A single Teleport process can run multiple different services, for example + multiple database access proxies as well as running other services such an + SSH service or an application access proxy. + + +Start the database service: + +```sh +$ teleport start --config=/path/to/teleport-db.yaml --token=/tmp/token +``` + +### GCP Credentials + +Teleport Database Service must have credentials of `teleport-db-service` GCP +service account we created [above](#create-service-account-for-teleport-database-service) +in order to be able to generate IAM auth tokens. + +The easiest way to ensure that is to set `GOOGLE_APPLICATION_CREDENTIALS` +environment variable to point to the JSON credentials file you downloaded +earlier. + +See [Authenticating as a service account](https://cloud.google.com/docs/authentication/production) +in Google Cloud documentation for more details. + +## Connect + +Once the database service has joined the cluster, login to see the available +databases: + +```sh +$ tsh login --proxy=teleport.example.com:3080 --user=alice +$ tsh db ls +Name Description Labels +-------- ------------------------ -------- +cloudsql GCP Cloud SQL PostgreSQL env=dev +``` + +Note that you will only be able to see databases your role has access to. See +[RBAC](../rbac.mdx) section for more details. + +To connect to a particular database server, first retrieve credentials from +Teleport using `tsh db login` command: + +```sh +$ tsh db login cloudsql +``` + + + You can be logged into multiple databases simultaneously. + + +You can optionally specify the database name and the user to use by default +when connecting to the database instance: + +```sh +$ tsh db login --db-user=teleport@.iam --db-name=postgres cloudsql +``` + + + When connecting to the database, use the name of the database service account + that you added as IAM database user [above](#create-service-account-for-database), + minus the `.gserviceaccount.com` suffix. The database user name is shown on + the Users page of your Cloud SQL instance. + + +When logging into a PostgreSQL database, `tsh` automatically configures a section +in the [connection service file](https://www.postgresql.org/docs/current/libpq-pgservice.html) +with the name of `-`. + +Suppose the cluster name is "teleport.example.com", then you can connect to the +database using the following `psql` command: + +```sh +# Use default database user and database name. +$ psql "service=teleport.example.com-cloudsql" +# Specify database user and database name explicitly. +$ psql "service=teleport.example.com-cloudsql user=teleport@.iam dbname=postgres" +``` + +To log out of the database and remove credentials: + +```sh +# Remove credentials for a particular database instance. +$ tsh db logout cloudsql +# Remove credentials for all database instances. +$ tsh db logout +``` diff --git a/docs/pages/database-access/reference.mdx b/docs/pages/database-access/reference.mdx index 2b296eec1e2..95dbf54fed9 100644 --- a/docs/pages/database-access/reference.mdx +++ b/docs/pages/database-access/reference.mdx @@ -31,6 +31,12 @@ db_service: aws: # Region the database is deployed in. region: "us-east-1" + # GCP specific configuration for Cloud SQL databases. + gcp: + # GCP project ID. + project_id: "xxx-1234" + # Cloud SQL instance ID. + instance_id: "example" # Static labels to assign to the database. Used in RBAC. static_labels: env: "prod" diff --git a/docs/pages/preview/upcoming-releases.mdx b/docs/pages/preview/upcoming-releases.mdx index 4bd49a8bf61..ab43812a328 100644 --- a/docs/pages/preview/upcoming-releases.mdx +++ b/docs/pages/preview/upcoming-releases.mdx @@ -6,28 +6,22 @@ h1: Upcoming Teleport Releases The teleport team delivers a new major release roughly every 3 months. -## Teleport 6.1 "New York" +## Teleport 6.2 "Buffalo" -The team adds per session U2F support, Dual Authorization and Access Workflows UI. +The team focuses on cleanup of customer-facing issues and documentation. ### Release Schedule | Version | Date | Description | | - | - | - | -| First alpha | March 15th, 2021 | Good for testing and demos. | -| First beta | March 31st, 2021 | Deploy on staging. | -| Release | April 7th, 2021 | Good to go for production. | +| First alpha | April 30th, 2021 | Good for testing and demos. | +| First beta | May 5th | Deploy on staging. | +| Release | May 10th, 2021 | Good to go for production. | ### Features You can find the full list of fixes and features in the -[Github milestone](https://github.com/gravitational/teleport/milestone/50). - -| Feature | Editions | Description | -| - | - | - | -| Dual Authorization Workflows | Enterprise, Cloud | Request multiple users to review and approve access requests. Find out more in [issue 5007](https://github.com/gravitational/teleport/issues/5007). | -| U2F for Kubernetes and SSH sessions | All | Adds an option to authorize with 2nd factor when connecting to a node/k8s cluster. Details in [issue 3828](https://github.com/gravitational/teleport/issues/3878). | -| Access Workflows UI | Enterprise, Cloud | Review access requests and assume roles in the UI. Some mockups are in [issue 4937](https://github.com/gravitational/teleport/issues/4937). | +[Github milestone](https://github.com/gravitational/teleport/milestone/55). ## Semantic Versioning