loginRequest

Is used to authenticate to a POA. It can also be used to log in as a user, a proxy user, or as a trusted application user. Keep in mind that login credentials are sent over the wire as plain text. We recommend using SSL to encrypt the data over the wire.

Request

<loginRequest>
   <auth type="types:Authentication"/>
   <language type="language"/>
   <version type="decimal"/>
   <application type="string"/>
   <userid type="xs:boolean"/>
   <system type="boolean"/>
</loginRequest>

Response

<loginResponse>
   <session type="string"/>
   <userinfo type="types:UserInfo"/>
   <entry" type="types:AccessRightEntry"/>
   <gwVersion" type="string"/>
   <build" type="string"/>
   <redirectToHost" type="types:Host"/>
   <serverUTCTime" type="dateTime"/>
   <status" type="types:Status"/>
</loginResponse>

Elements

auth

Specifies the type of authentication: PlainText, Proxy or TrustedApplication.

Plain Text

User authentication.

Proxy

Proxy authentication.

TrustedApplication

Trusted application authentication.

language

Used to return the language specific folder names on system folders. Also error descriptions will be based on the language entered.

version

Used to control which version of the schema to honor. The current values are:

  • “1.02” - 8.0.0

  • “1.03” - 8.0.1

  • “1.04” - 8.0.2

  • “1.05” - 2012

application

Specifies a string that describes the application. Administrators can use an HTTP monitor on a POA to view the application that is connected to the POA.

userid

Specifies the userid, postOffice, and domain information. To retrieve this information, specify TRUE.

session

Specifies and links the user with the login instance on the POA. The session string is required in all subsequent SOAP methods.

userinfo

Specifies information about the logged-in user. The userinfo element is returned when PlainText (user) authentication is used.

entry

Specifies information about the logged-in user. The userinfo element is returned when PlainText (user) or TrustedApplication authentication is used.

gwVersion

Specifies the version of the POA. For example, 8.0.1 is GroupWise 8.0 SP 1.

build

Specifies the build number of the POA.

redirectToHost

Specifies a user's POA IP address and port. This element is returned when the specified user is not on the POA. The application should try to log in to the IP address and port contained in the redirectToHost element.

serverUTCTime

Specifies the date and time of the POA in UTC time.

code

Returns the error number related to the event. 0 indicates that the request was successful.

status

Returns the success or failure of the method.

system

Specifies whether to return the GroupWise system name in the loginResponse.

Remarks

Before sending any credentials over the wire, verify that your application is talking to a valid GroupWise POA by using the following steps:

  • Examine the server certificate and make sure it is valid.

  • Ensure that the server’s certificate was issued by a trusted certificate authority or that it is listed in the trusted certificates for the client.

  • Check the certificate start and expiration dates.

After a successful login, a session string is returned from GroupWise. All subsequent calls to GroupWise Web Services need to include the session string.

Proxy login is a two-step process. First, the main user logs into hir or her account (login). Second, the main user proxies into the proxy account (proxy login).

Proxy rights are determined when the proxy login occurs. If the proxy rights are changed after a proxy login, the new proxy rights are not reflected until a logout and another login. For example, user1 proxies into user2's account. User1 has read and write rights to user2's account. While user1 is proxied into user2's account, user2 changes the rights of user1 to read-only. User1 does not see the modified rights until he or she logs out and proxies back into user2's account.

Applications cannot log in to GroupWise resources. To access resources data, log in as the owner of the resource and then proxy into the resource.

Example

The following sections contain several examples of loginRequest.

LoginRequest

<loginRequest> 
   <types:auth type="types:PlainText"> 
      <types:username>u1</types:username> 
      <types:password>u1</types:password> 
   </types:auth> 
   <application>BEEPClient</application> 
</loginRequest>

<loginResponse> 
   <session>5cCSFUxJ75UpLxFR</session> 
   <userinfo> 
      <name>u1</name> 
      <email>u1@phantom.com</email> 
      <uuid>1DEB6970-175B-0000-890F-6E00D5004E00</uuid> 
   </userinfo> 
   <gwVersion>7.0.1</gwVersion> 
   <build>341</build> 
   <serverUTCTime>2012-09-14T18:30:47Z</serverUTCTime> 
   <status> 
      <code>0</code> 
   </status> 
</loginResponse>

Proxy Login Request

<loginRequest> 
<types:auth type="types:Proxy"> 
<types:username>u1</types:username> 
<types:password>u1</types:password> 
<types:proxy>u2.po1.domain1</types:proxy> 
</types:auth> 
<application>BEEPClient</application> 
</loginRequest>
<loginResponse> 
<session>Tic8EqjFARMR2APt</session> 
<entry> 
<displayName>u2</displayName> 
<email>u2@phantom.com</email> 
<uuid>42F9A600-175B-0000-890F-6E00D5004E00</uuid> 
<appointment> 
<read>1</read> 
</appointment> 
<mail> 
<read>1</read> 
<write>1</write> 
</mail> 
<note> 
<read>1</read> 
</note> 
<task> 
<read>1</read> 
</task> 
</entry> 
<gwVersion>7.0.1</gwVersion> 
<build>341</build> 
<serverUTCTime>2012-09-14T18:33:51Z</serverUTCTime> 
<status> 
<code>0</code> 
</status> 
</loginResponse>

TrustedApplication LoginRequest

<loginRequest> 
<types:auth type="types:TrustedApplication"> 
<types:username>u1</types:username> 
<types:name>GWWS</types:name> 
<types:key>C0C0A3D206A90000875068005A00E700C0C0A3D306A90000875068005A00E700</types:key> 
</types:auth> 
<application>BEEPClient</application> 
</loginRequest>
<loginResponse> 
<session>ENT_TpWqn8byRcl2</session> 
<userinfo> 
<name>u1</name> 
<email>u1@phantom.com</email> 
<uuid>1DEB6970-175B-0000-890F-6E00D5004E00</uuid> 
</userinfo> 
<gwVersion>7.0.1</gwVersion> 
<build>341</build> 
<serverUTCTime>2012-09-14T18:36:34Z</serverUTCTime> 
<status> 
<code>0</code> 
</status> 
</loginResponse>