diff --git a/docs/images/screenshot_pgadmin.png b/docs/images/screenshot_pgadmin.png new file mode 100644 index 00000000..b7c831a2 Binary files /dev/null and b/docs/images/screenshot_pgadmin.png differ diff --git a/docs/using_entra_auth.md b/docs/using_entra_auth.md index b3b67fb5..1817601a 100644 --- a/docs/using_entra_auth.md +++ b/docs/using_entra_auth.md @@ -2,7 +2,10 @@ To follow security best practices, this project is setup to use passwordless authentication with the Azure Database for PostgreSQL Flexible Server. This means that you can't connect to the database with a password, but instead need to use a token associated with a Microsoft Entra user. Locally, the user should be your own Azure account, whichever account was used to run `azd up`. In production, the user will be the managed identity assigned to the Azure Container App. -## Using psql with Entra auth +* [Using Entra auth with psql](#using-entra-auth-with-psql) +* [Using Entra auth with pgAdmin](#using-entra-auth-with-pgadmin) + +## Using Entra auth with psql 1. Make sure you are logged into the Azure Developer CLI with the same account that was used to run `azd up`. @@ -45,3 +48,59 @@ To follow security best practices, this project is setup to use passwordless aut ``` 5. In psql, use `\d` to list the tables. When you `SELECT` from a table, select only the columns you're interested in, to avoid rendering the vector embeddings in the terminal. + +## Using Entra auth with pgAdmin + +1. Make sure you are logged into the Azure Developer CLI with the same account that was used to run `azd up`. + + ```shell + azd auth login + ``` + + If you used a non-default tenant to run `azd up`, you may need to specify the tenant ID: + + ```shell + azd auth login --tenant-id {tenant_id} + ``` + +2. Generate a token for the Azure Database for PostgreSQL Flexible Server. + + ```shell + azd auth token --scope https://ossrdbms-aad.database.windows.net/.default --output json + ``` + + Once again, if you used a non-default tenant to run `azd up`, you may need to specify the tenant ID. + + ```shell + azd auth token --scope https://ossrdbms-aad.database.windows.net/.default --tenant-id YOUR-TENANT-ID --output json + ``` + + This will output JSON with a token inside the "token" field. Copy the token. + +3. Open pgAdmin and create a new server connection. + +4. In the "General" tab, set the name to something memorable like "RAG PostgreSQL server". + +5. In the "Connection" tab, set the host to the `POSTGRES_HOST` value from the current `azd` environment. Run: + + ```shell + azd env get-value POSTGRES_HOST + ``` + +6. Set the database to the `POSTGRES_DATABASE` value from the current `azd` environment. Run: + + ```shell + azd env get-value POSTGRES_DATABASE + ``` + +7. Set the username to the `POSTGRES_USERNAME` value from the current `azd` environment. Run: + + ```shell + azd env get-value POSTGRES_USERNAME + ``` + +8. Set the password to the token you generated in step 2. You will need to refresh that password with a new token periodically (every few hours). + +9. Now you should be able to connect to the database and view the tables and data. + + ![Screenshot of pgAdmin showing the tables in the database](images/screenshot_pgadmin.png)