Automatically login to another application with an API
With HighQ, you can use other web applications, applications you have developed and/or host yourself, or applications hosted by third parties. You can give some users, especially external users, access to both HighQ and one or more of these other applications. A user would need only a single login to access all registered applications, with HighQ acting as the gatekeeper.
note
By default, your instance is limited to ten additional (user-generated) app registrations. If you require more, please contact your account manager.
HighQ-generated app registrations are created by the 'Default User' and do not count against this limit; user-generated app registrations show the name of the user who created the entry.
Overview
There are three principal steps to implementing a pass-through style authentication from HighQ to another web application:
- Registering a new API application in HighQ that corresponds to each of the other applications, which includes a redirect URL to a specified page in the other application.
- Embedding a link on a HighQ rich-text page back to this OAuth application that a user can access, which causes 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 HighQ to validate the identity of the user, based on the parameter contained in the redirect URL.
note
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 HighQ 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 HighQ
As a System Admin, select
API application registration
:
The
API application registration
screen opens:
When you register a new API application, it is important to include a redirect URL - a URL hosted by the other application. Registering a new API application also creates a unique client_id.
note
Deselect the
Show allow/deny screen
checkbox to take the user directly to the redirect URL.Step 2: Embedding a link to the API application in a HighQ page
The next step is to embed an external link to the API application in a rich-text page on HighQ. This can be done using the link embed method. 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 HighQ instance, and the client_id is obtained from the new API application. For example, the link might look like this:
https://collaborate-domain.highqsolutions.com/collaborate-domain/authorize.action?response_type=code&client_id=999
tip
It is advisable to have the link configured to open in a new window/tab, not in the current one.
When a logged in HighQ user clicks the link, their authentication is verified, and they are sent to the redirect URL with an additional OAuth "code" parameter.
note
If the user's session in HighQ is no longer valid, the user is asked to log in when accessing the URL. (If a user selected the "Remember me" feature or single sign-on, then the user is not 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 receives the request via the redirect URL and has access to the OAuth code URL parameters.
note
Note that the OAuth code is only valid for 30 minutes.
The other application can then make an API call against HighQ, using the information obtained when the API application was first registered (e.g. client_id, secret key), along with the Oauth code provided in the redirect URL. The other application makes the following API POST call:
content-type;application/x-www-form-url encoded 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, HighQ responds 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 key point, aside from confirming code validity, is the 'useremail' field, which contains the HighQ user's email. This assures the other application that the request comes from a valid HighQ user, enabling authentication.
note
This solution requires the user to have the same email address in both systems (HighQ and the other application). If this is not the case, the other application must be able to map the user's HighQ email address to the appropriate username.
If user authentication is unsuccessful in the other application, it can display an error message and/or take appropriate actions.
Adding a HighQ login page to another application
The same technique above can be used directly in another application. For example, if the other application has its own login page, then add a "Login with HighQ Instead" link to the login page, which is the same as the link mentioned above; for example:
https://collaborate-domain/instancename/authorize.action?response_type=code&client_id=clientid
Because the user may not currently be logged in to HighQ, or such a login is not available to the other application, the user is shown a HighQ login page (unless SSO is employed). If the user successfully logs in, they are redirected back to the other application, and the same workflow shown above is followed.
The advantage of this approach is that users, particularly external users, only need to remember their HighQ passwords and not passwords for any other applications. However, a user can always use the application-specific password if they so choose.