Documentation
  • Introduction
  • Installation
    • Docker Container
      • Database
      • Deployment Modes
      • Docker Environment Variables
      • Deploy on AWS
      • Deploy on Digital Ocean
    • First Steps After Installation
      • Add New Application
      • Publish Application
      • Use Application
  • Usage
    • Send Request To Endpoint
    • Request From Web Form
    • Web Form Controls Having Multiple Values
    • Web Form With File Upload
    • HTML Snippet embedded with Java Script
    • Authentication
    • Environments
    • Debug Mode
  • Configuration
    • Application Directory Structure
      • endpoints.xml
      • security.xml
      • email-sending-configuration.xml
      • service-portal-endpoint-menu-items.xml
      • Directory: data-source-post-processing
      • Directory: data-sources
      • Directory: data-source-xslt
      • Directory: fonts
      • Directory: http-xslt
      • Directory: parameter-xslt
      • Directory: static
      • Directory: transformers
      • Directory: xml-from-application
    • Endpoint Parameter
    • Types of Endpoints
      • Endpoint to Return XSLT Transformation
      • Endpoint to Return Content From Url
      • Endpoint to Return Static File
      • Endpoint to Return OOXML
      • Endpoint to Redirect Request
      • Forwarding Between Endpoints
      • Conditional Success Action
      • Error Case
    • Data Source Transformation
      • Load Parameter Values as a Data Source
      • Load Data From a Local XML File
      • Load Data from any REST-API
      • Load Data From Databases
      • List AWS S3 keys
      • Load AWS S3 object
      • Additional Useful Data Source Types
      • Transformation Options
      • Data Source Post-Processing
      • Using Parameter Placeholders in Data Sources
      • On-Demand Incrementing Number
      • Writing Transformation Input/Output to AWS S3
    • Parameter Transformation
      • Parameter Transformation Input
      • Parameter Transformation Output
    • Tasks
      • HttpRequest Task
      • Email Task
      • Create Shortlink Task
      • Request Log Task
      • Conditional Tasks
      • Parallel or Subsequent Execution of Tasks
      • Intermediate Values
    • PDF Created With XSLT
      • Embedding Fonts
      • Embedding Images
    • OpenEndpoints XSLT Specifics
Powered by GitBook
On this page
  • Secret Key(s)
  • Calculation of the Hash
  • Example Calculation
  • Include-In-Hash Use Cases
Export as PDF
  1. Usage

Authentication

PreviousHTML Snippet embedded with Java ScriptNextEnvironments

Last updated 2 years ago

Each request to OpenEndpoints requires a mandatory hash parameter:

Example

The hash is a SHA-256 hex calculated from several input values. On each request the server calculates the expected value of the user-supplied hash parameter. If the supplied value does not match the expected value the request will be denied.

The hash may be supplied as uppercase or lowercase in the request.

Secret Key(s)

In the security.xml file under application you have to create one or many secret keys.

<security>
    <!--it is mandatory to have at least 1 secret key-->
    <secret-key>any-string</secret-key>
    <!--optionally you can define any mumber of additional secret keys-->
    <secret-key>optional-another-string</secret-key>
</security>

Any secret key in security.xml will be a valid input to determine the expected calculated hash. The advantage of having more than one secret key is that you can implement a rotation of secret-keys without interruption of services:

  1. Add a new secret key

  2. Adopt new hash values in your applications or web forms (using the new secret key)

  3. Delete the old secret key

Calculation of the Hash

Input of the SHA256 function is the concatenated string of the following inputs:

  1. Name of the endpoint

  2. The values of all the parameters listed in the <include-in-hash> block of the endpoint, in the order in which they are listed there. (If there is no <include-in-hash> section, or there is but it's empty, then no parameters are added to the hash's source string for this step.)

  3. Environment name (either “live” or “preview”)

  4. Any secret key from the security.xml file

Potential Source of Error

Note that if you use parameter-transformation the parameter value taken for the calculation of <include-in-hash> commands is the value after transformation, not the originally submitted value.

Example Calculation

<security>
    <secret-key>openendpoints</secret-key>
</security>
<endpoint name="helloworld">
    ...
    <include-in-hash>
       <parameter name="foo"/>
        <parameter name="long"/>
    </include-in-hash>
      ...
</endpoint>

Assume that

# parameter name="foo" value="abc"

Expected Value LIVE environment

Input String = "helloworld" & "abc" & "def" & "live" & "openendpoints"

SHA256("helloworldabcdefliveopenendpoints")

= 82bb6e7f675a8d872688cb593a64f615b37f88478d7fed8705496d3e7a1c2699

Expected Value PREVIEW environment

SHA256("helloworldabcdefpreviewopenendpoints")

= 4afcbe21891e5be6762f495958659a25950a83e7c52f13594cbebe43cfdd9bf4

Include-In-Hash Use Cases

The possibility to include parameter values in the hash calculation can be used to implement use cases like:

  • Send a link to web form having some distinct mandatory input which shall not be changed. Changing the value of that parameter would result in a different expected hash value. Hence, the form will only work with the (unchanged) value.

  • Having the same endpoint implemented for different web forms or different applications could use a hidden parameter indicating the originating source. The expected hash can be different for each originator, making it impossible to modify that value.

  • Generate the hash in combination with a timestamp. You can invalidate the request after a certain time - and the timestamp can not be modified because this would change the expected hash value.

https://yoursever.com/{application}/{endpoint}?hash=7eba31be11799ccedf6fdd1d932ee1d2022ee22b1fea35baead5c92179372e9e