Federated Authentication Plugin

The Federated Authentication Plugin adds support for authentication via Federated Identity and then database access via IAM. Currently, only Microsoft Active Directory Federation Services (AD FS) is supported.

What is Federated Identity

Federated Identity allows users to use the same set of credentials to access multiple services or resources across different organizations. This works by having Identity Providers (IdP) that manage and authenticate user credentials, and Service Providers (SP) that are services or resources that can be internal, external, and/or belonging to various organizations. Multiple Service Providers can establish trust relationships with a single IdP.

When a user wants access to a resource, it authenticates with the IdP. From this a security token generated and is passed to the SP then grants access to said resource. In the case of AD FS, the user signs into the AD FS sign in page. This generates a SAML Assertion which acts as a security token. The user then passes the SAML Assertion to the SP when requesting access to resources. The SP verifies the SAML Assertion and grants access to the user.

Prerequisites

• This plugin does not create or modify any ADFS or IAM resources, therefore all permissions and policies must be correctly configured before using this plugin. If you plan on using Amazon Aurora Global Databases with this plugin, please see the Using Federated Authentication with Global Databases section as well.

How to use the Federated Authentication Plugin with the AWS Advanced Python Wrapper

Enabling the Federated Authentication Plugin

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:
   • If needed, review the documentation about IAM authentication for MariaDB, MySQL, and PostgreSQL.
2. Set up an IAM Identity Provider and IAM role. The IAM role should be using the IAM policy set up in step 1.
   • If needed, review the documentation about creating IAM identity providers. For AD FS, see the documentation about creating IAM SAML identity providers.
3. Add the plugin code federated_auth to the plugins value, or to the current driver profile.
4. Specify parameters that are required or specific to your case.

Federated Authentication Plugin Parameters

Parameter	Value	Required	Description	Default Value	Example Value
db_user	String	Yes	The user name of the IAM user with access to your database. If you have previously used the IAM Authentication Plugin, this would be the same IAM user. For information on how to connect to your Aurora Database with IAM, see this documentation.	None	some_user_name
idp_username	String	Yes	The user name for the idp_endpoint server. If this parameter is not specified, the plugin will fallback to using the user parameter.	None	jimbob@example.com
idp_password	String	Yes	The password associated with the idp_endpoint username. If this parameter is not specified, the plugin will fallback to using the password parameter.	None	some_random_password
idp_endpoint	String	Yes	The hosting URL for the service that you are using to authenticate into AWS Aurora.	None	ec2amaz-ab3cdef.example.com
iam_role_arn	String	Yes	The ARN of the IAM Role that is to be assumed to access AWS Aurora.	None	arn:aws:iam::123456789012:role/adfs_example_iam_role
iam_idp_arn	String	Yes	The ARN of the Identity Provider.	None	arn:aws:iam::123456789012:saml-provider/adfs_example
iam_region	String	Yes	The IAM region where the IAM token is generated.	None	us-east-2
idp_name	String	No	The name of the Identity Provider implementation used.	adfs	adfs
idp_port	Integer	No	The port that the host for the authentication service listens at.	443	1234
rp_identifier	String	No	The relaying party identifier.	urn:amazon:webservices	urn:amazon:webservices
iam_host	String	No	Overrides the host that is used to generate the IAM token.	None	database.cluster-hash.us-east-1.rds.amazonaws.com
iam_default_port	String	No	This property overrides the default port that is used to generate the IAM token. The default port is determined based on the underlying driver protocol. For now, there is support for PostgreSQL and MySQL. Target drivers with different protocols will require users to provide a default port.	None	1234
iam_token_expiration	Integer	No	Overrides the default IAM token cache expiration in seconds	870	123
http_request_connect_timeout	Integer	No	The timeout value in seconds to send the HTTP request data used by the FederatedAuthPlugin.	60	60
ssl_secure	Boolean	No	Whether the SSL session is to be secure and the server's certificates will be verified	True	False

Sample code

MySQLFederatedAuthentication.py PGFederatedAuthentication.py

Using Federated Authentication with Global Databases

When using Federated authentication with Amazon Aurora Global Databases, the IAM user or role requires the additional rds:DescribeGlobalClusters permission. This permission allows the wrapper to resolve the Global Database endpoint to the appropriate regional cluster for IAM token generation.

Example IAM policy:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "rds-db:connect",
                "rds:DescribeGlobalClusters"
            ],
            "Resource": "*"
        }
    ]
}