Both service classes (SOAP and REST) provide a built-in mechanism for authentication. SOAP applications that wish to implement single-point of login coordinated with the security system built-into the gateway can use either the Authenticate or Login service to verify login credentials. Login returns a security token that provides access to a session with duration of 20 minutes. This session can be extended by using the ExtendSessionToken service, or will be automatically extended by SOAP services called within the 20 minute window using this token. Authenticate does not create a session, merely verifies the credentials, so it is appropriate for applications which will not be able to asynchronously maintain the session token.
The web services use the additive, role-based authentication model used in the Global Gateway web site. Some web services are only available to logins that have the correct role. The required role or roles are listed with each service article.
All of the web services except for those that are part of the Authenticate entity require that the user have the Gateway.WebService role, in addition to whatever role is required for the service itself.
All SOAP services include authentication information. This allows client programs to run independently of any concept of a session. REST methods are different, and will be discussed in the next section. The authentication parameters are the username and password. Because all communication to the gateway is via https, there is no security risk here – the XML SOAP packets are encrypted in transit. Further, because usernames and passwords are fairly short, it may require less traffic to send the individual components than to send a session key. This also means that every web service can return an error code indicating that the authentication failed. This too is advantageous, as it allows finer control over authentication, allowing the system administrators to rapidly cut off access to the system in the event of security breaches.
SOAP applications which do not wish to keep login information for their duration can use the Login, ExtendSessionToken, and Logout services to maintain a session concept. Those applications should pass an empty password and include the session token in the username field. Using this approach, any SOAP calls made with the token in the username field will extend the life of that token, just as if the ExtendSessionToken service had been called. Applications using this approach need to be able to guarantee that they will either extend the session within the 20 minute window or respond appropriately to the possible expiration of their session token (possibly by requesting that the user login again, or by operating at a lower level of service, or by cleanly exiting).
The REST service layer supports Basic HTTP authentication to control access to the services. Thus, any time a REST service is called, if there is not an Authorization header, the service will return a 401 status code. The ACHeck21 gateway uses basic authentication as all communication is via https and therefore secure.
Because the REST services use this approach, there is no concept of a session (in fact, a session token will never be created for a REST client).
The Code and Message informational fields normally supplied in a SOAP response will only be available from within the HTTP header itself in order to maintain REST simplicity. All server based response codes should be ignored if the Code and Message fields have values within as these header fields will contain much more detailed responses as to why the error occurred.