Token Generation Function

Instructions for how to write a Lua function that generates a token which protects requests redirected to a CDN.
You're viewing a development version of router, the latest released version is 1.24.0

Page not available in that version

The current page Token Generation Function doesn't exist in version 1.24.0 of the documentation for this product.
We can take you to the closest parent section instead: /docs/acd/components/router/1.24.0/configuration/advancedfeatures/luahooks/

This documents how Lua code can be used for generating tokens which protect requests that are redirected to a CDN. See the section about token generation for general information about token generation.

The Lua code is written as a function body in the services.routing.tokens.generation.<n>.luaFunction configuration parameter. It has to generate the token and place it in the response that is sent back to the client. To be able to do that, the code can modify any aspect of the response that is sent back to the client, in the same way as a response translation function. It is not limited to placing the token in a query parameter, it can be placed anywhere.

The Lua code can either return nil, which means that the response is left unchanged, or modify the response by returning HTTPResponse(t) where t is a table with any of the following optional fields:

  • Code
    • Description: Replaces status code in the response being sent.
    • Type: integer
    • Example: 200, 404
  • Text
    • Description: Replaces status text in the response being sent.
    • Type: string
    • Example: 'OK', 'Not found'
  • MajorVersion
    • Description: Replaces major HTTP version such as x in HTTP/x.1 in the response being sent.
    • Type: integer
    • Example: 1
  • MinorVersion
    • Description: Replaces minor HTTP version such as x in HTTP/1.x in the response being sent.
    • Type: integer
    • Example: 1
  • Protocol
    • Description: Replaces protocol in the response being sent.
    • Type: string
    • Example: 'HTTP', 'HTTPS'
  • Body
    • Description: Replaces body in the response being sent.
    • Type: string or nil
    • Example: '{"foo": "bar"}'
  • Headers
    • Description: Adds, removes or replaces individual headers in the response being sent.
    • Type: nested table (indexed by number) representing an array of response headers as {[1]='Name',[2]='Value'} pairs that are added to the response being sent, or overwriting existing response headers with colliding names. To remove a header from the response, specify nil as value, i.e. Headers={..., {[1]='foo',[2]=nil} ...}. Duplicate names are supported. A multi-value header such as Foo: bar1,bar2 is defined by specifying Headers={..., {[1]='foo',[2]='bar1'}, {[1]='foo',[2]='bar2'}, ...}.
  • OutgoingRequest: See Sending HTTP requests from translation functions for more information.

Example of a token generation function body that sets a hard-coded access token in the X-AccessToken header:

return HTTPResponse({
  Headers = {
    {'X-AccessToken', 'abc123'}
  }
})

Arguments

The following (iterable) arguments will be known by the function:

Headers

  • Type: nested table (indexed by number).

  • Description: Array of response headers as {[1]='Name',[2]='Value'} pairs that are present in the response being sent. Format similar to the HTTPResponse.Headers field specified for the return value above. A multi-value header such as Foo: bar1,bar2 will not be split up as multiple headers. It will appear in the Lua function as Headers={..., {[1]='foo',[2]='bar1,bar2'}, ...}.

  • Example usage:

    for _, header in pairs(Headers) do
  print(header[1]..'='..header[2])
end

Secret

  • Type: string or nil

  • Description: The secret that is stored under services.routing.tokens.generation.<n>.secretId. If the secret cannot be found, Secret will be nil.

  • Example usage:

    return HTTPResponse({Headers={{'X-Token', to_hex_string(hmac_sha256(Secret, request.path))}}})

Additional Data

In addition to the arguments above, the following Lua tables, documented in Global Lua Tables, provide additional data that is available when executing the token generation function: