{"id":13878853,"url":"https://github.com/haines/pg-aws_rds_iam","last_synced_at":"2025-04-13T00:40:32.053Z","repository":{"id":37836710,"uuid":"226742262","full_name":"haines/pg-aws_rds_iam","owner":"haines","description":"IAM authentication in Ruby for PostgreSQL on Amazon RDS","archived":false,"fork":false,"pushed_at":"2024-10-29T22:28:22.000Z","size":1020,"stargazers_count":62,"open_issues_count":2,"forks_count":5,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-10-30T05:57:43.432Z","etag":null,"topics":["aws","iam","postgresql","rds","ruby"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/haines.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-12-08T22:38:59.000Z","updated_at":"2024-10-29T22:28:26.000Z","dependencies_parsed_at":"2023-10-17T11:41:28.763Z","dependency_job_id":"c13f94fd-122d-4ee7-8ff7-24b4d8db2bb5","html_url":"https://github.com/haines/pg-aws_rds_iam","commit_stats":{"total_commits":662,"total_committers":3,"mean_commits":"220.66666666666666","dds":0.4259818731117825,"last_synced_commit":"5c12db3ceaeaafb3f4bba343cad266b216bded6a"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haines%2Fpg-aws_rds_iam","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haines%2Fpg-aws_rds_iam/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haines%2Fpg-aws_rds_iam/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haines%2Fpg-aws_rds_iam/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/haines","download_url":"https://codeload.github.com/haines/pg-aws_rds_iam/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248650414,"owners_count":21139671,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","iam","postgresql","rds","ruby"],"created_at":"2024-08-06T08:02:02.056Z","updated_at":"2025-04-13T00:40:32.026Z","avatar_url":"https://github.com/haines.png","language":"Ruby","funding_links":[],"categories":["Ruby"],"sub_categories":[],"readme":"# PG::AWS_RDS_IAM\n\n[![Gem](https://img.shields.io/gem/v/pg-aws_rds_iam?style=flat-square)](https://rubygems.org/gems/pg-aws_rds_iam)\n\u0026ensp;\n[![Docs](https://img.shields.io/badge/yard-docs-blue?style=flat-square)](https://www.rubydoc.info/gems/pg-aws_rds_iam)\n\n`PG::AWS_RDS_IAM` is a plugin for the [`pg` gem](https://rubygems.org/gems/pg) that adds support for [IAM authentication](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.html) when connecting to PostgreSQL databases hosted in Amazon RDS.\n\nIAM authentication allows your application to connect to the database using secure, short-lived authentication tokens instead of a fixed password.\nThis gives you greater security and eliminates the operational overhead of rotating passwords.\n\n## Installation\n\nInstall manually:\n\n```console\n$ gem install pg-aws_rds_iam\n```\n\nor with Bundler:\n\n```console\n$ bundle add pg-aws_rds_iam\n```\n\n## Usage\n\nTo use IAM authentication for your database connections, you need to\n\n1. enable IAM authentication for your database,\n2. provide your application with IAM credentials, and\n3. configure your application to generate authentication tokens.\n\n### 1. Enable IAM authentication for your database\n\nStart by configuring your database to allow IAM authentication using either the [AWS console](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.Enabling.html#UsingWithRDS.IAMDBAuth.Enabling.Console) or the [`aws` CLI](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.Enabling.html#UsingWithRDS.IAMDBAuth.Enabling.CLI).\nThis doesn't require downtime so is safe to apply immediately, unless you already have pending modifications that require a database reboot.\n\nNext, [grant your database user the `rds_iam` role](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.DBAccounts.html#UsingWithRDS.IAMDBAuth.DBAccounts.PostgreSQL).\n\n### 2. Provide your application with IAM credentials\n\nThe most secure way to grant your application permission to connect to your database is to use an IAM role.\n\nStart by [creating a service role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html) if your application doesn't already have one.\nThen, create an [IAM policy granting the `rds-db:connect` permission](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.IAMPolicy.html) and attach it to the role.\n\nIf you've created a new service role, you'll need to associate it with your application.\nThe way to do this depends on where you are running your application:\n\n* for EC2 instances, [set up an instance profile](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2.html);\n* for EKS pods, [associate the IAM role with a Kubernetes service account](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html);\n* for ECS tasks, [configure a task role](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html); or\n* for Lambda functions, [set the execution role](https://docs.aws.amazon.com/lambda/latest/dg/lambda-intro-execution-role.html).\n\nIf you can't use a service role, then you can grant the permissions to an IAM user instead and supply the application with their access key through a [configuration profile](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-profiles.html) or via the `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` environment variables.\nHowever, you won't get the full security and operational benefits of RDS IAM authentication, because the access key is a long-lived secret that you need to supply to the application securely and rotate periodically.\n\n### 3. Configure your application to generate authentication tokens\n\nYou can use `PG::AWS_RDS_IAM`'s default authentication token generator if you are using a service role as described above, or if you configure your application using the standard AWS ways to provide [credentials](https://docs.aws.amazon.com/sdk-for-ruby/v3/developer-guide/setup-config.html#aws-ruby-sdk-setting-credentials) and [region](https://docs.aws.amazon.com/sdk-for-ruby/v3/developer-guide/setup-config.html#aws-ruby-sdk-setting-region).\n\nTo use the default authentication token generator, set the `aws_rds_iam_auth_token_generator` connection parameter to `default`.\nYou can set this parameter in\n\n* the query string of a connection URI:\n\n  ```\n  postgresql://andrew@postgresql.example.com:5432/blog?aws_rds_iam_auth_token_generator=default\n  ```\n\n* a `key=value` pair in a connection string:\n\n  ```\n  user=andrew host=postgresql.example.com port=5432 dbname=blog aws_rds_iam_auth_token_generator=default\n  ```\n\n* a `key: value` pair in a connection hash:\n\n  ```ruby\n  PG.connect(\n    user: \"andrew\",\n    host: \"postgresql.example.com\",\n    port: 5432,\n    dbname: \"blog\",\n    aws_rds_iam_auth_token_generator: \"default\"\n  )\n  ```\n\n* `database.yml`, if you're using Rails:\n\n  ```yaml\n  production:\n    adapter: postgresql\n    username: andrew\n    host: postgresql.example.com\n    port: 5432\n    database: blog\n    aws_rds_iam_auth_token_generator: default\n  ```\n\nIf the default authentication token generator doesn't meet your needs, you can register an alternative with\n\n```ruby\nPG::AWS_RDS_IAM.auth_token_generators.add :custom do\n  PG::AWS_RDS_IAM::AuthTokenGenerator.new(credentials: \"...\", region: \"...\")\nend\n```\n\nTo use this alternative authentication token generator, set the `aws_rds_iam_auth_token_generator` connection parameter to the name you registered it with (`custom`, in this example).\n\nThe block you give to `add` must construct and return the authentication token generator, which can either be an instance of `PG::AWS_RDS_IAM::AuthTokenGenerator` or another object that returns a string token in response to `call(host:, port:, user:)`.\nThe block will be called once, when the first token is generated, and the returned authentication token generator will be re-used to generate all future tokens.\n\n## Development\n\nAfter checking out the repo, run `bin/setup` to install dependencies.\nThen, run `bin/rake` to run the tests.\nYou can also run `bin/console` for an interactive prompt that will allow you to experiment.\n\nTo install this gem onto your local machine, run `bin/rake install`.\nTo release a new version, update the version number in `version.rb`, and then run `bin/rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).\n\n## Contributing\n\nBug reports and pull requests are welcome [on GitHub](https://github.com/haines/pg-aws_rds_iam).\nThis project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/haines/pg-aws_rds_iam/blob/main/CODE_OF_CONDUCT.md).\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhaines%2Fpg-aws_rds_iam","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhaines%2Fpg-aws_rds_iam","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhaines%2Fpg-aws_rds_iam/lists"}