75 WEM Framework: Using REST Resources

This chapter contains the following sections:

75.1 Authentication for REST Resources

The WEM Framework uses the SSO mechanism built on top of CAS (http://www.jasig.org/cas) for authentication purposes. The system behaves differently when the REST API is used from a browser or programmatically.

When accessing the REST API from a browser, the user is redirected to the CAS login page and, upon successful login, back to the original location with the ticket parameter, which is validated to establish the user's identity. When accessing the REST API programmatically, the developer must supply either the ticket or multiticket parameter.

Both the ticket and mu ltiticket parameters could be acquired by using either the Oracle SSO API if making calls from Java, or simply by using the HTTP protocol if making calls from any other language. The difference between ticket and multicket is that a ticket is acquired per each REST resource and can be used only once (as the name implies, think of a train or a theater ticket, which is valid for one ride or one play), while a multiticket could be used multiple times for any resource. Both the ticket and multiticket parameters are limited in time, but the typical usage pattern differs. As a ticket is acquired per each call, there is no need to worry about its expiration time. However, reusing the same multiticket will eventually lead to its expiration and getting an HTTP 403 error. The application must be able to recognize such behavior and fall back to the multiticket re-acquisition procedure in such a case. The decision to use either ticket or multiticket is up to the application developer.

This section contains the following topics:

75.1.1 Acquiring Tickets from Java Code

The Oracle SSO API is implemented in an authentication provider-independent manner. Users will not be able to register their own SSO authentication providers. Support for a new authentication provider can be implemented only by Oracle. Switching between providers involves only changing the SSO configuration files.

All SSO calls originate at the SSO front-end class SSO. It is used to get the SSOSession object. SSOSession is acquired per each SSO configuration. It is a single configuration in the web application case, which is loaded using the Spring Web application loader or a configuration loaded from a configuration file in the case of a standalone application.

Web Application

SSO.getSession().getTicket(String service, String username, String password)
SSO.getSession().getMultiTicket(String username, String password)

Standalone Application

SSO.getSession(String configName).getTicket
  (String service, String username, String password)
SSO.getSession(String configName).getMultiTicket
  (String username, String password)

75.1.2 Acquiring Tickets from Other Programming Languages (Over HTTP)

The CAS REST API is used to acquire a ticket and/or multiticket in the delivery environment. Two HTTP POST calls should be performed to acquire either ticket or multiticket. The difference between ticket and multiticket is that the service parameter is " * " for multiticket, while it is an actual REST resource you are trying to access for the ticket parameter.

The example below demonstrates the calls to be made to the CAS server to get a ticket to the http://localhost:8080/cs/REST/sites service with fwadmin/xceladmin credentials:

  1. Call to get Ticket Granting Ticket

    Request

    POST /cas/v1/tickets HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Content-Length: 35

username=fwadmin&password=xceladmin

    Response

    
HTTP/1.1 201 Created
Location: http://localhost:8080/cas/v1/tickets/TGT-1-ej2biTUFoCNBwA5X4lJn4PjYLRcLtLYg2QhLHclInfQqUk3au0-cas
Content-Length: 441
...

  2. Call to get a Service ticket

    Request

    POST /cas/v1/tickets/TGT-1-ej2biTUFoCNBwA5X4lJn4PjYLRcLtLYg2QhLHclInfQqUk3au0-cas  HTTP/1.1
Content-Type: application/x-www-form-urlencoded 
Content-Length: 57

service=http%3A%2F%2Flocalhost%3A8080%2Fcs%2FREST%2Fsites

    Response

    HTTP/1.1 200 OK
Content-Type: text/plain
Content-Length: 29

ST-1-7xsHEMYR9ZmKdyNuBz6W-cas

The protocol is fairly straightforward. First a call to get Ticket Granting Ticket (TGT) is made by passing the username and password parameter in application/x-www-form-urlencoded POST request. The Response will contain the Location HTTP header, which should be used to issue a second application/x-www-form-urlencoded POST request with service parameter. The response body will contain the actual ticket.

75.1.3 Using Tickets and Multitickets

To use the generated ticket/multiticket, supply the ticket/multiticket URL query parameter. For example:

http://localhost:8080/cs/REST/sites?ticket=ST-1-7xsHEMYR9ZmKdyNuBz6W-cas
http://localhost:8080/cs/REST/sites?multiticket=ST-2-Bhen7VnZBERxXcepJZaV-cas
Description of m_multitickets_rebrand.png follows
Description of the illustration m_multitickets_rebrand.png

  1. The application performs a call to get the ticket/multiticket.

    • Input: service, username, password

    • Output: ticket /multiticket

  2. The application performs call to Remote Satellite Server to get the resource.

    • Input: ticket, resource input data

    • Output: resource output data

  3. Remote Satellite Server performs a call to validate the resulting 'assertion'. The assertion contains user information. Satellite Server also maintains a time-based cache of multitickets, so that subsequent calls do not incur the cost of validation.

    • Input: ticket/multiticket

    • Output: assertion

  4. This step is optional. If the proxyTickets parameter in the SSOConfig.xml file parameter is set to true on the Satellite Server side, it also proxies the ticket.

    • Input: ticket

    • Output: proxied ticket

  5. Remote Satellite Server performs a call to WebCenter Sites.

    • Input: assertion (in serialized form), resource input data

    • Output: resource output data

  6. This step is optional. If security is enabled on the WebCenter Sites side, it performs a call to validate the ticket.

    • Input: ticket/multiticket

    • Output: assertion

By default the communication channel between WebCenter Sites and Remote Satellite Server is not trusted. The proxyTickets parameter in the SSOConfig.xml file on Remote Satellite Server is set to true, which forces Remote Satellite Server to proxy the ticket supplied by the application that is being accessed.

For optimal performance, the system can be configured for authentication by Satellite Server alone. The security check should be disabled on the WebCenter Sites side by excluding the REST and WebCenter Sites elements used by the REST API from the SSO filter; the proxyTickets parameter in the SSOConfig.xml file on Remote Satellite Server should be set to false. In this mode it is possible to leverage multitickets. Note that the WebCenter Sites installation should be hosted inside a private network in this mode, and the communication channel between WebCenter Sites and Remote Satellite Server should be trusted.

75.1.4 SSO Configuration for Standalone Applications

The single sign-on module relies on the Spring configuration. The only required bean is ssoprovider, which references the ssoconfig bean.

This section contains the following topics:

75.1.4.1 Beans and Properties

id="ssolistener", class="com.fatwire.wem.sso.cas.listener.CASListener"

Table 75-1 id="ssolistener"

Property Description

No properties for this bean.

n/a

 

id="ssofilter",
class="com.fatwire.wem.sso.cas.filter.CASFilter"

Table 75-2 id="ssofilter"

Property Description

config

Required. SSO configuration reference.

Sample Value: ssoconfig

provider

Required. SSO provider reference.

Sample Value: ssoprovider

 

id="provider",
class="com.fatwire.wem.sso.cas.CASProvider"

Table 75-3 id="provider"

Property Description

config

SSO configuration reference.

Sample Value: ssoconfig

 

id="config",
class="com.fatwire.wem.sso.cas.conf.CASConfig"

Table 75-4 id="config"

Property Description

applicationProxyCallbackPath

Proxy callback path, relative to casUrl.

Sample Value: /proxycallback

authRedirect

Use this property to specify the default behavior on unauthenticated access to protected pages. true redirects the user to the CAS login page; false displays a 403 error if users are not unauthenticated. This setting could be overridden by the Pragma: auth-redirect HTTP header.

Sample Value: true

casLoginPath

Login page path, relative to casUrl.

Can accept additional query parameters:

  • wemLoginTemplate, points to the page containing the HTML login template to be used instead of the default template. The template must have two input fields: username and password. Note, that the HTML <form> tag should not be used in the template.

  • wemLoginCss, points to the CSS page containing style declarations used on the login form.

Sample Value: /login

casRESTPath

CAS REST servlet path, relative to casUrl.

Sample Value: /v1

casSignoutPath

Logout page path, relative to casUrl.

Sample Value: /logout

casUrl

Required property. CAS URL prefix.

Example: http://localhost:8080/cas

gateway

If true, the request to protected pages will be redirected to CAS. If a ticket-granting cookie is present, then the user will be implicitly authenticated; if not, the user will be redirected back to the original location. This is used primarily to allow implicit authentication if the user is already logged in to another application.

gateway (continued)

Be careful when enabling the redirect behavior to occur by default. Make sure that the clients are able to follow the redirects. Otherwise, gateway=false URL query parameter should be used to override the default behavior. For example, while processing wemLoginTemplate and wemLoginCss parameters, CAS does not follow redirects; you will have to prepend gateway=false to URLs when turning this setting on.

Default value: false

multiticketTimeout

Multiticket timeout in msecs.

Default value: 600000

protectedMappingExcludes

List of mappings that should be excluded. Regular expressions are allowed.

Allowed value: See protectedMappingIncludes

protectedMappingIncludes

List of protected mappings. Regular expressions are allowed.

Allowed value: path?[name=value,#]

path is a URL path part. It may contain asterisks (* and **). The single asterisk * symbolizes any character sequence up to the forward slash character (/), while ** applies to the entire path.

Example

/folder1/folder2 matches against /folder1/*, while /folder1/folder2/folder3 does not.

/folder1/folder2 matches against /folder1/**, as well as /folder1/folder2/folder3.

?[..] block is optional. Query parameters can be specified inside the block. Parameters are comma separated. The special character # means that the specified parameters are a subset of those from the request; omitting # requires the request parameters to exactly match the specified parameters.

Parameters may contain only name. The match will be done against name only, or against name=value (i.e., both name and value). A parameter can take multiple values. In this case, the match test will pass if any of the specified parameter values match the corresponding parameter value from the request.

Example

/file1[size=1|2] matches against /file1?size=2, but not against /file1?size=2&author=admin

/file1[size=1|2,name=file1,#] matches against /file1?size=2 and /file1?size=2&author=admin,but not against /file1?size=3

protectedMappingIncludes (continued)

To make custom REST resources in an application available via remote Satellite Server, specify the following value:

/ContentServer?[pagename=rest/<path toCSElement>,#]

Example

/ContentServer?[pagename=rest/sample/recommendation,#] for custom REST resources in Chapter 73.1, "The Recommendations Sample Application."

proxyTickets

Specifies whether to proxy tickets.

Set this property to false for the last server in the call chain for optimal performance.

Set this property to true if you need to call another CAS-protected application from this application on behalf of the currently logged-in user. This results in the ability to call the following method: SSO.getSSOSession().getTicket(String service, String username, String password)

Default value: true

useMultiTickets

Specifies whether to use multitickets.

Default value: true

75.1.4.2 Query Parameters Processed by SSO Filter

Table 75-5 Query Parameters Processed by SSO Filter

Property Name Description

ticket

Used to verify user identity. Can be used only during some limited period of time for one resource and only once.

Type: <query parameter>

Value: <random string>

multiticket

Used to verify user identity. Can be used only during some limited period, multiple times for any resource.

Type: <query parameter>

Value: <random string>

gateway

If this property is set to true, the request for public pages will be redirected to CAS. If the ticket granting cookie is present, then the user will be implicitly authenticated; if not, the user will be redirected back to the original location. This is primarily to allow implicit authentication if the user is already logged in to another application.

Type: <query parameter>

Value: true | false

auth-redirect

Used to specify the default behavior on unauthenticated access to protected pages. If this property is set to true, the user will be redirected to the CAS login page; if false, a 403 error will be presented.

Type: <Pragma HTTP header>

Value: true | false

75.2 Configuring CAS

Information about CAS clustering can be found in the following sources:

  • For information about CAS architecture, use the following link:

    http://www.jasig.org/cas/about

  • For information about configuring CAS clustering during the WebCenter Sites installation, see the Oracle Fusion Middleware WebCenter Sites Installation Guide.

  • For information about configuring CAS with LDAP providers, use the following link:

    http://www.jasig.org/cas/server-deployment/authentication-handler

75.3 REST Authorization

This section is for developers who are interested in administrators' authorization processes. REST authorization is the process of granting privileges to perform REST operations on applications' resources (which map to objects in WebCenter Sites). REST authorization uses the "deny everything by default" model. If a privilege is not explicitly granted to a particular group, that privilege is denied.

This section contains the following topics:

75.3.1 Security Model

The WEM security model is based on objects, groups, and actions. Security must be configured per object type in the WebCenter Sites Admin interface:

Description of addnewsecconfig.gif follows
Description of the illustration addnewsecconfig.gif

  • Object is a generic term that refers to any entity in the WEM Framework such as a site, a user, or an asset. Protected objects are of the following types:

    • Asset Type

    • Asset

    • Index

    • Site

    • Role

    • User

    • User Locale

    • ACL

    • Application

  • Security groups are used to gather users for the purpose of managing their permissions (to operate on objects) simultaneously.

  • An action is a security privilege: LIST,READ, UPDATE, CREATE, DELETE. LIST provides GET permission on services that list objects (such as /types), whereas READ provides GET permission on services that retrieve individual objects in full detail (such as /types/{assettype}).

    Privileges are assigned to groups to operate on allowed objects. Some objects, such as ACLs, are read-only (they can be created directly in WebCenter Sites, but not over REST).

A security configuration is an array, such as shown above, which specifies:

  • The protected object type and object(s)

  • Groups that are able to access the objects

  • Actions that groups (and their members) can perform on the objects

For more information on possible security configurations and the Web Experience Management Framework, see the Oracle Fusion Middleware WebCenter Sites Administrator's Guide.

75.3.2 Using the Security Model to Access REST Resources

Object types and objects in WebCenter Sites map to REST resources in the WEM Framework. For example, the Asset Type object maps to:

  • <BaseURI>/types/ resource (which lists all asset types in the system)

  • <BaseURI>/types/<assettype> resource (which displays information about the selected asset type), and so on.

Actions in WebCenter Sites map to REST methods in the WEM Framework. For example, granting the READ privilege to group Editor to operate on asset type Content_C gives users in the Editor group permission to use GET and HEAD methods on the REST resource /types/Content_C.

  • The LIST action allows group members to use GET methods on REST resources.

  • The READ action allows group members to use GET and HEAD methods on REST resources.

  • The UPDATE action allows group members to use POST methods on REST resources.

  • The CREATE action allows group members to use PUT methods on REST resources.

  • The DELETE action allows group members to use DELETE methods on REST resources.

For comprehensive information, see the Oracle Fusion Middleware WebCenter Sites REST API Resource Reference

75.3.3 Configuring REST Security

For more information on configuring REST security and the Web Experience Management Framework, see the Oracle Fusion Middleware WebCenter Sites Administrator's Guide.

75.3.4 Privilege Resolution Algorithm

When configuring a security privilege, you can specify that the privilege applies to all objects of a certain type or a single object of a certain type. For example, granting the privilege to UPDATE (POST) any site allows users in the group to modify the details of all sites in the WEM Framework. Granting the privilege to UPDATE (POST) the FirstSiteII sample site allows users in the group to modify this site's details in WEM.

The Asset object type requires you to specify the site to which the security setting applies, as assets are always accessed from a particular site. The AssetType object can be extended by specifying a subtype, which is used to make the security configuration more granular. For example, setting the DELETE privilege on asset type Content_C in allows a DELETE request to be performed on the REST resource /types/Content_C (i.e., to delete the Content_C asset type from the system).

Because privileges can be granted only to groups, a user's total privileges are not obvious until they are computed across all of the user's groups. The WEM Framework provides a privilege resolution algorithm. Its basic steps are listed below:

  1. REST finds the groups in which the user has membership.

  2. REST determines which groups can perform which REST operations on which REST resources. If site or subtype is specified, each is taken into account.

  3. REST compares the results of steps 1 and 2. If at least one of the groups from step 1 is in the list of groups from step 2, then access is granted. Otherwise, access is denied.

75.4 Managing Assets Over REST

Sample code illustrating management of assets via the WebCenter Sites REST API is available in your WebCenter Sites installation directory, in the following paths:

Misc/Samples/WEM Samples/REST API samples/Basic Assets/com/fatwire/rest/samples/basic/
Misc/Samples/WEM Samples/REST API samples/Basic Assets/com/fatwire/rest/samples/flex/

The subfolders basic and flex each contain the following set of files:

  • CreateAsset.java

  • DeleteAsset.java

  • ReadAsset.java

  • UpdateAsset.java.

The code is richly documented with step-by-step instructions. Examples of basic asset management use the HelloAssetWorld sample site. Examples of flex asset management use the FirstSiteII sample site. All information regarding the required asset types and assets can be found in the java files.