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