Direct users to Atlassian extension if annotation is associated with atlassian.hypothes.is authority

[robertknight]

Background

Praecipio are building an integration between Confluence and Hypothesis. This uses a custom version of the Hypothesis Chrome extension which users log into using their Atlassian ID. Users see groups that correspond to the Spaces they belong to in Confluence. Annotations that are created get saved to Hypothesis and also posted as entries in Confluence pages.

Behind the scenes, this extension communicates with a custom H API endpoint which is a proxy server that wraps the real H API to customize the login process and "decorate" API calls with additional functionality related to the Confluence integration. The user accounts, groups and annotations used with this extension are all associated with the atlassian.hypothes.is authority in h.

See the #atlassian-demo channel in Slack for more details.

Problem

We want to support sharing links for these annotations, similar to the hyp.is links for regular Hypothesis users. These sharing links will be included in the entries posted in Confluence, so users have a convenient way to view the link in context.

The bouncer service currently directs users either to the regular Hypothesis Chrome extension or Via, depending on whether they have the extension installed. The regular Hypothesis Chrome extension assumes first party user accounts, which is not the case for these annotations. Via also won't work for the same reason.

Constraints

We'll need a solution we can quickly deploy for an upcoming demo. We will also need something we can run longer term.

Possible solutions

1. Run a separate instance of the bouncer service specifically for Atlassian users

The hyp.is server allows configuring the Chrome extension and Via URL via environment variables. We could run a new instance of bouncer which modifies this configuration. Sharing links in annotations would somehow need to be modified to reference this new instance. This could be done by the proxy server, although that wouldn't work for any system or client fetching annotations from the API directly rather than going via the proxy server.

Pros:

• Reduces amount of configurability required within the bouncer service

Cons:

• This adds additional infrastructure that we have to run and deploy new updates to
• We have to find a way to change the incontext_link field on annotations to point at the custom service. There is currently nowhere in h to configure authority-wide settings.
• We'll still need to make some changes to bouncer to handle the unavailability of Via for these annotations, and also customize attributes such as the logo

2. Add ability to configure behavior of bouncer depending on annotation authority

Allow some basic configuration of how Bouncer directs users depending on the annotation's authority. The minimal configurability we would need for this project is:

1. Direct users to a different extension if the annotation is associated with the atlassian.hypothes.is authority
2. Provide a fallback if the user does not have the Atlassian extension installed. This could be a redirect to a static URL which tells the user how to install the extension. In future we might want the ability to direct the user to a custom Via-like service.

We don't add new authorities often, so it would be fine if this configuration was stored in a static file.

Pros:

• Makes it easier to support similar use cases in future

Cons:

• Requires more configurability in bouncer