This chapter explains how to use the Oracle Communications Services Gatekeeper Session Manager Web service to manage the sessions that your applications use to communicate with Services Gatekeeper.
The Session Manager Web service contains operations for managing a session with Services Gatekeeper, including establishing the session, changing the application's password, querying the amount of time remaining in the session, refreshing the session, and terminating the session.
Note:
Not all installations of Services Gatekeeper require session management. The contents of this chapter apply only to those installations that do.When an operator requires it, an application must establish a session with Services Gatekeeper before the application can perform any operations using the Parlay X or Extended Web Services interfaces. When a session is established, a session ID is returned, which must be used in each subsequent operation toward Services Gatekeeper.
In order to interact with Services Gatekeeper, applications use SOAP-based, RESTful, OneAPI, or SOAP native interfaces. Those applications using SOAP-based interfaces must manipulate the SOAP messages that they use to make requests in certain specialized ways. They must add specific information to the SOAP header, and, if they are using Multimedia Messaging, they must send their message payload as a SOAP attachment. Applications using the native interfaces use the normal, native interface mechanisms, which are not covered in this document.
How developers program applications to manipulate SOAP messages depend on the environment in which the application is being developed.
Note:
Clients created using Axis 1.2 or older do not work with some communication services. Developers should use Axis 1.4 or newer if they wish to use Axis.For examples of using the Oracle WebLogic Server environment manipulate SOAP messages, see "Managing SOAP Headers and Attachments Programmatically".
You can configure whether SOAP, REST, or OneAPI-based applications must provide credentials and apply for a session ID before they can communicate with Services Gatekeeper. The default setting requires that these types of applications establish a session using the Session Manager Web service before they are allowed to run traffic through Services Gatekeeper. You can also make a session optional, or simply remove session checking completely.
The session requirement is useful as a security mechanism because it requires all applications to authorize themselves, and it allows Services Gatekeeper to keep track of all traffic for a session.
An application establishes a session in Services Gatekeeper by invoking the getSession() operation in the Session Manager Web service. The getSession() operation is the only operation that does not require a session ID to be invoked. This operation returns a string representing the session ID to the client, and Services Gatekeeper establishes a session identified by the ID string. See "Operation: getSession" for details about this operation.
Sessions last until they time out or until the application closes the session. You configure the timeout interval. Each session is valid for the entire Services Gatekeeper domain, across clusters, and covers all communication services to which the application has contractual access. Once established, the session ID must appear in the wlng:Session element in the header of every subsequent SOAP request.
Example 3-1 Example of a Session Header element
<Session> <SessionId>app:-2810834922008400383</SessionId> </Session>
You can configure the session mode that determines whether session IDs are required. The mode has these possible values:
Required - The default value. Requires that all applications authorize themselves with credentials before requesting a session ID. Services Gatekeeper validates session IDs and rejects communication attempts if the IDs are invalid. If the mode is Required, a session ID is required for all communication through Services Gatekeeper.
Disabled (sessionless) - Services Gatekeeper does not check whether a session ID exists. If applications successfully authenticate themselves, they receive a session ID string of sessionless, which is used in all communication within the session. If they do not authenticate, no session ID is provided or required. In this case the application uses whichever Web services Security (WS-Security) mechanism is required by the Services Gatekeeper operator for security.
Optional - Services Gatekeeper does not require that an application log on or request a session ID. If the application successfully authenticates, it is provided with a session ID that is checked for validity. If found invalid, the request is rejected. If the application passes in a header with a session ID of sessionless, or if no session ID is passed in, the request is accepted.
To change the Services Gatekeeper session mode:
Start the MBean browser that you use to configure Services Gatekeeper.
You can browse MBeans by using JConsole or PTE, which are supplied with Services Gatekeeper.
Navigate to wlng, then AccountService, then ApplicationSessionMBean, and then SessionRequired.
Check the box representing the session behavior that your implementation requires:
Required
Disabled
Optional
See "About Sessions" for details on the different options.
The WSDL file for the Session Manager Web service can be found here:
http://host:port/session_manager/SessionManager
where host and port are the host name and port of the system on which Services Gatekeeper is installed.
The Session Manager Web service interface includes these operations:
Establishes a session using WS-Security. Authentication information must be provided according to WS-Security. See "Understanding SOAP-Based Authentication" for more information.
Changes the password for an application.
Gets the remaining lifetime of an established session. The default lifetime is configured in Services Gatekeeper.
Refreshes the lifetime of a session. The session can be refreshed during a time interval after the session has expired. This time interval is configured in Services Gatekeeper.
Example 3-2 illustrates how to get the Session Manager Web service and how to prepare the generated stub with WS-Security information. The stub is generated from the Session Manager Web service.
Example 3-2 Get the Session Manager Web Service
protected ClientSessionManImpl(String sessionManagerURL, PolicyBase pbase) throws Exception {
SessionManagerService accessservice =
new SessionManagerService_Impl(sessionManagerURL+"?WSDL");
port = accessservice.getSessionManager();
pbase.prepareStub((Stub)port);
}
Example 3-3 illustrates how to prepare the Session Manager Web service stub with username token information according to WS-Policy.
Example 3-3 Prepare the Session Manager with Username Token information
package com.bea.wlcp.wlng.client.access.wspolicy;
import weblogic.wsee.security.unt.ClientUNTCredentialProvider;
import weblogic.xml.crypto.wss.WSSecurityContext;
import javax.xml.rpc.Stub;
import java.util.ArrayList;
import java.util.List;
public class UsernameTokenPolicy implements PolicyBase {
private String username;
private String password;
public UsernameTokenPolicy(String username, String password) {
this.username = username;
this.password = password;
}
public void prepareStub(Stub stub) throws Exception {
List<ClientUNTCredentialProvider> credProviders = new ArrayList<ClientUNTCredentialProvider>();
credProviders.add(new ClientUNTCredentialProvider(username.getBytes(),
password.getBytes()));
System.out.println("setting standard wssec");
stub._setProperty(WSSecurityContext.CREDENTIAL_PROVIDER_LIST,
credProviders);
}
}