BEA Logo BEA WebLogic Enterprise Release 5.0

  Corporate Info  |  News  |  Solutions  |  Products  |  Partners  |  Services  |  Events  |  Download  |  How To Buy

   e-docs.beasys.com   |   Site Map   |   Search   |   PDF Files   |   Contact   |   Glossary

 

   WLE Doc Home   |   Security & Related Topics   |   Previous   |   Next   |   Contents   |   Index

Automation Security Reference

This topic contains the Automation method descriptions for the WLE Security service. In addition, the topic contains programming examples that illustrate using the Automation methods to implement security in an ActiveX client application.

Note: The Automation security methods do not support certificate-based authentication or the use of the SSL procotol.

Method Descriptions

This section describes the Automation Security Service methods.

DISecurityLevel2_Current

The DISecurityLevel2_Current object is a BEA implementation of the CORBA Security model. In this release of the WLE software, the get_attributes() , set_credentials() , get_credentials() , and Principal_Authenticator() methods are supported.

DISecurityLevel2_Current.get_attributes

Synopsis

Returns attributes for the Current interface.

MIDL Mapping

HRESULT get_attributes(
[in] VARIANT attributes,
[in,out,optional] VARIANT* exceptionInfo,
[out,retval] VARIANT* returnValue);

Automation Mapping

Function get_attributes(attributes, [exceptionInfo])

Parameters

attributes

The set of security attributes (privilege attribute types) whose values are desired. If this list is empty, all attributes are returned.

exceptioninfo

An optional input argument that allows the client application to get additional exception data if an error occurs. For the ActiveX client applications, all exception data is returned in the OLE Automation Error Object.

Description

This method gets privilege (and other) attributes from the credentials for the client application from the Current interface.

Return Values

A variant containing an array of DISecurity_SecAttribute objects. The following table describes the valid return values.

Return Value

Meaning

Security::Public

Empty (Public is returned when no authentication was performed.)

Security::AccessId

Null-terminated ASCII string containing the WLE user name

Security::PrimaryGroupId

Null-terminated ASCII string containing the WLE name of the client application

DISecurityLevel2_Current.set_credentials

Synopsis

Sets credentials type.

MIDL Mapping

HRESULT set_credentials(
[in] Security_CredentialType cred_type,
[in] DISecurityLevel2_Credentials* cred,
[in,out,optional] VARIANT* exceptionInfo);

Automation Mapping

Sub set_credentials(cred_type As Security_CredentialType,
cred As DISecurityLevel2_Credentials,
[exceptionInfo])

Description

This method can be used only to set SecInvocationCredentials ; otherwise, -set_credentials raises CORBA::BAD_PARAM . The credentials must have been obtained from a previous call to DISecurityLevel2_Current.get_credentials .

Arguments

cred_type

The type of credentials to be set; that is, invocation, own, or nonrepudiation.

cred

The object reference to the Credentials object, which is to become the default.

exceptioninfo

An optional input argument that allows the client application to get additional exception data if an error occurs. For the ActiveX client applications, all exception data is returned in the OLE Automation Error Object.

Return Values

None.

DISecurityLevel2_Current.get_credentials

Synopsis

Gets credentials type.

MIDL Mapping

HRESULT get_credentials(
[in] Security_CredentialType cred_type,
[in,out,optional] VARIANT* exceptionInfo,
[out,retval] DISecurityLevel2_Credentials** returnValue);

Automation Mapping

Function get_credentials(cred_type As Security_CredentialType,
[exceptionInfo]) As DISecurityLevel2_Credentials

Description

This call can be used only to get SecInvocationCredentials ; otherwise, get_credentials raises CORBA::BAD_PARAM . If no credentials are available, get_credentials raises CORBA::BAD_INV_ORDER .

Arguments

cred_type

The type of credentials to get.

exceptioninfo

An optional input argument that allows the client application to get additional exception data if an error occurs. For the ActiveX client application, all exception data is returned in the OLE Automation Error Object.

Return Values

A DISecurityLevel2_Credentials object for the active credentials in the client application only.

DISecurityLevel2_Current.principal_authenticator

Synopsis

Returns the PrincipalAuthenticator.

MIDL Mapping

HRESULT principal_authenticator([out, retval]
DITobj_PrincipalAuthenticator** returnValue);

Automation Mapping

Property principal_authenticator As DITobj_PrincipalAuthenticator

Description

The PrincipalAuthenticator returned by the principal_authenticator property is of actual type DITobj_PrincipalAuthenticator . Therefore, it can be used as a DISecurityLevel2_PrincipalAuthenticator .

Note: This method raises CORBA::BAD_INV_ORDER if it is called on an invalid SecurityCurrent object.

Return Values

A DITobj_PrincipalAuthenticator object.

DITobj_PrincipalAuthenticator

The DITobj_PrincipalAuthenticator object is used to log in to and log out of the WLE domain. In this release of the WLE software, the authenticate , build_auth_data() , continue_authentication(), get_auth_type() , logon(), and logoff() methods are implemented

DITobj_PrincipalAuthenticator.authenticate

Synopsis

Authenticates the client application.

MIDL Mapping

HRESULT authenticate(
     [in] long 						method,
     [in] BSTR 						security_name,
     [in] VARIANT 						auth_data,
     [in] VARIANT 						privileges,
     [out] DISecurityLevel2_Credentials** 	
						creds,
     [out] VARIANT* 						continuation_data,
     [out] VARIANT* 						auth_specific_data,
     [in,out,optional] VARIANT* 						exceptionInfo,
     [out,retval] Security_AuthenticationStatus* returnValue);

Automation Mapping

Function authenticate(method As Long, security_name As String,
auth_data, privileges, creds As DISecurityLevel2_Credentials,
continuation_data, auth_specific_data,
[exceptionInfo]) As Security_AuthenticationStatus

Arguments

method

Must be Tobj::TuxedoSecurity . If method is invalid, authenticate raises CORBA::BAD_PARAM .

security_name

The WLE user name.

auth_data

As returned by DITobj_PrincipalAuthenticator.build_auth_data . If auth_data is invalid, authenticate raises CORBA::BAD_PARAM .

privileges

As returned by DITobj_PrincipalAuthenticator.build_auth_data. If privileges is invalid, authenticate raises CORBA::BAD_PARAM .

creds

Placed into the SecurityCurrent object.

continuation_data

Always empty.

auth_specific_data

Always empty.

exceptioninfo

An optional input argument that allows the client application to get additional exception data if an error occurs. For the ActiveX client application, all exception data is returned in the OLE Automation Error Object.

Description

This method authenticates the client application via the IIOP Listener/Handler so that it can access a WLE domain.

Return Values

A Security_AuthenticationStatus Enum value. The following table describes the valid return values.

Return Value

Meaning

Security::AuthenticationStatus::
SecAuthSuccess

The authentication succeeded.

Security::AuthenticationStatus::
SecAuthFailure

The authentication failed, or the client application was already authenticated and did not invoke Tobj::PrincipalAuthenticator:logoff or Tobj_Bootstrap::destroy_current .

DITobj_PrincipalAuthenticator.build_auth_data

Synopsis

Creates authentication data and attributes for use by DITobj_PrincipalAuthenticator.authenticate .

MIDL Mapping

HRESULT build_auth_data(
  [in] BSTR 				user_name,
  [in] BSTR 				client_name,
  [in] BSTR 				system_password,
  [in] BSTR 				user_password,
  [in] VARIANT 				user_data,
  [out] VARIANT* 				auth_data,
  [out] VARIANT* 				privileges,
  [in,out,optional] VARIANT* exceptionInfo);

Automation Mapping

Sub build_auth_data(user_name As String, client_name As String,
system_password As String, user_password As String, user_data,
auth_data, privileges, [exceptionInfo])

Arguments

user_name

The WLE user name.

client_name

A name of the WLE client application.

system_password

The password for the WLE client application.

user_password

The user password (default WLE authentication service).

user_data

Client application-specific data (custom WLE authentication service).

auth_data

For use by authenticate .

privileges

For use by authenticate .

exceptioninfo

An optional input argument that allows the client application to get additional exception data if an error occurs. For the ActiveX client application, all exception data is returned in the OLE Automation Error Object.

Note: If user_name , client_name , or system_password is NULL or empty, or exceeds 30 characters, the subsequent authenticate method invocation raises the CORBA::BAD_PARAM exception.

Note: The user_password and user_data parameters are mutually exclusive, depending on the requirements of the authentication service used in the configuration of the WLE domain. The WLE default authentication service expects a user password. A customized authentication service may require user data. If both user_password and user_data are specified, the subsequent authentication call raises the CORBA::BAD_PARAM exception.

Description

This method is a helper function that creates authentication data and attributes to be used by DITobj_PrincipalAuthenticator.authenticate .

Note: This method raises CORBA::BAD_INV_ORDER if it is called with an invalid SecurityCurrent object.

Return Values

None.

DITobj_PrincipalAuthenticator.continue_authentication

Synopsis

Always returns Security::AuthenticationStatus::SecAuthFailure.

MIDL Mapping

HRESULT continue_authentication(
[in] VARIANT response_data,
[in,out] DISecurityLevel2_Credentials** creds,
[out] VARIANT* continuation_data,
[out] VARIANT* auth_specific_data,
[in,out,optional] VARIANT* exceptionInfo,
[out,retval] Security_AuthenticationStatus* returnValue);

Automation Mapping

Function continue_authentication(response_data,
creds As DISecurityLevel2_Credentials, continuation_data,
auth_specific_data, [exceptionInfo]) As
Security_AuthenticationStatus

Description

Because the WLE software does authentication in one step, this method always fails and returns Security::AuthenticationStatus::SecAuthFailure .

Return Values

Always returns SecAuthFailure .

DITobj_PrincipalAuthenticator.get_auth_type

Synopsis

Gets the type of authentication expected by the WLE domain.

MIDL Mapping

HRESULT get_auth_type(
        [in, out, optional] VARIANT* exceptionInfo, 
        [out, retval] Tobj_AuthType* returnValue);

Automation Mapping

Function get_auth_type([exceptionInfo]) As Tobj_AuthType

Argument

exceptioninfo

An optional input argument that allows the client application to get additional exception data if an error occurs. For the ActiveX client application, all exception data is returned in the OLE Automation Error Object.

Description

This method returns the type of authentication expected by the WLE domain.

Note: This method raises CORBA::BAD_INV_ORDER if it is called with an invalid SecurityCurrent object.

Returned Values

A reference to the Tobj_AuthType enumeration. The following table describes the valid return values.

Return Value

Meaning

TOBJ_NOAUTH

No authentication is needed; however, the client application can still authenticate itself by specifying a user name and a client application name. No password is required.

To specify this level of security, specify the NONE value for the SECURITY parameter in the RESOURCES section of the UBBCONFIG file.

TOBJ_SYSAUTH

The client application must authenticate itself to the WLE domain, and must specify a user name, a name, and a password for the client application.

To specify this level of security, specify the APP_PW value for the SECURITY parameter in the RESOURCES section of the UBBCONFIG file.

TOBJ_APPAUTH

The client application must provide proof material that authenticates the client application to the WLE domain.The proof material may be a password or a digital certificate.

To specify this level of security, specify the USER_AUTH value for the SECURITY parameter in the RESOURCES section of the UBBCONFIG file.

DITobj_PrincipalAuthenticator.logon

Synopsis

Logs in to the WLE domain. The correct input parameters depend on the authentication level.

MIDL Mapping

HRESULT logon(
  [in] BSTR 						user_name,
  [in] BSTR						client_name,
  [in] BSTR 						system_password,
  [in] BSTR 						user_password,
  [in] VARIANT 						user_data,
  [in,out,optional] VARIANT* 						exceptionInfo,
  [out,retval] Security_AuthenticationStatus*
 						returnValue);

Automation Mapping

Function logon(user_name As String, client_name As String,
system_password As String, user_password As String,
user_data, [exceptionInfo]) As Security_AuthenticationStatus

Description

For remote WLE client applications, this method authenticates the client application via the IIOP Listener/Handler so that the remote client application can access a WLE domain. This method is functionally equivalent to DITobj_PrincipalAuthenticator.authenticate , but the parameters are oriented to WLE security.

Arguments

user_name

The WLE user name. This parameter is required for TOBJ_NOAUTH , TOBJ_SYSAUTH , and TOBJ_APPAUTH authentication levels.

client_name

The name of the WLE client application. This parameter is required for TOBJ_NOAUTH , TOBJ_SYSAUTH , and TOBJ_APPAUTH authentication levels.

system_password

A password for the WLE client application. This parameter is required for TOBJ_SYSAUTH and TOBJ_APPAUTH authentication levels.

user_password

The user password (default WLE authentication service). This parameter is required for the TOBJ_APPAUTH authentication level.

user_data

Application-specific data (custom authentication service). This parameter is required for the TOBJ_APPAUTH authentication level.

Note: If user_name , client_name , or system_password is NULL or empty, or exceeds 30 characters, the subsequent authenticate method invocation raises the CORBA::BAD_PARAM exception.

Note: If the authorization level is TOBJ_APPAUTH , only one of user_password or user_data may be supplied.

exceptioninfo

An optional input argument that allows the client application to get additional exception data if an error occurs. For the ActiveX client application, all exception data is returned in the OLE Automation Error Object.

Return Values

The following table describes the valid return values.

Return Value

Meaning

Security::AuthenticationStatus::
SecAuthSuccess

The authentication succeeded.

Security::AuthenticationStatus::
SecAuthFailure

The authentication failed, or the client application was already authenticated and did not call one of the following methods:

Tobj::PrincipalAuthenticator:logoff

Tobj_Bootstrap::destroy_current

DITobj_PrincipalAuthenticator.logoff

Synopsis

Discards the current security context associated with the WLE client application.

MIDL Mapping

HRESULT logoff([in, out, optional] VARIANT* exceptionInfo);

Automation Mapping

Sub logoff([exceptionInfo])

Description

This call discards the context associated with the WLE client application, but does not close the network connections to the WLE domain. Logoff also invalidates the current credentials. After logging off, calls using existing object references fail if the authentication type is not TOBJ_NOAUTH .

If the client application is currently authenticated to a WLE domain, calling Tobj_Bootstrap.destroy_current() calls logoff implicitly.

Argument

exceptioninfo

An optional input argument that allows the client application to get additional exception data if an error occurs. For the ActiveX client applications, all exception data is returned in the OLE Automation Error Object.

Return Values

None.

DISecurityLevel2_Credentials

The DISecurityLevel2_Credentials object is a BEA implementation of the CORBA Security model. In this release of the WLE software, the get_attributes() and is_valid() methods are supported.

DISecurityLevel2_Credentials.get_attributes

Synopsis

Gets the attribute list attached to the credentials.

MIDL Mapping

HRESULT get_attributes(
[in] VARIANT attributes,
[in,out,optional] VARIANT* exceptionInfo,
[out,retval] VARIANT* returnValue);

Automation Mapping

Function get_attributes(attributes, [exceptionInfo])

Arguments

attributes

The set of security attributes (privilege attribute types) whose values are desired. If this list is empty, all attributes are returned.

exceptioninfo

An optional input argument that allows the client application to get additional exception data if an error occurs. For the ActiveX client application, all exception data is returned in the OLE Automation Error Object.

Description

This method returns the attribute list attached to the credentials of the client application. In the list of attribute types, you are required to include only the type value(s) for the attributes you want returned in the AttributeList . Attributes are not currently returned based on attribute family or identities. In most cases, this is the same result you would get if you called DISecurityLevel2.Current::get_attributes() , since there is only one valid set of credentials in the client application at any instance in time. The results could be different if the credentials are not currently in use.

Return Values

A variant containing an array of DISecurity_SecAttribute objects.

DISecurityLevel2_Credentials.is_valid

Synopsis

Checks the status of credentials.

MIDL Mapping

HRESULT is_valid(
[out] IDispatch** expiry_time,
[in,out,optional] VARIANT* exceptionInfo,
[out,retval] VARIANT_BOOL* returnValue

Automation Mapping

Function is_valid(expiry_time As Object,
[exceptionInfo]) As Boolean

Description

This method returns TRUE if the credentials used are active at the time; that is, you did not call DITobj_PrincipalAuthenticator.logoff or destroy_curren t. If this method is called after DITobj_PrincipalAuthenticator.logoff() , FALSE is returned. If this method is called after destroy_current() , the CORBA::BAD_INV_ORDER exception is raised.

Return Values

The output expiry_time as a DITimeBase_UtcT object set to max.

Programming Example

This section contains the portions of an ActiveX client application that implement the following:

 

 

Copyright © 1999 BEA Systems, Inc. All rights reserved.
Required browser: Netscape 4.0 or higher, or Microsoft Internet Explorer 4.0 or higher.