Use the Go SDK to configure Referer-based hotlink protection to prevent other websites from referencing OSS files - Object Storage Service

You can use the Go SDK for Alibaba Cloud OSS to configure access rules based on the Referer request header, including setting a Referer whitelist, a Referer blacklist, and specifying whether to allow empty Referer headers. This lets you block specific Referers from accessing your OSS files, prevent other websites from hotlinking your resources, and avoid unnecessary traffic costs.

Usage notes

Before you configure hotlink protection, make sure that you familiarize yourself with this feature. For more information, see Hotlink protection.
In this topic, the public endpoint of the China (Hangzhou) region is used. If you want to access OSS from other Alibaba Cloud services in the same region as OSS, use an internal endpoint. For more information about OSS regions and endpoints, see Regions and endpoints.
In this topic, access credentials are obtained from environment variables. For more information about how to configure access credentials, see Configure access credentials.
In this topic, an OSSClient instance is created by using an OSS endpoint. If you want to create an OSSClient instance by using custom domain names or Security Token Service (STS), see Configure a client (Go SDK V1).
To configure hotlink protection, you must have the oss:PutBucketReferer permission. To query hotlink protection configurations, you must have the oss:GetBucketReferer permission. For more information, see Attach a custom policy to a RAM user.

Sample code

Configure hotlink protection

The following code shows how to configure hotlink protection.

package main

import (
	"log"

	"github.com/aliyun/aliyun-oss-go-sdk/oss"
)

func main() {
	// Specify the bucket name.
	bucketName := "examplebucket"

	// Obtain access credentials from environment variables. Before you run this sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured.
	provider, err := oss.NewEnvironmentVariableCredentialsProvider()
	if err != nil {
		log.Fatalf("Error creating credentials provider: %v", err)
	}

	// Create an OSSClient instance.
	// Set yourEndpoint to the endpoint of the bucket. For example, if the bucket is in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. For other regions, use the actual endpoint.
	// Set yourRegion to the region of the bucket. For example, if the bucket is in the China (Hangzhou) region, set the region to cn-hangzhou. For other regions, use the actual region.
	clientOptions := []oss.ClientOption{oss.SetCredentialsProvider(&provider)}
	clientOptions = append(clientOptions, oss.Region("yourRegion"))
	// Set the signature version.
	clientOptions = append(clientOptions, oss.AuthVersion(oss.AuthV4))
	client, err := oss.New("yourEndpoint", "", "", clientOptions...)
	if err != nil {
		log.Fatalf("Error creating OSS client: %v", err)
	}

	var setBucketReferer oss.RefererXML
	// Add referers to the Referer whitelist and allow requests with an empty Referer header. The Referer parameter supports the asterisk (*) and question mark (?) wildcard characters.
	setBucketReferer.RefererList = []string{
		"http://www.aliyun.com",
		"https://www.aliyun.com",
		"https://www.www.alibabacloud.com/help",
		"http://www.?.aliyuncs.com",
	}
	// Add referers to the Referer blacklist. Go SDK V2.2.8 and later support Referer blacklists.
	setBucketReferer.RefererBlacklist = &oss.RefererBlacklist{
		Referer: []string{
			"http://www.refuse.com",
			"https://*.hack.com",
			"http://ban.*.com",
			"https://www.?.deny.com",
		},
	}
	setBucketReferer.AllowEmptyReferer = true
	boolFalse := false
	setBucketReferer.AllowTruncateQueryString = &boolFalse

	err = client.SetBucketRefererV2(bucketName, setBucketReferer)
	if err != nil {
		log.Fatalf("Error setting bucket referer: %v", err)
	}

	log.Println("Set Bucket Referer Success")
}

Get hotlink protection configurations

The following code shows how to retrieve hotlink protection configurations.

package main

import (
	"log"

	"github.com/aliyun/aliyun-oss-go-sdk/oss"
)

func main() {
	// Specify the bucket name.
	bucketName := "yourBucketName"

	// Obtain access credentials from environment variables. Before you run this sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured.
	provider, err := oss.NewEnvironmentVariableCredentialsProvider()
	if err != nil {
		log.Fatalf("Error creating credentials provider: %v", err)
	}

	// Create an OSSClient instance.
	// Set yourEndpoint to the endpoint of the bucket. For example, if the bucket is in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. For other regions, use the actual endpoint.
	// Set yourRegion to the region of the bucket. For example, if the bucket is in the China (Hangzhou) region, set the region to cn-hangzhou. For other regions, use the actual region.
	clientOptions := []oss.ClientOption{oss.SetCredentialsProvider(&provider)}
	clientOptions = append(clientOptions, oss.Region("yourRegion"))
	// Set the signature version.
	clientOptions = append(clientOptions, oss.AuthVersion(oss.AuthV4))
	client, err := oss.New("yourEndpoint", "", "", clientOptions...)
	if err != nil {
		log.Fatalf("Error creating OSS client: %v", err)
	}

	// Get the hotlink protection configurations.
	refRes, err := client.GetBucketReferer(bucketName)
	if err != nil {
		log.Fatalf("Error getting bucket referer: %v", err)
	}

	// Print the hotlink protection configuration information.
	log.Println("Allow Empty Referer:", refRes.AllowEmptyReferer)
	if refRes.AllowTruncateQueryString != nil {
		log.Println("Allow Truncate QueryString:", *refRes.AllowTruncateQueryString)
	}
	if len(refRes.RefererList) > 0 {
		for _, referer := range refRes.RefererList {
			log.Println("Referer List:", referer)
		}
	}
	if refRes.RefererBlacklist != nil && len(refRes.RefererBlacklist.Referer) > 0 {
		for _, refererBlack := range refRes.RefererBlacklist.Referer {
			log.Println("Referer Black List:", refererBlack)
		}
	}

	log.Println("Get Bucket Referer Success")
}

Clear hotlink protection configurations

The following code shows how to clear hotlink protection configurations.

package main

import (
	"log"

	"github.com/aliyun/aliyun-oss-go-sdk/oss"
)

func main() {
	// Set yourBucketName to the bucket name.
	bucketName := "yourBucketName"

	// Obtain access credentials from environment variables. Before you run this sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured.
	provider, err := oss.NewEnvironmentVariableCredentialsProvider()
	if err != nil {
		log.Fatalf("Error creating credentials provider: %v", err)
	}

	// Create an OSSClient instance.
	// Set yourEndpoint to the endpoint of the bucket. For example, if the bucket is in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. For other regions, use the actual endpoint.
	// Set yourRegion to the region of the bucket. For example, if the bucket is in the China (Hangzhou) region, set the region to cn-hangzhou. For other regions, use the actual region.
	clientOptions := []oss.ClientOption{oss.SetCredentialsProvider(&provider)}
	clientOptions = append(clientOptions, oss.Region("yourRegion"))
	// Set the signature version.
	clientOptions = append(clientOptions, oss.AuthVersion(oss.AuthV4))
	client, err := oss.New("yourEndpoint", "", "", clientOptions...)
	if err != nil {
		log.Fatalf("Error creating OSS client: %v", err)
	}

	// Clear the hotlink protection configurations.
	var delBucketReferer oss.RefererXML
	delBucketReferer.RefererList = []string{}
	delBucketReferer.AllowEmptyReferer = true

	err = client.SetBucketRefererV2(bucketName, delBucketReferer)
	if err != nil {
		log.Fatalf("Error clearing bucket referer: %v", err)
	}

	log.Println("Delete Bucket Referer Success")
}

References

For the complete sample code for hotlink protection, see GitHub.
For more information about the API operation for setting hotlink protection, see SetBucketRefererV2.
For more information about the API operation for retrieving hotlink protection configurations, see GetBucketReferer.