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
- If the Web service or Web site is a Java Web application, do the following:
- In the root directory of the Web application, Open web.xml for editing.
- 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. - Save and close web.xml.
- Alternatively, if the Web service or Web site is a .NET Web application, do the following:
- In the root folder of the Web application, open web.config.
- 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.
- Save and close web.config.
- In the WEB-INF/classes (JSP) or bin\config\ (.NET) subdirectory, open cd_webservice_conf.xml for editing.
- The token expiration period defaults to 300 seconds. If you wish to change this value, change the
timeInSecondsattribute of theTokenExpireTimechild element. - After the
TokenExpireTimeelement, ensure the presence of a sibling<SharedSecret>element set to the shared secret (a string) shared with your secure token service. - 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). - If you set up HTTPS for this Web service, then in the
AuthenticationServerelement, set theForceSecureattribute totrue. - Save and close cd_webservice_conf.xml.
- In the same directory, open cd_ambient_conf.xml for editing.
- 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>
- Find the
<Security>section and uncomment the<RequestValidator>and<SharedSecret>child elements. - 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. - Save and close cd_ambient_conf.xml.
- 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
httpsif you set up HTTPS for this Web service, orhttpotherwise - <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, 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
- Include the following in the HTTP header "Authorization":
- 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.
- Example test page for OAuth authentication
The following test page, usable on a Java or .NET Web site, tests and demonstrates OAuth authentication.