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 HighQ support.
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 main steps to implement pass-through authentication from HighQ to another web application:
- Register an API application in HighQ for the target application. As part of the registration, specify the redirect URL for the target application.
- Add a link to a HighQ rich-text page that points to the OAuth application. When selected, the link redirects the user to the target application and passes an authentication parameter in the URL.
- The target application validates the user's identity by making an API call to HighQ using the parameter received 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 completed entirely within HighQ and typically take only a few minutes to configure. The final step must be implemented in the target 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 registering a new API application, it is important to specify a redirect URL hosted by the target application. The registration process also generates 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 recommended that the link open in a new browser tab or window rather than 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 HighQ session is no longer valid, they are prompted to sign in when accessing the URL. However, users who selected
Remember me
or use single sign-on (SSO) are not prompted to sign in again, even if their session has 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 target application). If this is not the case, the target application must be able to map the user's HighQ email address to the appropriate username.
If user authentication is unsuccessful in the target application, it can display an error message and/or take appropriate actions.
Adding HighQ login page to another application
The same technique above can be used directly in target application. For example, if the target 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 target 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.