This page describes how to configure Oracle Beehive for SAML
authentication and how to develop Oracle Beehive Web Services clients
that use SAML authentication.
Configuring Oracle Beehive Web Services Security for SAML Authentication
Security Assertion Markup Language (SAML) is an XML-based framework for exchanging security information. Oracle Beehive Web services support SAML tokens for message authentication. Enabling SAML token authentication for Oracle Beehive Web services involves configuring the Oracle Beehive keystore, which is an Oracle Wallet.
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.
Alternatively, follow these steps to create an auto-login wallet and configure it for Oracle Beehive:
Ensure that the environment variable ORACLE_HOME is set to the home directory of Oracle Beehive.
The Oracle Beehive command-line utility, beectl, is located in <Oracle Beehive home>/beehive/bin. <instance> is name of your Oracle Beehive instance. To retrieve the full instance name, run the command beectl list_components --type BeehiveInstance.
Activate the configuration and restart by running the following beectl command:
beectl activate_configuration
Notes:
If the beectl activate_configuration command asks you to run the beectl modify_local_configuration_files command, run this command.
The beectl modify_local_configuration_files will ask you to run this command on all your other instances. Do not run this command on all your other instances at this time. For each instance, you must perform steps 3 and 4 before running the beectl modify_local_configuration_files command.
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.
Adding a Self-Signed Certificate
Add a self-signed certificate to the wallet with the following command:
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
Add a certificate request to the Oracle Beehive wallet:
CN=user is the distinguished name of an arbitrary user who will issue the private key, who will also be the SAML authentication assertion issuer. Later, you will register this SAML authentication assertion issuer with Oracle Beehive.
The file certificate_request.txt is the exported certificate request.
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.
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:
Exporting Certificates to Client-Side Oracle Wallet
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.
If you are using a self-signed certificate, follow these steps:
Export the self-signed user certificate to a file:
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
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.
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:
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.
Generating Web Service Proxy Classes
The following steps generate proxy classes with the SAML WSDL
document with JDeveloper:
Obtain the location of the SAML WSDL document. 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.
Create a new empty project. Set the default package of the project to oracle.beehive.ws:
In the System Navigator, right-click your project and select Project Properties.
In the tree view, select Project Content. In the text field Default Package, enter oracle.beehive.ws.
Generate proxy classes for each Oracle Beehive Web service. For the WSDL Document URL, enter http://<Oracle
Beehive host>:<Web services
port>/ws/saml/<Web service
name>?WSDL. Refer to "Running Basic Web Service Samples" in "Oracle Beehive Basic Web Services Samples" for more information about generating proxy classes.
If you want to use the WebServicesAssembler tool to generate proxy classes, save the SAML WSDL document for each Oracle Beehive Web service in a directory. In addition, save the file custom_schema.xsd in the same directory. The location of this file is http://<Oracle Beehive host>:<Web services port>/ws/custom_schema.xsd. Refer to Chapter 18, "Using WebServicesAssembler" in Oracle Application Server Web Services Developer's Guide for more information about the WebServicesAssembler tool.
This section describes three simple command-line clients that demonstrate the available SAML authentication methods. Each client performs the same task: print out the user's workspace information.
The examples described in this section involve the following files:
The only difference between MySenderVouchesClient.java and MyHolderOfKeyClient.java is the SAML authentication method being used; no other code changes are required if you choose to use either of these authentication methods.
The MyUsernamePasswordClient.java does not use SAML authentication but uses the same authentication techniques (dynamically generating and setting the runtime configuration string). For a simpler way to authenticate Oracle Beehive Web Services with plain-text username/password authentication, refer to Oracle Beehive Basic Web Services Samples
.
Configure Development Environment
Ensure you have the following libraries and .jar files in your
classpath. The libraries are available from JDeveloper:
Set Required Information for SAML Assertion Issuer
The following table describes the properties required by the SAML
assertion issuer. Set these properties in a properties file such as MyClientSecurity.properties.
Properties Required By SAML Assertion Issuer
Property
Required/Optional
Description
beehive.ws.security.keystore.path
Required
Keystore path that contains
the issuer's private key and certificate
beehive.ws.security.keystore.type
Required
Keystore type
beehive.ws.security.keystore.password
Optional
Keystore password, if any, in plain-text format.
If you plan to store security
related properties in a properties file similar to
MyClientSecurity.properties in a
production environment, this password should be obfuscated. In
addition, you should also control access to the property file
should also be controlled.
beehive.ws.security.signature.key.alias
Required
Alias of the issuer's private
key. Note that issuer's private key is used to sign the SAML
assertion.
beehive.ws.security.signature.key.alias
Optional
Password required to access
the issuer's private key indicated by the
beehive.ws.security.signature.key.alias property.
beehive.ws.security.signature.algorithm
Optional
Signature algorithm to be
used. The signature algorithm is auto-detected if not specified.
beehive.ws.security.signature.inbound
Optional
Indicates whether a signature
is required for inbound messages. Valid values are true or false.
If true, then the inbound message signature is verified. Default
value is false.
beehive.ws.security.signature.expiry
Optional
Expiry time property
determines multiple parameters for the client. For assertion
generation, the expiry value determines the assertion validity
duration since the creation of the assertion. For the SOAP
outbound messages, the expiry value determines the validity
duration since the creation of the message. For the SOAP inbound
messages, the expiry value determines the validity duration of
the signature. The unit is in milliseconds. Default value is 1
hour.
beehive.ws.security.issuer.name
Required
Assertion issuer name
beehive.us.security.subject.format
Optional
Subject name format. Default value is UNSPECIFIED.
Initialize Client
The following code excerpt initializes a client for SAML authentication:
public void initialize() throws Exception {
// Get the service factory instance
ServiceFactory factory = ServiceFactory.newInstance ();
// Get the workspace service port instance
m_wspSvcPort = ((WorkspaceService_Service)factory.loadService
(WorkspaceService_Service.class)).getWorkspaceService ();
// Load the configuration
m_secCfg = new ClientSecurityCfg ();
ResourceBundle myResourceBundle =
ResourceBundle.getBundle(
"oracle.beehive.ws.example.saml.MyClientSecurity");
Properties myProperties = new Properties();
for (Enumeration keys = myResourceBundle.getKeys(); keys.hasMoreElements();) {
final String key = (String) keys.nextElement ();
final String value = myResourceBundle.getString (key);
myProperties.put(key, value);
}
m_secCfg.load (myProperties);
// Get the issuer configuration then set it on the thread
SamlAuthnAssertionIssuerCfg.setCfg (m_secCfg.getSamlAuthnAssertionIssuerCfg ());
}
You access the methods of Oracle Beehive Web Services from classes of the form <Web Services name>_PortType. For example, you would access the methods of WorkspaceService from the class WorkspaceService_PortType. You would retrieve an instance of this class through the method ServiceFactory.loadService.
Note that if you have generated the proxy classes with the SAML
WSDL document, you use the class WorkspaceService_PortType to access the Web service port for both username/password authentication and SAML assertion authentication even though the classes WorkspaceServiceClient.java and WorkspaceService_saml_authn__Client.java exist.
The class oracle.ocs.csi.authentication.saml.utils.ClientSecurityCfg enables you to load the Web Services client security configuration. The method ClientSecurityCfg.load() loads the security configuration from a Properties object or the full path name of a properties file.
The class oracle.ocs.csi.authentication.saml.SamlAuthnAssertionIssuerCfg stores the configuration parameters related to the SAML assertion issuer.
Configure SAML Token for Client
The following code excerpt configures the SAML token
public void bzx () throws Exception {
// ...
// Set security configuration
String runtimeSecurityCfg = m_secCfg.getRuntimeSecurityCfg (m_method);
((Stub)m_wspSvcPort)._setProperty(
ClientConstants.CLIENT_CONFIG,
XMLUtil.elementFromString (runtimeSecurityCfg));
// set the service endpoint
((Stub)m_wspSvcPort)._setProperty(
Stub.ENDPOINT_ADDRESS_PROPERTY,
this.m_WorkspaceServiceEndpoint);
// set the credential
SamlAuthnAssertionBuilder.Subject subject =
m_secCfg.newSubject(m_method, this.m_userName);
OcsSamlTokenCallbackHandler.setSubject (subject);
// ...
}
The method ClientSecurityCfg.getRuntimeSecurityCfg() retrieves the Web Services client runtime security string depending on the authentication method you are using. This method takes a ClientSecurityCfg.AuthenticationMethod object as an argument, which is an enumerated type that can have one of the following values:
The Web Services endpoint to set depends on which authentication method you are using. For SAML holder-of-key and SAML sender-vouches, use http://<host name>:<port number>/ws/saml/<Web Services name>. For username/password authentication, use http://<host name>:<port number>/ws/<Web Services name>.
The class SamlAuthnAssertionBuilder.Subject represents the subject being asserted. The method ClientSecurityCfg.newSubject creates an appropriate Subject object depending on the authentication method and the configuration parameters stored in the ClientSecurityCfg object. This method takes two arguments, a ClientSecurityCfg.AuthenticationMethod enumerated type (which represents the authentication method) and a String that represents the user.
The class oracle.ocs.csi.authentication.login.callback.OcsSamlTokenCallbackHandler plugs into the existing Oracle Web Services infrastructure to provide the SAML assertion. Note that regardless of the subject name passed to the callback handler by the Oracle Web Services infrastructure, the subject set by the OcsSamlTokenCallbackHandler.setSubject() method is used to generate the SAML assertion.
Alternatively, if your client needs a static security descriptor,
create the file
oracle/beehive/ws/client/runtime/WorkspaceService_PortType_WorkspaceService_Stub.xml
(assuming you generated the proxy classes in the package oracle.beehive.ws.client and that you are using WorkspaceService) and ensure it is packaged in the same .jar file as the rest of your generated proxy classes. For information about
creating a static security descriptor configured for SAML assertion
authentication, refer to Chapter 3, "Administrating Web Services
Security" in Oracle Application Server Web Services Security
Guide.
Call Web Services Methods
The method bzx in the examples performs workspace-related functions. It calls the getWorkspace operation on the workspace of the current
logged in user:
Bookmark
