Introduction

A common implementation model for Oracle Documaker Enterprise Edition ("ODEE") includes enabling interoperability with APIs and other interfaces such as enterprise service busses. For meeting these types of interoperability requirements, Documaker Web Services ("DWS") is part of ODEE — a set of SOAP 1.1 and SOAP 1.2 compliant web services that perform common functions such as submitting jobs and receiving job status or publications, and querying for information about jobs, transactions, batches, publications, and more. Business or Technical requirements may stipulate that web service security is required. Before delving into this configuration guide, it is worthwhile to review the WebLogic Server Security Service Architecture, and WebLogic Server Web Services.

Types of Web Service Security

Oracle WebLogic supports several types of Web Service security which can be applied to DWS. There are low-level security schemes such as transport-layer and message-layer security, which provide authentication/authorization as well as encryption and signatures, and web service security policies which provide a broad, extensible framework for creating security policies within WebLogic. Typically the layer-based security schemes are used to prevent inspection or alteration of messages exchanged between the service and the service consumer, whereas the security policies used to prevent access to the service as a consumer.

Transport-layer security

Transport-layer security secures the network communications between the client application and WebLogic Server by encrypting data before it is transmitted over the network. Such security is usually achieved using public key infrastructure (PKI) certificates, digital signatures, and hashing functions, and is implemented in industry-standard protocols such as SSL/TLS. There are two flavors of SSL/TLS: one-way and two-way. In one-way SSL, when a client attempts to connect to a server, the server must present an identity certificate with a valid trust chain attached to it and if the client can validate the trust chain, then the secure connection is allowed. In two-way SSL, both the client and the server must present and accept each other's identity certificates before secure communications are allowed. The keys used in these certificates are used in the encryption schemes to ensure that only the client and the server can read each other's messages. It is important to note that transport-layer security does not span all the potential connections between a client and a server – for example, in a connection over the internet from a client to a hosted server, SSL/TLS may be terminated at a an intermediary proxy service once traffic enters the hosted server's network. Other transport-layer security protocols may or may not be applied at this time, which is why message-layer security is often used with transport-layer security when the network architecture cannot be controlled.

Message-layer security

Message-layer security provides the capability to secure the contents of the messages exchanged between clients and web services hosted in WebLogic according the specifications set forth in the WS-Security standard. This standard defines several capabilities, including encrypting and/or digitally signing part or all of a message and authentication using token-based credentials. WebLogic also supports the WS-SecureConversation standard, which provides for secure sessions to facilitate the exchange of multiple messages in a stateful and secure manner between two trusted parties. It is important to note that message-layer security requires specific changes to the source code for the Web Service, and until such changes are present, message-layer security cannot be achieved for these services. At the time of this writing, DWS does not support message-layer security.

Security Policies

WebLogic provides the ability to create authorization policies that can be attached to web resources (such as applications and services) to round out the authentication/authorization security scheme. These policies can include multiple conditions combined in a multitude of way that can be based on a large number of variables such as user name, group membership, roles, and more. In order to create an authorization policy, the WebLogic domain should be configured with the desired authentication mechanism (e.g. "who are you") so that you can define the authorization (e.g. "what can you do").

Configuration Steps

The following sections illustrate how to configure Transport Layer Security and Security Policies.

Transport-Layer Security

Configuring transport-layer security is covered in great detail in the WebLogic documentation. The basic steps are:

  1. Obtain the identity for the server. How you do this depends on your organization; many large organization use internally-generated certificates for non-production environments or for internal production environments, or you may use an external vendor such as Version or Entrust. The end result of this step should be a private key and digital certificates, as well as the certificates (trust chain) for the certificate authority (CA) issuing the identity.
  2. Add the private key to the identity keystore, and add CA certificates to the trust keystore.
  3. Configure WebLogic for the identity and trust keystrokes.
  4. Configure SSL options e.g. key alias, password, and client-certificate requirements (e.g. two-way SSL).

The Oracle documentation is very in-depth, so the aim of this document is to provide guidance, and to reference the documentation for additional help. To complete the above steps in a non-production or demo environment, follow the below steps.

First, take a backup of your WebLogic domain config in the "/config" directory.

Then, using the keytool component of your JDK:

  1. Create certificates as detailed here.
  2. Create the identity and trust keystone as detailed here.

Finally, using the WebLogic Console:

  1. Login as a domain administrator.
  2. Navigate to Domain Structure > Servers > AdminServer > Keystores
  3. Click Change next to Keystores
  4. Select Custom Identity and Custom Trust,  then click Save.
  5. Enter the values for:
    1. Keystore location
    2. Keystore Type "JKS"
    3. Keystore Passphrase
    4. Repeat the settings for the trust store.
  6. Click Save.
  7. Navigate to the Configuration > General tab.
  8. Tick the box to enable SSL Listen Port, and specify the port number.
  9. Click Save, then restart the AdminServer

To test the settings, review the AdminServer startup logs to ensure you see messages similar to the below, where x.x.x.x represents the IP address of the network interface, and zzzz represents the configured SSL listen port. Note the list of protocols using the port include t3s, ldaps, and https.

<BEA-002613> <Channel "DefaultSecure" is now listening on x.x.x.x:zzzz for protocols iiops, t3s, ldaps, https.>

If you do not see this message, or see other exceptions in the log, review the Oracle documentation for SSL debugging.

Security Policies

The Oracle documentation covers the introduction, overview, and detailed configuration steps for securing resources (e.g. web applications and services) using roles and polices. For the purposes of this guide, the steps below will illustrate how to configure a basic policy to secure DWS. Refer to the linked documentation for additional details and information.

  1. Open WebLogic Console and login.
  2. Use the Domain Structure navigator and go to Deployments, then click the name of your web service, (e.g. DWS).
  3. Select the Security > Polices tab.
  4. Click Add Conditions.
  5. Select the type of predicate from the list for your condition. For example, you might restrict the web service access to a specific user or group, or to a role (that is mapped to one or more users/groups). Select the desired predicate and click Next (for this example select User).
  6. Edit the arguments for the predicate selected. This will vary based on the type of predicate. For the User predicate, we can add one or more user names. Enter your argument(s), then click Finish.
  7. The argument is added, and the predicate is now in the list for your policy. You can add more conditions, combine, reorder, or negate any of the conditions.
  8. For example, you might add a date policy that prevents access before or after a certain date, or you can combine different conditions to create complex rules. In the example to the right, the user must be weblogic, and the access attempt must be before 25 April 23, or after 25 April 26.
  9. Save the policy, and it will be applied.

To test the policy, use a test tool such as SoapUI, Postman, or your own client application. Depending on the type of policy created, you may need to adjust your client request. For example, if the conditions illustrated above are used, the client request will need to include authentication credentials. If an attempt is made to access the web service and the policy blocks the access, an appropriate response is received:

<S:Envelope>
<S:Body>
<ns0:Fault>
  <faultcode>ns0:Client.Authentication</faultcode>
   <faultstring>Access denied to operation doPublishFromImport</faultstring>
         <detail>
            <bea_fault:stacktrace>weblogic.wsee.util.AccessException: Access denied to operation doPublishFromImport

To configure Postman configuration for calling a DWS service, create a POST request to the service endpoint, and add the appropriate SOAP content to the Body of the request. If your security policy requires authentication, use the Auth tab in Postman, and select the Basic Auth type, then enter the credentials. Postman will encrypt the credentials and automatically add them to the request, which you can review on the Headers tab.

Advanced Methods: OAuth

It is possible to configure a WebLogic domain to use OAuth for authentication and for assisting in authorization. An OAuth configuration uses token generation and validation, so it is necessary to have a service that provides these features for WebLogic to consume. There are at least two options available:

Fusion Middleware and Oracle Access Manager Stack

This configuration uses Oracle Access Manager (OAM) in addition to the WebLogic Server and other Fusion Middleware components. To complete this option, you must Install and configure Oracle Access Manager (OAM), then create an Identity Domain, create a Resource, and create a Client. This setup provides the infrastructure required to generate and validate tokens, and provides the security policies that you can attach to the web services.

Custom Token Management Application

This is advanced configuration and has been covered in-depth in this article with the corresponding example code, and is useful for prototyping or situations where OAM is not viable, you can use a custom token management application.

Configuration/Deployment

  1. Make sure Oracle Web Service Manager (OWSM)  Policy Manager and Enterprise Manager (em) templates are applied to the domain. Use the config tool.
  2. In WLS Console
    1. 2.1.Create a group in the WLS security realm : tokenusers. Members of this group will be allowed to obtain tokens.
    2. 2.2.Create a user in the realm : tokenuser, and assign the password Welcome1. Add the user to the new group.
  3. Create a Keystore for OWSM. In the WLS Enterprise Manager (aka Fusion Middleware Control), login to the domain and:
    1. 3.1.Navigate to Domain > Security > Keystore
    2. 3.2.Click Create Stripe owsm
    3. 3.3.With the owsm stripe selected, click Create Keystore named “keystore”, protection by “policy”. This is because OWSM and its policies do not support password-based keystores.
    4. 3.4.Open the newly-created keystore and click Manage, then Generate Keypair. In a non-prototyping situation you would import your own keypair signed by a CA instead of generating a new key pair.
      1. 3.4.1.Common Name: oauth2keypair
      2. 3.4.2.Alias: oauth2keypair
      3. 3.4.3.Key Type RSA
      4. 3.4.4.Key Size 2048
      5. 3.4.5.Others can be empty.
  4. Configure the Token Service.
    1. 4.1.Open WLS Console and deploy a new application contained in oauth2.war, which contains the TokenService application.
    2. 4.2.Note that the default configuration in web.xml does not enforce encryption. If security is a concern you should:
      1. 4.2.1.Configure the web.xml to support <transport-guarantee>CONFIDENTIAL</transport-guarantee>
      2. 4.2.2.Configure SSL for the managed server where you target the application.As alternative you can terminate encryption prior to traffic entering WLS, then this would not be needed.
  5. Configure access for Token Service. The Token Service must have access to the keystore created above.
    1. 5.1.Login to EM and open the domain > Security > System Policies
    2. 5.2.Click Create (a new System Grant)
    3. 5.3.Grant To : Codebase
    4. 5.4.Codebase: file:${domain.home}/servers/${weblogic.Name}/tmp/_WL_user/oauth2/-
    5. 5.5.Under Permissions click Add:
      1. 5.5.1.Permission Class: oracle.security.jps.service.keystore.KeyStoreAccessPermission
      2. 5.5.2.Resource Name:  stripeName=owsm,keystoreName=keystore,alias=*
      3. 5.5.3.Permission Actions: read
      4. 5.5.4.Click OK (bottom right)
    6. 5.6.Click OK (top right)

Testing

Access the token service URL (http://yourserver:port/oauth2/resources/tokenservice) using either cURL or Postman.

cURL

$ curl -u tokenuser:Welcome1 -X POST -d "grant_type=client_credentials" http://yourserver:port/oauth2/resources/tokenservice

Postman

  1. Create a POST request called Token Request
  2. Set the URL to http://yourserver:port/oauth2/resources/tokenservice
  3. Set Authorization type: Basic Auth, and enter tokenuser/Welcome1 as the credential
  4. Set Header Content-Type to application/x-www-form-urlencoded (this should be auto-selected when you configure the Body)
  5. Set Body to x-www-form-urlencoded and add
Key: grant_type
Value: client_credentials

Note you may need to turn off SSL certificate validation if you are using demo/self-signed certificates.

RESPONSE

A valid response to either Postman or cURL should be HTTP 200 and contain a body with similar content:

{
    "access_token": "eyJraWQiOiJvYX****D_Dg",
    "scope": "read write",
    "token_type": "Bearer",
    "expires_in": 600000
}

Deploy Security Policy

Now that you have a method for obtaining tokens, you need to define a security policy that uses the tokens. You can test with a customuserpermissionpolicy.jar or use the source to model your own. This policy basically checks to see that the user is authenticated. To deploy the policy, place the JAR file in the <WLS_DOMAIN_HOME>/lib directory and restart the AdminServer and managed servers for the domain. Next, import the exported policy:

  1. Login to EM and open the domain > Web Services > WSM Policies
  2. Click Import and locate policyexport.zip from your filesystem, then click Import.
  3. CUSTOM/rest_user_assertion_policy should now be visible in the WSM Polices panel.

Secure DWS

The final step is to attach a policy to DWS.

  1. Login to EM and open the Target Navigation > Application Deployments > DWS
  2. When the deployment opens, select Application Deployment > Web Services
  3. Click an endpoint (e.g. PublishingService)
    1. 3.1.Click Attach/Detach Policies
    2. 3.2.Select CUSTOM/rest_user_assertion_policy
    3. 3.3.If encryption is used, select oracle/http_jwt_token_over_ssl_service_policy
    4. 3.4.If encryption is not used, select oracle/http_jwt_token_service_policy

With these methods, you can comply with your organization's security policies and provide secured access to your web services. If you have questions or comments, add them below, or visit the Documaker community.