fmorg-git commented on code in PR #510: URL: https://github.com/apache/ozone-site/pull/510#discussion_r3669563118
########## docs/04-user-guide/01-client-interfaces/03-s3/03-sts.md: ########## @@ -0,0 +1,591 @@ +--- +sidebar_label: Ozone S3 STS +--- + +# Ozone S3 Security Token Service (STS) + +This guide explains how to enable, configure, and use Ozone STS to issue short-lived S3 credentials through the AWS-compatible (at least for the supported features) **AssumeRole** API. Ozone STS is designed for scenarios such as data-lake workloads that need temporary, scoped access to Ozone buckets and keys without distributing long-lived credentials. + +## Background + +Ozone S3 credentials are normally tied to a Kerberos identity. STS adds a programmatic path to obtain **temporary** credentials (access key, secret key, and session token) that inherit permissions from a Ranger **role**, optionally narrowed further by an inline **IAM session policy**. + +The initial implementation: + +- Exposes a dedicated STS endpoint on the S3 Gateway (separate from the S3 object API port). +- Support the **AssumeRole** API. +- Requires **Apache Ranger** for authorization. + +## How Ozone STS Works + +1. A user with permanent S3 credentials calls **AssumeRole** on the STS endpoint. +2. Ozone validates the request signature and asks Ranger whether the caller may assume the target role. +3. If an optional inline session policy (`Policy` parameter) is supplied, Ozone converts it to Ranger permissions and actions via the `IamSessionPolicyResolver` Java class. +4. On success, Ozone returns temporary credentials: + - **AccessKeyId** — begins with `ASIA` + - **SecretAccessKey** + - **SessionToken** — opaque, server-side stateless token +5. Subsequent S3 API calls use the temporary credentials and must include the session token in the `x-amz-security-token` header. If an optional inline session policy was supplied in the initial AssumeRole call, the permissions and actions for the inline policy will be intersected with the role's permissions for authorization. Otherwise, the role's permissions only will be used for authorization. + +Temporary credential lifetime is **15 minutes to 12 hours** (900–43,200 seconds). If `DurationSeconds` is omitted, the token's expiration defaults to 3600 seconds (1 hour) per the AWS specification. + +## Prerequisites + +Before using STS, you need: + +1. **Secure Ozone cluster** with Kerberos and Ranger enabled. +2. **Ranger Ozone plugin** installed on OM/S3G with `RangerOzoneAuthorizer` configured (see [Configuring Apache Ranger](../configuration/security/ranger)). +3. **Permanent S3 credentials** for the calling user: + +```shell +kinit my-service-user +ozone s3 getsecret +# awsAccessKey=... +# awsSecret=... +``` + +4. **Ranger roles and policies**: + - Create a Ranger **role** for each role that can be assumed. + - Grant the calling user **assume_role** permission on that role. + - Grant the role the resource permissions and actions it needs (volume/bucket/key) via resource policies. + +The role name in `RoleArn` must match the Ranger role name: + +``` +arn:aws:iam::123456789012:role/my-data-reader-role + ^^^^^^^^^^^^^^^^^^^^ + Ranger role name +``` + +The account ID (`123456789012`) is accepted for AWS compatibility but is not used for authorization. + +Set environment variable `RANGER_URL` to your Ranger Admin base URL (for example `http://localhost:6080`) and environment variable `RANGER_SERVICE` to your Ozone Ranger service name (for example `dev_ozone`). The curl examples below authenticate to Ranger Admin with `-u admin:rangerR0cks!` (replace with your Ranger Admin username and password). Review Comment: updated to be more clear that this related to setting Ranger policies when using `curl` - 849a1bff17dd3aa06afb61748fe16caf1eb58261 ########## docs/04-user-guide/01-client-interfaces/03-s3/03-sts.md: ########## @@ -0,0 +1,591 @@ +--- +sidebar_label: Ozone S3 STS +--- + +# Ozone S3 Security Token Service (STS) + +This guide explains how to enable, configure, and use Ozone STS to issue short-lived S3 credentials through the AWS-compatible (at least for the supported features) **AssumeRole** API. Ozone STS is designed for scenarios such as data-lake workloads that need temporary, scoped access to Ozone buckets and keys without distributing long-lived credentials. + +## Background + +Ozone S3 credentials are normally tied to a Kerberos identity. STS adds a programmatic path to obtain **temporary** credentials (access key, secret key, and session token) that inherit permissions from a Ranger **role**, optionally narrowed further by an inline **IAM session policy**. + +The initial implementation: + +- Exposes a dedicated STS endpoint on the S3 Gateway (separate from the S3 object API port). +- Support the **AssumeRole** API. +- Requires **Apache Ranger** for authorization. + +## How Ozone STS Works + +1. A user with permanent S3 credentials calls **AssumeRole** on the STS endpoint. +2. Ozone validates the request signature and asks Ranger whether the caller may assume the target role. +3. If an optional inline session policy (`Policy` parameter) is supplied, Ozone converts it to Ranger permissions and actions via the `IamSessionPolicyResolver` Java class. +4. On success, Ozone returns temporary credentials: + - **AccessKeyId** — begins with `ASIA` + - **SecretAccessKey** + - **SessionToken** — opaque, server-side stateless token +5. Subsequent S3 API calls use the temporary credentials and must include the session token in the `x-amz-security-token` header. If an optional inline session policy was supplied in the initial AssumeRole call, the permissions and actions for the inline policy will be intersected with the role's permissions for authorization. Otherwise, the role's permissions only will be used for authorization. + +Temporary credential lifetime is **15 minutes to 12 hours** (900–43,200 seconds). If `DurationSeconds` is omitted, the token's expiration defaults to 3600 seconds (1 hour) per the AWS specification. + +## Prerequisites + +Before using STS, you need: + +1. **Secure Ozone cluster** with Kerberos and Ranger enabled. +2. **Ranger Ozone plugin** installed on OM/S3G with `RangerOzoneAuthorizer` configured (see [Configuring Apache Ranger](../configuration/security/ranger)). +3. **Permanent S3 credentials** for the calling user: + +```shell +kinit my-service-user +ozone s3 getsecret +# awsAccessKey=... +# awsSecret=... +``` + +4. **Ranger roles and policies**: + - Create a Ranger **role** for each role that can be assumed. + - Grant the calling user **assume_role** permission on that role. + - Grant the role the resource permissions and actions it needs (volume/bucket/key) via resource policies. + +The role name in `RoleArn` must match the Ranger role name: + +``` +arn:aws:iam::123456789012:role/my-data-reader-role + ^^^^^^^^^^^^^^^^^^^^ + Ranger role name +``` + +The account ID (`123456789012`) is accepted for AWS compatibility but is not used for authorization. + +Set environment variable `RANGER_URL` to your Ranger Admin base URL (for example `http://localhost:6080`) and environment variable `RANGER_SERVICE` to your Ozone Ranger service name (for example `dev_ozone`). The curl examples below authenticate to Ranger Admin with `-u admin:rangerR0cks!` (replace with your Ranger Admin username and password). Review Comment: updated to be more clear that this relates to setting up Ranger policies when using `curl` - 849a1bff17dd3aa06afb61748fe16caf1eb58261 -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
