Authentication

Authentication

If SICS API Server is started in secure mode, all normal Web Services calls must include an authentication token. The caller must obtain this token by sending an initial “login” message to SICS API Server.

The Login service #

Sample SOAP Request and Response #

The SOAP request (input message) for the login service must follow one of these formats (see discussion on OS AUTHENTICATION and <sicsUserId> further down):

<SOAP-ENV:Envelope ...>
  <SOAP-ENV:Body>
    <ep:login xmlns:ep="urn:SicsWsAdministrationEntryPoint">
      <loginRequest>
        <userid>JSMITH</userid>
        <password>myDBpasSw0rD</password>
      </loginRequest>
    </ep:login>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

or

<SOAP-ENV:Envelope ...>
  <SOAP-ENV:Body>
    <ep:login xmlns:ep="urn:SicsWsAdministrationEntryPoint">
      <loginRequest>
        <sicsUserId>JSMITH</sicsUserId>
        <userid>AUTH_USER</userid>
        <password>auTHpasSw0rD</password>
      </loginRequest>
    </ep:login>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

The SOAP response (output message) will follow this format:

<SOAP-ENV:Envelope ...>
  <SOAP-ENV:Body>
    <swaep:loginOut xmlns:swaep="urn:SicsWsAdministrationEntryPoint">
      <authenticationToken>
        <userid>JSMITH</userid>
        <expiration>2004-12-31T14:35:48</expiration>
        <signature>B3AD016431264D4D8153B1453C3E1876F9FF8745</signature>
       </authenticationToken> 
    </swaep:loginOut>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Providing a User ID for authentication purposes #

Authentication is done by means of checking that the caller can provide a valid database User ID and a corresponding password. Upon successful processing of a call to the login service, an ‘authentication token’ will be returned (see sample SOAP response above).

When “OS AUTHENTICATION” is NOT used #

In the login service call a valid SICS userId (in clear text) and a password (in clear text or encrypted) must be provided (mandatory data). The SICS userId must be provided in the xml field <userId>.
The password must be provided in the xml field <password>.
The optional field <sicsUserId> is not to be used.
Please refer to the file SicsAdministration.xsd in the \sicsxml folder.

The password may be encrypted. In the SICS installation folder, there is a file named encrypt.bat. This bat file takes a plain-text string (the password) as input, calls a SICS utility program and outputs an encrypted version of the string. This encrypted value will always be prefixed with % so as to later recognize it as an encrypted value. Such an encrypted password can be provided in the <password> field of the login service. Remember to include the % prefix.

By “valid SICS userId and password” we mean a userId and password that is defined in the database management system (RDBMS) and the userId must be defined as a SICS user in the security facility of SICS (i.e. in the CNU_USER table).

The userId must be set in the database management system with normal password, not with “OS authentication”.

The purpose of the userId is to provide a means to authenticate the “sender” of the service, and also to determine the authorization / access rights. When processing the login service request message, the system will:

  • Check the credentials of <userId> by performing a temporary login to the database, using the password provided in <password>.
  • Check that a user with id <userId> exists in the SICS security system (the CNU_USER table).
  • Generate a token based on <userId>.

The authentication token generated by the login service call will contain the userId (in clear text), the expiration timestamp (in clear text) and a digital signature. This token must be provided in all subsequent calls.

When “OS AUTHENTICATION” is used #

The login service cannot authenticate a SICS userId if it is defined in the database management system with “OS authentication” instead of a normal password. In such a case, the following setup is proposed:

  • Define a new user (let us assume it is named AUTH_USER) in the database management system.
  • Make sure to define this user with normal password, not with OS authentication.

The sole purpose of AUTH_USER is to provide a means to authenticate the “sender” of the service.
The caller of the login service must provide AUTH_USER in the xml field <userId> and the password for AUTH_USER (in clear text, or encrypted as discussed above) in the xml field <password>.
The actual SICS userId must be provided in the xml field <sicsUserId>.

When the login service request message provides a value for the <sicsUserId> (which is an optional field), the system will:

  • Check the credentials of <userId> (the AUTH_USER) by performing a temporary login to the database, using the password provided in <password>.
  • Check that a user with id <sicsUserId> (instead of <userId>) exists in the SICS security system (the CNU_USER table).
  • Generate an authentication token based on <sicsUserId> instead of <userId>.

It is the <sicsUserId> value used in the login service which must be provided in the authenticationToken as <userId> value in all subsequent calls.

Relevant XML files #

  • SicsSystemTypes.xsd
  • SicsWsAdministrationEntryPoint.wsdl
  • SicsWsAdministrationEntryPoint-interface.wsdl
Functional group Service name Input parameter Output parameter
SicsWsAdministrationEntryPoint Login loginRequest authenticationToken

Verifying the Token #

The token obtained by running the login service must be sent in all subsequent calls. The SICS API Server verifies the following:

  • That an authentication token is present in the input message.
  • That the token is valid (digital signature derived from the TokenKeyFile.ini file parameter is verified).
  • That the token has not expired (expiration timestamp derived from the AuthenticationTokenValidity parameter is verified).
  • That the userIdForLogging xml element - if present - matches the token’s userId.

Sample SOAP request for the createBusiness service:

<SOAP-ENV:Envelope ...>
  <SOAP-ENV:Body>
    <swbep:createBusiness xmlns:swbep="urn:SicsWsBusinessEntryPoint">
       <genericInput>
         <authenticationToken>
           <userid>JSMITH</userid>
           <expiration>2011-01-31T14:35:48</expiration>
           <signature>B3AD04D4D8153B1453C3E1876F9FF8745</signature>
         </authenticationToken>
       </genericInput>
       <createBusiness>
         ...
       </createBusiness>
    </swbep:createBusiness>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>