diff --git a/protocols/profiles/aws_oidc.md b/protocols/profiles/aws_oidc.md new file mode 100644 index 00000000..df9720d1 --- /dev/null +++ b/protocols/profiles/aws_oidc.md @@ -0,0 +1,66 @@ +Custom connection profile using OpenID Connect provider and AssumeRoleWithWebIdentity STS API +==== + +> With web identity federation, you don't need to create custom sign-in code or manage your own user identities. Instead, users of your app can sign in using a well-known external identity provider (IdP), such as Login with Amazon, Facebook, Google, or any other OpenID Connect (OIDC)-compatible IdP. They can receive an authentication token, and then exchange that token for temporary security credentials in AWS that map to an IAM role with permissions to use the resources in your AWS account. + +```{important} +* Cyberduck [8.7.0](https://cyberduck.io/changelog/) or later required +* Mountain Duck [4.15.0](https://mountainduck.io/changelog/) or later required +``` + +Connection profiles must include the `OAuth Authorization Url`, `OAuth Token Url`, `OAuth Redirect Url` and `Scopes` of the OpenID Connect (OIDC) identity provider and the `STS Endpoint` for the STS API endpoint which defaults to `https://sts.amazonaws.com/`. Set the property `s3.assumerole.rolearn` in the connection profile to the Role ARN configured in AWS. Set it to `s3.assumerole.rolearn=` for a prompt to enter on login. + +## Prerequisites + +- Register the OAuth Client ID with your identity provider (IdP) +- Configure the OIDC provider in AWS IAM or compatible implementation like [MinIO Security Token Service (STS)](https://min.io/docs/minio/linux/developers/security-token-service.html) +- Make sure to restrict access by configuring the role and trust policy using rules referencing the claims available in the JWT token from the identity provider that is passed to `AssumeRoleWithWebIdentity` STS API. + +## Blueprint + +```xml + + + + Protocol + s3 + Vendor + s3-sts + OAuth Authorization Url + … + OAuth Token Url + … + OAuth Client ID + … + OAuth Client Secret + … + OAuth Redirect Url + x-cyberduck-action:oauth + OAuth PKCE + + Scopes + + openid + offline_access + + Password Configurable + + Username Configurable + + Token Configurable + + Username Placeholder + Username + STS Endpoint + https://sts.amazonaws.com/ + Properties + + s3.assumerole.rolearn=arn:aws:iam::… + + + +``` + +### References + +- [About web identity federation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_oidc.html) \ No newline at end of file diff --git a/protocols/profiles/index.md b/protocols/profiles/index.md index 013408c4..ea632034 100644 --- a/protocols/profiles/index.md +++ b/protocols/profiles/index.md @@ -5,6 +5,7 @@ Connection Profiles :hidden: :titlesonly: google_client_id +aws_oidc ``` ```{contents} Content @@ -165,4 +166,13 @@ Create a *multi-TIFF* containing the needed icon sizes: /usr/bin/sips -s format png -z 128 128 -s dpiHeight 72.0 -s dpiWidth 72.0 ${png} --out ${tmp}/icon_256.png /usr/bin/tiffutil -cathidpicheck ${tmp}/icon_64x64@2x.png ${tmp}/icon_64x64.png ${tmp}/icon_96.png ${tmp}/icon_96@2x.png ${tmp}/icon_256.png ${tmp}/icon_256@2x.png -out ${target}/disk.tiff ``` -3. Use the command ``` base64 ./disk.tiff -b 70 ``` to generate the base64 version of the multi-TIFF file. This final version will be used for the connection profile. \ No newline at end of file +3. Use the command ``` base64 ./disk.tiff -b 70 ``` to generate the base64 version of the multi-TIFF file. This final version will be used for the connection profile. + +## Sample Connection Profiles + +### Google Custom OAuth Client ID +- [Custom OAuth 2.0 Client ID for Google Cloud Storage and Google Drive](google_client_id.md). + +### S3 and OpenID Connect Federation +Customization of connection profiles using OpenID Connect provider and AssumeRoleWithWebIdentity STS API +- [Sample connection profiles for S3 and OpenID Connect Federation](aws_oidc.md) diff --git a/protocols/s3/index.md b/protocols/s3/index.md index 622a193f..48b4d854 100644 --- a/protocols/s3/index.md +++ b/protocols/s3/index.md @@ -136,6 +136,40 @@ Connecting to a bucket owned by you or even a third party is possible without re No regional endpoint should be set while connecting to a single bucket. The endpoint will be determined automatically by querying the region of the bucket. ``` +### Connecting with OpenID Connect (OIDC) identity provider + +```{important} +* Cyberduck [8.7.0](https://cyberduck.io/changelog/) or later required +* Mountain Duck [4.15.0](https://mountainduck.io/changelog/) or later required +``` + +Connecting to AWS S3 with web identity federation using AWS Security Token Service (STS) is supported with connection profiles specifying configuration properties specific to your identity provider (IdP). + +```{attention} +The usage of these connection profiles requires the [configuration](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html) of an OpenID Connect (OIDC) identity provider and role and trust policy in AWS IAM. +``` + +The connection profiles connect using temporary security credentials from the AWS Security Token Service (STS) obtained using a web identity token from your OpenID Connect (OIDC) identity provider. Refer to [Custom connection profile using OpenID Connect provider and AssumeRoleWithWebIdentity STS API](../profiles/aws_oidc.md). + +```{admonition} Interoperability +`AssumeRoleWithWebIdentity` API from AWS Security Token Service (STS) is used to exchange the JSON Web Token with temporary security credentials. In addition to AWS, the following combinations of S3 & STS APIs with OpenID Connect (OIDC) have been tested: +- Connect to Minio S3 authenticating with [Minio STS](https://min.io/docs/minio/linux/developers/security-token-service.html) and Keycloak (OIDC) +- Connect to AWS S3 authenticating with AWS STS and Keycloak (OIDC) +``` + +#### Sample connection profiles for authorization with well known identity providers + +```{note} +When connecting the user is requested to enter the Role ARN of the IAM role that has a trust relationship configured with the identity provider in _Identity and Access Management (IAM)_. +``` + +##### S3 with Azure Active Directory (Azure AD) + +- {download}`Download` the *AWS S3+STS & Azure Active Directory (Azure AD) profile* for preconfigured settings + +##### S3 with Google OpenID Connect +- {download}`Download` the *AWS S3+STS & Google OpenID Connect profile* for preconfigured settings + ### Connecting with Temporary Access Credentials (Token) from EC2 If you are running Cyberduck for Windows or [Cyberduck CLI](https://duck.sh/) on EC2 and have setup [IAM Roles for Amazon EC2](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html) to provide access to S3 from the EC2 instance, you can use the connection profile below that will fetch temporary credentials from EC2 instance metadata service at `http://169.254.169.254/latest/meta-data/iam/security-credentials/s3access` to authenticate. Edit the profile to change the role name `s3access` to match your IAM configuration. @@ -169,14 +203,12 @@ You can also do this for a specific profile by adding `--profile myProfile` to t - [Configuring the AWS CLI to use AWS Single Sign-On](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sso.html) -### Connecting Using AssumeRole from AWS Security Token Service (STS) +#### Connecting Using AssumeRole from AWS Security Token Service (STS) Instead of providing Access Key ID and Secret Access Key, authenticate using temporary credentials from AWS Security Token Service (STS) with optional Multi-Factor Authentication (MFA). Refer to U[sing IAM Roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html). ![MFA Token Prompt](_images/MFA_Token_Prompt.png) -- {download}`Download` the *S3 (Credentials from AWS Security Token Service) profile* for preconfigured settings. - You must provide configuration in the standard credentials property file `~/.aws/credentials` on macOS or `%USERPROFILE%\.aws\credentials` on Windows from [AWS Command Line Interface](https://docs.aws.amazon.com/cli/latest/userguide/cli-multiple-profiles.html). Configure a bookmark with the field titled *Profile Name in `~/.aws/credentials`* matching the profile name from `~/.aws/credentials` on macOS or `%USERPROFILE%\.aws\credentials` on Windows with the `role_arn` configuration. #### Example Configuration