Skip to content

Documentation for AWS Authentication #131

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
justing-bq merged 6 commits into from
Apr 6, 2023
Merged

Documentation for AWS Authentication #131

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
6e5e51f
Documentation for AWS Authentication
Apr 5, 2023
2b51a9c
Move image file to correct location
Apr 5, 2023
bd6a613
Fix formatting
Apr 5, 2023
c5784f9
Fix formatting
Apr 5, 2023
1e4b866
Update sample_sm_dsn.png
Apr 5, 2023
070354d
Update description of AWS_REGION
Apr 5, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 6 additions & 1 deletion docs/Documentation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,10 +23,15 @@
- [Sample Code](./using-the-aws-driver/UsingTheAwsDriver.md#sample-code)
- [08007 - Connection Failure During Transaction](./using-the-aws-driver/UsingTheAwsDriver.md#08007---connection-failure-during-transaction)
- [Sample Code](./using-the-aws-driver/UsingTheAwsDriver.md#sample-code-1)
- [AWS Authentication](./using-the-aws-driver/UsingTheAwsDriver.md#aws-authentication)
- [IAM Authentication](./using-the-aws-driver/UsingTheAwsDriver.md#iam-authentication)
- [How to use IAM](./using-the-aws-driver/UsingTheAwsDriver.md#how-to-use-iam)
- [Secrets Manager Authentication](./using-the-aws-driver/UsingTheAwsDriver.md#secrets-manager-authentication)
- [How to use Secrets Manager](./using-the-aws-driver/UsingTheAwsDriver.md#how-to-use-secrets-manager)
- [Logging](./using-the-aws-driver/UsingTheAwsDriver.md#logging)
- [Enabling Logs On Windows](./using-the-aws-driver/UsingTheAwsDriver.md#enabling-logs-on-windows)
- [Example](./using-the-aws-driver/UsingTheAwsDriver.md#example)
- [Enabling Logs On MacOS and Linux](./using-the-aws-driver/UsingTheAwsDriver.md#enabling-logs-on-macos-and-linux)
- [Enabling Logs On MacOS and Linux](./using-the-aws-driver/UsingTheAwsDriver.md#enabling-logs-on-macos-and-linux)
- [Host Monitoring](./using-the-aws-driver/HostMonitoring.md)
- [Building the AWS ODBC Driver for MySQL](./building-the-aws-driver/BuildingTheAwsDriver.md)
- [Windows](./building-the-aws-driver/BuildingTheAwsDriver.md#windows)
Expand Down
0 ...the-aws-driver/enable-logging-windows.jpg → docs/images/enable-logging-windows.jpg
View file
Open in desktop
File renamed without changes
Binary file added docs/images/sample_iam_dsn.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/sample_sm_dsn.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
53 changes: 52 additions & 1 deletion docs/using-the-aws-driver/UsingTheAwsDriver.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -287,6 +287,57 @@ int main() {
}
```

## AWS Authentication

### IAM Authentication

AWS Identity and Access Management (IAM) grants users access control across all Amazon Web Services. IAM supports granular permissions, giving you the ability to grant different permissions to different users. For more information on IAM and it's use cases, please refer to the [IAM documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html).

The AWS ODBC Driver for MySQL supports Amazon AWS Identity and Access Management (IAM) authentication. When using AWS IAM database authentication, the host URL must be a valid Amazon endpoint, and not a custom domain or an IP address.
<br>ie. `db-identifier.cluster-XYZ.us-east-2.rds.amazonaws.com`

IAM database authentication use is limited to certain database engines. For more information on limitations and recommendations, please [review the IAM documentation](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.html).

#### How to use IAM?
1. Enable AWS IAM database authentication on an existing database or create a new database with AWS IAM database authentication on the AWS RDS Console:
1. If needed, review the documentation about [creating a new database](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_CreateDBInstance.html).
2. If needed, review the documentation about [modifying an existing database](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Overview.DBInstance.Modifying.html).
2. Set up an [AWS IAM policy](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.IAMPolicy.html) for AWS IAM database authentication.
3. [Create a database account](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.DBAccounts.html) using AWS IAM database authentication:
Use the following commands to create a new IAM user:<br>
`CREATE USER example_user_name IDENTIFIED WITH AWSAuthenticationPlugin AS 'RDS';`
`GRANT ALL PRIVILEGES ON example_database.* TO 'example_user_name'@'%';`
Copy link
Contributor

@yanw-bq yanw-bq Apr 5, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this necessary? I don't see it in JDBC doc https://github.com/awslabs/aws-advanced-jdbc-wrapper/blob/main/docs/using-the-jdbc-driver/using-plugins/UsingTheIamAuthenticationPlugin.md

Copy link
Contributor Author

@justing-bq justing-bq Apr 5, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are you talking specifically about the GRANT ALL PRIVILEGES command?
It may not be in that particular document but it is on our BQ confluence page and it is also in the JDBC wrapper's addAuroraAwsIamUser() logic.

Copy link
Contributor Author

@justing-bq justing-bq Apr 5, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Question for @karenc-bq.
Is the GRANT ALL PRIVILEGES command necessary for MySQL?

4. Connect to a MySQL database with the following connection parameters configured in a DSN or connection string. (Note these are in addition to the parameters that you can configure for the [MySQL Connector/ODBC driver](https://dev.mysql.com/doc/connector-odbc/en/connector-odbc-configuration-connection-parameters.html))

| Option | Description | Type | Required | Default |
| ---------------------------------- |------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------|----------|------------------------------------------|
| `AUTHENTICATION_MODE` | Set to `IAM` to enable IAM Authentication. | char* | No | Off |
| `AWS_REGION` | Region used to generate IAM tokens. | char* | No | `us-east-1`
| `IAM_HOST` | Host URL for IAM authentication. URL must be a valid Amazon endpoint, and not a custom domain or an IP address. | char* | No | Empty |
| `IAM_PORT` | Port used for IAM authentication. | int | No | `3306` |
| `IAM_EXPIRATION_TIME` | Amount of time in seconds before the generated IAM token expires. After expiration, future connections will require a new token to be generated. | int | No | `900`

If you are working with the Windows DSN UI, click `Details >>` and navigate to the `AWS Authentication` tab to configure the parameters.

![sample_iam_dsn](../images/sample_iam_dsn.png)

### Secrets Manager Authentication

The AWS ODBC Driver for MySQL supports usage of database credentials stored as secrets in the [AWS Secrets Manager](https://aws.amazon.com/secrets-manager/). When you connect using Secrets Manager authentication, the driver will retrieve the secret and the connection will be created with the credentials inside that secret.

#### How to use Secrets Manager
The following parameters are required for the AWS Secrets Manager Connection Plugin to retrieve database credentials from the AWS Secrets Manager.

| Option | Description | Type | Required | Default |
| ---------------------------------- |------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------|----------|------------------------------------------|
| `AUTHENTICATION_MODE` | Set to `SECRETS MANAGER` to enable Secrets Manager Authentication. | char* | No | Off |
| `AWS_REGION` | Region of the secret. | char* | No | `us-east-1`
| `SECRET_ID` | Secret name or secret ARN. | char* | No | Empty

If you are working with the Windows DSN UI, click `Details >>` and navigate to the `AWS Authentication` tab to configure the parameters.

![sample_sm_dsn](../images/sample_sm_dsn.png)

## Logging

### Enabling Logs On Windows
Expand All @@ -301,7 +352,7 @@ When connecting the AWS ODBC Driver for MySQL using a Windows system, ensure log

#### Example

![enable-logging-windows](./enable-logging-windows.jpg)
![enable-logging-windows](../images/enable-logging-windows.jpg)

The resulting log file, named `myodbc.log`, can be found under `%temp%`.

Expand Down