NAME
Siebel::SOAP::Auth - Moo based class to implement transparent Siebel Session Management for XML::Compile::WSDL11
SYNOPSIS
use XML::Compile::WSDL11;
use XML::Compile::SOAP11;
use XML::Compile::Transport::SOAPHTTP;
use Siebel::SOAP::Auth;
my $wsdlfile = File::Spec->catfile( 't', 'SWIContactServices.WSDL' );
my %request = (
ListOfSwicontactio => {
Contact =>
{ Id => '0-1', FirstName => 'Siebel', LastName => 'Administrator' }
}
);
my $wsdl = XML::Compile::WSDL11->new($wsdlfile);
my $auth = Siebel::SOAP::Auth->new(
{
user => 'sadmin',
password => 'XXXXXXX',
token_timeout => MAGIC_NUMBER,
remain_ttl => 0
}
);
my $call = $wsdl->compileClient(
operation => 'SWIContactServicesQueryByExample',
transport_hook => sub {
my ( $request, $trace, $transporter ) = @_;
# request was modified
my $new_request = $auth->add_auth_header($request);
return $trace->{user_agent}->request($new_request);
}
);
my ( $answer, $trace ) = $call->(%request);
if ( my $e = $@->wasFatal ) {
$e->throw;
} else {
# do something with the answer
}DESCRIPTION
Siebel::SOAP::Auth implements authentication for Oracle's Siebel inbound webservices by implementing Session Management.
Session Management is implemented by using a instance of Siebel::SOAP::Auth inside a transport_hook sub, passing to it the original request. The original request will be modified, adding necessary authentication data to the SOAP Header. The instance of Siebel::SOAP::Auth will also try to manage the session and token expiration times and request a new one before expiration, avoiding a new round-trip to the server for another successful request.
Session Management for calling Siebel web services great improves speed, since regular authentication takes a loot of additional steps. This class will implement the management of requesting tokens automatically (but some tuning with the parameters might be necessary).
This class is tight coupled to XML::Compile::WSDL11 interface. By using it, it is expected that you will use everything else from XML::Compile.
This class is a Moo class and it uses also Log::Report to provide debug information if required.
ATTRIBUTES
The following attributes are available:
token_key
A string of the respective key of the token value after response from the Siebel Server is converted to a hash by XML::Compile::WSDL11.
By default, it is defined as '{' . $self-get_header_ns() . '}SessionToken'>.
This is a lazy attribute, as defined by Moo.
header_ns
A string that represents the SOAP Header namespace.
By default it is http://siebel.com/webservices. You might want to change it depending on the WSDL (current this is not done automatically).
This is a read/write attribute.
user
A string representing the login to be used for web service authentication.
This is a required attribute during object creation.
password
A string representing the login password used for authentication.
This is a required attribute during object creation.
token
A string type attribute that holds the token.
All token details are handled internally.
lookup_ns
A string type attribute that holds the namespace that must be used to find the namespace prefix that should be used to declare the elements for authentication in the SOAP header.
By default is set to http://schemas.xmlsoap.org/soap/envelope/.
This is a read/write attribute.
remain_ttl
A integer that defines the minimum amount of remaining seconds the token should have before asking for a new one.
By default it is set to 10 seconds, but you might want to fine tune it depending on several factor, specially the average time the request to a web services takes to have an answer.
This is a read-only attribute, so you must set it's value during object creation.
session_type
A string type attribute that defines the session type to be used.
By default it is set to Stateless.
This is a read-only attribute, so you must set it's value during object creation.
last_fault
A string attribute type that holds the error message received from the Siebel Server.
This is a read-only attribute.
auth_fault
A compiled regular expression that is used to match specific SOAP faults returned by the Siebel Server that means "token expired".
It is set by default to /^Error\sCode:\s10944642/.
session_timeout
A integer type attribute that defines the Session Timeout to be considered, as defined on the Siebel Server.
By default is set to 900 seconds.
This is a read-only attribute.
token_timeout
A integer type attribute that defines the Token Timeout to be considered, as defined on the Siebel Server.
By default is set to 900 seconds.
This is a read-only attribute.
token_max_age
A integer type attribute that defines the Token Maximum Age to be considered, as defined on the Siebel Server.
By default is set to 172800 seconds.
This is a read-only attribute.
METHODS
All attributes have their respectiver getters and setters as defined in the Perl Best Practices book.
Of course, read-only attributes have only getters.
This is the list of those methods with a brief explanation:
get_token_key
Getter for the token_key attribute.
get_header_ns
Getter for the header_ns attribute.
set_header_ns
Setter for the header_ns attribute.
get_user
Getter for the user attribute.
set_user
Setter for the user attribute.
get_pass
Getter for the password attribute.
set_pass
Setter for the password attribute.
get_token
Getter for the token attribute.
get_lookup_ns
Getter for the lookup_ns attribute.
get_remain_ttl
Getter for the remain_ttl attribute.
get_session_type
Getter for the session_type attribute.
get_session_timeout
Getter for the session_timeout attribute.
get_token_timeout
Getter for the token_timeout attribute.
get_token_max_age
Getter for the token_max_age attribute.
get_auth_fault
Getter for the auth_fault attribute.
get_last_fault
Getter for the last_fault attribute.
add_auth_header
This method must be invoked inside the transport_hook parameter definition during the call to compileClient method of XML::Compile::WSDL11.
It expects as parameter the original HTTP::Request object, that will have its payload modified (SOAP Header).
It returns the HTTP::Request with its payload modified.
find_token
Finds and set the token returned by the Siebel Server in the response of a request.
It expects as parameter the hash reference returned by the execution of the code reference created by the compileClient method of XML::Compile::WSDL11. This hash reference must have a key as defined by the token_key attribute of a instance of Siebel::SOAP::Auth.
Once the token is found, the object updates itself internally. Otherwise an exception will be raised.
check_fault
Verifies if an answer from the Siebel Server is a failure of not.
Expects as parameter the answer.
If the fault returned by the server is related to a token expiration, a exception will be raised with the text "token expired".
That means you should check for this exception with the try function of Log::Report and provide a fallback routine (like resending your request). The instance of Siebel::SOAP::Auth will also resets the token status internally to allow reuse.
For other errors, an exception will be created with exactly the same message available in the fault element of the SOAP envelope. You should evaluate the error message and take appropriate measures.
SEE ALSO
AUTHOR
Alceu Rodrigues de Freitas Junior, <arfreitas@cpan.org>
COPYRIGHT AND LICENSE
This software is copyright (c) 2015 of Alceu Rodrigues de Freitas Junior, <arfreitas@cpan.org>
This file is part of Siebel-SOAP-Auth distribution.
Siebel-SOAP-Auth is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
Siebel-SOAP-Auth is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with Term-YAP. If not, see <http://www.gnu.org/licenses/>.