ceph/doc/radosgw/STSLite.rst

   1 =========
   2 STS Lite
   3 =========
   4
   5 Ceph Object Gateway provides support for a subset of Amazon Secure Token Service
   6 (STS) APIs. STS Lite is an extension of STS and builds upon one of its APIs to
   7 decrease the load on external IDPs like Keystone and LDAP.
   8
   9 A set of temporary security credentials is returned after authenticating
  10 a set of AWS credentials with the external IDP. These temporary credentials can be used
  11 to make subsequent S3 calls which will be authenticated by the STS engine in Ceph,
  12 resulting in less load on the Keystone/ LDAP server.
  13
  14 Temporary and limited privileged credentials can be obtained for a local user
  15 also using the STS Lite API.
  16
  17 STS Lite REST APIs
  18 ==================
  19
  20 The following STS Lite REST API is part of STS Lite in Ceph Object Gateway:
  21
  22 1. GetSessionToken: Returns a set of temporary credentials for a set of AWS
  23 credentials. After initial authentication with Keystone/ LDAP, the temporary
  24 credentials returned can be used to make subsequent S3 calls. The temporary
  25 credentials will have the same permission as that of the AWS credentials.
  26
  27 Parameters:
  28     **DurationSeconds** (Integer/ Optional): The duration in seconds for which the
  29     credentials should remain valid. Its default value is 3600. Its default max
  30     value is 43200 which is can be configured using rgw sts max session duration.
  31
  32     **SerialNumber** (String/ Optional): The Id number of the MFA device associated
  33     with the user making the GetSessionToken call.
  34
  35     **TokenCode** (String/ Optional): The value provided by the MFA device, if MFA is required.
  36
  37 An administrative user needs to attach a policy to allow invocation of GetSessionToken API using its permanent
  38 credentials and to allow subsequent S3 operations invocation using only the temporary credentials returned
  39 by GetSessionToken.
  40
  41 The user attaching the policy needs to have admin caps. For example::
  42
  43     radosgw-admin caps add --uid="TESTER" --caps="user-policy=*"
  44
  45 The following is the policy that needs to be attached to a user 'TESTER1'::
  46
  47     user_policy = "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Effect\":\"Deny\",\"Action\":\"s3:*\",\"Resource\":[\"*\"],\"Condition\":{\"BoolIfExists\":{\"sts:authentication\":\"false\"}}},{\"Effect\":\"Allow\",\"Action\":\"sts:GetSessionToken\",\"Resource\":\"*\",\"Condition\":{\"BoolIfExists\":{\"sts:authentication\":\"false\"}}}]}"
  48
  49
  50 STS Lite Configuration
  51 ======================
  52
  53 The following configurable options are available for STS Lite integration::
  54
  55   [client.radosgw.gateway]
  56   rgw sts key = {sts key for encrypting the session token}
  57   rgw s3 auth use sts = true
  58
  59 The above STS configurables can be used with the Keystone configurables if one
  60 needs to use STS Lite in conjunction with Keystone. The complete set of
  61 configurable options will be::
  62
  63   [client.radosgw.gateway]
  64   rgw sts key = {sts key for encrypting/ decrypting the session token}
  65   rgw s3 auth use sts = true
  66
  67   rgw keystone url = {keystone server url:keystone server admin port}
  68   rgw keystone admin project = {keystone admin project name}
  69   rgw keystone admin tenant = {keystone service tenant name}
  70   rgw keystone admin domain = {keystone admin domain name}
  71   rgw keystone api version = {keystone api version}
  72   rgw keystone implicit tenants = {true for private tenant for each new user}
  73   rgw keystone admin password = {keystone service tenant user name}
  74   rgw keystone admin user = keystone service tenant user password}
  75   rgw keystone accepted roles = {accepted user roles}
  76   rgw keystone token cache size = {number of tokens to cache}
  77   rgw s3 auth use keystone = true
  78
  79 The details of the integrating ldap with Ceph Object Gateway can be found here:
  80 :doc:`keystone`
  81
  82 The complete set of configurables to use STS Lite with LDAP are::
  83
  84   [client.radosgw.gateway]
  85   rgw sts key = {sts key for encrypting/ decrypting the session token}
  86   rgw s3 auth use sts = true
  87
  88   rgw_s3_auth_use_ldap = true
  89   rgw_ldap_uri = {LDAP server to use}
  90   rgw_ldap_binddn = {Distinguished Name (DN) of the service account}
  91   rgw_ldap_secret = {password for the service account}
  92   rgw_ldap_searchdn = {base in the directory information tree for searching users}
  93   rgw_ldap_dnattr = {attribute being used in the constructed search filter to match a username}
  94   rgw_ldap_searchfilter = {search filter}
  95
  96 The details of the integrating ldap with Ceph Object Gateway can be found here:
  97 :doc:`ldap-auth`
  98
  99 Note: By default, STS and S3 APIs co-exist in the same namespace, and both S3
 100 and STS APIs can be accessed via the same endpoint in Ceph Object Gateway.
 101
 102 Example showing how to Use STS Lite with Keystone
 103 =================================================
 104
 105 The following are the steps needed to use STS Lite with Keystone. Boto 3.x has
 106 been used to write an example code to show the integration of STS Lite with
 107 Keystone.
 108
 109 1. Generate EC2 credentials :
 110
 111 .. code-block:: javascript
 112
 113   openstack ec2 credentials create
 114   +------------+--------------------------------------------------------+
 115   | Field      | Value                                                  |
 116   +------------+--------------------------------------------------------+
 117   | access     | b924dfc87d454d15896691182fdeb0ef                       |
 118   | links      | {u'self': u'http://192.168.0.15/identity/v3/users/     |
 119   |            | 40a7140e424f493d8165abc652dc731c/credentials/          |
 120   |            | OS-EC2/b924dfc87d454d15896691182fdeb0ef'}              |
 121   | project_id | c703801dccaf4a0aaa39bec8c481e25a                       |
 122   | secret     | 6a2142613c504c42a94ba2b82147dc28                       |
 123   | trust_id   | None                                                   |
 124   | user_id    | 40a7140e424f493d8165abc652dc731c                       |
 125   +------------+--------------------------------------------------------+
 126
 127 2. Use the credentials created in the step 1. to get back a set of temporary
 128    credentials using GetSessionToken API.
 129
 130 .. code-block:: python
 131
 132     import boto3
 133
 134     access_key = <ec2 access key>
 135     secret_key = <ec2 secret key>
 136
 137     client = boto3.client('sts',
 138     aws_access_key_id=access_key,
 139     aws_secret_access_key=secret_key,
 140     endpoint_url=<STS URL>,
 141     region_name='',
 142     )
 143
 144     response = client.get_session_token(
 145         DurationSeconds=43200
 146     )
 147
 148 3. The temporary credentials obtained in step 2. can be used for making S3 calls:
 149
 150 .. code-block:: python
 151
 152     s3client = boto3.client('s3',
 153       aws_access_key_id = response['Credentials']['AccessKeyId'],
 154       aws_secret_access_key = response['Credentials']['SecretAccessKey'],
 155       aws_session_token = response['Credentials']['SessionToken'],
 156       endpoint_url=<S3 URL>,
 157       region_name='')
 158
 159     bucket = s3client.create_bucket(Bucket='my-new-shiny-bucket')
 160     response = s3client.list_buckets()
 161     for bucket in response["Buckets"]:
 162         print("{name}\t{created}".format(
 163                     name = bucket['Name'],
 164                     created = bucket['CreationDate'],
 165         ))
 166
 167 Similar steps can be performed for using GetSessionToken with LDAP.
 168
 169 Limitations and Workarounds
 170 ===========================
 171
 172 1. Keystone currently supports only S3 requests, hence in order to successfully
 173 authenticate an STS request, the following workaround needs to be added to boto
 174 to the following file - botocore/auth.py
 175
 176 Lines 13-16 have been added as a workaround in the code block below:
 177
 178 .. code-block:: python
 179
 180   class SigV4Auth(BaseSigner):
 181     """
 182     Sign a request with Signature V4.
 183     """
 184     REQUIRES_REGION = True
 185
 186     def __init__(self, credentials, service_name, region_name):
 187         self.credentials = credentials
 188         # We initialize these value here so the unit tests can have
 189         # valid values.  But these will get overridden in ``add_auth``
 190         # later for real requests.
 191         self._region_name = region_name
 192         if service_name == 'sts':
 193             self._service_name = 's3'
 194         else:
 195             self._service_name = service_name
 196