Ticket Authentication Follow

Ticket Authentication is one of the Authentication methods for a web service.
It protects a service by requesting the caller to provide a valid ticket, before allowing execution of the service.
The ticket serves as one-time password, and it may store some additional information such as user ID.
Another service allocates tickets - each ticket is valid up to a certain timeout.

Typical Usage

A system having a login service, and other functional services.
Motivation: reduce the risk of user credentials being exposed in application side or in transmission.

• The login service validates the legitimacy of the user by verifying his username & password via a back-end system (such as EBS/Forms).
• The functional services require identification of the user (and maybe do not provide user authentication by themselves).
• The caller of the webservices does not want to store and pass the user's original credentials on each functional call. 

The solution will be use of temporary token ('Ticket') that identifies a specific user, and expires after a certain time.

1. A login services validates the user's username & password, returning ticket in case of success.
2. Application (caller) stores the ticket for the current session.
3. Application passes the ticket with each subsequent functional service call.
4. Service verifies the ticket validity, and executes only if ticket is valid and not expired.
   Optionally, the ticket may store encrypted data such as username, and pass it to one of the input parameter of the webservice before executing it.
5. Service returns data to application.

Ticket Allocation

Ticket allocation is done by a web service that encloses a call to other service ("login service"), whose successful execution is prerequisite for allocating a ticket. If necessary, custom logic may be implemented according to the 'More technical information for Advanced Users' section bellow.

In your ServiceManager, open the 'Services' tab, and add a new 'Ticket Service':

A popup will open, in which you select your login service from a list of all existing services:

Once you confirm, it will navigate you to the ServiceEditor, displaying a coresponding JavaScript template.
Type a name for your service, and save it by clicking on the 'Create Service' button.

Run the service to test it.
By default, the ticket is returned as the value of AP_TICKET output parameter.

(This example assumes existance of such y_Login service, having input parameter named MAIN_USERNAME_0)

Authenticating via Ticket

Other web services may be protected by the generated ticket.
When executed, they will require the caller to pass a valid ticket via Basic Authentication:

• Basic authentication definition for Ticket Authentication: user='ticket', password=<VALID_TICKET>. 
• Reminder: valid ticket means a ticket that could be successfully decrypted, and has not expired yet.
• Note that Basic Authentication is used only as a protocol - Ticket Authentication is as secure as the strength of the encrypted ticket (AES 128bit).

To protect a service via ticket, edit the service and select Authentication Type 'Ticket' under Advanced Details:

You may optionaly configure a copy transformation to extract value from the ticket and pass it to one of the input parameters of the web service.
To refer ticket parameter value in input parameter value, use ${ticket.<parameter-name>} tokens:

In this example, the value of 'MAIN_USERNAME_0' will be extracted from the ticket, and copied to input parameter PERSONAL_USER_0 before executing the service.
 

Security

The ticket is encrypted via AES 128bit symmetric-key encryption algorithm.
The input JSON object and expiration timestamp are encrypted as part of the generated ticket.
A ticket cannot be decrypted without knowledge of the symmetric Secret Key used for encryption, and vice verca - a valid ticket cannot be generated without knowledge of the secret key that will be used for decryption.
 

Secret Key

The key is stored in the configuration file (Admin > System Properties), in property TICKET_SECRET:

• Random secret key will be automatically generated at ServiceManager startup, in case you don't have such key set yet.
• Your secret key will be overridden if you restore a full backup of your system.

The secret key should be known only to the ServiceManager, as it is the only one that encrypts and decrypts tickets.
Note that if there is a Load Balancer in effect, the secret key should be the same among all ServiceManager instances.

Validating a Ticket

Assuming that you have a ticket on your client app, you may check via simple API call whether the ticket is still valid (i.e. not expired):

POST http://{host}:{port}/ServiceManager/Macro/isTicketValid

And provide the ticket in the request body:

{
 "ticket": "Z5JDlhuQk1SYY3if47By9A==..."
}

The server will return simple true/false response.

Renewing a Ticket

A ticket-protected service may be configured to automatically renew the ticket it received - so the service will return a new ticket valid for additional ticket_expiry_minutes. This way you may ensure that a client session is always kept alive for ticket_expiry_minutes from his last activity.

To activate, make sure that your service is set to Authentication Type = Ticket, and add manually add an AP_TICKET output parameter.

Upon service execution, your ServiceManager will detect this parameter, and assign a renewed ticket for it.

Working with Tickets in Visualizer Application

Any visualizer application automatically handles ServiceManager tickets. Once a service returns AP_TICKET it automatically set the "Authorization" header to be used by all the following services. No additional code needed.

In external applications that uses ServiceManager Tickets you would need to set the "Authorization" header manually as in the following pseudocode example.

ticket = <get AP_TICKET value from response>
set Header "Authorization" : "Basic " + btoa("ticket:" + ticket);

Extending Ticket Automatically

Ticket service expires in a specific time, that was determined at the time that the ticket was created.

If you want to extend the Ticket to the 'last used time" + expiration - it can be done automatically.

When the user calls any service that is using TICKET authentication, you should add output parameter: AP_TICKET.

So, whenever the service is being called with a specific ticket, it would return a new Ticket with EXTENDED time (the current time + expiration).

The new Ticket would include all the data that is in the original Ticket.