The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Siebel-SOAP-Auth-0.004
River stage zero No dependents
++
/ Siebel::SOAP::Auth

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 provides authentication for Oracle's Siebel inbound web services by implementing Session Management.

Implementation uses 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 Moo based 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.

The method also will invoke check_fault automatically to validate the answer.

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.

DEBUGGING

You can enable debug messages for your code in the same way it is possible for XML::Compile::WSDL11: by using Log::Report. For example, the line:

    use Log::Report mode => 'DEBUG';

Added to your code will print trace messages of Siebel::SOAP::Auth object.

To disable just change the line to:

    use Log::Report mode => 'NORMAL';

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/>.