Documentation Center

Setting up Content Delivery Web service security

About this task

By default, the Content Delivery Web service is not secure. If you wish to implement security for the Content Delivery Web service, using the HTTPS protocol, do the following:

Procedure

  1. If your Content Delivery Web service server role is a JSP Web application, open the web.xml file in its WEB-INF/ folder in a plain-text or XML editor and uncomment parts of the file so that the following fragments are no longer commented out:
    <servlet>
      <servlet-name>Content Delivery Authorization Server</servlet-name>
      <servlet-class>com.tridion.webservices.security.authentication.OAuth2AccessTokenHandler</servlet-class>
    </servlet>
    
    <servlet-mapping>
      <servlet-name>Content Delivery Authorization Server</servlet-name>
      <url-pattern>/access_token</url-pattern>
    </servlet-mapping>
    
    <filter>
      <filter-name>Ambient Data Framework</filter-name>
      <filter-class>com.tridion.ambientdata.web.AmbientDataServletFilter</filter-class>
    </filter>
    
    <filter-mapping>
      <filter-name>Ambient Data Framework</filter-name>
      <servlet-name>Content Delivery Webservices</servlet-name>
    </filter-mapping>

    The <servlet> and <servlet-mapping> elements specify a servlet that returns access tokens. This access token servlet is included in SDL Tridion, but if you prefer to use your own access token provider, you can configure it instead.

  2. Save and close web.xml.
  3. Alternatively, if your Content Delivery Web service server role is a .NET Web application, enable SSL in IIS and open the Web.config file in the root of the Web application in a plain-text or XML editor. Search for the phrase "HTTP support" in the comments to find the following:
    • A section that enables HTTP support, consisting of a number of service elements. Put this section in comments.
    • A commented-out section that enables HTTPS support, consisting of a number of service elements. Uncomment this section.
    • A commented-out section that specifies bindings for HTTPS, consisting of a bindings element. Uncomment this section.

    Save and close Web.config.

  4. Access the WEB-INF/classes (JSP) or lib\config\ (.NET) subdirectory and open cd_webservice_conf.xml in a plain-text or XML editor.
  5. By default, the token expiration period set to 300 seconds. If you wish to change this value, change the timeInSeconds attribute of the TokenExpireTime element.
  6. Additionally, specify one or more user accounts that can request a token from the authorization server by inserting one or more Account elements contained in the <Accounts> element in the sample configuration. Each Account element you insert must have an Id attribute set to the username, and a Password attribute set to a password (encrypted or not). (Refer to Encrypting sensitive strings to learn how to obtain an encrypted version of your password.)
  7. Inside each Account element you insert, you also have the option to insert a <Metadata> element which itself can contain any number of named parameters (Param elements with Name and Value attributes) inside.
  8. Switch on HTTPS by ensuring that the AuthenticationServer element has an attribute called ForceSecure that is set to true.
  9. Save and close cd_webservice_conf.xml.
  10. In the same directory, open cd_ambient_conf.xml in a plain-text or XML editor.
  11. Exclude the path from the Ambient Data Framework by adding one of the following to the configuration:
    JSP
    <ExcludedPaths>
      <Path>/access_token</Path>
    </ExcludedPaths>
    .NET
    <ExcludedPaths>
      <Path>/access_token.svc</Path>
    </ExcludedPaths>
  12. Save and close cd_ambient_conf.xml.
  13. Ensure that the Content Delivery Web service and all clients that connect to it have a certificate that allows the HTTPS connection to be made.
  14. Now, prior to each Web service request, first do one of the following POST requests to the Web service:
    • JSP: https://<servername:portnumber>/cd_webservice/access_token
    • .NET: https://<servername:portnumber>/access_token.svc

    where

    • <servername:portnumber> identifies the server and port on which the Web service may be accessed

    and in which you specify the following POST parameters:

    • client_id is one of the usernames specified in an Id attribute of an Account element in the Accounts section of the Web service configuration file.
    • client_secret is a valid, unencrypted password for that user.

    If the username and password are correct, the Web service returns a response of content type application/json of the following format (on a single line):

    {"access_token":"HufXeuUt%2FYYElA8SYjJOkUkrXxV9dyXRirmKhjW%2Fb%2FU%3D","expires_in":300}
  15. In your actual Web service request (again using HTTPS), include this access token in one of the following ways:
    • Include the following in the HTTP header "Authorization":

      OAuth HufXeuUt%2FYYElA8SYjJOkUkrXxV9dyXRirmKhjW%2Fb%2FU%3D
    • Specify the access token as a query parameter of your URL called oauth_token, as follows:

      ?oauth_token=HufXeuUt%2FYYElA8SYjJOkUkrXxV9dyXRirmKhjW%2Fb%2FU%3D
  16. You can keep using the access token until it expires. Refer to the expires_in property in the response to the access token request to see how long the current token is still valid.