# oss-access

Part of **OSS**

<!-- intent-backlink:auto -->

> 💡 **Path Selection**: This skill is one implementation path for [Configure bucket-level security policies](../../intent/oss-configure-security/SKILL.md). If you're unsure which path to take, check the routing skill first.

# Object Storage Service Access Control CLI Reference

## Command Overview

| Command | Purpose | Syntax |
|--------|---------|--------|
| create-access-point | Create an access point for a bucket | `ossutil api create-access-point --bucket BUCKET --create-access-point-configuration CONFIG` |
| delete-access-point | Delete an access point | `ossutil api delete-access-point --bucket BUCKET --access-point-name NAME` |
| list-access-points | List access points in a bucket or account | `ossutil api list-access-points [flags]` |
| get-access-point | Retrieve details of an access point | `ossutil api get-access-point --bucket BUCKET --access-point-name NAME [flags]` |
| put-access-point-policy | Attach a policy to an access point | `ossutil api put-access-point-policy --bucket BUCKET --access-point-name NAME --body POLICY` |
| get-access-point-policy | Retrieve the policy attached to an access point | `ossutil api get-access-point-policy --bucket BUCKET --access-point-name NAME` |
| delete-access-point-policy | Remove the policy from an access point | `ossutil api delete-access-point-policy --bucket BUCKET --access-point-name NAME` |
| delete-access-point-public-access-block | Remove public access block from an access point | `ossutil api delete-access-point-public-access-block --bucket BUCKET --access-point-name NAME` |
| delete-bucket-public-access-block | Remove public access block from a bucket | `ossutil api delete-bucket-public-access-block --bucket BUCKET` |
| bucket-cname | Manage CNAME tokens and configurations | `ossutil bucket-cname --method METHOD [flags]` |

## Command Details

### create-access-point

**Purpose**: Create an access point for secure and controlled access to an OSS bucket.

**Syntax**:
```bash
ossutil api create-access-point --bucket BUCKET --create-access-point-configuration CONFIG
```

| Parameter | Short | Type | Required | Description |
|----------|-------|------|----------|-------------|
| --bucket | — | string | Yes | The name of the bucket. |
| --create-access-point-configuration | — | string | Yes | Configuration as inline JSON/XML or file path prefixed with `file://`. |

```bash
# Create access point using XML config file
ossutil api create-access-point --bucket examplebucket --create-access-point-configuration file://create-access-point-configuration.xml

# Create access point using JSON config file
ossutil api create-access-point --bucket examplebucket --create-access-point-configuration file://create-access-monitor-configuration.json

# Create access point with inline JSON
ossutil api create-access-point --bucket examplebucket --create-access-point-configuration "{\"AccessPointName\":\"ap-01\",\"NetworkOrigin\":\"internet\"}"
```

### delete-access-point

**Purpose**: Delete an existing access point associated with a bucket.

**Syntax**:
```bash
ossutil api delete-access-point --bucket BUCKET --access-point-name NAME
```

| Parameter | Short | Type | Required | Description |
|----------|-------|------|----------|-------------|
| --bucket | — | string | Yes | Name of the bucket. |
| --access-point-name | — | string | Yes | Name of the access point to delete. |

```bash
# Delete access point named ap-01 from examplebucket
ossutil api delete-access-point --bucket examplebucket --access-point-name ap-01
```

### list-access-points

**Purpose**: List all access points in the account or within a specific bucket.

**Syntax**:
```bash
ossutil api list-access-points [--bucket BUCKET] [--continuation-token TOKEN] [--max-keys N] [--output-format FORMAT]
```

| Parameter | Short | Type | Required | Description |
|----------|-------|------|----------|-------------|
| --bucket | — | string | No | The name of the bucket to filter results. |
| --continuation-token | — | string | No | Token to resume listing from a previous response. |
| --max-keys | — | string | No | Maximum number of access points to return (e.g., "10"). |
| --output-format | — | string | No | Output format: `json` or `yaml` (default: `json`). |

```bash
# List all access points in the account
ossutil api list-access-points

# List access points in examplebucket in JSON format
ossutil api list-access-points --bucket examplebucket --output-format json

# List up to 10 access points starting from a token
ossutil api list-access-points --max-keys 10 --continuation-token CgJiYw123
```

### get-access-point

**Purpose**: Retrieve detailed information about a specific access point.

**Syntax**:
```bash
ossutil api get-access-point --bucket BUCKET --access-point-name NAME [--output-format FORMAT]
```

| Parameter | Short | Type | Required | Description |
|----------|-------|------|----------|-------------|
| --bucket | — | string | Yes | Name of the bucket. |
| --access-point-name | — | string | Yes | Name of the access point. |
| --output-format | — | string | No | Output format: `json` or `yaml` (default: `json`). |

```bash
# Get access point info in default JSON format
ossutil api get-access-point --bucket examplebucket --access-point-name ap-01

# Explicitly request YAML output
ossutil api get-access-point --bucket examplebucket --access-point-name ap-01 --output-format yaml
```

### put-access-point-policy

**Purpose**: Attach a JSON-formatted policy to an access point to define permissions.

**Syntax**:
```bash
ossutil api put-access-point-policy --bucket BUCKET --access-point-name NAME --body POLICY
```

| Parameter | Short | Type | Required | Description |
|----------|-------|------|----------|-------------|
| --bucket | — | string | Yes | Name of the bucket. |
| --access-point-name | — | string | Yes | Name of the access point. |
| --body | — | string | Yes | Policy as inline JSON or file path prefixed with `file://`. |

```bash
# Apply policy from a JSON file
ossutil api put-access-point-policy --bucket examplebucket --access-point-name ap-01 --body file://access-point-name.json

# Apply inline deny policy
ossutil api put-access-point-policy --bucket examplebucket --access-point-name ap-01 --body "{\"Version\":\"1\",\"Statement\":[{\"Action\":[\"oss:PutObject\",\"oss:GetObject\"],\"Effect\":\"Deny\",\"Principal\":[\"27737962156157xxxx\"],\"Resource\":[\"acs:oss:cn-hangzhou:111933544165xxxx:accesspoint/$ap-01\",\"acs:oss:cn-hangzhou:111933544165xxxx:accesspoint/ap-01/object/*\"]}]}"
```

### get-access-point-policy

**Purpose**: Retrieve the policy currently attached to an access point.

**Syntax**:
```bash
ossutil api get-access-point-policy --bucket BUCKET --access-point-name NAME
```

| Parameter | Short | Type | Required | Description |
|----------|-------|------|----------|-------------|
| --bucket | — | string | Yes | Name of the bucket. |
| --access-point-name | — | string | Yes | Name of the access point. |

```bash
# Get the policy for access point ap-01
ossutil api get-access-point-policy --bucket examplebucket --access-point-name ap-01
```

**Output Example**:
```text
{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": "*",
      "Action": "oss:GetObject",
      "Resource": "acs:oss:cn-hangzhou:111933544165xxxx:accesspoint/ap-01/object/*"
    }
  ]
}
```

### delete-access-point-policy

**Purpose**: Remove the policy attached to an access point.

**Syntax**:
```bash
ossutil api delete-access-point-policy --bucket BUCKET --access-point-name NAME
```

| Parameter | Short | Type | Required | Description |
|----------|-------|------|----------|-------------|
| --bucket | — | string | Yes | Name of the bucket. |
| --access-point-name | — | string | Yes | Name of the access point. |

```bash
# Delete the policy from access point ap-01
ossutil api delete-access-point-policy --bucket examplebucket --access-point-name ap-01
```

### delete-access-point-public-access-block

**Purpose**: Remove the public access block configuration from an access point.

**Syntax**:
```bash
ossutil api delete-access-point-public-access-block --bucket BUCKET --access-point-name NAME
```

| Parameter | Short | Type | Required | Description |
|----------|-------|------|----------|-------------|
| --bucket | — | string | Yes | Name of the bucket. |
| --access-point-name | — | string | Yes | Name of the access point. |

```bash
# Remove public access block from ap-01
ossutil api delete-access-point-public-access-block --bucket examplebucket --access-point-name ap-01
```

### delete-bucket-public-access-block

**Purpose**: Remove the public access block configuration from a bucket.

**Syntax**:
```bash
ossutil api delete-bucket-public-access-block --bucket BUCKET
```

| Parameter | Short | Type | Required | Description |
|----------|-------|------|----------|-------------|
| --bucket | — | string | Yes | Name of the bucket. |

```bash
# Remove public access block from examplebucket
ossutil api delete-bucket-public-access-block --bucket examplebucket
```

### bucket-cname

**Purpose**: Manage CNAME tokens and configurations for custom domain mapping to buckets.

**Syntax**:
```bash
ossutil bucket-cname --method METHOD [--item ITEM] oss://BUCKET [DOMAIN] [FILE] [flags]
```

| Parameter | Short | Type | Required | Description |
|----------|-------|------|----------|-------------|
| --method | — | string | Yes | Operation: `put`, `get`, or `delete`. |
| --item | — | string | No | When method=put: `token` or `certificate`. |
| bucketname (positional) | — | string | Yes | Bucket name (as `oss://examplebucket`). |
| domainname (positional) | — | string | Conditional | Custom domain name (required for most operations). |
| local_xml_file (positional) | — | string | No | Local file path for certificate input or output. |
| -e | — | string | No | Endpoint URL (e.g., `oss-cn-hangzhou.aliyuncs.com`). |
| -i | — | string | No | AccessKey ID. |
| -k | — | string | No | AccessKey Secret. |

```bash
# Create a CNAME token for example.com
ossutil bucket-cname --method put --item token oss://examplebucket example.com

# Retrieve CNAME token
ossutil bucket-cname --method get --item token oss://examplebucket example.com

# Add CNAME record (after DNS verification)
ossutil bucket-cname --method put oss://examplebucket example.com

# List all CNAME configurations for a bucket
ossutil bucket-cname --method get oss://examplebucket

# Associate an SSL certificate (from local.xml)
ossutil bucket-cname --method put --item certificate oss://examplebucket local.xml

# Delete a CNAME record
ossutil bucket-cname --method delete oss://examplebucket example.com

# Full command with explicit credentials and endpoint
ossutil bucket-cname --method put oss://testbucket example.org -e oss-cn-hangzhou.aliyuncs.com -i yourAccessKeyID -k yourAccessKeySecret
```

**Output Example**:
```text
<CnameToken>
 <Bucket>examplebucket</Bucket>
 <Cname>example.com</Cname>
 <Token>4db41c3ad0c4c4b690d4c17fb34e****</Token>
 <ExpireTime>Thu, 26 May 2022 19:14:12 GMT</ExpireTime>
</CnameToken>

0.270654(s) elapsed
```

## Common Scenarios

### Scenario 1: Set Up Secure Access Point with Policy

```bash
# Step 1: Create an access point for internet-origin access
ossutil api create-access-point --bucket mydata --create-access-point-configuration "{\"AccessPointName\":\"secure-ap\",\"NetworkOrigin\":\"internet\"}"

# Step 2: Define a restrictive policy in a file (secure-ap-policy.json)
# (Assume file contains appropriate JSON policy)

# Step 3: Attach the policy to the access point
ossutil api put-access-point-policy --bucket mydata --access-point-name secure-ap --body file://secure-ap-policy.json

# Step 4: Verify the policy was applied
ossutil api get-access-point-policy --bucket mydata --access-point-name secure-ap
```

### Scenario 2: Configure Custom Domain with SSL

```bash
# Step 1: Generate a CNAME token for your domain
ossutil bucket-cname --method put --item token oss://mywebsite example.com

# Step 2: Add a TXT record in your DNS provider using the returned token
# (Manual step outside CLI)

# Step 3: After DNS propagation, add the CNAME record
ossutil bucket-cname --method put oss://mywebsite example.com

# Step 4: Upload SSL certificate (assume cert.xml contains cert info)
ossutil bucket-cname --method put --item certificate oss://mywebsite cert.xml

# Step 5: Verify configuration
ossutil bucket-cname --method get oss://mywebsite
```

## Environment Setup

### Installation
Install `ossutil` by downloading the binary from the official Alibaba Cloud OSS documentation or using package managers as described in the installation guide. Ensure the binary is in your system PATH.

### Configuration
Configure credentials and region using one of the following methods:

1. **Environment variables**:
   ```bash
   export OSS_ACCESS_KEY_ID=yourAccessKeyID
   export OSS_ACCESS_KEY_SECRET=yourAccessKeySecret
   export OSS_ENDPOINT=oss-cn-hangzhou.aliyuncs.com
   ```

2. **Configuration file** (`~/.ossutilconfig`):
   ```ini
   [Credentials]
   language=EN
   accessKeyId=yourAccessKeyID
   accessKeySecret=yourAccessKeySecret
   endpoint=oss-cn-hangzhou.aliyuncs.com
   ```

3. **Inline flags** (for one-off commands):
   Use `-e`, `-i`, and `-k` flags with `bucket-cname` commands as shown in examples.

Ensure your account or RAM user has required permissions such as `oss:CreateAccessPoint`, `oss:PutAccessPointPolicy`, `oss:CreateCnameToken`, etc.

## FAQ

Q: How do I configure credentials for ossutil?
A: You can configure credentials via environment variables (`OSS_ACCESS_KEY_ID`, `OSS_ACCESS_KEY_SECRET`), a config file at `~/.ossutilconfig`, or by passing `-i` and `-k` flags directly in commands that support them (like `bucket-cname`). For API-level commands (e.g., `create-access-point`), use the config file or environment variables.

Q: What is the difference between `--create-access-point-configuration` and `--body` in policy commands?
A: `--create-access-point-configuration` is used with `create-access-point` to define metadata like name and network origin. `--body` is used with `put-access-point-policy` to specify the JSON policy document that defines permissions.

Q: How do I verify that a CNAME configuration is working?
A: After adding the CNAME record, run `ossutil bucket-cname --method get oss://BUCKET` to check the status. It should show `Enabled`. Also, test accessing your bucket via the custom domain in a browser or with `curl`.

Q: Are there limits on the number of access points or CNAME records?
A: Yes. You can create up to 1,000 access points per account and 100 per bucket. For CNAME, you can configure up to 100 custom domains per bucket.

Q: Why am I getting a 403 error when running these commands?
A: A 403 error indicates insufficient permissions. Ensure your RAM user or role has the required OSS permissions (e.g., `oss:CreateAccessPoint`, `oss:PutCname`). Check your policy attachments and verify the resource ARNs match your bucket and region.