Oracle Beehive RESTful Web Services Authentication

Oracle Beehive RESTful Web services supports the following types of authentication:

Single Sign-On
Basic HTTP Authentication
S2S Authentication

The following topics are also covered:

Session Timeouts
Securing POST, PUT, and DELETE Method Calls
Security Best Practices

Single Sign-On

You may use the following single sign-on technologies to secure Oracle Beehive RESTful Web services:

Oracle Application Server Single-Sign On
OC4J Java Single-Sign On

Oracle Application Server Single-Sign On

You may register Oracle Beehive as a partner application with Oracle Application Server Sign-On (which is also know as Oracle Single Sign-On or OSSO). This means you may delegate authentication to the OSSO server. For more information, refer to the module "Configuring Single Sign-On with Oracle Beehive" in the installation guide of the operating system of your Oracle Beehive deployment.

OC4J Java Single-Sign On

OC4J Java Single Sign-On is an alternative single sign-on solution that does not rely on additional required infrastructure. By default, OC4J Java Single Sign-On is automatically configured for Oracle Beehive.

Basic HTTP Authentication

Oracle Beehive RESTful Web Services follows these standards:

RFC 1945, Hypertext Transfer Protocol—HTTP/1.0
RFC 2616, Hypertext Transfer Protocol—HTTP/1.1
RFC 2617, HTTP Authentication: Basic and Digest Access Authentication

Form Based Authentication

Refer to JSR 154: Java Servlet 2.4 Specification for more information about form-based authentication:

http://jcp.org/en/jsr/detail?id=154

Form based authentication involves the HTTP POST method and the action j_security_check. This action requires the following parameters:

j_username
j_password
j_character_encoding: This parameter is not part of the Java Servlet 2.4 specification. Specify the value utf-8 for this parameter.

Use the session tracking cookie named JSESSIONID to set these parameters.

If you are not using an HTML form to perform form based authentication, set the parameter submit to the value Login in your HTTP POST request.

S2S Authentication

S2S (service-to-service) authentication enables external services to securely call Oracle Beehive services on behalf of users provisioned in Oracle Beehive.

To enable S2S authentication, follow these steps:

Create an Oracle Beehive user that external services will use to authenticate with Oracle Beehive services. These steps use the user portalapp.

Call the following beectl command:

beectl add_trusted_identity --type S2S --password --service_name portalapp

Note:

To change the context to another user, use the runas parameter. For example, to retrieve the user first.user, call /my/user?runas=first.user. Later on, you may call /my/user?runas=second.user to retrieve the user second.user.

Session Timeouts

Depending on the authentication method you use, the authenticated user is logged out after a specific amount of time:

OC4J Java Single-Sign On: The authenticated user is logged out after two hours irrespective of whether that user was active or not.
HTTP authentication (basic only): By default, the authenticated user is logged out after one hour of inactivity.

Changing Timeout of Oracle Beehive's HTTP Server

You may change the timeout value of Oracle Beehive's HTTP server. Run the following beectl commands:

beectl list_components --type HttpServer

-----------------+-------------------------------------------------------------
Component type | Component identifier
-----------------+-------------------------------------------------------------
HttpServer | ohs_site1.example.com
-----------------+-------------------------------------------------------------

beectl modify_property --component ohs_site1.example.com -–name Timeout --value <new timeout value in seconds>

beectl activate_configuration
beectl modify_local_configuration_files
beectl restart --component ohs_site1.example.com

Securing POST, PUT, and DELETE Method Calls

All calls to POST, PUT, and DELETE method calls require an anti-CSRF token. This token guards against cross-site request forgery (CSRF) attacks.

Follow these steps to retrieve and specify this anti-CSRF token whenever you call a POST, PUT, and DELETE method.

Step 1 Retrieve the anti-CSRF token

This step assumes you already successfully logged in with the POST method /session/login

Retrieve the anti-CSRF token with the GET method /session/anticsrf:

GET /comb/v1/d/session/anticsrf

Step 2 URL encode the anti-CSRF token

Convert the anti-CSRF token to the application/x-www-form-urlencoded MIME format so that the anti-CSRF token is valid as a parameter in a HTTP method call. This token frequently contains an equal sign (=). To use the anti-CSRF token in URIs with characters like the equal sign, you must URL encode the token.

Most programming languages and environment have built-in operations for URL encoding strings. The following are suggested utilities:

Adobe Flex: escape ActionScript method
C#: HttpServerUtility.UrlEncode method
Java: java.net.URLEncoder class
JavaScript: encodeURIComponent function

Step 3 Specify the URL encoded anti-CSRF token in the HTTP method call

In the HTTP method call, set the parameter anticsrf to the URL encoded anti-CSRF token. For example, the following method demonstrates how to call the Read Batch method, /afrh/read:

POST /comb/v1/d/afrh/read?anticsrf=kp3PZtMeXK0%3D

Notes:

If you use the method override header X-HTTP-Method-Override to GET, for example, to perform a GET method with a POST method, you still need the anti-CSRF token. Any call that reaches the servlet as a HTTP POST, PUT, or DELETE method requires this token irrespective of the method override.
It is simpler for your application to pass this token on every call. For example, you can create a common routine that handles all server traffic. If you decide to do this, note that passing the token on GET calls will not result in an error.

Security Best Practices

The following security and management best practices are recommended when building applications with Oracle Beehive RESTful Web services:

Use HTTPS

Use HTTPS (as opposed to HTTP) when communicating with Oracle Beehive.

Ensure Secured System When Using S2S Authentication

Note that S2S authentication delegates authentication to the system built by the developer. Therefore, for example, if you are building an Oracle Beehive RESTful Web services application with Oracle WebCenter and decide to use S2S authentication, then you should follow the security practices of Oracle WebCenter.

Protect Your Site from XSS Attacks

Cross site-scripting (also referred to as XSS) is a security breach that takes advantage of dynamically generated Web pages. In a XSS attack, a Web application is sent a script that activates when it is read by a user's browser. Once activated, these scripts can steal data, even session credentials, and return the information to the attacker.

Do Not Use JavaScript eval() Function to Parse JSON Data

It is possible to use the built-in JavaScript eval() function to convert JSON data to native JavaScript objects. However, unless the JSON data comes from a single trusted source, using eval() to parse JSON data may create security vulnerabilities in your application. For example, your application may be open to JavaScript code injection attacks if untrusted JSON data contains malicious JavaScript code, then executed by eval().

Instead of using eval(), use a JSON specific parser. It will recognize and parse only valid JSON data. Some web browsers support JSON, which come with native JSON parsers. For more information about this issue, refer to JSON in JavaScript.