Skip Headers
Oracle® Beehive Application Developer's Guide
Release 1 (1.4)

Part Number E13800-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

3 Oracle Beehive Web Services

This module describes the Web services available in Oracle Beehive and how to access them.

The following are the names of all Oracle Beehive Web services:

See Appendix A, "Oracle Beehive Web Services" for descriptions of Oracle Beehive Web services methods and the data types they use.

Web Service Locations

Each Web service URL has the following syntax:

http://<Oracle Beehive server host>:<Port>/ws/<Web service name>

When you open a Web service URL in a browser, you will find a form that enables you to input parameters and invoke different methods in the Web service.

This form also contains a link named "Service Description" that brings you to the WSDL for the Web service. The following is the syntax for the WSDL URL:

<Web service URL>?WSDL

For example, if your Oracle Beehive server host is www.example.com and its port is 7777, then the following is the location for WorkspaceService:

http://www.example.com:7777/ws/WorkspaceService

The following is the location for the WSDL of WorkspaceService:

http://www.example.com:7777/ws/WorkspaceService?WSDL

To use Web services in a Java programming environment, you must generate proxy classes for each Web service you use. In JDeveloper, use the Web service WSDL URL to generate proxy classes.

Web Services Security and SAML

Security Assertion Markup Language (SAML) is an XML-based framework for exchanging security information. Oracle Beehive Web services support SAML tokens for message authentication. SAML authentication enables you to secure Web Services clients with a different authentication mechanism that does not require the user name and password of any Oracle Beehive users. Enabling SAML token authentication for Oracle Beehive Web Services involves configuring the Oracle Beehive keystore, which is an Oracle Wallet.

Oracle Beehive Web Services supports SAML sender-vouches and SAML holder-of-key authentication methods.

In a sender-vouches scenario, an attesting entity has an existing trust relationship with the receiver (Oracle Beehive). The attesting entity vouches for the verification of the subject (such as a user invoking a Web Services client). In this scenario, you first establish the attesting entity (who is simply an arbitrary user) by adding a signed user certificate (issued by the attesting entity) and the associated trusted certificate to the Oracle Beehive keystore. Then, you establish the trust relationship between the attesting entity and Oracle Beehive with the command beectl add_trusted_identity. In your Web Services client, you specify the distinguished name of the attesting entity in the SAML token.

In a holder-of-key scenario, there is a third party involved, the identity provider, who has the existing trust relationship with the receiver. In this scenario, you add a signed user certificate (signed by the identity provider) and the associated trusted certificate to the Oracle Beehive keystore. In your Web Services client, you include the location of a keystore in the SAML token. This keystore contains a user certificate (signed by the identity provider) and the associated trusted certificate.

For more information about SAML, refer to the following chapters and sections in Oracle Application Server Web Services Security Guide:

Configuring Oracle Beehive Web services to use SAML authentication involves the following steps:

  1. Creating Server-Side Auto-Login Wallet and Configuring it for Oracle Beehive

  2. Adding Signed User Certificate and Associated Trusted Certificate to Server-Side Wallet

  3. Exporting Certificates to Client-Side Oracle Wallet

  4. Configuring Oracle Beehive for SAML Authentication

To create a Web service client that uses Oracle Beehive Web services secured for SAML authentication, refer to "Location of SAML WSDL Documents", then refer to the Oracle Beehive Web site on Oracle Technology Network for sample code.

Creating Server-Side Auto-Login Wallet and Configuring it for Oracle Beehive

If you have not already done so, create an auto-login Oracle Beehive and configure it for Oracle Beehive as described in "Configuring TLS with Oracle Wallet" in the Oracle Beehive installation guide of your operating system.

Adding Signed User Certificate and Associated Trusted Certificate to Server-Side Wallet

You may either add a self-signed certificate or a CA-signed (certificate authority) certificate.

Use a self-signed certificate only for test purposes because it does not provide adequate security for a production environment. With a self-signed certificate, a user creates a certificate, then signs it with his or her own private key. In this case, the user himself or herself is verifying his or her own identity, and therefore, you should not trust the certificate.

With a CA-signed certificate, a user creates a certificate, then has a trusted CA, such as VeriSign, sign it. This means that the CA (who you trust) has verified the identity of the user (meaning that the CA certifies that the public key is of the claimed entity). Therefore you may trust the certificate. Consequently, use a self-signed certificate in situations where security is not an issue, such as test environments. In a production environment, you should use a CA-signed certificate.

Adding a Self-Signed Certificate

Add a self-signed certificate to the wallet with the following command:

orapki wallet add
  -wallet <Oracle home>/Apache/Apache/conf/ssl.wlt/default/
  -dn CN=user
  -keysize 2048
  -self_signed
  -validity 3650

CN=user is the distinguished name of an arbitrary user who will issue the private key and also be the SAML authentication assertion issuer. Later, you will register this SAML authentication assertion issuer with Oracle Beehive.

Adding a CA-Signed Certificate

  1. Add a certificate request to the Oracle Beehive wallet:

    orapki wallet add
      -wallet <Oracle home>/Apache/Apache/conf/ssl.wlt/default/
      -dn CN=user
      -keysize 2048
      -validity 3650
    

    The directory <Oracle home>/Apache/Apache/conf/ssl.wlt/default/ is the Oracle Beehive default wallet directory. CN=user is the distinguished name of an arbitrary user who will issue the private key and also be the SAML authentication assertion issuer. Later, you will register this SAML authentication assertion issuer with Oracle Beehive.

  2. Export the certificate request to a file:

    orapki wallet export
      -wallet <Oracle home>/Apache/Apache/conf/ssl.wlt/default/
      -dn CN=user
      -request certificate_request.txt
    

    The file certificate_request.txt is the exported certificate request.

  3. With your certificate authority (CA) and your certificate request (certificate_request.txt), create a signed user certificate. In addition, export the trusted certificate from your CA. These steps use the file user_certificate.txt as the signed user certificate and the file trusted_certificate.txt as the trusted certificate exported from your CA.

    You may use Oracle Wallet as a CA for testing purposes by following these steps.

    1. Create an auto-login wallet to act as a certificate authority. These steps assume that this wallet is stored in /private/ca_wallet. Create a signed certificate from the request for test purposes:

      orapki cert create
        -wallet /private/ca_wallet
        -request certificate_request.txt
        -cert user_certificate.txt
        -validity 3650
      

      The file user_certificate.txt is the signed user certificate.

    2. Export the trusted certificate from the CA wallet:

      orapki wallet export
        -wallet /private/ca_wallet
        -dn CN=ca_user
        -cert trusted_certificate.txt
      

      The file trusted_certificate.txt is the exported (test) trusted certificate from the CA wallet.

  4. Add the trusted certificate from the CA to the Oracle Beehive wallet:

    orapki wallet add
      -wallet <Oracle home>/Apache/Apache/conf/ssl.wlt/default/
      -trusted_cert
      -cert trusted_certificate.txt
    
  5. Add the user certificate to the Oracle Beehive wallet:

    orapki wallet add
      -wallet <Oracle home>/Apache/Apache/conf/ssl.wlt/default/
      -user_cert user_certificate.txt
    

Exporting Certificates to Client-Side Oracle Wallet

  1. Create a wallet with the orapki wallet create command on the machine from which you will run your Web services client. These steps assume that you have created this wallet in the directory /private/client_side_wallet.

  2. If you are using a self-signed certificate, follow these steps:

    1. Export the self-signed user certificate to a file:

      orapki wallet export
        -wallet <Oracle home>/Apache/Apache/conf/ssl.wlt/default/
        -dn CN=user
        -cert exported_certificate.txt
      
    2. Add the self-signed certificate to the client-side wallet:

      orapki wallet add
        -wallet /private/client_side_wallet
        -user_cert exported_certificate.txt
      
  3. If you are using a CA-signed certificate, follow these steps:

    1. Add the trusted certificate from the CA to the client-side wallet:

      orapki wallet add
        -wallet /private/client_side_wallet
        -trusted_cert
        -cert trusted_certificate.txt
      
    2. Add the CA-signed user certificate to the wallet:

      orapki wallet add
        -wallet /private/client_side_wallet
        -user_cert user_certificate.txt
      

Note:

For testing purposes, you may simply copy the server-side keystore to the machine from which you will run your Web services client.

Configuring Oracle Beehive for SAML Authentication

  1. In the component _authenticationService, set the following properties with the beectl command:

    • WsSecuritySamlEnabled: true

    • WsSecuritySigKeyAlias: This is the distinguished name you specified when you created a self-signed certificate or certificate request.

    beectl list_properties --component _authenticationService
     
    ----------------------+----------------------------------------------------
    Property name         | Property value
    ----------------------+----------------------------------------------------
    ...
    ----------------------+----------------------------------------------------
    WsSecuritySamlEnabled | false
    ----------------------+----------------------------------------------------
    WsSecuritySigKeyAlias |
    ----------------------+----------------------------------------------------
    WsSecuritySigKeyPwd   |
    ----------------------+----------------------------------------------------
    ...
    27 Record(s) displayed.
     
    beectl modify_property
      --component _authenticationService
      --name WsSecuritySamlEnabled
      --value true
     
    Changes to configuration repository are not activated.
    Successfully stored the property for component id cfaaf634-df35-46da-b5e7-456672d9b495.
     
    beectl modify_property
      --component _authenticationService
      --name WsSecuritySigKeyAlias
      --value "CN=user"
     
    Changes to configuration repository are not activated.
    Successfully stored the property for component id cfaaf634-df35-46da-b5e7-456672d9b495.
     
    beectl list_properties --component _authenticationService
     
    -----------------------+---------------------------------------------------
    Property name          | Property value
    -----------------------+---------------------------------------------------
    ...
    -----------------------+---------------------------------------------------
    *WsSecuritySamlEnabled | true
    -----------------------+---------------------------------------------------
    *WsSecuritySigKeyAlias | CN=user
    -----------------------+---------------------------------------------------
    ...
    27 Record(s) displayed.
    NOTE:- * indicates that property value is changed and change is not yet activated.
     
    beectl activate_configuration
     
    Local configuration files are not in sync with system model. Please run "modify_local_configuration_files" manually.
    Proposed configuration is saved successfully and activated now.
     
    beectl modify_local_configuration_files
     
    The following local configuration files were modified for authentication
    ...
    Successfully ran the command in Oracle home /example/product/beehive.
    Please run this command on all midtier instances.
    
  2. Register the SAML authentication assertion issuer. Depending on the type of SAML authentication you are using, follow one of these steps:

    • If you are using SAML sender-vouches authentication, register the SAML issuer as a trusted service identity with the following beectl command:

      beectl add_trusted_identity
        --type WSSEC
        --is_service true
        --key_alias CN=user
        --service_name example.com
      

      The DN CN=user is the alias of the trusted service certificate and example.com is an arbitrary name to identify this trusted service identity.

    • If you are using SAML holder-of-key authentication, register the SAML issuer as a trusted issuer identity with the following beectl command:

      beectl add_trusted_identity
        -type WSSEC
        --is_service false
        --key_alias CN=user
        --service_name example.com
      

Note:

The --service_name option specifies the name of the service that is being authenticated. It is used only for sender-vouches authentication.

When you use sender-vouches subject confirmation, Oracle Beehive first authenticates the service name, then authenticates the credential in the message (which is the user credential). This, you may interpret running the command beectl add_trusted_identity as "Add a service with name <service name> to the list of trusted services kept by Oracle Beehive. This service can perform actions for Oracle Beehive end users".

Location of SAML WSDL Documents

After configuring Oracle Beehive for SAML authentication, the location of this WSDL document will be http://<Oracle Beehive host>:<Web services port>/ws/saml/<Web service name>?WSDL.

For example, if your Oracle Beehive instance is hosted on example.com, the Web services port is 7777, and you want to generate the proxy classes for WorkspaceService, you would use the SAML WSDL document located at http://example.com:7777/ws/saml/WorkspaceService?WSDL.

Searching for Artifacts with Web Services

You may use the following methods to search for artifacts with Oracle Beehive Web Services:

Searching for Artifacts with Filters

Each Web service contains one or more methods whose name starts with "get" that retrieves artifacts of the specified type. For example, the GetWorkspaces method of WorkspaceService retrieves workspaces.

Each of these get methods may take a WSFilter object as an input element. A filter determines the contents of the returned list of artifacts for the get method. It consists of the following:

  • A WSLogicalOperator object named anyAllListRelation.

    • If the value of this object is AND, then an artifact will be selected by the filter if both matchAllList and matchAnyList evaluate to true.

    • If the value of this object is OR, then an artifact will be selected by the filter if either matchAllList or matchAnyList evaluate to true.

  • A list of WSPredicate objects named matchAnyList. It evaluates to true if any of its predicates are satisfied

  • A WSProjection object. A projection defines the amount of data retrieved for each item in the retrieved list of artifacts. It may have a value of FULL, NONE, BASIC, or META. Use NONE or BASIC if you expect the retrieved list of artifacts to be large and do not require detailed information for each artifact to improve the performance of the get method.

  • A list of WSPredicate objects named matchAllList. It evaluates to true only if all of its predicates are satisfied

  • A list of WSSortCriteria objects named sortCriteriaList. A sort criteria contains a parameter (for example, NAME) by which you want to sort the retrieved list of artifacts and the sort order you want the artifacts ordered (either ascending or descending)

A predicate contains the value you want to find, the kind of value you want to find, and the operation you want to use to evaluate the search. For example, you may define a predicate that determines whether a particular artifact contains (which is the operation) the string "Summary" (which is the value) in the name parameter (which is the kind of value you want to find).

Refer to "Oracle Beehive Basic Web Service Samples" found in the Oracle Beehive Web site on Oracle Technology Network for examples of how to search with filters.

Searching for Artifacts with FindArtifacts Method of GeneralArtifactService

The searchString input element of the FindArtifacts method of GeneralArtifactService method accepts any string value, which is then used to perform a basic keyword search across all searchable artifacts in Oracle Beehive. Currently, Oracle Beehive supports searching of e-mail messages, documents, and calendar meetings. The following attributes are included in basic keyword searches in Oracle Beehive. Use wildcards (asterisk (*) and question mark (?) by default) to search all the following attributes except ID attributes, which only support exact matches:

  • Documents

    • Name

    • Creator name

    • Creator ID (internal enterprise ID)

    • Content

  • E-mail messages

    • Subject

    • Sender name

    • Sender ID (internal enterprise ID)

    • To, Cc, or Bcc recipient

    • Body

  • Meetings

    • Title

    • Creator ID (internal enterprise ID)

    • Details

    • Invitees

Refer to "Oracle Beehive Basic Web Service Samples" found in the Oracle Beehive Web site on Oracle Technology Network for an example of GeneralArtifactService that demonstrates how to search with FindArtifacts.