From 06e6b5c1bd0609b85a73773ba60edf57d3c0276a Mon Sep 17 00:00:00 2001
From: Alex Smolen <alexsmolen@Alexs-MacBook-Air.local>
Date: Mon, 27 Apr 2026 11:59:59 -0700
Subject: [PATCH] docs: add session policies section to AssumeRole concept page

Documents Policy and PolicyArns as session policies, including their
restrict-only behavior, inline JSON examples, and combined usage.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 docs/concepts/assumerole.rst | 65 ++++++++++++++++++++++++++++++++++--
 1 file changed, 62 insertions(+), 3 deletions(-)

diff --git a/docs/concepts/assumerole.rst b/docs/concepts/assumerole.rst
index 5c45d44..70eb6e7 100644
--- a/docs/concepts/assumerole.rst
+++ b/docs/concepts/assumerole.rst
@@ -7,8 +7,8 @@ AssumeRole
 
     The only required parameter for the ``AssumeRole`` object is ``RoleArn``.
     All other parameters are completely optional.
-  
-.. warning:: 
+
+.. warning::
 
     Although you *may* provide ``TokenCode`` for MFA, **this is not recommended**.
     You will need to edit your config every time your MFA token changes, which is roughly every 30 seconds.
@@ -38,4 +38,63 @@ The ``AssumeRole`` object in a config represents parameters for :meth:`STS.Clien
         - str
       ProvidedContexts:
         - ProviderArn: str
-          ContextAssertion: str
\ No newline at end of file
+          ContextAssertion: str
+
+.. _assumerole-session-policies:
+
+Session policies: ``Policy`` and ``PolicyArns``
+-----------------------------------------------
+
+``Policy`` and ``PolicyArns`` are both **session policies** — IAM policies you attach at the moment of role assumption to further restrict what the resulting session can do.
+
+.. important::
+
+    Session policies can only **restrict** permissions, never expand them.
+    The effective permissions of the session are the intersection of the role's identity-based policies and the session policies you provide.
+    You cannot use a session policy to grant access that the role itself does not already have.
+
+Use ``Policy`` to supply an inline JSON policy document directly in your config:
+
+.. code-block:: yaml
+
+    AssumeRole:
+      RoleArn: arn:aws:iam::123456789012:role/MyRole
+      Policy: '{"Version":"2012-10-17","Statement":[{"Effect":"Allow","Action":"s3:GetObject","Resource":"arn:aws:s3:::my-bucket/*"}]}'
+
+For readability, YAML block scalars work equally well:
+
+.. code-block:: yaml
+
+    AssumeRole:
+      RoleArn: arn:aws:iam::123456789012:role/MyRole
+      Policy: |
+        {
+          "Version": "2012-10-17",
+          "Statement": [
+            {
+              "Effect": "Allow",
+              "Action": "s3:GetObject",
+              "Resource": "arn:aws:s3:::my-bucket/*"
+            }
+          ]
+        }
+
+Use ``PolicyArns`` to reference one or more existing managed policies by ARN — both AWS managed and customer managed policies are supported:
+
+.. code-block:: yaml
+
+    AssumeRole:
+      RoleArn: arn:aws:iam::123456789012:role/MyRole
+      PolicyArns:
+        - arn:aws:iam::aws:policy/ReadOnlyAccess
+        - arn:aws:iam::123456789012:policy/MyCustomPolicy
+
+You can use both ``Policy`` and ``PolicyArns`` together. In that case, the session's effective permissions are the intersection of the role's policies with *all* provided session policies:
+
+.. code-block:: yaml
+
+    AssumeRole:
+      RoleArn: arn:aws:iam::123456789012:role/MyRole
+      Policy: '{"Version":"2012-10-17","Statement":[{"Effect":"Allow","Action":"s3:*","Resource":"*"}]}'
+      PolicyArns:
+        - arn:aws:iam::aws:policy/ReadOnlyAccess
\ No newline at end of file