9. Access Control¶
9.1. Geo-Blocking¶
Geographic blocking (geo-blocking) allows content access controlls based on the requesting client’s geographic region (country). Defining a geo-blocking rule is done in two steps:
- Create the geo-blocking definition that identifies the country codes you want to either deny or allow.
- Create a match rule defintion that references the geo-blocking definition created in step 1.
The geo-blocking definition is defined at the subscriber level and can be used by any property under that subscriber. This avoids having to define the same country code list for multiple properties. A geo-blocking defintion includes a comma-separated list of up to 10 ISO Alpha-2 (2-Letter) country codes, a name and an ID. The name is used for reference by the location defintion using the geo definition. The ID is an internal reference that, once set, cannot be changed. Following is a sample geo definition using the JSON schema:
"geoDefinitions": [ { "id": 1175760, "name": "Nordics", "countryCodes": [ "NO", "DK", "SE", "FI", "IS" ] } ]
Attributes of a geo definition are:
- id: unique static identifier for a geo definition. Integer, Required.
- name: human-readable name given for the geo definition, unique within a single subscriber. Required.
- countryCode: comma-separated list of 2-character country codes. Required.
A geo policy is applied by creating a match rule (within the subscriber service image) which references the defined geo definition. Following is a sample geo definition using the JSON schema:
"matchRules": [ { "expression": "/Geo-Protected", "geo": { "value": { "ipWhitelist": [ 84560 ], "matchAnonymizers": true, "denial": { "action": "Redirect", "redirectUrl": "http://www.example.com/Geo-Deny.html" }, "actionType": "Deny", "idList": [ 1175760 ] } } } ]
Attributes of a geo policy are:
- idList: one or more subscriber geo definitions.
- matchAnonymizers: blocks requests from known anonymizing proxies, regardless of their location.
- actionType: defines whether the geo list is an Allow (allow only clients from the countries in the reference geo definition country code list, reject all others) or deny (deny all clients from the listed countries, allow all others).
- denial action: defines the response the CDN returns to a client whose access is being denied due to the defined geo policy. The response can be either an Error (403 Response) or a redirect to another site (typicaly used to explain to the user why they are being denied access).
- ipWhitelist: an IP whitelist can be provided (IPv4 and/or IPv6) to allow clients whose IP is on the whitelist to bypass the geo restriction. This is typically used for testing purposes.
The CenturyLink Geo DB is provided by Digital Element and updated monthly.
9.2. Token Authentication¶
The token authentication service is used to authenticate client requests for protected objects.
The token is created by the content provider and embedded into the object URL as a set of query string parameters. When the client presents the URL to the CDN, the CDN creates its own version of the token using a shared secret and pre-defined token generation algorithm (sha1). If the client’s token does not match, the CDN will return either an HTTP 403 response or 302 Temporary Redirect. If the client’s token matches the CDN calculated token, the client’s request is allowed to proceed and the requested object is returned to the client.
In addition to defining the shared secret, the following query string parameters are supported by the Token Authentication service:
| QS Name | description |
|---|---|
| hash | contains the calculated hash using hmac-sha1. The hash value is defined below. |
| nva | Not valid after - the time at which the token is no longer valid, expressed in Epoch or GMT (yyyyMMddhhmmss) |
| nvb | Not valid before - the time before which the token cannot be used, expressed in Epoch or GMT (yyyyMMddhhmmss) |
To enable Token Authentication, a token group is first defined. A token group consists of up to 10 secrets (0-9). A secret is an ASCII character string of up to 64 bytes. Following is a sample token definition using the JSON schema:
"tokenDefinitions": [ { "id": 1, "name": "Token_1", "sharedSecrets": [ "1234567890abcdefg" ], "datePreference": "EPOCH", "queryParameterControl": "Exclude", "queryParameterNames": [example], "nva": "nva", "nvb": "nvb", "hash": "hash", } ]
The token definition supports the following configuration attributes:
- Name: name of the token group, referenced in a location definition.
- SharedSecrets: a list of up to 10 shared secrets can be provisioned against a single token group. All of the shared secrets are active.
- DatePreference: the date preference for the Not-Valid-After/Not-Valid-Before query string parameter. Either EPOCH or GMT.
- QueryParameterControl: either include or exclude query strings from the hash.
- QueryParameterNames: a list of query string parameter names to either include or exclude from the hash (see QueryParameterControl above).
- nva: override the default query string name of nva (Not-Valid-After).
- nvb: override the default query string name of nvb (Not-Valid-Before).
- hash: override the default query string name of hash.
The hash used for the token is defined as a concatenation of the following information:
- The Secret ID of the secret used to calculate the hash (a single digit 0-9).
- The first twenty characters of the resulting hash.
As part of defining the token feature, the user is able to define query string parameters to either include or exclude from the token hash calculation.
To cacluate a hash, the following high-level algorithm is used:
- Remove protocol, hostname and any query strings to be excluded from hash input leaving: /path1/resource?&otherstuff=xyz
- Add desired time validity tokens: /path1/resource?&product=A123&otherstuff=xyz&nvb=20081201060100&nva=20081201183000
- Translate result to lower-case if the origin server is case-insensitive.
- Calculate the result to an HMAC-SHA1 hash using the resulting URL and the chosen secret.
- When building new URL, add the token query string parameter and prefix with the secret ID used to calculate the token (0-9) followed by the first twenty characters of the resulting hash: http:www.sample.com/path1/resource?otherstuff=xyz&nvb=20081201060100&nva=20081201183000&token=<hash>
A Token Policy is applied by creating a match rule (within the subscriber service image) which references the defined Token definition. Following is a sample Token Policy definition using the JSON schema:
"matchGroups": [ { "id": 8456, "matchRules": [ { "expression": "/Token", "features": { "token": { "value": { "ipWhitelist": [ 84560 ], "denial": { "action": "Redirect", "redirectUrl": "http://www.example.com/Token-Deny.html" }, "id": 1 } } } } ] } ]
Attributes of a Token policy are:
- id: reference a subscriber token definition.
- denial action: defines the response the CDN returns to a client whose access is being denied due to the applied token policy. The response can be either an Error (403 Response) or a redirect to another site (typically used to explain to the user why they are being denied access).
- ipWhitelist: an IP whitelist can be provided (IPv4 and/or IPv6) to allow clients whose IP is on the whitelist to bypass the token auth restriction. This is typically used for testing purposes.
See the schema for the definitions and full set of options supported by the Token Auth feature.
9.3. IP Access Control¶
The IP access control service is used to control access to protected objects through the use of IP lists (v4 and v6). Defining an IP access control is done in two steps:
- Create an IP list which identifies the IPs you want to either deny or allow.
- Create a match rule definition which references the previously defined IP list.
The IP list is defined at the subscriber level and can be used by any match rule under that subscriber. An IP list contains a comma-separated list of individual IP addresses or ranges of IPs expressed in CIDR notation, a name and an ID. The name is used for referencing an IP list within the match rule definition. The ID is an internal reference that, once set, cannot be changed. Following is a sample IP list using the JSON schema:
"ipDefinitions": [ { "id": 2010480, "name": "IP_List", "ipCidrs": [ "100.80.56.53" ] } ]
Attributes of a IPDefinition are:
- id: unique static identifier for a geo definition. Integer, Required.
- name: human-readable name given to the IP definition, unique within a single subscriber. Required.
- ipCidrs: comma-separated list of IP addresses or CIDR blocks. May contain both IPv4 & IPv6 addresses. Required.
An IP Access Control Policy is applied by creating a match rule (within the subscriber service image) which references the defined IP definition. Following is a sample IP Access Control Policy using the JSON schema:
"matchGroups": [ { "id": 8456, "matchRules": [ { "expression": "/ip-block", "features": { "ipBlock": { "value": { "denial": { "action": "Redirect", "redirectUrl": "http://www.example.com/IP-Deny.html" }, "actionType": "Deny", "idList": [ 2010480 ] } } } } ] } ]
Attributes of a IP Access Control policy are:
- idList: one or more subscriber IP definitions.
- denial action: defines the response the CDN returns to a client whose access is being denied due to the applied IP Access Control policy. The response can be either an Error (403 Response) or a redirect to another site (typically used to explain to the user why they are being denied access).
See the schema for the definitions and full set of options supported by the IP Access Control feature.
9.4. Deny Policy¶
A deny policy allows for all requests matching a defined criterion to be rejected or redirected to an alternate URL. A deny policy is defined and applied within a match rule. There is no separate definition of a deny policy outside of a match rule. Following is a sample match rule using the JSON schema:
"matchRules": [ { "expression": "/Deny-Path", "features": { "denyPolicy": { "headers": [ { "name": "lvlt-hdr" "value": ""ctl-cdn" } ] "denial": "error" } } } } ]
Attributes of a Deny Policy definition are:
- headers: A name value list of header name and value to be included in the Response to the client
- denial: Either error or redirect. If redirect a URL to redirect to must also be included, per the schema
Changed in version 19.1: Removed the statuscode option to align with other access control features.