|
|
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
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.
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
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
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
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.
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
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
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.
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
system_password
user_data
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.
Return Values
The following table describes the valid return values.
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
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
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:
Listing 17-1 ActiveX Client Application That Uses Tuxedo-Style Authentication
Set objSecurityCurrent = objBootstrap.CreateObject("Tobj.SecurityCurrent")
Set objPrincipalAuthenticator = objSecurityCurrent.principal_authenticator
AuthorityType = objPrincipalAuthenticator.get_auth_type
If AuthorityType = TOBJ_APPAUTH Then logonStatus =
oPrincipalAuthenticator.Logon(
UserName,_
ClientName,_
SystemPassword,_
UserPassword
User Data)
End If
objPrincipalAuthenticator.logoff()
|
Copyright © 2001 BEA Systems, Inc. All rights reserved.
|