The security programming model differs between the client and server side. The client side model is programmatic in nature, i.e. security related code is driven by making actual function calls, whereas the server side model is declarative, i.e. security related settings are declared in a security descriptor. For more information on the available client side calls see Section 7, “Semantics and syntax of domain-specific interface”. More information about the security descriptor can be found in Java WS Security Descriptor Framework .

1.2. Component API

Stable interfaces:
- org.globus.wsrf.security.Constants
- org.globus.wsrf.security.SecureResource
- org.globus.wsrf.security.SecurityManager
- org.globus.wsrf.security.SecurityException
Less stable interfaces:
- org.globus.wsrf.impl.security.descriptor.ClientSecurityDescriptor
- org.globus.wsrf.impl.security.descriptor.ResourceSecurityDescriptor

Documentation for these interfaces can be found here.

2. Semantics and syntax of the WSDL

2.1. Secure Conversation Service

2.1.1. Protocol overview

This service provides a mechanism for generating a security session, i.e the negotiation of a shared secret which may be used to secure a set of subsequent messages. It is based on the WS-Trust and WS-SecureConversation specifications.

2.1.2. Operations

RequestSecurityToken: This operation initiates a new security session negotiation. Furthermore, since the actual schema for this message is not unambiguously defined by the specifications, this is the actual schema used:

<xs:element name='RequestSecurityToken'>
   <xs:complexType name='RequestSecurityTokenType'>
      <xs:sequence>
         <xs:element ref='wst:TokenType'/>
         <xs:element ref='wst:RequestType'/>
         <xs:element ref='wst:BinaryExchange'/>
      </xs:sequence>
      <xs:attribute name='Context' type='xs:anyURI'/>
   </xs:complexType>
</xs:element>

<xs:element name='RequestSecurityTokenResponse'>
   <xs:complexType name='RequestSecurityTokenResponseType'>
      <xs:sequence>
         <xs:element ref='wst:TokenType'/>
         <xs:element ref='wst:RequestType'/>
         <xs:element ref='wst:BinaryExchange'/>
      </xs:sequence>
      <xs:attribute name='Context' type='xs:anyURI'/>
   </xs:complexType>
</xs:element>

RequestSecurityTokenResponse: This operation continues a security session negotiation. Furthermore, since the actual schema for this message is not unambiguously defined by the specifications, this is the actual schema used:

<xs:element name='RequestSecurityTokenResponse'>
   <xs:complexType name='RequestSecurityTokenResponseType'>
      <xs:sequence>
         <xs:element ref='wst:TokenType'/>
         <xs:element ref='wst:RequestType'/>
         <xs:element ref='wst:BinaryExchange'/>
      </xs:sequence>
      <xs:attribute name='Context' type='xs:anyURI'/>
   </xs:complexType>
</xs:element>
 
<xs:element name='RequestSecurityTokenResponse'>
   <xs:complexType name='RequestSecurityTokenResponseType'>
      <xs:sequence>
         <xs:element ref='wst:TokenType'/>
         <xs:element ref='wst:RequestType'/>
         <xs:element ref='wst:BinaryExchange'
                     minOccurs="0"/>
         <xs:element ref='wsc:SecurityContextToken'/>
      </xs:sequence>
      <xs:attribute name='Context' type='xs:anyURI'/>
   </xs:complexType>
</xs:element>

In the above the second RequestSecurityTokenResponse element refers to the final message in the exchange.

2.1.3. Resource properties

This service has no associated resource properties

2.1.4. Faults

Both RequestSecurityToken and RequestSecurityTokenResponse throw the following faults:

ValueTypeNotSupportedFault: This fault indicates that the value type attribute on the binary exchange token element is not supported by the service.
EncodingTypeNotSupportedFault: This fault indicates that the encoding type attribute on the binary exchange token element is not supported by the service.
RequestTypeNotSupportedFault: This fault indicates that the request type specified in the request type element is not supported by the service
TokenTypeNotSupportedFault: This fault indicates that the token type specified in the token type element is not supported by the service.
MalformedMessageFault: This fault indicates that the message content received by the service does not conform to the expected content. This is necessary since the schema does not give a well defined content model.
BinaryExchangeFault: This fault indicates that a failure occurred during the in the underlying security constant responsible for the session negotiation.
InvalidContextIdFault: This fault indicates that the context id passed in the message is not valid within the context of this service or negotiation.

2.1.5. WSDL and Schema Definitions

WS-Trust WSDL
WS-Trust XSD
WS-SecureConversation XSD
Secure Conversation WSDL [link]

3. Semantics and syntax of non-WSDL protocols

3.1. WS-Security

The framework implements the Web Services Security: SOAP Message Security, Web Services Security: Username Token Profile and Web Services Security: X.509 Token Profile specifications.

3.2. Transport (HTTPS) Security

The transport security solution used by the framework consists of HTTP over SSL/TLS (HTTPS) using X.509 certificates. The path validation step has been augmented to support the Proxy Certificate Profile (RFC3820).

4. Framework-level Protocols

4.1. WS-Security

The framework implements the Web Services Security: SOAP Message Security, Web Services Security: Username Token Profile and Web Services Security: X.509 Token Profile specifications.

4.2. Transport (HTTPS) Security

5. Command-line tools

This component has no command line tools.

6. Overview of Graphical User Interfaces

This component has no associated GUIs.

7. Semantics and syntax of domain-specific interface

7.1. Interface introduction

Client side security is set up by either setting individual properties on the javax.xml.rpc.Stub object used for the web service method invocation or by setting properties on a client side security descriptor object, which in turn is propagated to client side security handlers by making it available as a stub object property. Here are examples for the two approaches:

Setting property on the stub:

// Create endpoint reference
EndpointReferenceType endpoint = new EndpointReferenceType();
// Set address of service
String counterAddr = 
   "http://localhost:8080/wsrf/services/CounterService";
// Get handle to port 
CounterPortType port = 
   locator.getCounterPortTypePort(endpoint);
// set client authorization to self 
  ((Stub)port)._setProperty(Constants.AUTHORIZATION, 
               SelfAuthorization.getInstance());

Setting properties using a client descriptor:

// Client security descriptor file 
String CLIENT_DESC = 
   "org/globus/wsrf/samples/counter/client/client-security-config.xml"; 
// Create endpoint reference
EndpointReferenceType endpoint = new EndpointReferenceType();
// Set address of service
String counterAddr = 
   "http://localhost:8080/wsrf/services/CounterService";
// Get handle to port 
CounterPortType port = 
   locator.getCounterPortTypePort(endpoint);
//Set descriptor on Stub 
((Stub)port)._setProperty(Constants.CLIENT_DESCRIPTOR_FILE, CLIENT_DESC);

The descriptor file is described in detail in Section 1, “Security Descriptors Introduction”.

	Note
If the client needs to use transport security, the following API must be used to register the Axis transport handler for "https": import org.globus.axis.util.Util; static { Util.registerTransport(); }

Note

If the client needs to use transport security, the following API must be used to register the Axis transport handler for "https":

import org.globus.axis.util.Util;
static {
        Util.registerTransport();
    }

7.2. Syntax of the interface

Table 1. Client side security properties

Number	Task	Stub Configuration	Descriptor Configuration
1.	Allows for configuration of credentials for authentication.	Property: org.globus.axis.gsi.GSIConstants.GSI_CREDENTIALS Value equals the Instance of `org.ietf.jgss.GSSCredential`.	Section 4.1.2.1, “Configuring credentials ”
2.	Allows for configuring client side authorization.	Property: org.globus.wsrf.security.Constants.AUTHORIZATION Value equals the Instance of `org.globus.wsrf.security.authorization.Authorization` If GSI Secure Transport or GSI Secure Conversation is used the value should be an instance of `org.globus.gsi.gssapi.auth.Authorization`. But this translation is done automatically by the toolkit.	Refer to Section 4.1.2.2, “Configuring authorization mechanism ”
3.	Enable GSI Secure Conversation with specified message protection level.	Property: org.globus.wsrf.security.Constants.GSI_SEC_CONV Values equal one of the following: Constants.ENCRYPTION Constants.SIGNATURE Furthermore, you can set the SOAP Actor of the GSI signed/encrypted SOAP message by using the `gssActor` property. We recommend that you not do this unless you really know what you are doing.	Refer Section 4.1.2.3, “Configuring GSI Secure Conversation ”.
4.	Sets the GSI delegation mode. Used for GSI Secure Conversation only. If limited or full delegation is chosen, then some form of client side authorization needs to be done (i.e client side authorization cannot be set to none).	Property: org.globus.axis.gsi.GSIConstants.GSI_MODE Value equals one of following: `GSIConstants.GSI_MODE_NO_DELEG`: No delegation is performed. `GSIConstants.GSI_MODE_LIMITED_DELEG`: Limited delegation is performed `GSIConstants.GSI_MODE_FULL_DELEG`: Full delegation is performed.	Refer Section 4.1.2.3, “Configuring GSI Secure Conversation ”
5.	Enables GSI Secure Transport with some protection level.	Property: org.globus.gsi.GSIConstants.GSI_TRANSPORT Values equal one of the following: `Constants.ENCRYPTION` `Constants.SIGNATURE`	Refer Section 4.1.2.5, “Configuring GSI Secure Transport ”
6.	Enables anonymous authentication. This option only applies to GSI Secure Conversation and GSI Transport.	Property: org.globus.wsrf.security.Constants.GSI_ANONYMOUS Value equals one of following: Boolean.FALSE: Anonymous authentication is disabled. Boolean.TRUE: Anonymous authentication is enabled.	Refer Section 4.1.2.3, “Configuring GSI Secure Conversation ” abd Section 4.1.2.5, “Configuring GSI Secure Transport ”
7.	Enable GSI Secure Message with specified message protection level.	Property: org.globus.wsrf.security.Constants.GSI_SEC_MSG Values equal one of the following: `Constants.ENCRYPTION` `Constants.SIGNATURE` You can set the SOAP Actor of the signed message using the `x509Actor` property, but we do not recommend this unless you know what you are doing.	Refer Section 4.1.2.4, “Configuring GSI Secure Message ”.
8.	Enable WS-Security username/password authentication	Properties: org.globus.wsrf.security.Constants.USERNAME Value equals the username. org.globus.wsrf.security.Constants.PASSWORD Value equals the password.	Refer Section 4.1.2.6, “Configuring Username/Password ”
9.	Sets the credential that is used to encrypt the message (typically, the recipient's public key). Used for GSI Secure Message only.	Property: org.globus.wsrf.impl.security.authentication .Constants.PEER_SUBJECT Value equals the instance of `javax.security.auth.Subject`. The credential object needs to be wrapped in `org.globus.wsrf.impl.security.authentication.encryption` and added to the set of public credentials of the `Subject` object. For example, if `publicKeyFilename` was the file that had the recipient's public key: Subject subject = new Subject(); X509Certificate serverCert = CertUtil.loadCertificate(publicKeyFilename); EncryptionCredentials encryptionCreds = new EncryptionCredentials( new X509Certificate[] { serverCert }); subject.getPublicCredentials().add(encryptionCreds); stub._setProperty(Constants.PEER_SUBJECT, subject);	Refer Section 4.1.2.4, “Configuring GSI Secure Message ”
10.	Sets the trusted certificates location.	Property: org.globus.wsrf.security.TRUSTED_CERTIFICATES Value should be a comma separated list of directories and file neams	Refer Section 4.1.2.7, “Configuring trusted credentials ”
11.	Sets the SAML Authorization Assertion to embed in SOAP Headee.	Property: org.globus.wsrf.impl.security.authentication.Constants.SAML_AUTHZ_ASSERTION Value should be an instance of org.opensaml.SAMLAssertion;	Cannot be configured using descriptors.

8. Configuration interface

8.1. Configuration overview

Configuration of service-side security settings can be achieved in two ways. The preferred way is to provide these settings in a security descriptor, although it is also possible to manipulate security settings via CoG properties.

8.2. Syntax of the interface

Information on the syntax of security descriptors can be found in Java WS Security Descriptor Framework .

Information on available CoG security properties can be found Section 3.1, “Trusted Certificates Location”

9. Environment variable interface

Refer to Section 3, “Configuring” for environment variables.Note that the above environment variable does not supersede any settings provided in security descriptors.

Prev	Up	Next
GT4 Message & Transport Level Security Developer's Guide	Home	GT4 Message & Level Security Quality Profile