diff --git a/docs/img/database-access/guides/azure/add-custom-role@2x.png b/docs/img/database-access/guides/azure/add-custom-role@2x.png new file mode 100644 index 0000000000000..6d60ce3bbd4bf Binary files /dev/null and b/docs/img/database-access/guides/azure/add-custom-role@2x.png differ diff --git a/docs/img/database-access/guides/azure/create-role-assignment@2x.png b/docs/img/database-access/guides/azure/create-role-assignment@2x.png new file mode 100644 index 0000000000000..57e9018bae515 Binary files /dev/null and b/docs/img/database-access/guides/azure/create-role-assignment@2x.png differ diff --git a/docs/img/database-access/guides/azure/create-role-from-json@2x.png b/docs/img/database-access/guides/azure/create-role-from-json@2x.png new file mode 100644 index 0000000000000..1091cde4d0379 Binary files /dev/null and b/docs/img/database-access/guides/azure/create-role-from-json@2x.png differ diff --git a/docs/img/database-access/guides/azure/created-identity@2x.png b/docs/img/database-access/guides/azure/created-identity@2x.png index 536b0389b752d..002eca8c62555 100644 Binary files a/docs/img/database-access/guides/azure/created-identity@2x.png and b/docs/img/database-access/guides/azure/created-identity@2x.png differ diff --git a/docs/img/database-access/guides/azure/registered-app@2x.png b/docs/img/database-access/guides/azure/registered-app@2x.png index efb42160d43c1..6f9bcc0da1a28 100644 Binary files a/docs/img/database-access/guides/azure/registered-app@2x.png and b/docs/img/database-access/guides/azure/registered-app@2x.png differ diff --git a/docs/pages/database-access/guides/azure-postgres-mysql.mdx b/docs/pages/database-access/guides/azure-postgres-mysql.mdx index d280aa3dde54d..d4b4335af6c48 100644 --- a/docs/pages/database-access/guides/azure-postgres-mysql.mdx +++ b/docs/pages/database-access/guides/azure-postgres-mysql.mdx @@ -10,8 +10,8 @@ description: How to configure Teleport Database Access with Azure Database for P scopeOnly={true} min="8.1" > - Database access for Azure PostgreSQL/MySQL is available starting from Teleport - `8.1`. + Static configuration of database access for Azure PostgreSQL/MySQL is available starting from Teleport + `8.1` and Azure database auto-discovery is available starting from Teleport `10.2`. This guide will help you to: @@ -44,7 +44,7 @@ This guide will help you to: (!docs/pages/includes/user-client-prereqs.mdx!) -## Step 1/4. Install and configure Teleport +## Step 1/5. Install and configure Teleport ### Set up the Teleport Auth and Proxy Services @@ -58,36 +58,30 @@ Install Teleport on the host where you will run the Teleport Database Service: (!docs/pages/includes/install-linux.mdx!) - +Create the Database Service configuration, specifying a region like this: -Start the Teleport Database Service. Make sure to update `--auth-server` to point to -your Teleport Proxy Service address and `--uri` to the Azure database server -endpoint. + ```code - $ teleport db start \ + $ teleport db configure create \ + -o file \ + --proxy=tele.example.com:443 \ --token=/tmp/token \ - --auth-server=teleport.example.com:3080 \ - --name=azure-db \ - --protocol=postgres \ - --uri=example.postgres.database.azure.com:5321 \ - --labels=env=dev + --azure-postgres-discovery=eastus ``` ```code - $ teleport db start \ + $ teleport db configure create \ + -o file \ + --proxy=teleport.example.com:3080 \ --token=/tmp/token \ - --auth-server=teleport.example.com:3080 \ - --name=azure-db \ - --protocol=mysql \ - --uri=example.mysql.database.azure.com:3306 \ - --labels=env=dev + --azure-mysql-discovery=eastus ``` @@ -96,34 +90,26 @@ endpoint. -Start the Teleport Database Service. Make sure to update `--auth-server` to point to -your Teleport Cloud tenant address and `--uri` to the Azure database server -endpoint. - ```code - $ teleport db start \ + $ teleport db configure create \ + -o file \ + --proxy=teleport.example.com:3080 \ --token=/tmp/token \ - --auth-server=mytenant.teleport.sh:443 \ - --name=azure-db \ - --protocol=postgres \ - --uri=example.postgres.database.azure.com:5321 \ - --labels=env=dev + --azure-postgres-discovery=eastus ``` ```code - $ teleport db start \ + $ teleport db configure create \ + -o file \ + --proxy=teleport.example.com:3080 \ --token=/tmp/token \ - --auth-server=mytenant.teleport.sh:443 \ - --name=azure-db \ - --protocol=mysql \ - --uri=example.mysql.database.azure.com:3306 \ - --labels=env=dev + --azure-mysql-discovery=eastus ``` @@ -131,16 +117,15 @@ endpoint. - - You can start the Teleport Database Service using a configuration file instead of - CLI flags. See the [YAML reference](../reference/configuration.mdx). - +The command will generate a Database Service configuration with Azure MySQL/Postgres +database auto-discovery enabled in the `eastus` region and place it at the +`/etc/teleport.yaml` location. ### Create a Teleport user (!docs/pages/includes/database-access/create-user.mdx!) -## Step 2/4. Configure Azure service principal +## Step 2/5. Configure Azure service principal To authenticate with PostgreSQL or MySQL databases, Teleport Database Service needs to obtain access tokens from Azure AD. There are a couple of ways to @@ -203,7 +188,7 @@ achieve that: ![Registered app secrets](../../../img/database-access/guides/azure/registered-app-secrets@2x.png) The Teleport Database Service uses Azure SDK's default credential provider chain to - look for credentials. Refer to [Authentication methods](https://docs.microsoft.com/en-us/azure/developer/go/azure-sdk-authorization) + look for credentials. Refer to [Azure SDK Authorization](https://docs.microsoft.com/en-us/azure/developer/go/azure-sdk-authorization) to pick a method suitable for your use-case. For example, to use environment-based authentication with a client secret, the Database Service should have the following environment variables set: @@ -216,10 +201,88 @@ achieve that: -## Step 3/4. Create Azure database users +## Step 3/5. Configure IAM permissions for Teleport + +### Create a custom role + +Teleport needs Azure IAM permissions to discover and register MySQL and PostgreSQL databases. +Create a role with assignable scope(s) that include all databases that Teleport should discover. For example: + +```json +{ + "properties": { + "roleName": "TeleportDiscovery", + "description": "Allows Teleport to discover MySQL and PostgreSQL databases", + "assignableScopes": [ + "/subscriptions/11111111-2222-3333-4444-555555555555" + ], + "permissions": [ + { + "actions": [ + "Microsoft.DBforMySQL/servers/read", + "Microsoft.DBforPostgreSQL/servers/read" + ], + "notActions": [], + "dataActions": [], + "notDataActions": [] + } + ] + } +} +``` + +This role definition allows Teleport to discover MySQL and PostgreSQL databases, but Teleport only needs +permissions for the database types you have. The assignable scopes include a subscription, so +the role can be assigned at any resource scope within that subscription, or assigned using the +subscription scope itself. + + +Custom roles, unlike +[Azure built-in roles](https://docs.microsoft.com/en-us/azure/role-based-access-control/built-in-roles), +can not have a root assignable scope. The highest assignable scope that +can be used in a custom role is subscription scope. Using a management group scope is currently an Azure +preview feature, and only allows for a single management group in the "assignableScopes" of a role +definition. +See [Azure RBAC custom roles](https://docs.microsoft.com/en-us/azure/role-based-access-control/custom-roles) for +more information. + + +Go to the [Subscriptions](https://portal.azure.com/#view/Microsoft_Azure_Billing/SubscriptionsBlade) page and select a subscription. + +Click on *Access control (IAM)* in the subscription and select *Add > Add custom role*: +
+![IAM custom role](../../../img/database-access/guides/azure/add-custom-role@2x.png) +
+ +In the custom role creation page, click the *JSON* tab and click *Edit*, then paste the JSON example +and replace the subscription in "assignableScopes" with your own subscription id: +
+![Create JSON role](../../../img/database-access/guides/azure/create-role-from-json@2x.png) +
+ +### Create a role assignment for the Teleport Database Service principal. + +To grant Teleport permissions, the custom role you created must be assigned to the Teleport service principal - +either the managed identity or the app registration you created earlier. + +Navigate to the resource scope where you want to make the role assignment. Click *Access control (IAM)* and +select *Add > Add role assignment*. Choose the custom role you created as the role and the Teleport +service principal as a member. + +
+![Assign role](../../../img/database-access/guides/azure/create-role-assignment@2x.png) +
+ + +The role assignment should be at a high enough scope to allow the Teleport Database Service to discover +all matching databases. See +[Identify the needed scope](https://docs.microsoft.com/en-us/azure/role-based-access-control/role-assignments-steps#step-3-identify-the-needed-scope) +for more information about Azure scopes and creating role assignments. + +## Step 4/5. Create Azure database users To let Teleport connect to your Azure database authenticating as a service -principal, you need to create Azure AD users for that principal in the database. +principal, you need to create Azure AD users authenticated by that principal in the database. ### Assign Azure AD administrator @@ -229,7 +292,13 @@ and set the AD admin using the *Set admin* button: ![Set AD admin](../../../img/database-access/guides/azure/set-ad-admin@2x.png) -Note that only one AD user can be set as an admin for the database. + +Only one Azure user (or group) can be set as an Azure AD admin for the database. +If the Azure AD admin is removed from the server, all Azure AD logins will be disabled for the server. +Adding a new Azure AD admin from the same tenant will re-enable Azure AD logins. +Refer to [Use Azure Active Directory for authenticating with PostgreSQL](https://docs.microsoft.com/en-us/azure/postgresql/single-server/concepts-azure-ad-authentication) +for more information. + ### Connect to the database as an AD admin @@ -280,12 +349,19 @@ registrations: mysql> CREATE AADUSER 'teleport' IDENTIFIED BY '11111111-2222-3333-4444-555555555555'; Query OK, 0 rows affected (0.92 sec) ``` + + The created user may not have access to anything by default so let's grant it + some permissions: + + ```sql + GRANT ALL ON `%`.* TO 'teleport'@'%'; + ``` -You can create multiple database users for the same service principal. +You can create multiple database users identified by the same service principal. -## Step 4/4. Connect +## Step 5/5. Connect Log in to your Teleport cluster. Your Azure database should appear in the list of available databases: @@ -330,6 +406,10 @@ To log out of the database and remove credentials: $ tsh db logout azure-db ``` +## Troubleshooting + +(!docs/pages/includes/database-access/azure-troubleshooting.mdx!) + ## Next steps (!docs/pages/includes/database-access/guides-next-steps.mdx!) diff --git a/docs/pages/includes/database-access/azure-troubleshooting.mdx b/docs/pages/includes/database-access/azure-troubleshooting.mdx new file mode 100644 index 0000000000000..2122907471c3f --- /dev/null +++ b/docs/pages/includes/database-access/azure-troubleshooting.mdx @@ -0,0 +1,19 @@ +### No credential providers error + +If you see the error `DefaultAzureCredential: failed to acquire a token.` in Database Service logs then Teleport +is not detecting the required credentials to connect to the Azure SDK. Check whether +the credentials have been applied in the machine running the Teleport Database Service and restart +the Teleport Database Service. +Refer to [Azure SDK Authorization](https://docs.microsoft.com/en-us/azure/developer/go/azure-sdk-authorization) +for more information. + +### Timeout errors + +The Teleport Database Service needs connectivity to your database endpoints. That may require +enabling inbound traffic on the database from the Database Service on the same VPC or routing rules from another VPC. Using the `nc` +program you can verify connections to databases: + +```code +$ nc -zv server-name.postgres.database.azure.com 5432 +# Connection to server-name.postgres.database.azure.com 5432 port [tcp/postgresql] succeeded! +``` diff --git a/docs/pages/includes/database-access/database-config.yaml b/docs/pages/includes/database-access/database-config.yaml index 4f79b39c76303..b6889f9242b2c 100644 --- a/docs/pages/includes/database-access/database-config.yaml +++ b/docs/pages/includes/database-access/database-config.yaml @@ -21,6 +21,26 @@ db_service: tags: "*": "*" + # Matchers for registering Azure-hosted databases. + azure: + # Database types. Valid options are: + # 'mysql' - discovers and registers Azure MySQL single-server databases. + # 'postgres' - discovers and registers Azure PostgreSQL single-server databases. + - types: ["mysql", "postgres"] + # Azure regions to register databases from. Valid options are: + # '*' - discovers databases in all regions (default). + # Any valid Azure region name. List all valid regions using the Azure "az" cli: `az account list-locations -o table` + regions: ["eastus", "westus"] + # Azure subscription IDs to register databases from. Valid options are: + # '*' - discovers databases in all subscriptions (default). + subscriptions: ["11111111-2222-3333-4444-555555555555"] + # Azure resource groups to register databases from. Valid options are: + # '*' - discovers databases in all resource groups within configured subscription(s) (default). + resource_groups: ["group1", "group2"] + # Azure resource tags to match when registering databases. + tags: + "*": "*" + # Lists statically registered databases proxied by this agent. databases: # Name of the database proxy instance, used to reference in CLI.