5 Secure Token Service is a web service in AWS that returns a set of temporary security credentials for authenticating federated users.
6 The link to official AWS documentation can be found here: https://docs.aws.amazon.com/STS/latest/APIReference/Welcome.html.
8 Ceph Object Gateway implements a subset of STS APIs that provide temporary credentials for identity and access management.
9 These temporary credentials can be used to make subsequent S3 calls which will be authenticated by the STS engine in Ceph Object Gateway.
10 Permissions of the temporary credentials can be further restricted via an IAM policy passed as a parameter to the STS APIs.
15 The following STS REST APIs have been implemented in Ceph Object Gateway:
17 1. AssumeRole: Returns a set of temporary credentials that can be used for
18 cross-account access. The temporary credentials will have permissions that are
19 allowed by both - permission policies attached with the Role and policy attached
20 with the AssumeRole API.
23 **RoleArn** (String/ Required): ARN of the Role to Assume.
25 **RoleSessionName** (String/ Required): An Identifier for the assumed role
28 **Policy** (String/ Optional): An IAM Policy in JSON format.
30 **DurationSeconds** (Integer/ Optional): The duration in seconds of the session.
31 Its default value is 3600.
33 **ExternalId** (String/ Optional): A unique Id that might be used when a role is
34 assumed in another account.
36 **SerialNumber** (String/ Optional): The Id number of the MFA device associated
37 with the user making the AssumeRole call.
39 **TokenCode** (String/ Optional): The value provided by the MFA device, if the
40 trust policy of the role being assumed requires MFA.
42 2. AssumeRoleWithWebIdentity: Returns a set of temporary credentials for users that
43 have been authenticated by a web/mobile app by an OpenID Connect /OAuth2.0 Identity Provider.
44 Currently Keycloak has been tested and integrated with RGW.
47 **RoleArn** (String/ Required): ARN of the Role to Assume.
49 **RoleSessionName** (String/ Required): An Identifier for the assumed role
52 **Policy** (String/ Optional): An IAM Policy in JSON format.
54 **DurationSeconds** (Integer/ Optional): The duration in seconds of the session.
55 Its default value is 3600.
57 **ProviderId** (String/ Optional): Fully qualified host component of the domain name
58 of the IDP. Valid only for OAuth2.0 tokens (not for OpenID Connect tokens).
60 **WebIdentityToken** (String/ Required): The OpenID Connect/ OAuth2.0 token, which the
61 application gets in return after authenticating its user with an IDP.
63 Before invoking AssumeRoleWithWebIdentity, an OpenID Connect Provider entity (which the web application
64 authenticates with), needs to be created in RGW.
66 The trust between the IDP and the role is created by adding a Condition to the role trust policy, which
67 allows access only to applications with the app id given in the trust policy document. The Condition
70 "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Effect\":\"Allow\",\"Principal\":{\"Federated\":[\"arn:aws:iam:::oidc-provider/<URL of IDP>\"]},\"Action\":[\"sts:AssumeRoleWithWebIdentity\"],\"Condition\":{\"StringEquals\":{\"<URL of IDP> :app_id\":\"<aud>\"\}\}\}\]\}"
72 The app_id in the condition above must match the 'aud' field of the incoming token.
77 The following configurable options have to be added for STS integration::
79 [client.radosgw.gateway]
80 rgw sts key = {sts key for encrypting the session token}
81 rgw s3 auth use sts = true
83 Note: By default, STS and S3 APIs co-exist in the same namespace, and both S3
84 and STS APIs can be accessed via the same endpoint in Ceph Object Gateway.
89 1. The following is an example of AssumeRole API call, which shows steps to create a role, assign a policy to it
90 (that allows access to S3 resources), assuming a role to get temporary credentials and accessing s3 resources using
91 those credentials. In this example, TESTER1 assumes a role created by TESTER, to access S3 resources owned by TESTER,
92 according to the permission policy attached to the role.
94 .. code-block:: python
98 iam_client = boto3.client('iam',
99 aws_access_key_id=<access_key of TESTER>,
100 aws_secret_access_key=<secret_key of TESTER>,
101 endpoint_url=<IAM URL>,
105 policy_document = "{\"Version\":\"2012-10-17\",\"Statement\":{\"Effect\":\"Allow\",\"Principal\":{\"AWS\":[\"arn:aws:iam:::user/TESTER1\"]},\"Action\":[\"sts:AssumeRole\"]}]}"
107 role_response = iam_client.create_role(
108 AssumeRolePolicyDocument=policy_document,
113 role_policy = "{\"Version\":\"2012-10-17\",\"Statement\":{\"Effect\":\"Allow\",\"Action\":\"s3:*\",\"Resource\":\"arn:aws:s3:::*\"}}"
115 response = iam_client.put_role_policy(
117 PolicyName='Policy1',
118 PolicyDocument=role_policy
121 sts_client = boto3.client('sts',
122 aws_access_key_id=<access_key of TESTER1>,
123 aws_secret_access_key=<secret_key of TESTER1>,
124 endpoint_url=<STS URL>,
128 response = sts_client.assume_role(
129 RoleArn=role_response['Role']['Arn'],
130 RoleSessionName='Bob',
134 s3client = boto3.client('s3',
135 aws_access_key_id = response['Credentials']['AccessKeyId'],
136 aws_secret_access_key = response['Credentials']['SecretAccessKey'],
137 aws_session_token = response['Credentials']['SessionToken'],
138 endpoint_url=<S3 URL>,
141 bucket_name = 'my-bucket'
142 s3bucket = s3client.create_bucket(Bucket=bucket_name)
143 resp = s3client.list_buckets()
145 2. The following is an example of AssumeRoleWithWebIdentity API call, where an external app that has users authenticated with
146 an OpenID Connect/ OAuth2 IDP (Keycloak in this example), assumes a role to get back temporary credentials and access S3 resources
147 according to permission policy of the role.
149 .. code-block:: python
153 iam_client = boto3.client('iam',
154 aws_access_key_id=<access_key of TESTER>,
155 aws_secret_access_key=<secret_key of TESTER>,
156 endpoint_url=<IAM URL>,
160 oidc_response = iam_client.create_open_id_connect_provider(
161 Url=<URL of the OpenID Connect Provider,
163 <Client id registered with the IDP>
166 <Thumbprint of the IDP>
170 policy_document = "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Effect\":\"Allow\",\"Principal\":{\"Federated\":[\"arn:aws:iam:::oidc-provider/localhost:8080/auth/realms/demo\"]},\"Action\":[\"sts:AssumeRoleWithWebIdentity\"],\"Condition\":{\"StringEquals\":{\"localhost:8080/auth/realms/demo:app_id\":\"customer-portal\"}}}]}"
171 role_response = iam_client.create_role(
172 AssumeRolePolicyDocument=policy_document,
177 role_policy = "{\"Version\":\"2012-10-17\",\"Statement\":{\"Effect\":\"Allow\",\"Action\":\"s3:*\",\"Resource\":\"arn:aws:s3:::*\"}}"
179 response = iam_client.put_role_policy(
181 PolicyName='Policy1',
182 PolicyDocument=role_policy
185 sts_client = boto3.client('sts',
186 aws_access_key_id=<access_key of TESTER1>,
187 aws_secret_access_key=<secret_key of TESTER1>,
188 endpoint_url=<STS URL>,
192 response = client.assume_role_with_web_identity(
193 RoleArn=role_response['Role']['Arn'],
194 RoleSessionName='Bob',
195 DurationSeconds=3600,
196 WebIdentityToken=<Web Token>
199 s3client = boto3.client('s3',
200 aws_access_key_id = response['Credentials']['AccessKeyId'],
201 aws_secret_access_key = response['Credentials']['SecretAccessKey'],
202 aws_session_token = response['Credentials']['SessionToken'],
203 endpoint_url=<S3 URL>,
206 bucket_name = 'my-bucket'
207 s3bucket = s3client.create_bucket(Bucket=bucket_name)
208 resp = s3client.list_buckets()
210 How to obtain thumbprint of an OpenID Connect Provider IDP
211 ==========================================================
212 1. Take the OpenID connect provider's URL and add /.well-known/openid-configuration
213 to it to get the URL to get the IDP's configuration document. For example, if the URL
214 of the IDP is http://localhost:8000/auth/realms/quickstart, then the URL to get the
215 document from is http://localhost:8000/auth/realms/quickstart/.well-known/openid-configuration
217 2. Use the following curl command to get the configuration document from the URL described
222 -H "Content-Type: application/x-www-form-urlencoded" \
223 "http://localhost:8000/auth/realms/quickstart/.well-known/openid-configuration" \
226 3. From the response of step 2, use the value of "jwks_uri" to get the certificate of the IDP,
227 using the following code::
230 -H "Content-Type: application/x-www-form-urlencoded" \
231 "http://$KC_SERVER/$KC_CONTEXT/realms/$KC_REALM/protocol/openid-connect/certs" \
234 3. Copy the result of "x5c" in the response above, in a file certificate.crt, and add
235 '-----BEGIN CERTIFICATE-----' at the beginning and "-----END CERTIFICATE-----"
238 4. Use the following OpenSSL command to get the certificate thumbprint::
240 openssl x509 -in certificate.crt -fingerprint -noout
242 5. The result of the above command in step 4, will be a SHA1 fingerprint, like the following::
244 SHA1 Fingerprint=F7:D7:B3:51:5D:D0:D3:19:DD:21:9A:43:A9:EA:72:7A:D6:06:52:87
246 6. Remove the colons from the result above to get the final thumbprint which can be as input
247 while creating the OpenID Connect Provider entity in IAM::
249 F7D7B3515DD0D319DD219A43A9EA727AD6065287
254 More information for role manipulation can be found here
257 OpenID Connect Provider in RGW
258 ==============================
260 More information for OpenID Connect Provider entity manipulation
264 Keycloak integration with Radosgw
265 =================================
267 Steps for integrating Radosgw with Keycloak can be found here
272 STSLite has been built on STS, and documentation for the same can be found here