iterate-ch · dkocher · Sep 9, 2025 · Sep 9, 2025 · Sep 9, 2025 · Sep 9, 2025
diff --git a/protocols/profiles/aws_oidc.md b/protocols/profiles/aws_oidc.md
@@ -12,6 +12,12 @@ Connection [profiles](index.md#technical-file-format-specification) must include
 
 ## Prerequisites
 
+:::{admonition} Tutorial
+:class: tip
+
+Follow the [step-by-step instructions](../../tutorials/s3_microsoft_entra_oidc.md) to configure Microsoft Entra ID (formerly Azure AD) as a custom OIDC (OpenID Connect) identity provider (IdP) for S3.
+:::
+
 - 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.

diff --git a/protocols/s3/index.md b/protocols/s3/index.md
@@ -194,6 +194,12 @@ with the identity provider in _Identity and Access Management (IAM)_.
 - {download}`Download<https://profiles.cyberduck.io/AWS%20S3%2BSTS%20%26%20Azure%20Active%20Directory%20%28Azure%20AD%29%20OpenID%20Connect.cyberduckprofile>`
   the *AWS S3+STS &amp; Azure Active Directory (Azure AD) profile* for preconfigured settings
 
+:::{admonition} Tutorial
+:class: tip
+
+Follow the [step-by-step instructions](../../tutorials/s3_microsoft_entra_oidc.md) to configure Microsoft Entra ID as an OpenID Connect (OIDC) Identity Provider in AWS IAM and authenticate with S3.
+:::
+
 ##### S3 with Google OpenID Connect
 
 - {download}`Download<https://profiles.cyberduck.io/AWS%20S3%2BSTS%20%26%20Google%20OpenID%20Connect.cyberduckprofile>`

diff --git a/tutorials/_images/S3_Client_Id_Prompt.png b/tutorials/_images/S3_Client_Id_Prompt.png
diff --git a/tutorials/_images/S3_Role_ARN_Prompt.png b/tutorials/_images/S3_Role_ARN_Prompt.png
diff --git a/tutorials/index.md b/tutorials/index.md
@@ -6,6 +6,7 @@ Tutorials
 :titlesonly:
 hidden_properties
 custom_oauth_client_id
+s3_microsoft_entra_oidc
 iam
 vault_localdisk
 sftp_publickeyauth
@@ -23,6 +24,9 @@ Workaround to register your own Custom OAuth 2.0 Client ID for [Google Cloud Sto
 ## [Add Hidden Configuration Options to Mountain Duck and Cyberduck](hidden_properties.md)
 Configure hidden preferences.
 
+## [Authenticate with Microsoft Entra ID to connect to S3](s3_microsoft_entra_oidc.md)
+Use Microsoft Entra ID to authenticate with S3 by configuring as an OpenID Connect (OIDC) Identity Provider in AWS IAM.
+
 ## [AWS Identity & Access Management (IAM)](iam.md)
 IAM allows you to create credentials for third parties accessing your S3 account with permission constraints.
 

diff --git a/tutorials/s3_microsoft_entra_oidc.md b/tutorials/s3_microsoft_entra_oidc.md
@@ -0,0 +1,108 @@
+Connect to S3 authenticating with Microsoft Entra ID
+====
+
+> Use Microsoft Entra ID to authenticate with S3 by configuring as an OpenID Connect (OIDC) Identity Provider in AWS IAM.
+
+
+:::{tip}
+Refer to [Custom connection profile using OpenID Connect provider and AssumeRoleWithWebIdentity STS API](../protocols/profiles/aws_oidc.md) for custom configuration of connection profiles using OIDC web identity federation to connect to AWS S3.
+:::
+
+## Configuration in Microsoft Entra ID
+
+Create an application in the [Microsoft Entra ID portal](https://portal.microsoftonline.com/applications) and configure it as an OIDC Identity Provider.
+
+1. Navigate to _Identity → Applications → App registrations_ in the [Microsoft Entra ID portal](https://portal.microsoftonline.com/applications) and choose _New registration_.
+2. In _Authentication_, add a redirect URI with the value `x-cyberduck-action://oauth` to allow authentication with Cyberduck.
+3. In _Authentication_, add a redirect URI with the value `x-mountainduck-action://oauth` to allow authentication with Mountain Duck.
+4. Copy the OAuth Client ID from _Overview → Essentials → Application (client) ID_.
+
+
+## Configuration in AWS IAM
+
+### Create an OIDC identity provider
+1. In AWS [IAM console](https://console.aws.amazon.com/iam/) add a new identity provider in _Identity providers_.
+2. Configure the provider as type _OpenID Connect_ with the provider URL set to `https://login.microsoftonline.com/<TENANT-ID>/v2.0`. Replace <TENANT-ID> with your Microsoft Entra ID tenant ID. Copy the ARN for the next [step](#create-a-role).
+
+### Create a role
+
+Assign a role to the identity provider created in the previous step with permissions to access S3.
+
+1. In AWS [IAM console](https://console.aws.amazon.com/iam/) add a new role.
+2. Choose _Amazon S3_ as the service to use.
+3. Choose _Assign role_ followed by _Create a new role_ with a _Web identity_ trusted entity type. It should have _Identity provider_ and _Audience_ options prefilled with the ARN of the identity provider and Client ID from Microsoft Entra.
+4. The resulting trust policy will look similar to the following:
+
+    ```json
+   {
+    "Version": "2012-10-17",
+    "Statement": [
+        {
+            "Effect": "Allow",
+            "Principal": {
+                "Federated": "arn:aws:iam::<ACCOUNT_ID>:oidc-provider/login.microsoftonline.com/<TENANT-ID>/v2.0"
+            },
+            "Action": "sts:AssumeRoleWithWebIdentity",
+            "Condition": {
+                "StringEquals": {
+                    "login.microsoftonline.com/<TENANT-ID>/v2.0:aud": "<Application (client) ID>"
+                }
+            }
+        }
+    ]
+   }
+    ```
+
+    :::{tip}
+    The `<ACCOUNT_ID>` is replaced with your AWS account ID and `<Application (client) ID>` with the OAuth Client ID of the application you created in the previous [step](#configuration-in-microsoft-entra-id). For `Federated`, the ARN of the identity provider you created in the previous step is set. For the condition `aud` use the application client ID of the application you created in the previous step.
+    :::
+
+5. In the next step attach a permission policy to the role such as the managed policy `AmazonS3FullAccess`.
+6. Copy the Role ARN from the _Summary_ tab.
+
+
+### Create a bookmark in Cyberduck or Mountain Duck
+
+1. Open _Preferences… → Profiles_ in Cyberduck or Mountain Duck.
+2. Enable the *AWS S3 (Microsoft Entra)* connection profile.
+3. Add a new [Bookmark](../cyberduck/bookmarks.md) in Cyberduck or Mountain Duck and choose *AWS S3 (Microsoft Entra)* in the protocol dropdown.
+4. Enter the Application (client) ID from the application registration in Microsoft Entra for _OAuth Client ID_ when prompted. It will be saved in the bookmark as a [custom property](hidden_properties.md#in-duck-bookmark-files).
+
+   :::{image} _images/S3_Client_Id_Prompt.png
+   :alt: OAuth Client ID Prompt
+   :width: 400px
+   :::
+
+   :::{tip}
+   The _OAuth Client ID_ is the same as the _Application (client) ID_ from the application registration in Microsoft Entra.
+   :::
+
+   :::{note}
+   Alternatively set `OAuth Client ID` in a [custom connection profile](../protocols/profiles/aws_oidc.md).
+   :::
+
+5. Enter the Role ARN from the previous step when prompted. It will be saved in the bookmark as a [custom property](hidden_properties.md#in-duck-bookmark-files).
+
+   :::{note}
+   Alternatively set `role_arn` as a custom property in a [custom connection profile](../protocols/profiles/aws_oidc.md).
+   :::
+
+   :::{image} _images/S3_Role_ARN_Prompt.png
+   :alt: MFA Prompt
+   :width: 400px
+   :::
+
+:::{admonition} Troubleshooting
+:class: attention
+### `Not authorized to perform sts:AssumeRoleWithWebIdentity`
+Validate the _Trusted entities_ in _Trust relationships_ in the IAM console.
+
+### `Request ARN is invalid`
+The role ARN entered is not valid.
+
+### `The security token included in the request is invalid`
+Invalid client token ID. Check the OAuth Client ID in the connection profile.
+:::
+
+## References
+- [AWS Identity and Access Management → OIDC federation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_oidc.html)