BEA Logo BEA BEA Tuxedo Release [Release Number]

  BEA Home  |  Events  |  Solutions  |  Partners  |  Products  |  Services  |  Download  |  Developer Center  |  WebSUPPORT

 

   BEA Tuxedo Doc Home   |   Using Security in CORBA Applications   |   Previous Topic   |   Next Topic   |   Contents   |   Index

Automation Security Reference

 

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

This topic includes the following sections:

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

 


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 BEA Tuxedo 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 BEA Tuxedo username.

Security::PrimaryGroupId

Null-terminated ASCII string containing the BEA Tuxedo 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 BEA Tuxedo domain. In this release of the BEA Tuxedo 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 BEA Tuxedo username.

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 BEA Tuxedo 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 BEA Tuxedo username.

client_name

A name of the CORBA client application.

system_password

The password for the CORBA client application.

user_password

The user password (for default authentication service).

user_data

Client application-specific data (custom 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 BEA Tuxedo domain. The 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 BEA Tuxedo 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 BEA Tuxedo 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 BEA Tuxedo 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 username 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 BEA Tuxedo domain, and must specify a username, 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 BEA Tuxedo 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 BEA Tuxedo 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 CORBA client applications, this method authenticates the client application via the IIOP Listener/Handler so that the remote client application can access a BEA Tuxedo domain. This method is functionally equivalent to DITobj_PrincipalAuthenticator.authenticate, but the parameters are oriented to security.

Arguments

user_name

The BEA Tuxedo username. This parameter is required for TOBJ_NOAUTH, TOBJ_SYSAUTH, and TOBJ_APPAUTH authentication levels.

client_name

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

system_password

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

user_password

The user password (default 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 CORBA 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 CORBA client application, but does not close the network connections to the BEA Tuxedo 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 BEA Tuxedo 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 BEA Tuxedo 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_current. 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:

 

back to top previous page