Github authentication is an option with the Versatile PlantUML Renderer (for Confluence) which allows you to link to PlantUML code in a private repository for rendering in your Confluence pages. The authentication is on a user by user basis an so it’s worth noting that just because you decide to add a document from a Github repository to which you have access it doesn’t mean that other Confluence users will be able to see the document unless they have access and they have authenticated the plugin to their Github account.
How do I set this up?
The setup is quite simple and users are guided through it when required.
What do I see when I have not created the link to Github?
This depends on whether you are trying to use the Github macro or just viewing a page on which someone has already added a diagram from Github.
Adding the Github Macro to a page
When editing a page you would choose the “Add a PlantUML diagram from a Private Github repository” option.
Then you will be prompted to link your account to Github in the “Insert PlantUML Diagram from Github” dialog as shown below:
Viewing a page with a Github diagram already on it
Each Github diagram on a page will show the following warning message when the user hasn’t yet configured their link.
Configuring the Link
No matter how you arrive at the link configuration screen the process is the same… and the screen looks like this:
Step 1. Click the “Connect Github button”
When you click the button our servers will contact Github and ask for a one-time authorisation code tied to our plugin.
You will see this code on screen along with a link to the website that Github wants you to access to enter the code.
Step 2. Copy the authorisation code and go to Github
Github tells our servers which link to show on the screen and we provide the link to it - but if you’re feeling particularly security conscious feel free to manually type the URL into a new tab or window in your browser. It should always be to a page on the github.com domain.
Copy the code to your clipboard.
Step 3. Enter the authorisation code
Paste your authorisation code into the prompts on the Github page and then press Continue.
Step 4. Confirm that you want to link our plugin to your Github account
If you aren’t already logged into Github then you will be asked to login.
After that Github will show you a screen similar to the following (we’ve covered up one of our organizations for our security purposes).
We ask for Full Control of private repositories - see the Security Concerns below for an explanation of why we do this (TL;DR - Github permissions are not very granular).
Click the “Authorize Purple-Rhapsody-Tech” button.
Step 5. Confirm your Github password
Github now needs to ensure that you are who you say you are so their site asks you to enter your password.
The page will look like this:
Ensure that the URL in the address bar is a github.com domain before entering your password. This means that you can be sure nobody except Github will be sent your password. Just to reiterate - we do not ask you to enter your password on our site, or directly on your Confluence site… only Github asks you for your password and you should only enter it on a Github page.
Step 6. All done!
Once you enter you password and click “Confirm Password” that’s you done. The page in Confluence will show a bit green tick and the form with the authorisation code will disappear.
How do I revoke access?
This is done on Github itself.
On Github - login to your account, go to your settings, and then select Applications from the options.
You’ll be shown all the applications you’ve linked to Github:
Click on the Versatile PlantUML Renderer for Confluence application and you’ll be shown the details of the link between your Github account and our plugin.
To revoke access click the “Revoke access” button - you will be asked to confirm this. Once you’ve done it our plugin will no longer have access to your Github files and will not be able to show your diagrams.
NB: This is only for this Github user so don’t worry about this affecting other users. It is just for the link to your Github account.
Authorising access to your code repository is something that should not be taken lightly. However at Purple Rhapsody Tech we are aware of this and so here are the details of exactly what we do, why we do it, and what data we store.
To enable the Confluence functionality we already need to store your company’s Confluence URL and a secret key that Atlassian tell us about when you install the plugin.
When you decide that you want to link the plugin to Github so that we can render your diagrams from there we are provided with a user-specific token from Github that we then store in the database. To ensure that we can use the correct token for the correct Confluence user we need to relate the user’s Atlassian Account Id with the Github token. The Atlassian Account Id is a long string of letters and numbers like this 123456:ad4435a5-35a3-37d0-af3d-123a14f9135f.
For each user who decides they wish to link the plugin to Github we will store:
the company’s Confluence URL
the user’s Atlassian Account Id
the Github token
None of this information enables us to identify a particular user either on the Atlassian side or the Github side because Atlassian do not provide us with access to query users based on their account ID, and the Github token does not contain any user-identifiable information whatseover.
How do you make sure you use the correct user’s link?
As explained above - for each user who elects to link their Github access with our plugin we store 3 pieces of information:
Company Confluence URL
User’s Atlassian Account Id
A token from Github
When the plugin tries to render an image from Github the current user’s Atlassian Account Id is supplied to our servers by Atlassian together with information that allows us to determine the user’s company Confluence URL. We then use that information to retrieve the Github token. Because every user has a unique Atlassian Account Id we will never use the Github token for the incorrect user.
Why do you ask for full access to our private Github repositories?
We don’t actually want that access… all that we want is access to read the files in your private repositories. However, Github themselves don’t provide that level of granularity.
The list of scopes is detailed on their Scopes for OAuth Apps page and you can see that, as at the time of writing, there is no option for just read access to private repositories. We will be keeping an eye on this situation and will update our Github scope requests as soon as a more granular option is made available to us.
Rest assured that once a user has granted access to Github from our plugin that all we do is request the file contents for URLs that you put into our plugin macro and we don’t store any of the file contents (or even the URLs themselves) on our servers.
Why do you use “Device Flow” Authorisation?
This gets a little complicated. So let’s break it down.
Atlassian Confluence lets vendors like us show our content (i.e. rendered diagrams) in an iframe. This is basically a web page within a web page.
The Github Device Flow however requires the user to visit a Github page to enter a one-time authorisation code.
The Device Flow is designed for apps that aren’t able to use the standard web application flow and seeing as our plugin is an app hosted within an environment that Github Web Application Flow restricts then this is a solid, secure, and sensible solution to allow us to show your diagrams from Github.
What if my company stops using your plugin?
Well firstly, we really hope you don’t do that! We believe that our plugin is the most flexible and fully-featured in the Atlassian Marketplace for generating PlantUML diagrams. We always strive to keep ahead of other vendors but if we fall short please consider raising an enhancement request for us to look at implementing the functionality you need!
But… if you really want to stop using our plugin then when you Uninstall our app from your Confluence site we not only permanently delete the record of your organisation completely from our database, we also delete all of the Github access tokens associated with your company.