Security Layer Walkthrough

Figure 10.1 shows a simplified flow through the WebLogic Server runtime and into the WebLogic Workshop runtime. This diagram shows the three security areas, with WebLogic Server having responsibility for transport security and WebLogic Workshop having responsibility for message-based security and role-based security.

Figure 10.1. Web Services Security layers .

When a message comes into WebLogic Server destined for a Workshop Web service and transport security has been configured, WebLogic Server, taking advantage of the WebLogic Security Framework, does the following:

1. Negotiates the SSL connection.

2. Gathers and validates credentials (username/password, X.509 certificate, and so on).

3. Maps the credentials to a user .

4. Maps the user to roles.

If transport security is not specified, or even if it is, the next layer is message-based security, which is handled by the WebLogic Workshop runtime. You can receive three types of security artifacts in a message security scenario: tokens, XML Encryption, and XML Signature. WebLogic Workshop works with the WebLogic Security Framework to

1. Extract the token (similar to credentials), validate it, and perform the credential-to-user-to-role mapping.

2. Decrypt or encrypt the XML Encryption.

3. Sign and verify XML Signatures.

For both transport- and message-based security, the result in your JWS is that a user (an authenticated Subject , to use Java Authentication and Authorization Service, that is JAAS, terms) is bound to your thread, and you are subsequently able to use role-based security. Although Figure 10.1 shows both transport- and message-based security, it is likely that in WebLogic Workshop you will choose one or the other to secure your Web services.

Once you are in your JWS, you can use several annotations to enforce role-based security. Role-based security allows you to specify what roles can access functionality within your Web services. Using roles instead of specific users allows administrators to add and remove users from the roles versus having to change code to accomplish this task. The most common way to use roles is to specify the roles that are allowed using the @common:roles-allowed annotation either at the top of the JWS or over a specific operation within a JWS.

The following sections briefly describe how Workshop supports these three security layers.

Transport-Level Security

Three interrelated options are available when you use transport security. One is to use one-way SSL; this accomplishes two tasks :

• The server is authenticated.

• The session is encrypted.

The second option is to use basic authentication. HTTP basic authentication is username/password-based authentication. One point to remember when designating basic authentication is that the password is put in an HTTP header in the clear. To overcome this, you usually combine one-way SSL with basic authentication.

The final, most powerful, but also most complex option is to use two-way SSL, also known as client authentication . When you use this option, both the client and server authenticate to each other using X.509 certificates.

The primary approach to configuring transport security inbound is to make configuration changes in web.xml within your Web application's WEB-INF directory. You can consult the WebLogic Workshop documentation for specific setup information. In the case of client authentication, you also must tell WebLogic Server to request the client certificate by selecting this option on the console.

For outbound transport security, for example, when you call a Web service that requires transport security, WebLogic Workshop provides an API for setting the username/password or client certificate information.

Message-Level Security

WebLogic Workshop supports all three types of security artifacts that can be contained in a WS-Security security header: tokens, an XML Encryption element, and/or an XML Signature element.

The WebLogic Workshop implementation supports two token types: UserNameToken , which represents a username and a password, and BinarySecurityToken with a type of X509 (we call this X509Token ), which represents an X.509 certificate. You can include a UserNameToken by itself; however, in Workshop, X509Token must be accompanied by an XML Signature. This makes sense because an X.509 certificate is a public piece of information that, by itself, does not prove anything about the identity of the sender. A corresponding XML Signature is needed to prove that the sender had control of the associated private key associated with X509Token .

In WebLogic Workshop, if you designate encryption, the SOAP body is encrypted along with the conversation header if you are participating in a conversation.

XML Signature is used for two purposes:

• To authenticate the identity of the sender, which is accomplished via the X509Token .

• To ensure the integrity of the message. If even a single bit of the message has changed, the XML Signature validation will fail.

In WebLogic Workshop, if you designate a signature, the SOAP body is digitally signed along with the conversation header if you are participating in a conversation.

To configure WS-Security in WebLogic Workshop, you create a WS-Security policy file and associate it with your Web service by using the following annotation:

 @jws:ws-security-policy-service file="yourPolicy.xml" 

Putting this annotation at the top of your JWS configures the WS-Security policy for messages coming into your Web service. Putting this annotation at the top of a Web service control configures the WS-Security policy for a Web service you are calling.

The WS-Security annotation points to an XML file containing the WS-Security policy you want to apply. Corresponding to the request and response message in a typical synchronous Web service call are two sections in a WS-Security policy: wsSecurityIn and wsSecurityOut .

In wsSecurityIn , you declare what security you expect in your Web service. This policy answers the following questions:

• Does this Web service require a token, and if so, which type?

• Does it require encryption?

• If the Web service requires encryption, where is the private key to decrypt with?

• Is a signature required?

On the other hand, wsSecurityOut answers these questions:

• Does a token need to be added to this message on the way out, and if so, which type?

• Does this message need to be encrypted?

• If so, what public key should be used to encrypt the message?

• Does the message need to be signed, and if so, what private key should be used to create the XML Signature?

Role-Based Security

The result of transport- or message-based security is an authenticated subject that has a corresponding set of roles associated. These roles are your primary mechanism for security within your JWS. The annotation @common:security is used for role-based security, and the possible attributes are roles-allowed , roles-referenced , and run-as . You can also use the API context.isCallerInRole("role") , where context is an instance of the weblogic.jws.JwsContext class within your code to test for a specific role.

The most commonly used annotation is roles-allowed . As you might expect, if you use roles-allowed , only users belonging to the specified roles can execute the requested operation. The roles-allowed annotation can be used at the class level (above the class declaration) or above an operation. When an operation is invoked, roles-allowed at the class level and roles-allowed at the operation level are unioned. Thus, adding roles-allowed at the operation level expands the number of roles able to access a particular application.

The @common:security roles-referenced attribute enables you to surface the roles that you have accessed in your JWS code using context.isCallerInRole("role " ) . The objective is to allow the roles that you have used in your code to be mapped to the roles that are appropriate for the target environment. Thus, you can choose roles that make sense in the scope of your application but are named differently in the deployment environment.

The @common:security run-as attribute enables you to change your identity within your JWS so that when you call out, you assume this new identity. For example, if you have a database or Enterprise JavaBean (EJB) that requires you to have the role of system, you can use run-as to change the outbound identity of your JWS.

Now let's walk through an example of using these security types in WebLogic Workshop.