saml updates

content/en/docs/Access_Management/_index.md

@@ -2,7 +2,6 @@
 linktitle: Identity and Access Management (IAM)
 title: Identity and Access Management (IAM)
 Description: Manage the permissions for accessing PlaidCloud
-weight: 5.0
 ---
 
 Identity and Access Management

content/en/docs/Access_Management/advanced/auth0-saml-setup.md

@@ -0,0 +1,136 @@
+---
+title: Setting Up Auth0 SAML for Single Sign-On
+slug: auth0-saml-setup
+description: Configure Auth0 as a SAML identity provider for PlaidCloud Single Sign-On
+date: 2024-01-01T00:00:00
+tags:
+- plaidcloud
+- sso
+- saml
+- auth0
+categories:
+- PlaidCloud
+- Access Management
+---
+
+PlaidCloud supports Single Sign-On (SSO) via SAML 2.0. This guide walks through configuring Auth0 as a SAML identity provider so your organization's users can authenticate through Auth0 when accessing PlaidCloud.
+
+{{< note >}}
+The PlaidCloud-side configuration is handled by the PlaidCloud team. Your responsibility is to set up the SAML application in Auth0 and provide PlaidCloud with your **Identity Provider Metadata URL**. PlaidCloud support will complete the remaining configuration.
+{{< /note >}}
+
+## Prerequisites
+
+- An Auth0 tenant
+- An Auth0 account with the **Administrator** role
+- Contact with PlaidCloud support to coordinate the setup and exchange configuration values
+
+## Overview
+
+The setup process involves two parties exchanging SAML metadata:
+
+1. **You configure** an application in Auth0 with the SAML2 Web App addon enabled and provide PlaidCloud with your Identity Provider Metadata URL.
+2. **PlaidCloud provides** you with the Service Provider (SP) Entity ID and ACS URL (Assertion Consumer Service URL) needed to complete your Auth0 application configuration.
+
+Coordinate with PlaidCloud support to obtain the SP values before completing Step 3 below.
+
+## Step 1: Create an Application
+
+1. Sign in to the [Auth0 Dashboard](https://manage.auth0.com).
+2. In the left sidebar, navigate to **Applications** > **Applications**.
+3. Click **Create Application**.
+4. Enter a name for the application (e.g., `PlaidCloud SSO`).
+5. Select **Regular Web Applications** as the application type.
+6. Click **Create**.
+
+## Step 2: Enable the SAML2 Web App Addon
+
+1. On the application detail page, select the **Addons** tab.
+2. Click the **SAML2 Web App** addon to enable it.
+3. The addon settings panel will open. Leave it open — you will configure it in the next step.
+
+## Step 3: Configure SAML Settings
+
+{{< note >}}
+You will need the **SP Entity ID** and **ACS URL** from PlaidCloud before completing this step. Contact PlaidCloud support to obtain these values.
+{{< /note >}}
+
+In the **SAML2 Web App** addon settings panel:
+
+1. In the **Application Callback URL** field, enter the ACS URL provided by PlaidCloud.
+2. In the **Settings** JSON editor, set the `audience` field to the SP Entity ID provided by PlaidCloud:
+
+```json
+{
+  "audience": "your-sp-entity-id-from-plaidcloud",
+  "mappings": {
+    "email": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
+    "given_name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname",
+    "family_name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname"
+  },
+  "nameIdentifierFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
+  "nameIdentifierProbes": [
+    "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
+  ]
+}
+```
+
+3. Click **Enable** (or **Save**) to apply the settings.
+
+## Step 4: Retrieve and Send the Identity Provider Metadata URL
+
+Once the addon is enabled, locate the metadata URL and send it to PlaidCloud so the integration can be completed.
+
+1. In the **SAML2 Web App** addon settings panel, select the **Usage** tab.
+2. Copy the **Identity Provider Metadata** URL (formatted as `https://{your-auth0-domain}/samlp/metadata/{client-id}`).
+
+**Send this Metadata URL to PlaidCloud support.** This is the Entity Descriptor URL that PlaidCloud needs to configure the trust relationship on the identity provider side. Once PlaidCloud receives this URL, the team will complete the Keycloak configuration and notify you when SSO is ready to test.
+
+## Step 5: Configure Attribute Mappings for Groups (Optional)
+
+If your PlaidCloud configuration uses group-based security role assignments, you can pass group membership through the SAML assertion using Auth0 rules or actions.
+
+### Using Auth0 Actions
+
+1. In the left sidebar, navigate to **Actions** > **Library**.
+2. Click **Build Custom** and create a new action for the **Login / Post Login** trigger.
+3. Add logic to append group information to the SAML assertion. For example, if groups are stored as user metadata:
+
+```javascript
+exports.onExecutePostLogin = async (event, api) => {
+  const groups = event.user.app_metadata?.groups || [];
+  api.samlResponse.setAttribute("groups", groups);
+};
+```
+
+4. Deploy the action and add it to the **Login** flow.
+
+{{< note >}}
+Discuss with PlaidCloud support which group attribute name and format are expected so that group-based security role assignments work correctly in PlaidCloud.
+{{< /note >}}
+
+## Step 6: Control User Access
+
+Auth0 controls which users can authenticate based on the connections and rules attached to the application.
+
+1. On the application detail page, select the **Connections** tab.
+2. Enable the appropriate connections (e.g., your organization's database connection, Active Directory, or social connections) for this application.
+3. Disable any connections that should not have access to PlaidCloud.
+
+To restrict access to specific users within a connection, use Auth0 Actions or Rules to allow or deny authentication based on user attributes or group membership.
+
+## Testing the Integration
+
+After PlaidCloud confirms the configuration is complete:
+
+1. Navigate to your organization's PlaidCloud Workspace (e.g., `https://my-workspace.plaid.cloud`).
+2. You will be redirected to the Auth0 sign-in page (or your configured connection's login).
+3. Sign in with your Auth0 credentials.
+4. Upon successful authentication, you will be redirected back to PlaidCloud.
+
+If you encounter errors, verify that:
+- The Application Callback URL and audience match exactly what PlaidCloud provided
+- The SAML2 Web App addon is enabled on the application
+- The `nameIdentifierFormat` is set to the email address format
+- The Metadata URL you sent to PlaidCloud is accessible
+- The user's connection is enabled on the application

content/en/docs/Access_Management/advanced/aws-saml-setup.md

@@ -0,0 +1,114 @@
+---
+title: Setting Up AWS IAM Identity Center SAML for Single Sign-On
+slug: aws-saml-setup
+description: Configure AWS IAM Identity Center as a SAML identity provider for PlaidCloud Single Sign-On
+date: 2024-01-01T00:00:00
+tags:
+- plaidcloud
+- sso
+- saml
+- aws
+- iam
+categories:
+- PlaidCloud
+- Access Management
+---
+
+PlaidCloud supports Single Sign-On (SSO) via SAML 2.0. This guide walks through configuring AWS IAM Identity Center (formerly AWS SSO) as a SAML identity provider so your organization's users can authenticate through AWS when accessing PlaidCloud.
+
+{{< note >}}
+The PlaidCloud-side configuration is handled by the PlaidCloud team. Your responsibility is to set up the custom SAML application in IAM Identity Center and provide PlaidCloud with your **IAM Identity Center SAML Metadata URL**. PlaidCloud support will complete the remaining configuration.
+{{< /note >}}
+
+## Prerequisites
+
+- An AWS account with **IAM Identity Center** enabled
+- An IAM user or role with the **AWSSSOMasterAccountAdministrator** managed policy or equivalent permissions
+- IAM Identity Center must be configured with an identity source (the built-in directory, Active Directory, or an external IdP)
+- Contact with PlaidCloud support to coordinate the setup and exchange configuration values
+
+## Overview
+
+The setup process involves two parties exchanging SAML metadata:
+
+1. **You configure** a custom SAML application in IAM Identity Center and provide PlaidCloud with your SAML Metadata URL.
+2. **PlaidCloud provides** you with the Service Provider (SP) Entity ID and ACS URL (Assertion Consumer Service URL) needed to complete your application configuration.
+
+Coordinate with PlaidCloud support to obtain the SP values before completing Step 3 below.
+
+## Step 1: Create a Custom SAML Application
+
+1. Sign in to the [AWS Management Console](https://console.aws.amazon.com) and navigate to **IAM Identity Center**.
+2. In the left sidebar, select **Applications**.
+3. Click **Add application**.
+4. Select **I have an application I want to set up** and choose **Custom SAML 2.0 application**.
+5. Click **Next**.
+6. Enter a **Display name** for the application (e.g., `PlaidCloud SSO`) and optionally a description.
+
+## Step 2: Retrieve the IAM Identity Center SAML Metadata URL
+
+Before configuring the service provider details, locate your IAM Identity Center metadata URL to send to PlaidCloud.
+
+1. On the application configuration page, scroll to the **IAM Identity Center metadata** section.
+2. Copy the **IAM Identity Center SAML metadata URL** (formatted as `https://portal.sso.{region}.amazonaws.com/saml/metadata/{instanceId}`).
+
+**Send this Metadata URL to PlaidCloud support.** This is the Entity Descriptor URL that PlaidCloud needs to configure the trust relationship on the identity provider side. Once PlaidCloud receives this URL, the team will complete the Keycloak configuration and notify you when SSO is ready to test.
+
+## Step 3: Configure Service Provider Details
+
+{{< note >}}
+You will need the **SP Entity ID** and **ACS URL** from PlaidCloud before completing this step. Contact PlaidCloud support to obtain these values.
+{{< /note >}}
+
+1. Scroll to the **Application properties** section.
+2. In the **Application ACS URL** field, enter the ACS URL provided by PlaidCloud.
+3. In the **Application SAML audience** field, enter the SP Entity ID provided by PlaidCloud.
+4. Click **Submit**.
+
+## Step 4: Configure Attribute Mappings
+
+IAM Identity Center passes user attributes to PlaidCloud in the SAML assertion. Configure attribute mappings so PlaidCloud receives the necessary user details.
+
+1. On the application detail page, select the **Attribute mappings** tab.
+2. Click **Add new attribute mapping** and add the following:
+
+| User attribute in the application | Maps to this string value or user attribute in IAM Identity Center | Format |
+|---|---|---|
+| `Subject` | `${user:email}` | emailAddress |
+| `email` | `${user:email}` | unspecified |
+| `firstName` | `${user:givenName}` | unspecified |
+| `lastName` | `${user:familyName}` | unspecified |
+
+3. Click **Save changes**.
+
+### Group Membership (Optional)
+
+IAM Identity Center does not natively pass group membership as a SAML attribute in the same way as other providers. If your PlaidCloud configuration requires group-based security role assignments, discuss the available options with PlaidCloud support. Common approaches include using the built-in directory with group assignments or syncing groups from an external identity source such as Active Directory.
+
+{{< note >}}
+Discuss with PlaidCloud support how group membership should be conveyed so that group-based security role assignments work correctly in PlaidCloud.
+{{< /note >}}
+
+## Step 5: Assign Users and Groups to the Application
+
+Only users and groups assigned to the application will be able to authenticate through this SSO configuration.
+
+1. On the application detail page, select the **Assign users and groups** tab.
+2. Click **Assign users and groups**.
+3. Search for and select the users or groups that should have SSO access to PlaidCloud.
+4. Click **Assign users**.
+
+## Testing the Integration
+
+After PlaidCloud confirms the configuration is complete:
+
+1. Navigate to your organization's PlaidCloud Workspace (e.g., `https://my-workspace.plaid.cloud`).
+2. You will be redirected to the AWS IAM Identity Center sign-in page.
+3. Sign in with your AWS IAM Identity Center credentials.
+4. Upon successful authentication, you will be redirected back to PlaidCloud.
+
+If you encounter errors, verify that:
+- The ACS URL and SP Entity ID match exactly what PlaidCloud provided
+- The user attempting to log in is assigned to the application in IAM Identity Center
+- The Subject attribute is mapped to `${user:email}` with the **emailAddress** format
+- The Metadata URL you sent to PlaidCloud is accessible from PlaidCloud's servers

content/en/docs/Access_Management/advanced/entra-saml-setup.md

@@ -0,0 +1,114 @@
+---
+title: Setting Up Microsoft Entra ID SAML for Single Sign-On
+slug: entra-saml-setup
+description: Configure Microsoft Entra ID (Azure AD) as a SAML identity provider for PlaidCloud Single Sign-On
+date: 2024-01-01T00:00:00
+tags:
+- plaidcloud
+- sso
+- saml
+- entra
+- azure
+categories:
+- PlaidCloud
+- Access Management
+---
+
+PlaidCloud supports Single Sign-On (SSO) via SAML 2.0. This guide walks through configuring Microsoft Entra ID (formerly Azure Active Directory) as a SAML identity provider so your organization's users can authenticate through Entra when accessing PlaidCloud.
+
+{{< note >}}
+The PlaidCloud-side configuration is handled by the PlaidCloud team. Your responsibility is to set up the Enterprise Application in Entra and provide PlaidCloud with your **App Federation Metadata URL**. PlaidCloud support will complete the remaining configuration.
+{{< /note >}}
+
+## Prerequisites
+
+- An active Microsoft Entra ID (Azure AD) tenant
+- An account with one of the following Entra roles: **Global Administrator**, **Cloud Application Administrator**, or **Application Administrator**
+- Contact with PlaidCloud support to coordinate the setup and exchange configuration values
+
+## Overview
+
+The setup process involves two parties exchanging SAML metadata:
+
+1. **You configure** an Enterprise Application in Entra ID and provide PlaidCloud with your App Federation Metadata URL.
+2. **PlaidCloud provides** you with the Service Provider (SP) Entity ID and Reply URL (Assertion Consumer Service URL) needed to complete your Entra configuration.
+
+Coordinate with PlaidCloud support to obtain the SP values before completing Step 3 below.
+
+## Step 1: Create an Enterprise Application
+
+1. Sign in to the [Azure portal](https://portal.azure.com) and navigate to **Microsoft Entra ID**.
+2. In the left sidebar, select **Enterprise Applications**.
+3. Click **+ New application**.
+4. Click **+ Create your own application**.
+5. Enter a name for the application (e.g., `PlaidCloud SSO`).
+6. Select **Integrate any other application you don't find in the gallery (Non-gallery)**.
+7. Click **Create**.
+
+## Step 2: Enable SAML-Based Single Sign-On
+
+1. After the application is created, select **Single sign-on** from the left sidebar under **Manage**.
+2. On the "Select a single sign-on method" screen, click **SAML**.
+
+## Step 3: Configure Basic SAML Settings
+
+{{< note >}}
+You will need the **SP Entity ID** and **Reply URL (ACS URL)** from PlaidCloud before completing this step. Contact PlaidCloud support to obtain these values.
+{{< /note >}}
+
+1. In the **Basic SAML Configuration** section, click **Edit**.
+2. In the **Identifier (Entity ID)** field, enter the SP Entity ID provided by PlaidCloud.
+3. In the **Reply URL (Assertion Consumer Service URL)** field, enter the ACS URL provided by PlaidCloud.
+4. Click **Save**.
+
+## Step 4: Configure Attributes and Claims
+
+By default, Entra will pass the user's email address and name in the SAML assertion. If your PlaidCloud configuration uses security group assignments from SSO, you should also include group claims.
+
+### Add Group Claims
+
+1. In the **Attributes & Claims** section, click **Edit**.
+2. Click **+ Add a group claim**.
+3. Choose **Groups assigned to the application** (recommended to limit token size).
+4. Under **Source attribute**, select an appropriate value:
+   - **Group ID** — passes the Azure Object ID (UUID) of the group
+   - **Cloud-only group display names** — passes the human-readable group name (for cloud-only groups)
+   - **sAMAccountName** — passes the on-premises group name (for hybrid/synced environments)
+5. Click **Save**.
+
+{{< note >}}
+Discuss with PlaidCloud support which group attribute format is expected so that group-based security role assignments work correctly in PlaidCloud.
+{{< /note >}}
+
+## Step 5: Assign Users and Groups to the Application
+
+Only users and groups assigned to the Enterprise Application will be able to authenticate through this SSO configuration.
+
+1. In the left sidebar, select **Users and groups** under **Manage**.
+2. Click **+ Add user/group**.
+3. Select the users or groups that should have SSO access to PlaidCloud.
+4. Click **Assign**.
+
+## Step 6: Retrieve and Send the App Federation Metadata URL
+
+Once the application is configured, locate the Federation Metadata URL and send it to PlaidCloud so the integration can be completed.
+
+1. Navigate to the **Single sign-on** page for your Enterprise Application.
+2. Scroll to the **SAML Certificates** section.
+3. Copy the **App Federation Metadata URL**.
+
+**Send this URL to PlaidCloud support.** This is the Entity Descriptor URL that PlaidCloud needs to configure the trust relationship on the identity provider side. Once PlaidCloud receives this URL, the team will complete the Keycloak configuration and notify you when SSO is ready to test.
+
+## Testing the Integration
+
+After PlaidCloud confirms the configuration is complete:
+
+1. Navigate to your organization's PlaidCloud Workspace (e.g., `https://my-workspace.plaid.cloud`).
+2. You will be redirected to the Microsoft login page.
+3. Sign in with your Entra ID credentials.
+4. Upon successful authentication, you will be redirected back to PlaidCloud.
+
+If you encounter errors, verify that:
+- The SP Entity ID and Reply URL match exactly what PlaidCloud provided
+- The user attempting to log in is assigned to the Enterprise Application
+- The App Federation Metadata URL you sent to PlaidCloud is accessible (not blocked by a firewall or conditional access policy)