Documentation Center

Setting up OAuth authentication

Set up OAuth to implement authentication for the Content Delivery Web service and the SDL Tridion-based Web site. To do so, edit several configuration files.

Before you begin

To implement OAuth authentication, the following must be true:
  • You must have enabled the Ambient Data Framework for the Server Roles (Web service and/or Web site) for which you want to implement OAuth authentication.
  • If you want to implement OAuth authentication for the Web site, you must have installed the Content Delivery Web site, you must have installed the Content Delivery Web service Server Role on the Web site.

Procedure

  1. If the Web service or Web site is a Java Web application, do the following:
    1. In the root directory of the Web application, Open web.xml for editing.
    2. 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.

      The <filter> and <filter-mapping> elements take care of request validation.

    3. Save and close web.xml.
  2. Alternatively, if the Web service or Web site is a .NET Web application, do the following:
    1. In the root folder of the Web application, open web.config.
    2. Ensure the presence of the following element in the section system.serviceModel > services:
      <service name="Tridion.ContentDelivery.Webservice.AccessTokenService">
        <endpoint behaviorConfiguration="webHttp" bindingConfiguration="HttpBinding"
          binding="webHttpBinding" contract="Tridion.ContentDelivery.Webservice.IOAuth2AccessToken" />
      </service>

      Note that this element is already present and uncommented by default.

    3. Save and close web.config.
  3. In the WEB-INF/classes (JSP) or bin\config\ (.NET) subdirectory, open cd_webservice_conf.xml for editing.
  4. The token expiration period defaults to 300 seconds. If you wish to change this value, change the timeInSeconds attribute of the TokenExpireTime child element.
  5. After the TokenExpireTime element, ensure the presence of a sibling <SharedSecret> element set to the shared secret (a string) shared with your secure token service.
  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).
  8. If you set up HTTPS for this Web service, then in the AuthenticationServer element, set the ForceSecure attribute to true.
  9. Save and close cd_webservice_conf.xml.
  10. In the same directory, open cd_ambient_conf.xml for editing.
  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. Find the <Security> section and uncomment the <RequestValidator> and <SharedSecret> child elements.
  13. Set the <Security> child element <SharedSecret> to the same value you specified for the <SharedSecret> element in cd_webservice_conf.xml; that is, the secret shared with the secure token service.
  14. Save and close cd_ambient_conf.xml.
  15. Prior to each Web service request, first do one of the following POST requests to the Web service:
    • JSP: <protocol>://<servername:portnumber>/cd_webservice/access_token.svc
    • .NET: <protocol>://<servername:portnumber>/access_token.svc/
    where
    • <protocol> is https if you set up HTTPS for this Web service, or http otherwise
    • <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}
  16. In your actual Web service request, 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
  17. 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.