Setting up granular access to Object Storage
You may need certain IAM permissions to carry out some actions described on this page. This means:
- you are the Owner of the Scaleway Organization in which the actions will be carried out, or
- you are an IAM user of the Organization, with a policy granting you the necessary permission sets
- You have an account and are logged into the Scaleway console
- You have configured your API keys
- You have created an Object Storage bucket
The bucket policy configurations described on this page take into consideration the 2023-04-17
version of bucket policies. If you use the 2012-10-17
version, keep in mind that everything that is not explicitly denied by a bucket policy is allowed if also allowed by an IAM policy.
For example:
- if a user has Object Storage permissions on Project A, they will have access to all buckets in said Project
- adding a bucket policy with Project B as a principal to a bucket in Project A will not remove the user’s full access to the Object Storage resources in said Project.
- If the user does not have Object Storage permissions on Project A, they will have access denied to all Object Storage resources in Project A. Unless the user has permissions on Project B, and Project B is defined as the principal of a bucket policy of a bucket in Project A, they will not gain access to a bucket without having the appropriate IAM permissions.
For the new 2023-04-17
version, everything that is not explicitly allowed by the bucket policy is denied, regardless of what is defined in the IAM policy.
Identity and Access Management (IAM) brings a set of new features to your Scaleway account, allowing you to control and manage access to your resources. For users of Scaleway Object Storage, this means that besides configuring access via bucket policies, you can now use IAM policies to configure permissions.
An IAM policy is used to define the permissions of users, groups and applications in a given Organization. A policy is composed of a principal (the user, group or application to which it applies) and one or more IAM rules (which describe the permission sets the principal should have, and the scope of those permission sets).
Bucket policies are a resource-based S3 policy option that allow you to grant users and/or applications access to a specific bucket in a project. The different component strings of a bucket policy allow you to configure fine-grained permissions.
Bucket policies behave like objects: they can be uploaded into buckets. Once you upload, or “put”, a bucket policy into a bucket, it takes immediate effect and will from then on define who can access and perform actions on the bucket.
Defining whether to use IAM or bucket policies
IAM can be used when you do not need to configure Project-level access to specific buckets, and favor simplicity over granularity. IAM is central, and policy-based: it says where people can perform actions in the entire Scaleway ecosystem. For example, if access to resources at Project level is enough for your Object Storage use cases, we advise you to use IAM only.
Bucket policies operate at the bucket level, and enable you to state clearly who can perform different actions on which specific bucket.
If you need to configure more granular access to your Object Storage buckets, you can combine both IAM and bucket policies. For example, if you must restrict access to specific actions you can perform on a bucket, or if you need the bucket to be available only to certain users, you can use a combination of IAM and bucket policies.
Combining IAM and bucket policies
In order to perform actions on a bucket, a principal (user or application) must be granted access via an IAM policy, and optionally via a bucket policy.
For example, if a user wants to list the objects in a bucket, they must ensure that:
- the IAM policy explicitly allows the user to list Objects (for example, with an
ObjectStorageReadOnly
or aObjectStorageObjectRead
permission set specified in the policy) - if there is no existing bucket policy, the action allowed by IAM is enough to grant them list access
- if there is a bucket policy, the list action is explicitly allowed in the policy
There are a couple of important things to keep in mind when using bucket and IAM policies concurrently:
- Even if you only want to define the permissions available for bucket policies, you must first define IAM policy permissions. This is a necessary step of the process.
- when you create a Scaleway API key with IAM, you are prompted to specify the API key’s preferred Project for Object Storage. This API key will always use this Project when carrying out Object Storage actions via any API/CLI.
- the preferred Project must always be the one of the bucket where you wish to perform an action.
Before the arrival of IAM principals in a Scaleway bucket policy were defined by the project_id
. Now they can either be specified by the user_id
or the application_id
.
Examples
In the sections below we provide different examples of how to combine IAM and bucket policies.
In the following examples we use fictional UUIDs as the values for the user_id
, application_id
, project_ids
and organization_id
variables. Make sure you replace these UUIDs with your own when using the referenced policies.
Allowing all actions except DeleteObject
In the example below, we provide the IAM and bucket policy configurations needed to allow an application to perform all actions in a bucket except to delete it.
An IAM policy must be created to grant full access to Object Storage resources in Project 1 to application A.
{ "name": "policy-S3-proj1", "description": "This policy grants full access to Object Storage resources in Project 1 to application A", "organization_id": "946552dd-a7dc-4d35-81df-11532f025b28", "rules": [ { "permission_set_names": [ "ObjectStorageFullAccess" ], "project_ids": [ "c6842bac-7938-4c04-9e03-f48147eee1f1" ] } ], "application_id": "950dde46-5cba-427d-a4f5-ce5a8a79717c"}
To block the deletion of objects in production-bucket-1
for application A, the bucket policy below must be combined with the IAM policy above.
{ "Version": "2023-04-17", "Id": "production-bucket-1-policy", "Statement": [ { "Sid": "allow all actions", "Effect": "Allow", "Principal": { "SCW": "application_id:950dde46-5cba-427d-a4f5-ce5a8a79717c" }, "Action": [ "s3:*" ], "Resource": [ "production-bucket-1", "production-bucket-1/*" ] }, { "Sid": "deny delete object", "Effect": "Deny", "Principal": { "SCW": "application_id:950dde46-5cba-427d-a4f5-ce5a8a79717c" }, "Action": [ "s3:DeleteObject" ], "Resource": [ "production-bucket-1/*" ] } ]}
Allowing only GetObject
In the example below, we provide the IAM and bucket policy configurations needed to allow an application only to retrieve information about objects in a bucket.
An IAM policy must be created to grant full access to Object Storage resources in Project 1 to application A.
{ "name": "policy-S3-proj1", "description": "This policy grants full access to Object Storage resources in Project 1 to application A", "organization_id": "946552dd-a7dc-4d35-81df-11532f025b28", "rules": [ { "permission_set_names": [ "ObjectStorageFullAccess" ], "project_ids": [ "c6842bac-7938-4c04-9e03-f48147eee1f1" ] } ], "application_id": "950dde46-5cba-427d-a4f5-ce5a8a79717c"}
To block all actions besides GetObject
, only an explicit Allow
is necessary. Whenever an action is not explicitly allowed, it is automatically denied. The bucket policy below must be combined with the IAM policy above.
{ "Version": "2023-04-17", "Id": "production-bucket-1-policy", "Statement": [ { "Sid": "allow get object", "Effect": "Allow", "Principal": { "SCW": "application_id:950dde46-5cba-427d-a4f5-ce5a8a79717c" }, "Action": [ "s3:GetObject" ], "Resource": [ "production-bucket-1/*" ] } ]}
Denying all actions by not including an explicit allow
In the example below, we provide the IAM and bucket policy configurations needed to deny a user to perform any actions on a bucket.
An IAM policy must be created to grant full access to Object Storage resources in Project 1 to application A.
{ "name": "policy-s3-proj1", "description": "This policy grants full access to Object Storage resources in Project 1 to user B", "organization_id": "946552dd-a7dc-4d35-81df-11532f025b28", "rules": [ { "permission_set_names": [ "ObjectStorageFullAccess" ], "project_ids": [ "c6842bac-7938-4c04-9e03-f48147eee1f1" ] } ], "user_id": "81a2ad27-2273-4bf9-976f-3f06957ab6e1"}
Whenever an action is not explicitly allowed, it is automatically denied. In the bucket policy below we explicitly deny the GetObject
action, but do not allow any others. This means that by default all actions will be denied.
{ "Version": "2023-04-17", "Id": "production-bucket-1-policy", "Statement": [ { "Sid": "deny get object", "Effect": "Deny", "Principal": { "SCW": "user_id:81a2ad27-2273-4bf9-976f-3f06957ab6e1" }, "Action": [ "s3:GetObject" ], "Resource": [ "production-bucket-1/*" ] } ]}
Giving a application full access to a bucket
In the example below, we provide the IAM and bucket policy configurations needed to give an application within an IAM group full access to a bucket. This means only one application within the IAM group will be able to perform any of the available S3 actions on the bucket.
An IAM policy must be created to grant full access to Object Storage resources in Project 1 to group Alpha, which includes application A, user B and application C.
{ "name": "policy-S3-proj1", "description": "This policy grants full access to Object Storage resources in Project 1 to applications A and C, and user B", "organization_id": "946552dd-a7dc-4d35-81df-11532f025b28", "rules": [ { "permission_set_names": [ "ObjectStorageFullAccess" ], "project_ids": [ "c6842bac-7938-4c04-9e03-f48147eee1f1" ] } ], "group_id": "ec204230-2011-4ac6-b86e-1d960b4c54cd"}
In the bucket policy below, we declare that all available actions are allowed for application A. We set the action field to *
to include all available bucket actions in the statement, and we set the effect to Allow
.
Even if, in this example, all users and applications in group Alpha have full access to Object Storage through the IAM policy, the existing bucket policy only explicitly allows actions for application A. This means all other members in the group are automatically denied permissions to perform actions, since they are not explicitly allowed to do so.
{ "Version": "2023-04-17", "Id": "production-bucket-1-policy", "Statement": [ { "Sid": "allow all actions", "Effect": "Allow", "Principal": { "SCW": "application_id:950dde46-5cba-427d-a4f5-ce5a8a79717c" }, "Action": [ "*" ], "Resource": [ "production-bucket-1", "production-bucket-1/*" ] } ]}