ceph/doc/radosgw/session-tags.rst

   1 =======================================================
   2 Session tags for Attribute Based Access Control in STS
   3 =======================================================
   4
   5 Session tags are key-value pairs that can be passed while federating a user (currently it
   6 is only supported as part of the web token passed to AssumeRoleWithWebIdentity). The session
   7 tags are passed along as aws:PrincipalTag in the session credentials (temporary credentials)
   8 that is returned back by STS. These Principal Tags consists of the session tags that come in
   9 as part of the web token and the tags that are attached to the role being assumed. Please note
  10 that the tags have to be always specified in the following namespace: https://aws.amazon.com/tags.
  11
  12 An example of the session tags that are passed in by the IDP in the web token is as follows:
  13
  14 .. code-block:: python
  15
  16     {
  17         "jti": "947960a3-7e91-4027-99f6-da719b0d4059",
  18         "exp": 1627438044,
  19         "nbf": 0,
  20         "iat": 1627402044,
  21         "iss": "http://localhost:8080/auth/realms/quickstart",
  22         "aud": "app-profile-jsp",
  23         "sub": "test",
  24         "typ": "ID",
  25         "azp": "app-profile-jsp",
  26         "auth_time": 0,
  27         "session_state": "3a46e3e7-d198-4a64-8b51-69682bcfc670",
  28         "preferred_username": "test",
  29         "email_verified": false,
  30         "acr": "1",
  31         "https://aws.amazon.com/tags": [
  32             {
  33                 "principal_tags": {
  34                     "Department": [
  35                         "Engineering",
  36                         "Marketing"
  37                     ]
  38                 }
  39             }
  40         ],
  41         "client_id": "app-profile-jsp",
  42         "username": "test",
  43         "active": true
  44     }
  45
  46 Steps to configure Keycloak to pass tags in the web token are described here:
  47 :ref:`radosgw_keycloak`.
  48
  49 The trust policy must have 'sts:TagSession' permission if the web token passed
  50 in by the federated user contains session tags, otherwise the
  51 AssumeRoleWithWebIdentity action will fail. An example of the trust policy with
  52 sts:TagSession is as follows:
  53
  54 .. code-block:: python
  55
  56     {
  57             "Version":"2012-10-17",
  58             "Statement":[
  59             {
  60                 "Effect":"Allow",
  61                 "Action":["sts:AssumeRoleWithWebIdentity","sts:TagSession"],
  62                 "Principal":{"Federated":["arn:aws:iam:::oidc-provider/localhost:8080/auth/realms/quickstart"]},
  63                 "Condition":{"StringEquals":{"localhost:8080/auth/realms/quickstart:sub":"test"}}
  64             }]
  65         }
  66
  67 Tag Keys
  68 ========
  69
  70 The following are the tag keys that can be used in the role's trust policy or the role's permission policy:
  71
  72 1. aws:RequestTag: This key is used to compare the key-value pair passed in the request with the key-value pair
  73 in the role's trust policy. In case of AssumeRoleWithWebIdentity, the session tags that are passed by the idp
  74 in the web token can be used as aws:RequestTag in the role's trust policy based on which a federated user can be
  75 allowed to assume a role.
  76
  77 An example of a role trust policy that uses aws:RequestTag is as follows:
  78
  79 .. code-block:: python
  80
  81     {
  82             "Version":"2012-10-17",
  83             "Statement":[
  84             {
  85                 "Effect":"Allow",
  86                 "Action":["sts:AssumeRoleWithWebIdentity","sts:TagSession"],
  87                 "Principal":{"Federated":["arn:aws:iam:::oidc-provider/localhost:8080/auth/realms/quickstart"]},
  88                 "Condition":{"StringEquals":{"aws:RequestTag/Department":"Engineering"}}
  89             }]
  90         }
  91
  92 2. aws:PrincipalTag: This key is used to compare the key-value pair attached to the principal with the key-value pair
  93 in the policy. In case of AssumeRoleWithWebIdentity, the session tags that are passed by the idp in the web token appear
  94 as Principal tags in the temporary credentials once a user has been authenticated, and these tags can be used as
  95 aws:PrincipalTag in the role's permission policy.
  96
  97 An example of a role permission policy that uses aws:PrincipalTag is as follows:
  98
  99 .. code-block:: python
 100
 101     {
 102             "Version":"2012-10-17",
 103             "Statement":[
 104             {
 105                 "Effect":"Allow",
 106                 "Action":["s3:*"],
 107             "Resource":["arn:aws:s3::t1tenant:my-test-bucket","arn:aws:s3::t1tenant:my-test-bucket/*],"+
 108                 "Condition":{"StringEquals":{"aws:PrincipalTag/Department":"Engineering"}}
 109             }]
 110         }
 111
 112 3. iam:ResourceTag: This key is used to compare the key-value pair attached to the resource with the key-value pair
 113 in the policy. In case of AssumeRoleWithWebIdentity, tags attached to the role can be used to compare with that in
 114 the trust policy to allow a user to assume a role.
 115 RGW now supports REST APIs for tagging, listing tags and untagging actions on a role. More information related to
 116 role tagging can be found here :doc:`role`.
 117
 118 An example of a role's trust policy that uses aws:ResourceTag is as follows:
 119
 120 .. code-block:: python
 121
 122     {
 123             "Version":"2012-10-17",
 124             "Statement":[
 125             {
 126                 "Effect":"Allow",
 127                 "Action":["sts:AssumeRoleWithWebIdentity","sts:TagSession"],
 128                 "Principal":{"Federated":["arn:aws:iam:::oidc-provider/localhost:8080/auth/realms/quickstart"]},
 129                 "Condition":{"StringEquals":{"iam:ResourceTag/Department":"Engineering"}}
 130             }]
 131         }
 132
 133 For the above to work, you need to attach 'Department=Engineering' tag to the role.
 134
 135 4. aws:TagKeys: This key is used to compare tags in the request with the tags in the policy. In case of
 136 AssumeRoleWithWebIdentity this can be used to check the tag keys in a role's trust policy before a user
 137 is allowed to assume a role.
 138 This can also be used in the role's permission policy.
 139
 140 An example of a role's trust policy that uses aws:TagKeys is as follows:
 141
 142 .. code-block:: python
 143
 144     {
 145             "Version":"2012-10-17",
 146             "Statement":[
 147             {
 148                 "Effect":"Allow",
 149                 "Action":["sts:AssumeRoleWithWebIdentity","sts:TagSession"],
 150                 "Principal":{"Federated":["arn:aws:iam:::oidc-provider/localhost:8080/auth/realms/quickstart"]},
 151                 "Condition":{"ForAllValues:StringEquals":{"aws:TagKeys":["Department"]}}
 152             }]
 153         }
 154
 155 'ForAllValues:StringEquals' tests whether every tag key in the request is a subset of the tag keys in the policy. So the above
 156 condition restricts the tag keys passed in the request.
 157
 158 5. s3:ResourceTag: This key is used to compare tags present on the s3 resource (bucket or object) with the tags in
 159 the role's permission policy.
 160
 161 An example of a role's permission policy that uses s3:ResourceTag is as follows:
 162
 163 .. code-block:: python
 164
 165     {
 166         "Version":"2012-10-17",
 167         "Statement":[
 168         {
 169             "Effect":"Allow",
 170             "Action":["s3:PutBucketTagging"],
 171             "Resource":["arn:aws:s3::t1tenant:my-test-bucket\","arn:aws:s3::t1tenant:my-test-bucket/*"]
 172         },
 173         {
 174             "Effect":"Allow",
 175             "Action":["s3:*"],
 176             "Resource":["*"],
 177             "Condition":{"StringEquals":{"s3:ResourceTag/Department":\"Engineering"}}
 178         }
 179     }
 180
 181 For the above to work, you need to attach 'Department=Engineering' tag to the bucket (and on the object too) on which you want this policy
 182 to be applied.
 183
 184 More examples of policies using tags
 185 ====================================
 186
 187 1. To assume a role by matching the tags in the incoming request with the tag attached to the role.
 188 aws:RequestTag is the incoming tag in the JWT (access token) and iam:ResourceTag is the tag attached to the role being assumed:
 189
 190 .. code-block:: python
 191
 192     {
 193             "Version":"2012-10-17",
 194             "Statement":[
 195             {
 196                 "Effect":"Allow",
 197                 "Action":["sts:AssumeRoleWithWebIdentity","sts:TagSession"],
 198                 "Principal":{"Federated":["arn:aws:iam:::oidc-provider/localhost:8080/auth/realms/quickstart"]},
 199                 "Condition":{"StringEquals":{"aws:RequestTag/Department":"${iam:ResourceTag/Department}"}}
 200             }]
 201         }
 202
 203 2. To evaluate a role's permission policy by matching principal tags with s3 resource tags.
 204 aws:PrincipalTag is the tag passed in along with the temporary credentials and s3:ResourceTag is the tag attached to
 205 the s3 resource (object/ bucket):
 206
 207 .. code-block:: python
 208
 209
 210     {
 211         "Version":"2012-10-17",
 212         "Statement":[
 213         {
 214             "Effect":"Allow",
 215             "Action":["s3:PutBucketTagging"],
 216             "Resource":["arn:aws:s3::t1tenant:my-test-bucket\","arn:aws:s3::t1tenant:my-test-bucket/*"]
 217         },
 218         {
 219             "Effect":"Allow",
 220             "Action":["s3:*"],
 221             "Resource":["*"],
 222             "Condition":{"StringEquals":{"s3:ResourceTag/Department":"${aws:PrincipalTag/Department}"}}
 223         }
 224     }
 225
 226 Properties of Session Tags
 227 ==========================
 228
 229 1. Session Tags can be multi-valued. (Multi-valued session tags are not supported in AWS)
 230 2. A maximum of 50 session tags are allowed to be passed in by the IDP.
 231 3. The maximum size of a key allowed is 128 characters.
 232 4. The maximum size of a value allowed is 256 characters.
 233 5. The tag or the value can not start with "aws:".
 234
 235 s3 Resource Tags
 236 ================
 237
 238 As stated above 's3:ResourceTag' key can be used for authorizing an s3 operation in RGW (this is not allowed in AWS).
 239
 240 s3:ResourceTag is a key used to refer to tags that have been attached to an object or a bucket. Tags can be attached to an object or
 241 a bucket using REST APIs available for the same.
 242
 243 The following table shows which s3 resource tag type (bucket/object) are supported for authorizing a particular operation.
 244
 245 +-----------------------------------+-------------------+
 246 | Operation                         | Tag type          |
 247 +===================================+===================+
 248 | **GetObject**                     | Object tags       |
 249 | **GetObjectTags**                 |                   |
 250 | **DeleteObjectTags**              |                   |
 251 | **DeleteObject**                  |                   |
 252 | **PutACLs**                       |                   |
 253 | **InitMultipart**                 |                   |
 254 | **AbortMultipart**                |                   |
 255 | **ListMultipart**                 |                   |
 256 | **GetAttrs**                      |                   |
 257 | **PutObjectRetention**            |                   |
 258 | **GetObjectRetention**            |                   |
 259 | **PutObjectLegalHold**            |                   |
 260 | **GetObjectLegalHold**            |                   |
 261 +-----------------------------------+-------------------+
 262 | **PutObjectTags**                 | Bucket tags       |
 263 | **GetBucketTags**                 |                   |
 264 | **PutBucketTags**                 |                   |
 265 | **DeleteBucketTags**              |                   |
 266 | **GetBucketReplication**          |                   |
 267 | **DeleteBucketReplication**       |                   |
 268 | **GetBucketVersioning**           |                   |
 269 | **SetBucketVersioning**           |                   |
 270 | **GetBucketWebsite**              |                   |
 271 | **SetBucketWebsite**              |                   |
 272 | **DeleteBucketWebsite**           |                   |
 273 | **StatBucket**                    |                   |
 274 | **ListBucket**                    |                   |
 275 | **GetBucketLogging**              |                   |
 276 | **GetBucketLocation**             |                   |
 277 | **DeleteBucket**                  |                   |
 278 | **GetLC**                         |                   |
 279 | **PutLC**                         |                   |
 280 | **DeleteLC**                      |                   |
 281 | **GetCORS**                       |                   |
 282 | **PutCORS**                       |                   |
 283 | **GetRequestPayment**             |                   |
 284 | **SetRequestPayment**             |                   |
 285 | **PutBucketPolicy**               |                   |
 286 | **GetBucketPolicy**               |                   |
 287 | **DeleteBucketPolicy**            |                   |
 288 | **PutBucketObjectLock**           |                   |
 289 | **GetBucketObjectLock**           |                   |
 290 | **GetBucketPolicyStatus**         |                   |
 291 | **PutBucketPublicAccessBlock**    |                   |
 292 | **GetBucketPublicAccessBlock**    |                   |
 293 | **DeleteBucketPublicAccessBlock** |                   |
 294 +-----------------------------------+-------------------+
 295 | **GetACLs**                       | Bucket tags for   |
 296 | **PutACLs**                       | bucket ACLs       |
 297 |                                   | Object tags for   |
 298 |                                   | object ACLs       |
 299 +-----------------------------------+-------------------+
 300 | **PutObject**                     | Object tags of    |
 301 | **CopyObject**                    | source object     |
 302 |                                   | Bucket tags of    |
 303 |                                   | destination bucket|
 304 +-----------------------------------+-------------------+
 305
 306
 307 Sample code demonstrating usage of session tags
 308 ===============================================
 309
 310 The following is a sample code for tagging a role, a bucket, an object in it and using tag keys in a role's
 311 trust policy and its permission policy, assuming that a tag 'Department=Engineering' is passed in the
 312 JWT (access token) by the IDP
 313
 314 .. code-block:: python
 315
 316     # -*- coding: utf-8 -*-
 317
 318     import boto3
 319     import json
 320     from nose.tools import eq_ as eq
 321
 322     access_key = 'TESTER'
 323     secret_key = 'test123'
 324     endpoint = 'http://s3.us-east.localhost:8000'
 325
 326     s3client = boto3.client('s3',
 327     aws_access_key_id = access_key,
 328     aws_secret_access_key = secret_key,
 329     endpoint_url = endpoint,
 330     region_name='',)
 331
 332     s3res = boto3.resource('s3',
 333             aws_access_key_id = access_key,
 334             aws_secret_access_key = secret_key,
 335             endpoint_url = endpoint,
 336             region_name='',)
 337
 338     iam_client = boto3.client('iam',
 339     aws_access_key_id=access_key,
 340     aws_secret_access_key=secret_key,
 341     endpoint_url=endpoint,
 342     region_name=''
 343     )
 344
 345     bucket_name = 'test-bucket'
 346     s3bucket = s3client.create_bucket(Bucket=bucket_name)
 347
 348     bucket_tagging = s3res.BucketTagging(bucket_name)
 349     Set_Tag = bucket_tagging.put(Tagging={'TagSet':[{'Key':'Department', 'Value': 'Engineering'}]})
 350     try:
 351         response = iam_client.create_open_id_connect_provider(
 352             Url='http://localhost:8080/auth/realms/quickstart',
 353             ClientIDList=[
 354                 'app-profile-jsp',
 355                 'app-jee-jsp'
 356             ],
 357             ThumbprintList=[
 358                 'F7D7B3515DD0D319DD219A43A9EA727AD6065287'
 359         ]
 360         )
 361     except ClientError as e:
 362         print ("Provider already exists")
 363
 364     policy_document = "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Effect\":\"Allow\",\"Principal\":{\"Federated\":[\"arn:aws:iam:::oidc-provider/localhost:8080/auth/realms/quickstart\"]},\"Action\":[\"sts:AssumeRoleWithWebIdentity\",\"sts:TagSession\"],\"Condition\":{\"StringEquals\":{\"aws:RequestTag/Department\":\"${iam:ResourceTag/Department}\"}}}]}"
 365     role_response = ""
 366
 367     print ("\n Getting Role \n")
 368
 369     try:
 370         role_response = iam_client.get_role(
 371             RoleName='S3Access'
 372         )
 373         print (role_response)
 374     except ClientError as e:
 375         if e.response['Code'] == 'NoSuchEntity':
 376             print ("\n Creating Role \n")
 377             tags_list = [
 378                 {'Key':'Department','Value':'Engineering'},
 379             ]
 380             role_response = iam_client.create_role(
 381                 AssumeRolePolicyDocument=policy_document,
 382                 Path='/',
 383                 RoleName='S3Access',
 384                 Tags=tags_list,
 385             )
 386             print (role_response)
 387         else:
 388             print("Unexpected error: %s" % e)
 389
 390     role_policy = "{\"Version\":\"2012-10-17\",\"Statement\":{\"Effect\":\"Allow\",\"Action\":\"s3:*\",\"Resource\":\"arn:aws:s3:::*\",\"Condition\":{\"StringEquals\":{\"s3:ResourceTag/Department\":[\"${aws:PrincipalTag/Department}\"]}}}}"
 391
 392     response = iam_client.put_role_policy(
 393                 RoleName='S3Access',
 394                 PolicyName='Policy1',
 395                 PolicyDocument=role_policy
 396             )
 397
 398     sts_client = boto3.client('sts',
 399     aws_access_key_id='abc',
 400     aws_secret_access_key='def',
 401     endpoint_url = endpoint,
 402     region_name = '',
 403     )
 404
 405
 406     print ("\n Assuming Role with Web Identity\n")
 407     response = sts_client.assume_role_with_web_identity(
 408     RoleArn=role_response['Role']['Arn'],
 409     RoleSessionName='Bob',
 410     DurationSeconds=900,
 411     WebIdentityToken='<web-token>')
 412
 413     s3client2 = boto3.client('s3',
 414     aws_access_key_id = response['Credentials']['AccessKeyId'],
 415     aws_secret_access_key = response['Credentials']['SecretAccessKey'],
 416     aws_session_token = response['Credentials']['SessionToken'],
 417     endpoint_url='http://s3.us-east.localhost:8000',
 418     region_name='',)
 419
 420     bucket_body = 'this is a test file'
 421     tags = 'Department=Engineering'
 422     key = "test-1.txt"
 423     s3_put_obj = s3client2.put_object(Body=bucket_body, Bucket=bucket_name, Key=key, Tagging=tags)
 424     eq(s3_put_obj['ResponseMetadata']['HTTPStatusCode'],200)
 425
 426     s3_get_obj = s3client2.get_object(Bucket=bucket_name, Key=key)
 427     eq(s3_get_obj['ResponseMetadata']['HTTPStatusCode'],200)