A client that has licensed Collaborate may use other web applications, applications they have developed and/or host themselves, or applications hosted by third parties. Often, the client will give the same users, especially external users, access to both Collaborate and one or more of these other applications. Ideally, such a user would need only a single login to access all of those applications, with Collaborate acting as the gatekeeper.
Overview
There are three principal steps to implementing a pass-through style authentication from Collaborate to another web application:
- Registering a new API application in Collaborate that corresponds to each of the other applications, which will include a redirect URL to a specified page in the other application.
- Embedding a link on a Collaborate rich-text page back to this OAuth application that a user can access, which will cause the user to be redirected to the other application, along with a URL parameter to help authenticate the user in the other application.
- The other application performs an API call against Collaborate to validate the identity of the user, based on the parameter contained in the redirect URL.
Example URLs may include text that will be replaced with client-specific strings; this text is shown in italics.
The first two steps can be implemented completely within Collaborate and should take no more than a few minutes to configure. The last step must be done in the other application.
Step 1: Registering a new API Application in Collaborate
The first step requires that a System Admin add a new API application via API application registration:
The API application registration screen is displayed:
When a new API application is registered, it is important to include a redirect URL, a URL that is hosted by the other application. Registering a new API application will also create a unique client_id.
It may be advisable to deselect the Show allow/deny screen checkbox and just take the user straight to the redirect URL.
Step 2: Embedding a link to the API application in a collaborate page
The next step is to embed a link to the API application in any rich-text Collaborate page, which should be added as an external link. This can be done using the link embed method found here. The link should have this format:
https://collaborate-domain/instancename/authorize.action?response_type=code&client_id=clientid
Where the domain and instance are from the Collaborate instance and the client_id is obtained from the new API application. For example, the link might look like this:
https://collaborate3uat.highqsolutions.com/collaborate3uat/authorize.action?response_type=code&client_id=999
It is advisable to have the link configured to open in a new window/tab, not in the current one.
Any logged-in Collaborate user who accesses that link will have their Collaborate authentication validated and then they will be redirected to the redirect URL, with an OAuth "code" parameter added to the redirect URL.
Note that if the user's session in Collaborate is no longer valid, the user will first be asked to login when accessing the URL. (If a user has utilized the "Remember me" feature or single sign-on, then the user will not be asked to log in again, even if their session had expired.)
Step 3: Authenticating the user in the other application
The last step must be performed within the other application. The other application will receive the request via the redirect URL and will have access to the OAuth code URL parameters. (Note that the OAuth code is only valid for 30 minutes.) The other application can then make an API call against Collaborate, using the information obtained when the API application was first registered (like client_id, secret key), along with the Oauth code provided in the redirect URL. The other application would make the following API POST call:
content-type;application/x-www-form-urlencoded
URI: https://collaborate-domain/instancename/api/oauth2/token
Post Body: grant_type=authorization_code&client_id=clientid&client_secret=clientsecret&code=oauthcode
If the API call is successful and the code is valid, Collaborate will respond as follows (emphasis added):
<TokenResponse>
<access_token>accesstoken</access_token>
<expires_in>2419200</expires_in>
<refresh_token>refreshtoken</refresh_token>
<token_type>bearer</token_type>
<useremail>user@clientname.com</useremail>
</TokenResponse>
The most important part, besides indicating that the code was valid, is the value of the "useremail" field. That is the email address of the Collaborate user who is attempting to access the other application. The other application can now be satisfied that the request was made by a user with that email address and that user has a valid account in Collaborate. That user can now be authenticated by the other application.
Note that this solution requires that the user who is accessing both Collaborate and the other application must have the same email address in both systems. If that is not the case, the other application must be able to map the user's email address used in Collaborate to the user's username in the other application.
If the authentication of the user is unsuccessful in the other application, the other application can display an error message and/or take any other appropriate actions.
Adding a collaborate login page to another application
The same technique above can be used directly within another application. For example, if the other application has its own login page, then a "Login with Collaborate Instead" link can be added to the login page, which will be the same as the link mentioned above, like:
https://collaborate-domain/instancename/authorize.action?response_type=code&client_id=clientid
Because the user may not currently be logged in to Collaborate, or such login will not be available to the other application, the user will be shown a Collaborate login page (unless SSO is employed). Once the user successfully logs in, they will be redirected back to the other application, and the same workflow shown above will be followed.
The advantage of this approach is that users, particularly external users, will only need to remember their Collaborate passwords and not passwords for any other applications. However, a user can always use the application-specific password, if they so choose.
