At some point you may need to revoke an OnTime Access Token ("token") if a mobile device has been stolen or you fear that a token which is still valid has been compromised. Revoking the token takes effect immediately and renders the token unusable. To obtain a new token the user will need to reauthenticate to OnTime Group Calendar.
To revoke a token follow the below steps:
- Open the OnTime Group Calendar Configuration database
- Open the Users view and locate the user for whom you need to revoke the token
- From the toolbar select "Selected/Force new Web Logon"
OnTime Access Tokens
Please note: The below information pertains to HTTP based access to the OnTime Group Calendar API that is for OnTime Group Calendar Web, Mobile and Social. It also pertains to Notes and Team-At-A-Glance if these are configured for HTTP access. If native IBM Notes API (NRPC) access is used for the latter two clients an OnTime Access Token is not used.
Users are solely authenticated to the OnTime Group Calendar API (the "service" that provides the data for the OnTime Group Calendar user interfaces such as Web, Mobile, Notes etc.) using an OnTime Access Token. An OnTime Access Token is an encrypted text token that identifies the user and has a point in time it expires encoded in it (among other things). In order to obtain an OnTime Access Token the user must be authenticated to IBM Domino in whatever way the organisation requires such as basic authentication, form based authentication (using LtpaToken), certificates based authentication etc. Once an OnTime Access Token has been obtained it is used on subsequent requests to the OnTime Group Calendar API and identifies the user to the OnTime Group Calendar API. Once an OnTime Access Token is issued it is valid until it expires. The expiration duration can be controlled in the OnTime Group Calendar server document(s) and may be set to a duration in hours. The OnTime Group Calendar API issues a new OnTime Access Token on each request so the expiration time set in the OnTime Group Calendar server document(s) should be considered an "Idle time between requests".
Please note: In the OnTime Group Calendar Configuration database the OnTime Access Token idle timeout is referred to as the "HTTP Token Timeout".
Once an OnTime Group Calendar client obtains an OnTime Access Token it is cached by the client (for Mobile and Web it is cached in a browser cookie) and attempted used on subsequent requests to the API. This means that a user may access OnTime Group Calendar Web or OnTime Group Calendar Mobile without reauthenticating to IBM Domino if a valid OnTime Access Token is available. It also means that a suitable idle time should be set that suits the organisations security policy. For example if permitted by the security policy an idle time of 24 hours allows a user to use OnTime Group Calendar Mobile or Web during the day and reopen the client next day without reauthentication to IBM Domino as the OnTime Access Token is still valid.
It follows from the above that all API requests following obtaining an OnTime Access Token may be unauthenticated ("anonymous") from an IBM Domino perspective. This is not a security hole but is simply because non-token requests are solely authenticated from the OnTime Access Token. It also means that the IBM Domino HTTP server must allow anonymous requests whether that be over HTTP or HTTPs.
Please note that an OnTime Access Token may be revoked from the OnTime Group Calendar Configuration database. This means that even though a user have obtained an OnTime Access Token valid a year into the future the administrator may revoke it requiring the user to reauthenticate to use OnTime Group Calendar. This is a security measure.
How login to OnTime Group Calendar Web works
Below we assume that your OnTime Group Calendar Client database (”Client database”) is called ”ontimegcclient.nsf” and is in the ”ontime” directory. To open OnTime Group Calendar Web you would redirect users to ”/ontime/ontimegcclient.nsf/web”.
The login process is as follows:
- User navigate to ”/ontime/ontimegcclient.nsf/web”.
- The code checks whether an OnTime Access Token is present as a browser cookie or in the URL if launched from the Notes workspace icon. If it is, access is attempted using it.
- If that OnTime Access Token doesn’t work (i.e. is expired) any browser cookie is cleared and the login process restarts.
- If no OnTime Access Token is found an API call is performed to obtain an OnTime Access Token. If the user is not authenticated to IBM Domino the API tells the client that and the user is redirected to the IBM Domino login page (hard coded which is why we only support form based authentication for this process).
- If an OnTime Access Token is obtained is it stored in a browser cookie and the login process restarts.
How login to OnTime Group Calendar Mobile works
Below we assume that your OnTime Group Calendar Client database (”Client database”) is called ”ontimegcclient.nsf” and is in the ”ontime” directory. To open OnTime Group Calendar Mobile you would redirect users to ”/ontime/ontimegcclient.nsf/mobile”.
Besides the URL required the login process is the same as for OnTime Group Calendar Web.
How login to OnTime Group Calendar Notes and Team-At-A-Glance works
When the OnTime Group Calendar Notes and/or Team-At-A-Glance clients are launched they need information about how to access the OnTime Group Calendar API. This information is stored in the users mail file in a profile document maintained by the OnTime Group Calendar synchronisation process. This profile document is updated every time OnTime Group Calendar reads in (”synchronises”) appointment data from the mail file.
Please note: It follows from the above that while having multiple OnTime Group Calendar environments read appointment data from the same mail file it is important that only one environment is configured to write this profile document.
The launch process is as follows:
- User clicks the icon to launch the client.
- If access information is cached this information is attempted used to access the OnTime Group Calendar API. If this does not work (or any cached token has been explicitly revoked) this cached information is cleared the the launch process is restarted.
- The users mail file is located using the information specified in the users location document. If the user cannot press Ctrl-M (Cmd-M on Mac) to compose a new email this process will fail.
- The profile document is retrieved and access information is read.
- If OnTime Group Calendar is configured for HTTP access an OnTime Access Token is obtained using native IBM Notes API access using digital signatures to verify and identify the user. Once an OnTime Access Token has been obtained the API is accessed over HTTP identifying the user by the OnTime Access Token.
- If OnTime Group Calendar is configured for native Notes API access information is tranferred using the native IBM Notes API using digital signatures to verify and identify the user.
When using the native IBM Notes API and digital signatures to verify and identify the user both the OnTime Group Calendar client and the OnTime Group Calendar API participate in the cryptographic process.
Single Sign On (SSO)
Often customers are looking to provide a Single Sign On solution to OnTime Group Calendar and its user interfaces. Choosing the correct solution depends on the security infrastructure in place but most times the user is authenticated by some other system and/or the user identity may not map to IBM Domino. It may also be the case that the user is authenticated to some other system but the credentials cannot be reused for IBM Domino. There are various ways to solve this as described below.
The simple approach
Use the OnTime Group Calendar security as-is but set a long idle time for the OnTime Access Token. While this strictly speaking does not provide Single Sign On it will only require the user to authenticate once as long as the idle time for the OnTime Access Token is long enough and the user access OnTime Group Calendar within the idle time period set. This option is available out-of-the-box.
The API approach
If you have purchased the OnTime Group Calendar Open API option (sold separately) you may also use the OnTime Group Calendar API to issue tokens to users. Using the OnTime Group Calendar API a system user may obtain an OnTime Access Token on behalf of other users and thus provide access to OnTime Group Calendar using an identity verified by some other system such as Microsoft Sharepoint, a CRM system or an MDM provider. We have previously created Single Sign On (SSO) solutions for customers wanting to provide SSO from non-IBM Domino platforms to OnTime Group Calendar running on IBM Domino.
For example we have a customer with an intranet based on Microsoft technologies where the user is automatically authenticated to the intranet using Windows Integrated Authentication (IWA). The customer wanted users to be able to open OnTime Group Calendar Web without having to re-authenticate which was tricky as the user was only authenticated to the Microsoft intranet and not IBM Domino. To solve this we employed the OnTime Group Calendar API.
We solved it by having the intranet, once the user had logged in to it, use the verified username to obtain an OnTime Access Token on behalf of the user (using the OnTime Group Calendar API). Once the intranet server obtained an OnTime Access Token for the user it set the correct browser cookie to complete the puzzle. Now when the user tries to access OnTime Group Calendar the browser automatically provides the obtained OnTime Access Token and the user may access OnTime Group Calendar without reauthentication thus achiving Single Sign On.
SPNEGO / Kerberos (or if form based authentication cannot be used)
For customers using SPNEGO with IBM Domino the default access control list (ACL) setup of the OnTime Group Calendar Client database can cause problems. This is due to the fact that the Client database allows Anonymous access by default and hence the required HTTP 401 response code that cause the operating system to initialiate the authorization handshake is never sent. To solve this the Client database has a special page that does require the user to be authenticated. Instead of using the page called ”Web” you simply use the page called ”WebSSO”.
For example if your Client database is called ”ontimegcclient.nsf” and is in the ”ontime” directory you would normally redirect users to ”/ontime/ontimegcclient.nsf/web” to open the OnTime Group Calendar Web user interface. If using SPNEGO simply replace ”/web” with ”/websso” and redirect users to /ontime/ontimegcclient.nsf/websso”. Nothing more is required.
Please note: It’s very important that the ACL is configured correctly as described in the documentation for this to work.