ceph/doc/radosgw/role.rst

   1 ======
   2  Role
   3 ======
   4
   5 A role is similar to a user and has permission policies attached to it, that determine what a role can or can not do. A role can be assumed by any identity that needs it. If a user assumes a role, a set of dynamically created temporary credentials are returned to the user. A role can be used to delegate access to users, applications, services that do not have permissions to access some s3 resources.
   6
   7 The following radosgw-admin commands can be used to create/ delete/ update a role and permissions associated with a role.
   8
   9 Create a Role
  10 -------------
  11
  12 To create a role, execute the following::
  13
  14         radosgw-admin role create --role-name={role-name} [--path=="{path to the role}"] [--assume-role-policy-doc={trust-policy-document}]
  15
  16 Request Parameters
  17 ~~~~~~~~~~~~~~~~~~
  18
  19 ``role-name``
  20
  21 :Description: Name of the role.
  22 :Type: String
  23
  24 ``path``
  25
  26 :Description: Path to the role. The default value is a slash(/).
  27 :Type: String
  28
  29 ``assume-role-policy-doc``
  30
  31 :Description: The trust relationship policy document that grants an entity permission to assume the role.
  32 :Type: String
  33
  34 For example::
  35
  36   radosgw-admin role create --role-name=S3Access1 --path=/application_abc/component_xyz/ --assume-role-policy-doc=\{\"Version\":\"2012-10-17\",\"Statement\":\[\{\"Effect\":\"Allow\",\"Principal\":\{\"AWS\":\[\"arn:aws:iam:::user/TESTER\"\]\},\"Action\":\[\"sts:AssumeRole\"\]\}\]\}
  37
  38 .. code-block:: javascript
  39
  40   {
  41     "id": "ca43045c-082c-491a-8af1-2eebca13deec",
  42     "name": "S3Access1",
  43     "path": "/application_abc/component_xyz/",
  44     "arn": "arn:aws:iam:::role/application_abc/component_xyz/S3Access1",
  45     "create_date": "2018-10-17T10:18:29.116Z",
  46     "max_session_duration": 3600,
  47     "assume_role_policy_document": "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Effect\":\"Allow\",\"Principal\":{\"AWS\":[\"arn:aws:iam:::user/TESTER\"]},\"Action\":[\"sts:AssumeRole\"]}]}"
  48   }
  49
  50
  51 Delete a Role
  52 -------------
  53
  54 To delete a role, execute the following::
  55
  56         radosgw-admin role delete --role-name={role-name}
  57
  58 Request Parameters
  59 ~~~~~~~~~~~~~~~~~~
  60
  61 ``role-name``
  62
  63 :Description: Name of the role.
  64 :Type: String
  65
  66 For example::
  67
  68   radosgw-admin role delete --role-name=S3Access1
  69
  70 Note: A role can be deleted only when it doesn't have any permission policy attached to it.
  71
  72 Get a Role
  73 ----------
  74
  75 To get information about a role, execute the following::
  76
  77         radosgw-admin role get --role-name={role-name}
  78
  79 Request Parameters
  80 ~~~~~~~~~~~~~~~~~~
  81
  82 ``role-name``
  83
  84 :Description: Name of the role.
  85 :Type: String
  86
  87 For example::
  88
  89   radosgw-admin role get --role-name=S3Access1
  90
  91 .. code-block:: javascript
  92
  93   {
  94     "id": "ca43045c-082c-491a-8af1-2eebca13deec",
  95     "name": "S3Access1",
  96     "path": "/application_abc/component_xyz/",
  97     "arn": "arn:aws:iam:::role/application_abc/component_xyz/S3Access1",
  98     "create_date": "2018-10-17T10:18:29.116Z",
  99     "max_session_duration": 3600,
 100     "assume_role_policy_document": "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Effect\":\"Allow\",\"Principal\":{\"AWS\":[\"arn:aws:iam:::user/TESTER\"]},\"Action\":[\"sts:AssumeRole\"]}]}"
 101   }
 102
 103
 104 List Roles
 105 ----------
 106
 107 To list roles with a specified path prefix, execute the following::
 108
 109         radosgw-admin role list [--path-prefix ={path prefix}]
 110
 111 Request Parameters
 112 ~~~~~~~~~~~~~~~~~~
 113
 114 ``path-prefix``
 115
 116 :Description: Path prefix for filtering roles. If this is not specified, all roles are listed.
 117 :Type: String
 118
 119 For example::
 120
 121   radosgw-admin role list --path-prefix="/application"
 122
 123 .. code-block:: javascript
 124
 125   [
 126     {
 127         "id": "3e1c0ff7-8f2b-456c-8fdf-20f428ba6a7f",
 128         "name": "S3Access1",
 129         "path": "/application_abc/component_xyz/",
 130         "arn": "arn:aws:iam:::role/application_abc/component_xyz/S3Access1",
 131         "create_date": "2018-10-17T10:32:01.881Z",
 132         "max_session_duration": 3600,
 133         "assume_role_policy_document": "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Effect\":\"Allow\",\"Principal\":{\"AWS\":[\"arn:aws:iam:::user/TESTER\"]},\"Action\":[\"sts:AssumeRole\"]}]}"
 134     }
 135   ]
 136
 137
 138 Update Assume Role Policy Document of a role
 139 --------------------------------------------
 140
 141 To modify a role's assume role policy document, execute the following::
 142
 143         radosgw-admin role modify --role-name={role-name} --assume-role-policy-doc={trust-policy-document}
 144
 145 Request Parameters
 146 ~~~~~~~~~~~~~~~~~~
 147
 148 ``role-name``
 149
 150 :Description: Name of the role.
 151 :Type: String
 152
 153 ``assume-role-policy-doc``
 154
 155 :Description: The trust relationship policy document that grants an entity permission to assume the role.
 156 :Type: String
 157
 158 For example::
 159
 160   radosgw-admin role modify --role-name=S3Access1 --assume-role-policy-doc=\{\"Version\":\"2012-10-17\",\"Statement\":\[\{\"Effect\":\"Allow\",\"Principal\":\{\"AWS\":\[\"arn:aws:iam:::user/TESTER2\"\]\},\"Action\":\[\"sts:AssumeRole\"\]\}\]\}
 161
 162 .. code-block:: javascript
 163
 164   {
 165     "id": "ca43045c-082c-491a-8af1-2eebca13deec",
 166     "name": "S3Access1",
 167     "path": "/application_abc/component_xyz/",
 168     "arn": "arn:aws:iam:::role/application_abc/component_xyz/S3Access1",
 169     "create_date": "2018-10-17T10:18:29.116Z",
 170     "max_session_duration": 3600,
 171     "assume_role_policy_document": "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Effect\":\"Allow\",\"Principal\":{\"AWS\":[\"arn:aws:iam:::user/TESTER2\"]},\"Action\":[\"sts:AssumeRole\"]}]}"
 172   }
 173
 174
 175 In the above example, we are modifying the Principal from TESTER to TESTER2 in its assume role policy document.
 176
 177 Add/ Update a Policy attached to a Role
 178 ---------------------------------------
 179
 180 To add or update the inline policy attached to a role, execute the following::
 181
 182         radosgw-admin role policy put --role-name={role-name} --policy-name={policy-name} --policy-doc={permission-policy-doc}
 183
 184 Request Parameters
 185 ~~~~~~~~~~~~~~~~~~
 186
 187 ``role-name``
 188
 189 :Description: Name of the role.
 190 :Type: String
 191
 192 ``policy-name``
 193
 194 :Description: Name of the policy.
 195 :Type: String
 196
 197 ``policy-doc``
 198
 199 :Description: The Permission policy document.
 200 :Type: String
 201
 202 For example::
 203
 204   radosgw-admin role-policy put --role-name=S3Access1 --policy-name=Policy1 --policy-doc=\{\"Version\":\"2012-10-17\",\"Statement\":\[\{\"Effect\":\"Allow\",\"Action\":\[\"s3:*\"\],\"Resource\":\"arn:aws:s3:::example_bucket\"\}\]\}
 205
 206 In the above example, we are attaching a policy 'Policy1' to role 'S3Access1', which allows all s3 actions on 'example_bucket'.
 207
 208 List Permission Policy Names attached to a Role
 209 -----------------------------------------------
 210
 211 To list the names of permission policies attached to a role, execute the following::
 212
 213         radosgw-admin role policy get --role-name={role-name}
 214
 215 Request Parameters
 216 ~~~~~~~~~~~~~~~~~~
 217
 218 ``role-name``
 219
 220 :Description: Name of the role.
 221 :Type: String
 222
 223 For example::
 224
 225   radosgw-admin role-policy list --role-name=S3Access1
 226
 227 .. code-block:: javascript
 228
 229   [
 230     "Policy1"
 231   ]
 232
 233
 234 Get Permission Policy attached to a Role
 235 ----------------------------------------
 236
 237 To get a specific permission policy attached to a role, execute the following::
 238
 239         radosgw-admin role policy get --role-name={role-name} --policy-name={policy-name}
 240
 241 Request Parameters
 242 ~~~~~~~~~~~~~~~~~~
 243
 244 ``role-name``
 245
 246 :Description: Name of the role.
 247 :Type: String
 248
 249 ``policy-name``
 250
 251 :Description: Name of the policy.
 252 :Type: String
 253
 254 For example::
 255
 256   radosgw-admin role-policy get --role-name=S3Access1 --policy-name=Policy1
 257
 258 .. code-block:: javascript
 259
 260   {
 261     "Permission policy": "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Effect\":\"Allow\",\"Action\":[\"s3:*\"],\"Resource\":\"arn:aws:s3:::example_bucket\"}]}"
 262   }
 263
 264
 265 Delete Policy attached to a Role
 266 --------------------------------
 267
 268 To delete permission policy attached to a role, execute the following::
 269
 270         radosgw-admin role policy delete --role-name={role-name} --policy-name={policy-name}
 271
 272 Request Parameters
 273 ~~~~~~~~~~~~~~~~~~
 274
 275 ``role-name``
 276
 277 :Description: Name of the role.
 278 :Type: String
 279
 280 ``policy-name``
 281
 282 :Description: Name of the policy.
 283 :Type: String
 284
 285 For example::
 286
 287   radosgw-admin role-policy delete --role-name=S3Access1 --policy-name=Policy1
 288
 289
 290 REST APIs for Manipulating a Role
 291 =================================
 292
 293 In addition to the above radosgw-admin commands, the following REST APIs can be used for manipulating a role. For the request parameters and their explanations, refer to the sections above.
 294
 295 In order to invoke the REST admin APIs, a user with admin caps needs to be created.
 296
 297 .. code-block:: javascript
 298
 299   radosgw-admin --uid TESTER --display-name "TestUser" --access_key TESTER --secret test123 user create
 300   radosgw-admin caps add --uid="TESTER" --caps="roles=*"
 301
 302
 303 Create a Role
 304 -------------
 305
 306 Example::
 307   POST "<hostname>?Action=CreateRole&RoleName=S3Access&Path=/application_abc/component_xyz/&AssumeRolePolicyDocument=\{\"Version\":\"2012-10-17\",\"Statement\":\[\{\"Effect\":\"Allow\",\"Principal\":\{\"AWS\":\[\"arn:aws:iam:::user/TESTER\"\]\},\"Action\":\[\"sts:AssumeRole\"\]\}\]\}"
 308
 309 .. code-block:: XML
 310
 311   <role>
 312     <id>8f41f4e0-7094-4dc0-ac20-074a881ccbc5</id>
 313     <name>S3Access</name>
 314     <path>/application_abc/component_xyz/</path>
 315     <arn>arn:aws:iam:::role/application_abc/component_xyz/S3Access</arn>
 316     <create_date>2018-10-23T07:43:42.811Z</create_date>
 317     <max_session_duration>3600</max_session_duration>
 318     <assume_role_policy_document>{"Version":"2012-10-17","Statement":[{"Effect":"Allow","Principal":{"AWS":["arn:aws:iam:::user/TESTER"]},"Action":["sts:AssumeRole"]}]}</assume_role_policy_document>
 319   </role>
 320
 321
 322 Delete a Role
 323 -------------
 324
 325 Example::
 326   POST "<hostname>?Action=DeleteRole&RoleName=S3Access"
 327
 328 Note: A role can be deleted only when it doesn't have any permission policy attached to it.
 329
 330 Get a Role
 331 ----------
 332
 333 Example::
 334   POST "<hostname>?Action=GetRole&RoleName=S3Access"
 335
 336 .. code-block:: XML
 337
 338   <role>
 339     <id>8f41f4e0-7094-4dc0-ac20-074a881ccbc5</id>
 340     <name>S3Access</name>
 341     <path>/application_abc/component_xyz/</path>
 342     <arn>arn:aws:iam:::role/application_abc/component_xyz/S3Access</arn>
 343     <create_date>2018-10-23T07:43:42.811Z</create_date>
 344     <max_session_duration>3600</max_session_duration>
 345     <assume_role_policy_document>{"Version":"2012-10-17","Statement":[{"Effect":"Allow","Principal":{"AWS":["arn:aws:iam:::user/TESTER"]},"Action":["sts:AssumeRole"]}]}</assume_role_policy_document>
 346   </role>
 347
 348
 349 List Roles
 350 ----------
 351
 352 Example::
 353   POST "<hostname>?Action=ListRoles&RoleName=S3Access&PathPrefix=/application"
 354
 355 .. code-block:: XML
 356
 357   <role>
 358     <id>8f41f4e0-7094-4dc0-ac20-074a881ccbc5</id>
 359     <name>S3Access</name>
 360     <path>/application_abc/component_xyz/</path>
 361     <arn>arn:aws:iam:::role/application_abc/component_xyz/S3Access</arn>
 362     <create_date>2018-10-23T07:43:42.811Z</create_date>
 363     <max_session_duration>3600</max_session_duration>
 364     <assume_role_policy_document>{"Version":"2012-10-17","Statement":[{"Effect":"Allow","Principal":{"AWS":["arn:aws:iam:::user/TESTER"]},"Action":["sts:AssumeRole"]}]}</assume_role_policy_document>
 365   </role>
 366
 367
 368 Update Assume Role Policy Document
 369 ----------------------------------
 370
 371 Example::
 372   POST "<hostname>?Action=UpdateAssumeRolePolicy&RoleName=S3Access&PolicyDocument=\{\"Version\":\"2012-10-17\",\"Statement\":\[\{\"Effect\":\"Allow\",\"Principal\":\{\"AWS\":\[\"arn:aws:iam:::user/TESTER2\"\]\},\"Action\":\[\"sts:AssumeRole\"\]\}\]\}"
 373
 374 Add/ Update a Policy attached to a Role
 375 ---------------------------------------
 376
 377 Example::
 378   POST "<hostname>?Action=PutRolePolicy&RoleName=S3Access&PolicyName=Policy1&PolicyDocument=\{\"Version\":\"2012-10-17\",\"Statement\":\[\{\"Effect\":\"Allow\",\"Action\":\[\"s3:CreateBucket\"\],\"Resource\":\"arn:aws:s3:::example_bucket\"\}\]\}"
 379
 380 List Permission Policy Names attached to a Role
 381 -----------------------------------------------
 382
 383 Example::
 384   POST "<hostname>?Action=ListRolePolicies&RoleName=S3Access"
 385
 386 .. code-block:: XML
 387
 388   <PolicyNames>
 389     <member>Policy1</member>
 390   </PolicyNames>
 391
 392
 393 Get Permission Policy attached to a Role
 394 ----------------------------------------
 395
 396 Example::
 397   POST "<hostname>?Action=GetRolePolicy&RoleName=S3Access&PolicyName=Policy1"
 398
 399 .. code-block:: XML
 400
 401   <GetRolePolicyResult>
 402     <PolicyName>Policy1</PolicyName>
 403     <RoleName>S3Access</RoleName>
 404     <Permission_policy>{"Version":"2012-10-17","Statement":[{"Effect":"Allow","Action":["s3:CreateBucket"],"Resource":"arn:aws:s3:::example_bucket"}]}</Permission_policy>
 405   </GetRolePolicyResult>
 406
 407
 408 Delete Policy attached to a Role
 409 --------------------------------
 410
 411 Example::
 412   POST "<hostname>?Action=DeleteRolePolicy&RoleName=S3Access&PolicyName=Policy1"
 413
 414 Tag a role
 415 ----------
 416 A role can have multivalued tags attached to it. These tags can be passed in as part of CreateRole REST API also.
 417 AWS does not support multi-valued role tags.
 418
 419 Example::
 420   POST "<hostname>?Action=TagRole&RoleName=S3Access&Tags.member.1.Key=Department&Tags.member.1.Value=Engineering"
 421
 422 .. code-block:: XML
 423
 424   <TagRoleResponse>
 425     <ResponseMetadata>
 426       <RequestId>tx000000000000000000004-00611f337e-1027-default</RequestId>
 427     </ResponseMetadata>
 428   </TagRoleResponse>
 429
 430
 431 List role tags
 432 --------------
 433 Lists the tags attached to a role.
 434
 435 Example::
 436   POST "<hostname>?Action=ListRoleTags&RoleName=S3Access"
 437
 438 .. code-block:: XML
 439
 440   <ListRoleTagsResponse>
 441     <ListRoleTagsResult>
 442       <Tags>
 443         <member>
 444           <Key>Department</Key>
 445           <Value>Engineering</Value>
 446         </member>
 447       </Tags>
 448     </ListRoleTagsResult>
 449     <ResponseMetadata>
 450       <RequestId>tx000000000000000000005-00611f337e-1027-default</RequestId>
 451     </ResponseMetadata>
 452   </ListRoleTagsResponse>
 453
 454 Delete role tags
 455 ----------------
 456 Delete a tag/ tags attached to a role.
 457
 458 Example::
 459   POST "<hostname>?Action=UntagRoles&RoleName=S3Access&TagKeys.member.1=Department"
 460
 461 .. code-block:: XML
 462
 463   <UntagRoleResponse>
 464     <ResponseMetadata>
 465       <RequestId>tx000000000000000000007-00611f337e-1027-default</RequestId>
 466     </ResponseMetadata>
 467   </UntagRoleResponse>
 468
 469
 470 Sample code for tagging, listing tags and untagging a role
 471 ----------------------------------------------------------
 472
 473 The following is sample code for adding tags to role, listing tags and untagging a role using boto3.
 474
 475 .. code-block:: python
 476
 477     import boto3
 478
 479     access_key = 'TESTER'
 480     secret_key = 'test123'
 481
 482     iam_client = boto3.client('iam',
 483     aws_access_key_id=access_key,
 484     aws_secret_access_key=secret_key,
 485     endpoint_url='http://s3.us-east.localhost:8000',
 486     region_name=''
 487     )
 488
 489     policy_document = "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Effect\":\"Allow\",\"Principal\":{\"Federated\":[\"arn:aws:iam:::oidc-provider/localhost:8080/auth/realms/quickstart\"]},\"Action\":[\"sts:AssumeRoleWithWebIdentity\"],\"Condition\":{\"StringEquals\":{\"localhost:8080/auth/realms/quickstart:sub\":\"user1\"}}}]}"
 490
 491     print ("\n Creating Role with tags\n")
 492     tags_list = [
 493         {'Key':'Department','Value':'Engineering'}
 494     ]
 495     role_response = iam_client.create_role(
 496         AssumeRolePolicyDocument=policy_document,
 497         Path='/',
 498         RoleName='S3Access',
 499         Tags=tags_list,
 500     )
 501
 502     print ("Adding tags to role\n")
 503     response = iam_client.tag_role(
 504                 RoleName='S3Access',
 505                 Tags= [
 506                         {'Key':'CostCenter','Value':'123456'}
 507                     ]
 508                 )
 509     print ("Listing role tags\n")
 510     response = iam_client.list_role_tags(
 511                 RoleName='S3Access'
 512                 )
 513     print (response)
 514     print ("Untagging role\n")
 515     response = iam_client.untag_role(
 516         RoleName='S3Access',
 517         TagKeys=[
 518             'Department',
 519         ]
 520     )
 521
 522
 523