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
- 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. - Save and close web.xml.
- 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
serviceelements. Put this section in comments. - A commented-out section that enables HTTPS support, consisting of a number of
serviceelements. Uncomment this section. - A commented-out section that specifies bindings for HTTPS, consisting of a
bindingselement. Uncomment this section.
Save and close Web.config.
- A section that enables HTTP support, consisting of a number of
- Access the WEB-INF/classes (JSP) or lib\config\ (.NET) subdirectory and open cd_webservice_conf.xml in a plain-text or XML editor.
- By default, the token expiration period set to 300 seconds. If you wish to change this value, change the
timeInSecondsattribute of theTokenExpireTimeelement. - Additionally, specify one or more user accounts that can request a token from the authorization server by inserting one or more
Accountelements contained in the<Accounts>element in the sample configuration. EachAccountelement you insert must have anIdattribute set to the username, and aPasswordattribute set to a password (encrypted or not). (Refer to Encrypting sensitive strings to learn how to obtain an encrypted version of your password.) - Inside each
Accountelement you insert, you also have the option to insert a<Metadata>element which itself can contain any number of named parameters (Paramelements withNameandValueattributes) inside. - Switch on HTTPS by ensuring that the
AuthenticationServerelement has an attribute calledForceSecurethat is set totrue. - Save and close cd_webservice_conf.xml.
- In the same directory, open cd_ambient_conf.xml in a plain-text or XML editor.
- 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>
- Save and close cd_ambient_conf.xml.
- 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.
- 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_idis one of the usernames specified in anIdattribute of anAccountelement in theAccountssection of the Web service configuration file.client_secretis a valid, unencrypted password for that user.
If the username and password are correct, the Web service returns a response of content type
application/jsonof the following format (on a single line):{"access_token":"HufXeuUt%2FYYElA8SYjJOkUkrXxV9dyXRirmKhjW%2Fb%2FU%3D","expires_in":300} - JSP:
- 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%3DSpecify the access token as a query parameter of your URL called
oauth_token, as follows:?oauth_token=HufXeuUt%2FYYElA8SYjJOkUkrXxV9dyXRirmKhjW%2Fb%2FU%3D
- You can keep using the access token until it expires. Refer to the
expires_inproperty in the response to the access token request to see how long the current token is still valid.