Skip to content

Commit f0a0936

Browse files
hessjcghessjcg
authored
docs: Add documentation for Service Account Impersonation feature. (#1427)
Add documentation of the new `cloudSqlTargetPrincipal` and `cloudSqlDelegates` properties that control service account impersonation. fixes #1168
1 parent 7750bcd commit f0a0936

File tree

6 files changed

+347
-0
lines changed

6 files changed

+347
-0
lines changed

‎docs/jdbc-mariadb.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -96,6 +96,59 @@ Note: a non-empty string value for the `password` property must be set. While th
9696
be ignored when connecting with the Cloud SQL Connector using IAM auth, leaving it empty will cause
9797
driver-level validations to fail.
9898

99+
### Service Account Impersonation
100+
101+
The Java Connector supports service account impersonation with the
102+
`cloudSqlTargetPrincipal` JDBC connection property. When enabled,
103+
all API requests are made impersonating the supplied service account. The
104+
IAM principal must have the iam.serviceAccounts.getAccessToken permission or
105+
the role roles/iam.serviceAccounts.serviceAccountTokenCreator.
106+
107+
Example:
108+
```java
109+
// Set up URL parameters
110+
String jdbcURL = String.format("jdbc:mariadb://ignoreme:123/%s", DB_NAME);
111+
Properties connProps = new Properties();
112+
connProps.setProperty("user", "mysql-iam-user@gmail.com");
113+
connProps.setProperty("password", "password");
114+
connProps.setProperty("sslmode", "disable");
115+
connProps.setProperty("socketFactory", "com.google.cloud.sql.mariadb.SocketFactory");
116+
connProps.setProperty("cloudSqlInstance", "project:region:instance");
117+
connProps.setProperty("enableIamAuth", "true");
118+
connProps.setProperty("cloudSqlTargetPrincipal", "mysql-iam-user@gmail.com");
119+
120+
// Initialize connection pool
121+
HikariConfig config = new HikariConfig();
122+
config.setJdbcUrl(jdbcURL);
123+
config.setDataSourceProperties(connProps);
124+
config.setConnectionTimeout(10000); // 10s
125+
126+
HikariDataSource connectionPool = new HikariDataSource(config);
127+
```
128+
129+
In addition, the `cloudSqlDelegates` property controls impersonation delegation.
130+
The value is a comma-separated list of service accounts containing chained
131+
list of delegates required to grant the final access_token. If set,
132+
the sequence of identities must have "Service Account Token Creator" capability
133+
granted to the preceding identity. For example, if set to
134+
`"serviceAccountB,serviceAccountC"`, the application default credentials must
135+
have the Token Creator role on serviceAccountB. serviceAccountB must have
136+
the Token Creator on serviceAccountC. Finally, C must have Token Creator on
137+
`cloudSqlTargetPrincipal`. If unset, the application default credential principal
138+
must "Service Account Token Creator" capability granted that role on the
139+
targetPrincipal service account.
140+
141+
142+
For example:
143+
```java
144+
connProps.setProperty("cloudSqlTargetPrincipal", "TARGET_SERVICE_ACCOUNT");
145+
connProps.setProperty("cloudSqlDelegates", "SERVICE_ACCOUNT_1,SERVICE_ACCOUNT_2");
146+
```
147+
148+
In this example, the environment's application default principal impersonates
149+
SERVICE_ACCOUNT_1 which impersonates SERVICE_ACCOUNT_2 which then
150+
impersonates the TARGET_SERVICE_ACCOUNT.
151+
99152
## Examples
100153

101154
Examples for using the Cloud SQL JDBC Connector for MySQL/MariaDB can be found by looking at the integration tests in this repository.

‎docs/jdbc-mysql.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -94,6 +94,59 @@ Example:
9494
HikariDataSource connectionPool = new HikariDataSource(config);
9595
```
9696

97+
### Service Account Impersonation
98+
99+
The Java Connector supports service account impersonation with the
100+
`cloudSqlTargetPrincipal` JDBC connection property. When enabled,
101+
all API requests are made impersonating the supplied service account. The
102+
IAM principal must have the iam.serviceAccounts.getAccessToken permission or
103+
the role roles/iam.serviceAccounts.serviceAccountTokenCreator.
104+
105+
Example:
106+
```java
107+
// Set up URL parameters
108+
String jdbcURL = String.format("jdbc:mysql:///%s", DB_NAME);
109+
Properties connProps = new Properties();
110+
connProps.setProperty("user", "iam-user"); // iam-user@gmail.com
111+
connProps.setProperty("sslmode", "disable");
112+
connProps.setProperty("socketFactory", "com.google.cloud.sql.postgres.SocketFactory");
113+
connProps.setProperty("cloudSqlInstance", "project:region:instance");
114+
connProps.setProperty("enableIamAuth", "true");
115+
connProps.setProperty("cloudSqlTargetPrincipal", "iam-user@gmail.com");
116+
117+
// Initialize connection pool
118+
HikariConfig config = new HikariConfig();
119+
config.setJdbcUrl(jdbcURL);
120+
config.setDataSourceProperties(connProps);
121+
config.setConnectionTimeout(10000); // 10s
122+
123+
HikariDataSource connectionPool = new HikariDataSource(config);
124+
```
125+
126+
In addition, the `cloudSqlDelegates` property controls impersonation delegation.
127+
The value is a comma-separated list of service accounts containing chained
128+
list of delegates required to grant the final access_token. If set,
129+
the sequence of identities must have "Service Account Token Creator" capability
130+
granted to the preceding identity. For example, if set to
131+
`"serviceAccountB,serviceAccountC"`, the application default credentials must
132+
have the Token Creator role on serviceAccountB. serviceAccountB must have
133+
the Token Creator on serviceAccountC. Finally, C must have Token Creator on
134+
`cloudSqlTargetPrincipal`. If unset, the application default credential principal
135+
must "Service Account Token Creator" capability granted that role on the
136+
`cloudSqlTargetPrincipal` service account.
137+
138+
139+
For example:
140+
```java
141+
connProps.setProperty("cloudSqlTargetPrincipal", "TARGET_SERVICE_ACCOUNT");
142+
connProps.setProperty("cloudSqlDelegates", "SERVICE_ACCOUNT_1,SERVICE_ACCOUNT_2");
143+
```
144+
145+
In this example, the environment's application default principal impersonates
146+
SERVICE_ACCOUNT_1 which impersonates SERVICE_ACCOUNT_2 which then
147+
impersonates the TARGET_SERVICE_ACCOUNT.
148+
149+
97150
### Connection via Unix Sockets
98151

99152
To connect using a Unix domain socket (such as the one created by the Cloud SQL

‎docs/jdbc-postgres.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -91,6 +91,63 @@ Note: a non-empty string value for the `password` property must be set. While th
9191
be ignored when connecting with the Cloud SQL Connector using IAM auth, leaving it empty will cause
9292
driver-level validations to fail.
9393

94+
95+
### Service Account Impersonation
96+
97+
The Java Connector supports service account impersonation with the
98+
`cloudSqlTargetPrincipal` JDBC connection property. When enabled,
99+
all API requests are made impersonating the supplied service account. The
100+
IAM principal must have the iam.serviceAccounts.getAccessToken permission or
101+
the role roles/iam.serviceAccounts.serviceAccountTokenCreator.
102+
103+
Example:
104+
105+
```java
106+
// Set up URL parameters
107+
String jdbcURL = String.format("jdbc:postgresql:///%s", DB_NAME);
108+
Properties connProps = new Properties();
109+
connProps.setProperty("user", "postgres-iam-user@gmail.com");
110+
connProps.setProperty("password", "password");
111+
connProps.setProperty("sslmode", "disable");
112+
connProps.setProperty("socketFactory", "com.google.cloud.sql.postgres.SocketFactory");
113+
connProps.setProperty("cloudSqlInstance", "project:region:instance");
114+
connProps.setProperty("enableIamAuth", "true");
115+
connProps.setProperty("cloudSqlTargetPrincipal", "postgres-iam-user@gmail.com");
116+
117+
// Initialize connection pool
118+
HikariConfig config = new HikariConfig();
119+
config.setJdbcUrl(jdbcURL);
120+
config.setDataSourceProperties(connProps);
121+
config.setConnectionTimeout(10000); // 10s
122+
123+
HikariDataSource connectionPool = new HikariDataSource(config);
124+
```
125+
126+
127+
In addition, the `cloudSqlDelegates` property controls impersonation delegation.
128+
The value is a comma-separated list of service accounts containing chained
129+
list of delegates required to grant the final access_token. If set,
130+
the sequence of identities must have "Service Account Token Creator" capability
131+
granted to the preceding identity. For example, if set to
132+
`"serviceAccountB,serviceAccountC"`, the application default credentials must
133+
have the Token Creator role on serviceAccountB. serviceAccountB must have
134+
the Token Creator on serviceAccountC. Finally, C must have Token Creator on
135+
`cloudSqlTargetPrincipal`. If unset, the application default credential principal
136+
must "Service Account Token Creator" capability granted that role on the
137+
cloudSqlTargetPrincipal service account.
138+
139+
140+
For example:
141+
```java
142+
connProps.setProperty("cloudSqlTargetPrincipal", "TARGET_SERVICE_ACCOUNT");
143+
connProps.setProperty("cloudSqlDelegates", "SERVICE_ACCOUNT_1,SERVICE_ACCOUNT_2");
144+
```
145+
146+
In this example, the environment's application default principal impersonates
147+
SERVICE_ACCOUNT_1 which impersonates SERVICE_ACCOUNT_2 which then
148+
impersonates the TARGET_SERVICE_ACCOUNT.
149+
150+
94151
### Connection via Unix Sockets
95152

96153
To connect using a Unix domain socket (such as the one created by the Cloud SQL

‎docs/r2dbc-mysql.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,68 @@ Add the following parameters:
3535
| DB_USER | MySQL username |
3636
| DB_PASS | MySQL user's password |
3737

38+
## Service Account Delegation
39+
40+
41+
The Java Connector supports service account impersonation with the
42+
`TARGET_PRINCIPAL` option. When enabled, all API requests are made impersonating
43+
the supplied service account. The IAM principal must have the
44+
iam.serviceAccounts.getAccessToken permission or the role
45+
roles/iam.serviceAccounts.serviceAccountTokenCreator.
46+
47+
```java
48+
// Set up ConnectionFactoryOptions
49+
ConnectionFactoryOptions options = ConnectionFactoryOptions.builder()
50+
.option(DRIVER, "gcp")
51+
.option(PROTOCOL, "mysql")
52+
.option(PASSWORD, "password")
53+
.option(USER, "mysql-iam-user@gmail.com")
54+
.option(DATABASE, "my_db")
55+
.option(HOST, "project:region:instance")
56+
.option(ENABLE_IAM_AUTH, true)
57+
.option(TARGET_PRINCIPAL, "mysql-iam-user@gmail.com")
58+
.build();
59+
60+
// Initialize connection pool
61+
ConnectionFactory connectionFactory = ConnectionFactories.get(options);
62+
ConnectionPoolConfiguration configuration = ConnectionPoolConfiguration
63+
.builder(connectionFactory)
64+
.build();
65+
66+
this.connectionPool = new ConnectionPool(configuration);
67+
```
68+
69+
In addition, the `DELEGATES` option controls impersonation delegation.
70+
The value is a comma-separated list of service accounts containing chained
71+
list of delegates required to grant the final access_token. If set,
72+
the sequence of identities must have "Service Account Token Creator" capability
73+
granted to the preceding identity. For example, if set to
74+
`"serviceAccountB,serviceAccountC"`, the application default credentials must
75+
have the Token Creator role on serviceAccountB. serviceAccountB must have
76+
the Token Creator on serviceAccountC. Finally, C must have Token Creator on
77+
target principal. If unset, the application default credential principal
78+
must "Service Account Token Creator" capability granted that role on the
79+
target principal service account.
80+
81+
82+
For example:
83+
```java
84+
options.option(TARGET_PRINCIPAL, "TARGET_SERVICE_ACCOUNT");
85+
options.option(DELEGATES, "SERVICE_ACCOUNT_1,SERVICE_ACCOUNT_2");
86+
```
87+
88+
In this example, the environment's application default principal impersonates
89+
SERVICE_ACCOUNT_1 which impersonates SERVICE_ACCOUNT_2 which then
90+
impersonates the TARGET_SERVICE_ACCOUNT.
91+
92+
In addition, the `DELEGATES` option supports an impersonation delegation chain
93+
where the value is a comma-separated list of service accounts. The first service
94+
account in the list is the impersonation target. Each subsequent service
95+
account is a delegate to the previous service account. When delegation is
96+
used, each delegate must have the permissions named above on the service
97+
account it is delegating to.
98+
99+
38100
## Examples
39101

40102
Examples for using the Cloud SQL JDBC Connector for Postgres can be found by looking at the integration tests in this repository.

‎docs/r2dbc-postgres.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -73,6 +73,67 @@ Note: a non-empty string value for the `password` property must be set. While th
7373
be ignored when connecting with the Cloud SQL Connector using IAM auth, leaving it empty will cause
7474
driver-level validations to fail.
7575

76+
## Service Account Delegation
77+
78+
The Java Connector supports service account impersonation with the
79+
`TARGET_PRINCIPAL` option. When enabled, all API requests are made impersonating
80+
the supplied service account. The IAM principal must have the
81+
iam.serviceAccounts.getAccessToken permission or the role
82+
roles/iam.serviceAccounts.serviceAccountTokenCreator.
83+
84+
```java
85+
// Set up ConnectionFactoryOptions
86+
ConnectionFactoryOptions options = ConnectionFactoryOptions.builder()
87+
.option(DRIVER, "gcp")
88+
.option(PROTOCOL, "postgresql")
89+
.option(PASSWORD, "password")
90+
.option(USER, "postgres-iam-user@gmail.com")
91+
.option(DATABASE, "my_db")
92+
.option(HOST, "project:region:instance")
93+
.option(ENABLE_IAM_AUTH, true)
94+
.option(TARGET_PRINCIPAL, "postgres-iam-user@gmail.com,db-service-account@iam.gooogle.com")
95+
.build();
96+
97+
// Initialize connection pool
98+
ConnectionFactory connectionFactory = ConnectionFactories.get(options);
99+
ConnectionPoolConfiguration configuration = ConnectionPoolConfiguration
100+
.builder(connectionFactory)
101+
.build();
102+
103+
this.connectionPool = new ConnectionPool(configuration);
104+
```
105+
106+
In addition, the `DELEGATES` option controls impersonation delegation.
107+
The value is a comma-separated list of service accounts containing chained
108+
list of delegates required to grant the final access_token. If set,
109+
the sequence of identities must have "Service Account Token Creator" capability
110+
granted to the preceding identity. For example, if set to
111+
`"serviceAccountB,serviceAccountC"`, the application default credentials must
112+
have the Token Creator role on serviceAccountB. serviceAccountB must have
113+
the Token Creator on serviceAccountC. Finally, C must have Token Creator on
114+
target principal. If unset, the application default credential principal
115+
must "Service Account Token Creator" capability granted that role on the
116+
target principal service account.
117+
118+
119+
For example:
120+
```java
121+
options.option(TARGET_PRINCIPAL, "TARGET_SERVICE_ACCOUNT");
122+
options.option(DELEGATES, "SERVICE_ACCOUNT_1,SERVICE_ACCOUNT_2");
123+
```
124+
125+
In this example, the environment's application default principal impersonates
126+
SERVICE_ACCOUNT_1 which impersonates SERVICE_ACCOUNT_2 which then
127+
impersonates the TARGET_SERVICE_ACCOUNT.
128+
129+
In addition, the `DELEGATES` option supports an impersonation delegation chain
130+
where the value is a comma-separated list of service accounts. The first service
131+
account in the list is the impersonation target. Each subsequent service
132+
account is a delegate to the previous service account. When delegation is
133+
used, each delegate must have the permissions named above on the service
134+
account it is delegating to.
135+
136+
76137
## Examples
77138

78139
Examples for using the Cloud SQL JDBC Connector for Postgres can be found by looking at the integration tests in this repository.

‎docs/r2dbc-sqlserver.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,67 @@ Add the following parameters:
3434
| DB_USER | SQL Server username |
3535
| DB_PASS | SQL Server user's password |
3636

37+
38+
## Service Account Delegation
39+
The Java Connector supports service account impersonation with the
40+
`TARGET_PRINCIPAL` option. When enabled, all API requests are made impersonating
41+
the supplied service account. The IAM principal must have the
42+
iam.serviceAccounts.getAccessToken permission or the role
43+
roles/iam.serviceAccounts.serviceAccountTokenCreator.
44+
45+
```java
46+
// Set up ConnectionFactoryOptions
47+
ConnectionFactoryOptions options = ConnectionFactoryOptions.builder()
48+
.option(DRIVER, "gcp")
49+
.option(PROTOCOL, "mssql")
50+
.option(PASSWORD, "password")
51+
.option(USER, "my_db_user")
52+
.option(DATABASE, "my_db")
53+
.option(HOST, "project:region:instance")
54+
.option(TARGET_PRINCIPAL, "mssql-iam-user@gmail.com,db-service-account@iam.gooogle.com")
55+
.build();
56+
57+
// Initialize connection pool
58+
ConnectionFactory connectionFactory = ConnectionFactories.get(options);
59+
ConnectionPoolConfiguration configuration = ConnectionPoolConfiguration
60+
.builder(connectionFactory)
61+
.build();
62+
63+
this.connectionPool = new ConnectionPool(configuration);
64+
```
65+
66+
In addition, the `DELEGATES` option controls impersonation delegation.
67+
The value is a comma-separated list of service accounts containing chained
68+
list of delegates required to grant the final access_token. If set,
69+
the sequence of identities must have "Service Account Token Creator" capability
70+
granted to the preceding identity. For example, if set to
71+
`"serviceAccountB,serviceAccountC"`, the application default credentials must
72+
have the Token Creator role on serviceAccountB. serviceAccountB must have
73+
the Token Creator on serviceAccountC. Finally, C must have Token Creator on
74+
target principal. If unset, the application default credential principal
75+
must "Service Account Token Creator" capability granted that role on the
76+
target principal service account.
77+
78+
79+
For example:
80+
```java
81+
options.option(TARGET_PRINCIPAL, "TARGET_SERVICE_ACCOUNT");
82+
options.option(DELEGATES, "SERVICE_ACCOUNT_1,SERVICE_ACCOUNT_2");
83+
```
84+
85+
In this example, the environment's application default principal impersonates
86+
SERVICE_ACCOUNT_1 which impersonates SERVICE_ACCOUNT_2 which then
87+
impersonates the TARGET_SERVICE_ACCOUNT.
88+
89+
In addition, the `DELEGATES` option supports an impersonation delegation chain
90+
where the value is a comma-separated list of service accounts. The first service
91+
account in the list is the impersonation target. Each subsequent service
92+
account is a delegate to the previous service account. When delegation is
93+
used, each delegate must have the permissions named above on the service
94+
account it is delegating to.
95+
96+
97+
3798
## Examples
3899

39100
Examples for using the Cloud SQL JDBC Connector for Postgres can be found by looking at the integration tests in this repository.

0 commit comments

Comments
 (0)