• Home
  • Support
  • OnTime for IBM
  • FAQ
  • Development
  • OnBehalfOf - How does it work? Do you have an example?

OnBehalfOf - How does it work? Do you have an example?

Developers new to using the OnBehalfOf functionality of the OnTime Group Calendar API (hereafter “API”) sometimes finds it awkward to understand when first introduced to it. This post aims to solve that by explaining exactly how it works.

All requests made to the API needs to run in the context of a user in OnTime Group Calendar as it needs to figure out the access to calendar data. This is why only users in OnTime Group Calendar can make requests against the API. By default when a request is made to the API the request run as the owner of the OnTime Group Calendar access token if using HTTP or the signer of the request if using NRPC. This is what you want when you write a client application where requests should be done as the logged in user. When for some reason you want to perform API operations using the access context of someone else than the OnTime Group Calendar access token (if using HTTP) or the signer of the request (if using NRPC) you use OnBehalfOf.

Examples could be a Domino agent running as under a server identity, applications on a Java Enterprise Edition server such as WebSphere Application Server or simply if a user needs to make requests for other users.

Example

Below is an example of using the OnBehalfOf functionality over HTTP where the Chris Holmes (Chris Holmes/OnTime, chris.holmes[at]ontimesuite.com) user makes requests for Linda Rohdes (linda.rohdes[at]ontimesuite.com) and Jane Fonda (Jane Fonda/OnTime).

Start by registering the caller identity (e.g. “Chris Holmes/OnTime”) in the “Users allowed to run OnBehalfOf” field on Server Settings in the OnTime Group Calendar Configuration database.

With Chris Holmes logged into IBM Domino a request to the apihttptoken endpoint is performed to obtain a HTTP access token.

Request

POST /ontime/ontimegcweb.nsf/apihttptoken HTTP/1.0
Host: ontime.example.com
Cookie: LtpaToken2=abc123
Content-Length: xyz
Connection: Close

{"Main": {"APIVer": 5, "ApplVer": 1, "ApplID": "MyCustomApp"}}

Response

{APIVersion: "3.10.0",
APIBuild: 567,
Status: "OK",
Token: "chris.holmes.token123"
}

Now using the access token (for Chris Holmes) I can perform a Login call as though I’m either Linda Rohdes.

Request

POST /ontime/ontimegcweb.nsf/apihttp HTTP/1.0
Host: ontime.example.com
Content-Length: xyz
Connection: Close

{"Main": {"APIVer": 5, "ApplVer": 1, "ApplID": "MyCustomApp", "Token": "chris.holmes.token123", "OnBehalfOf": "linda.rohdes[at]ontimesuite.com"}, "Login": {}}

Response

{APIVersion: "3.10.0",
APIBuild: 567,
Login: {
Global: {...},
User: {
ID: "5",
Name: "Linda Rohdes/OnTime",
Email: "linda.rohdes[at]ontimesuite.com",
MailSource: "Domino"
}},
Token: "chris.holmes.token234",
Status: "OK"
}

...or Jane Fonda (here using her DN).

Request

POST /ontime/ontimegcweb.nsf/apihttp HTTP/1.0
Host: ontime.example.com
Content-Length: xyz
Connection: Close

{"Main": {"APIVer": 5, "ApplVer": 1, "ApplID": "MyCustomApp", "Token": "chris.holmes.token234", "OnBehalfOf": "Jane Fonda/OnTime"}, "Login": {}}

Response

{APIVersion: "3.10.0",
APIBuild: 567,
Login: {
Global: {...},
User: {
ID: "23",
Name: "Jane Fonda/OnTime ",
Email: "jane.fonda[at]ontimesuite.com",
MailSource: "Domino"
}},
Token: "chris.holmes.token345",
Status: "OK"
}

If I do not add the OnBehalfOf information the request will be processed for Chris Holmes himself as show below:

Request

POST /ontime/ontimegcweb.nsf/apihttp HTTP/1.0
Host: ontime.example.com
Content-Length: xyz
Connection: Close

{"Main": {"APIVer": 5, "ApplVer": 1, "ApplID": "MyCustomApp", "Token": "chris.holmes.token345"}, "Login": {}}

Response

{APIVersion: "3.10.0",
APIBuild: 567,
Login: {
Global: {...},
User: {
ID: "1",
Name: "Chris Holmes/OnTime ",
Email: "chris.holmes[at]ontimesuite.com",
MailSource: "Domino"
}},
Token: "chris.holmes.token456",
Status: "OK"
}

 

Tuesday, 28 October 2014 Posted in Development