OAuth on GitHub
About GitHub
GitHub is one of the Git hosting systems explicitly supported by OpenSquiggly. Once you’ve installed your OpenSquiggly instance, users can connect to their repositories on GitHub and bring them into their OpenSquiggly accounts.
Public repositories can always be brought into OpenSquiggly with no additional configuration work on the part of the OpenSquiggly instance administrator.
Private repositories can also be brought into OpenSquiggly using the user’s personal access token which they’ve manually created within the GitHub system. Use of personal access tokens does not require any additional configuration work on the part of the OpenSquiggly instance administrator.
Another way of connecting to private repositories is to use OAuth authentication. This is more convenient for the user because they do not need to manually create and maintain their personal access tokens.
In order for users to use OAuth authentication, the OpenSquiggly instance administrator must follow some additional steps to enable OAuth authentication. This section covers how to configure OAuth for GitHub.
Note that in the cloud-hosted shared OpenSquiggly portal, these steps are not necessary because we’ve already performed the setup and configured the cloud portal. However, the keys we use are private and cannot be shared with the public, as that would defeat the purpose of OAuth authentication. Each private OpenSquiggly instance must be configured to use it’s own private keys.
Configuring GitHub for OAuth
-
Create an account and an organization on GitHub by visiting https://github.com.
-
Since we are assuming that you are creating an OpenSquiggly self-managed instance for a company, vs. a personal instance, you’ll want to create an “organization” on GitHub and associate your personal account with the company’s GitHub organization.
-
Select the GitHub organization for which you wish to create the OAuth application.
- In the user options drop in the upper-right of the GitHub header bar, select “Settings” to open up the settings for your user account.
- In the sidebar, select “Organizations”.
- In the list of organizations, click on the organization for which you wish to create the OAuth application.
-
Navigate to the organization settings by clicking on the “Settings” icon in the menu across the top. Note that you are now entering the screen for ORGANIZATION settings, not your personal settings.
-
In the sidebar, select the “Developer settings” dropdown, and within the dropdown list, select “OAuth Apps”.
-
Create a new OAuth App by clicking on the button “New OAuth App”, and fill in the fields in the form:
- Application name - You should fill in this field with information that let’s the user know what they are authorizing. It’s a good idea to include both “OpenSquiggly” and your company name, such as “OpenSquiggly at YourCompany”. This will let users know that they are authorizing the private instance within your company to access their repositories, and not some other public or private OpenSquiggly instance.
- Homepage URL - Enter the full URL where the OpenSquiggly instance is installed, for example “https://opensquiggly.yourcompany.com”
- Application description - Enter a description for OpenSquiggly such as “A documentation portal and notebook for developers”.
- Authorization callback URL - Enter the full URL plus the suffix “/home”, for example “https://opensquiggly.yourcompany.com/home".
- IMPORTANT: The callback URL must EXACTLY MATCH the location where you have installed OpenSquiggly with the “/home” suffix appended.
- Enable Device Flow - Leave this checkbox unchecked
- When finished, click the “Register application” button to create OAuth App.
-
Take note of the “Client ID” for the newly registered application and store it in a secure location. You will need the Client ID for later steps.
-
Click the “Generate a new client secret” and take note of the client secret value that is generated for you. Store the client secret in a secure location. You will need the client secret for later steps.
- Note that after you exit this screen, you can no longer retrieve the client secret value, so you need to enter the value in your secure location before proceeding further. However, if you lose your client secret you can always generate a new client secret and reconfigure OpenSquiggly with the new secret.
-
Open an SSH connection to your virtual machine on your cloud provider where you installed OpenSquiggly
-
Open the appsettings.json file with the command:
sudo vi /opt/OpenSquiggly/bin/appsettings.json -
Add the following section to your appsettings.json file:
"GitHubOAuthTokenProviderOptions": { "AppId": "[The Client ID assigned by GitHub]", "AppSecret": "[The client secret generated by GitHub]", "RedirectUri": "https://[OpenSquiggly URL]/home", "Scope": "repo" }Example:
"GitHubOAuthTokenProviderOptions": { "AppId": "XXXXXXXXXXXXXXXXXX", "AppSecret": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" "RedirectUri": "https://opensquiggly.yourcompany.com/home", "Scope": "repo" } -
Save the appsettings.json file
-
Restart the OpenSquiggly service with:
sudo systemctl restart opensquiggly