Add documentation for Custom Roles feature

docs/cloud/get-started/users.mdx

@@ -65,6 +65,8 @@ In addition, there are two roles that the Global Admin cannot assign:
   - Otherwise, has the same permissions as Account Read-only users
   - Can be assigned to Service Accounts by a Global Admin, but otherwise can only be assigned by an Account Owner
 
+You can also assign more granular permissions for a Namespace with [Custom Roles](/cloud/manage-access/custom-roles).
+
 :::note Default Role
 
 When the account is created, the initial user who logs in is automatically assigned the Account Owner role.
@@ -105,6 +107,8 @@ For a Namespace, a user can have one of the following permissions:
 - **Read-Only:**
   - Can only read information from the Namespace
 
+You can also assign more granular permissions for a Namespace with [Custom Roles](/cloud/manage-access/custom-roles).
+
 ## How to update an account-level role in Temporal Cloud {#update-roles}
 
 With Global Admin or Account Owner privileges, you can update any user's account-level [role](#account-level-roles) using either the Web UI or the tcld CLI utility.

docs/cloud/manage-access/custom-roles.mdx

@@ -0,0 +1,117 @@
+---
+id: custom-roles
+title: Manage custom roles
+sidebar_label: Manage custom roles
+description: Custom roles enable users to create fine-grained authorization in Temporal Cloud. This will give you precise control over who can do what within your account.
+slug: /cloud/manage-access/custom-roles
+toc_max_heading_level: 4
+keywords:
+  - explanation
+  - feature
+  - manage access
+  - custom roles
+  - how to
+tags:
+  - Temporal Cloud
+  - custom roles
+  - user management
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+Temporal Cloud currently offers a fixed set of predefined [account-level roles and Namespace-level permissions](https://docs.temporal.io/cloud/users#account-level-roles). 
+These roles are sufficient for many Temporal use cases, but not for supporting enterprise-grade access models
+that require least privilege, delegation, and automation-safe permissions. 
+
+## What are Custom Roles?
+
+Custom Roles enable you to define your own roles as bundles of permission primitives (operations/actions) 
+scoped to applicable resources (namespaces, projects, account objects) and assign them to any 
+principal (user, group, service account). 
+
+## Why use Custom Roles?
+
+Use Custom Roles if you want more fine-grained authentication than Temporal Cloud's predefined roles and permissions provide.
+
+Use Custom Roles if your access model requires the Principle of Least Privilege or delegation.
+
+Using Custom Roles with [Service Accounts](/cloud/service-accounts) can make them more secure for automation purposes. 
+
+## Defining Custom Roles
+
+Custom Roles are made up of bundles of permission operations that map to Temporal Control Plane operations.
+You can scope a permission to all resources of a type, or to specific resources.
+
+For example, the following JSON code defines a global, read-only Namespace role called `NamespaceGlobalReadOnly`,
+to use for auditing and monitoring. 
+Users with this role will be able to retrieve information about any Namespace, but will not be able to modify them.
+The `grants` field is an array of the available permission operations, in this case `cloud.namespace.list` and `cloud.namespace.get`.
+The operations are limited to a `resourceType` of `Namespace`, and the scope is `all`.
+
+You can scope roles to:
+* All resources of a given type
+* Specific resources by explicit ID list
+* Resource subsets
+
+```
+{
+  "name": "NamespaceGlobalReadOnly",
+  "description": "Read-only access to all namespaces for monitoring and compliance",
+  "grants": [
+    {
+      "operation": "cloud.namespace.list",
+      "resourceType": "Namespace",
+      "scope": { "all": true }
+    },
+    {
+      "operation": "cloud.namespace.get",
+      "resourceType": "Namespace",
+      "scope": { "all": true }
+    }
+  ]
+}
+```
+
+### Create Custom Roles from the Web UI
+
+<!-- TBD: The UI is subject to change -->
+
+To create a Custom Role from the Web UI, select Org Settings in the left sidebar, and then click the Custom Roles tab on the Settings page.
+
+On the Custom Roles tab, you'll see a list of the roles that have already been defined for your account, 50 to a page.
+Click the three dots menu to view details about an existing Custom Role, or to edit or delete that role.
+
+Click the Create Custom Role button to create a new role.
+On the Create Custom Role page, give the Custom Role a name, and optionally a description.
+In the Permissions section, you'll assign the appropriate resources and its permissions.
+Select the Resource Type from the drop-down; your choices are Namespace and Account.
+
+If you select Namespace, search for the Namespace for which you want to add permissions, then click Add Resource.
+The Namespace you selected appears in the Permissions By Resource list.
+
+If you select Account, the permissions apply to the current account, so only the Add Resource button appears. 
+Click Add Resource, and the Account will be added to the Permissions By Resource list.
+
+Once the Namespace or Account appears in the Permissions By Resource list, you can toggle individual permissions
+on or off for that resource. 
+If you want to start with the permission set of one of the pre-defined Temporal roles, choose the role from 
+the Select Preset drop-down, and the appropriate permissions will be toggled for you.
+
+<!-- TBD: If we choose to add info about available permissions, we should add a link or list here. -->
+
+When you're done assiging permissions to resources, click Create Custom Role at the bottom of the page.
+
+### Create Custom Roles with the API
+
+<!-- Need more information here. -->
+
+### Create Custom Roles with Terraform
+
+<!-- Need more information here. -->
+
+## Assigning Custom Roles to users
+
+Once you have created a Custom Role, it is available on the Identities page to assign to a user
+or group, the same as the pre-defined Temporal permissions. See [How to update an account-level role in Temporal Cloud](/cloud/users#update-roles)
+for more inforamtion.

docs/cloud/manage-access/index.mdx

@@ -21,5 +21,6 @@ Temporal Cloud offers several ways to manage access to your Temporal Cloud accou
 - [**Users**](/cloud/users) - Manage individual user accounts and permissions
 - [**User Groups**](/cloud/user-groups) - Organize users into groups for simplified access management
 - [**Service Accounts**](/cloud/service-accounts) - Configure service accounts for automated access
+- [**Custom Roles**](/cloud/manage-access/custom-roles) - Define custom permissions for specific use cases
 - [**SAML**](/cloud/saml) - Configure SAML-based single sign-on integration
 - [**SCIM**](/cloud/scim) - Use your IDP to manage Temporal Cloud users and access via SCIM integration

docs/cloud/manage-access/saml.mdx

@@ -0,0 +1,176 @@
+---
+id: saml
+title: SAML authentication
+sidebar_label: SAML authentication
+description:
+  Integrate SAML 2.0 with your Temporal Cloud account for secure user authentication. Connect via Microsoft Entra ID or
+  Okta and ensure seamless SSO. Charges apply.
+slug: /cloud/saml
+toc_max_heading_level: 4
+keywords:
+  - how-to
+  - introduction
+  - security
+  - temporal cloud
+tags:
+  - Security
+  - Temporal Cloud
+  - Users
+---
+
+To authenticate the users of your Temporal Cloud account, you can connect an identity provider (IdP) to your account by
+using Security Assertion Markup Language (SAML) 2.0.
+
+:::info
+
+SAML is a paid feature. See the [pricing page](/cloud/pricing) for details.
+
+:::
+
+## Integrate SAML with your Temporal Cloud account
+
+1. Locate your [Temporal Cloud Account Id](/cloud/namespaces#temporal-cloud-account-id). Your Account Id can be viewed
+   and copied from the Temporal Cloud user profile dropdown menu in the top right corner. Alternatively, find your
+   [Namespace Id](/cloud/namespaces#temporal-cloud-namespace-id). The Account Id is the five or six characters following
+   the period (.), such as `f45a2`. You will need the Account Id to construct your callback URL and your entity
+   identifier.
+1. Configure SAML with your IdP by following one of these sets of instructions:
+   - [Microsoft Entra ID](#configure-saml-with-azure-ad)
+   - [Okta](#configure-saml-with-okta)
+1. [Share your connection information with us and test your connection.](#finish-saml-configuration)
+
+## How to configure SAML with Microsoft Entra ID {#configure-saml-with-azure-ad}
+
+If you want to use the general Microsoft login mechanism, you don't need to set up SAML with Entra ID. Just select
+**Continue with Microsoft** on the Temporal Cloud sign-in page.
+
+To use Entra ID as your SAML IdP, create a Microsoft Entra ID Enterprise application.
+
+1. Sign in to the [Microsoft Entra ID](https://portal.azure.com/).
+1. On the home page, under **Manage Microsoft Entra ID**, select **View**.
+1. On the **Overview** page near the top, select **Add > Enterprise application**.
+1. On the **Browse Microsoft Entra ID Gallery** page near the top, select **Create your own application**.
+1. In the **Create your own application** pane, provide a name for your application (such as `temporal-cloud`) and
+   select **Integrate any other application you don't find in the gallery**.
+1. Select **Save**.
+1. In the **Getting Started** section, select **2. Set up single sign on**.
+1. On the **Single sign-on** page, select **SAML**.
+1. In the **Basic SAML Configuration** section of the **SAML-based Sign-on** page, select **Edit**.
+1. In **Identifier (Entity ID)**, enter the following entity identifier, including your Account Id where indicated:
+
+   ```bash
+   urn:auth0:prod-tmprl:ACCOUNT_ID-saml
+   ```
+
+   A correctly formed entity identifier looks like this:
+
+   ```bash
+   urn:auth0:prod-tmprl:f45a2-saml
+   ```
+
+1. In **Reply URL (Assertion Consumer Service URL)**, enter the following callback URL, including your Account Id where
+   indicated:
+
+   ```bash
+   https://login.tmprl.cloud/login/callback?connection=ACCOUNT_ID-saml
+   ```
+
+   A correctly formed callback URL looks like this:
+
+   ```bash
+   https://login.tmprl.cloud/login/callback?connection=f45a2-saml
+   ```
+
+1. In **Sign on URL**, enter the following login url, including your Account Id where indicated:
+
+   ```bash
+   https://cloud.temporal.io/login/saml?connection=ACCOUNT_ID-saml
+   ```
+
+   A correctly formed login URL looks like this:
+
+   ```bash
+   https://cloud.temporal.io/login/saml?connection=f45a2-saml
+   ```
+
+1. You can leave the other fields blank. Near the top of the pane, select **Save**.
+1. In the **Attributes & Claims** section, select **Edit**. Configure the following settings. Under **Required claim**:
+
+   - Set **Unique User Identifier (NameID)** to `user.userprincipalname`
+   - Set the **NameID format** to `emailAddress`
+
+   These are the default settings for Microsoft Entra ID. Then under **Additional claims**, ensure **Email** and
+   **Name** are present.
+
+1. Collect information that you need to send to us:
+   - In the **SAML Certificates** section of the **SAML-based Sign-on** page, select the download link for **Certificate
+     (Base64)**.
+   - In the **Set up _APPLICATION_NAME_** section of the **SAML-based Sign-on** page, copy the value of **Login URL**.
+
+To finish setting up Microsoft Entra ID as your SAML IdP, see [Finish SAML configuration](#finish-saml-configuration).
+
+## How to configure SAML with Okta {#configure-saml-with-okta}
+
+To use Okta as your SAML IdP, configure a new Okta application integration.
+
+1. Sign in to the [Okta Admin Console](https://www.okta.com/login/).
+1. In the left navigation pane, select **Applications > Applications**.
+1. On the **Applications** page, select **Create App Integration**.
+1. In the **Create a new app integration** dialog, select **SAML 2.0** and then select **Next**.
+1. On the **Create SAML Integration** page in the **General Settings** section, provide a name for your application
+   (such as `temporal-cloud`) and then select **Next**.
+1. In the **Configure SAML** section in **Single sign on URL**, enter the following callback URL, including your Account
+   Id where indicated:
+
+   ```bash
+   https://login.tmprl.cloud/login/callback?connection=ACCOUNT_ID-saml
+   ```
+
+   A correctly formed callback URL looks like this:
+
+   ```bash
+   https://login.tmprl.cloud/login/callback?connection=f45a2-saml
+   ```
+
+1. In **Audience URI (SP Entity ID)**, enter the following entity identifier, including your Account Id where indicated:
+
+   ```bash
+   urn:auth0:prod-tmprl:ACCOUNT_ID-saml
+   ```
+
+   A correctly formed entity identifier looks like this:
+
+   ```bash
+   urn:auth0:prod-tmprl:f45a2-saml
+   ```
+
+1. We require the user's full email address when connecting to Temporal.
+   - In **Name ID format**, select `EmailAddress`.
+   - In **Attribute Statements**, set **email** and **name**.
+1. Select **Next**.
+1. In the **Feedback** section, select **Finish**.
+1. On the **Applications** page, select the name of the application integration you just created.
+1. On the application integration page, select the **Sign On** tab.
+1. Under **SAML Setup**, select **View SAML setup instructions**.
+1. Collect information that you need to send to us:
+   - Copy the IdP settings.
+   - Download the active certificate.
+
+To finish setting up Okta as your SAML IdP, see the next section,
+[Finish SAML configuration](#finish-saml-configuration).
+
+## How to finish your SAML configuration {#finish-saml-configuration}
+
+After you configure SAML with your IdP, we can finish the configuration on our side.
+[Create a support ticket](/cloud/support#support-ticket) that includes the following information:
+
+- The sign-in URL from your application
+- The X.509 SAML sign-in certificate in PEM format
+- One or more IdP domains to map to the SAML connection
+
+Generally, the provided IdP domain is the same as the domain for your email address. You can provide multiple IdP
+domains.
+
+When you receive confirmation from us that we have finished configuration, log in to Temporal Cloud. This time, though,
+enter your email address in **Enterprise identity** and select **Continue**. Do not select **Continue with Google** or
+**Continue with Microsoft**. You will be redirected to the authentication page of your IdP.