GitHub & Gitlab UAC Configuration
Outline of the process described below:
- Register a GitHub and/or Gitlab application
- Run the configuration script to get the application running
- If behind a proxy, apply appropriate configurations
- Sign into the UI using GitHub or Gitlab, and complete registration
- Use the script to promote a user to admin
- Complete further user approvals through the admin dashboard
Requirements:
- Unfetter & Docker installed (note, the unfetter-discover-api will not run correctly before these configurations are complete)
- python 2
- pip or another python package manager that can install PyMongo
Register a GitHub OAuth application here:
https://github.com/settings/applications/new
The Homepage URL will be https://(domain)
The Authorization callback URL will be https://(domain)/api/auth/github-callback
domain is the domain that the users will accessing Unfetter from. For local development, that will be localhost.
After the application is registered, you will need the Client ID and Client Secret from:
https://github.com/settings/developers
Register a Gitlab OAuth application here:
https://gitlab.com/profile/applications
You can replace https://gitlab.com, if you have a private Gitlab instance you would prefer to use. Note that the URL and configuration screens may be different on older versions of Gitlab.
The Redirect URL will be https://(domain)/api/auth/gitlab-callback
domain is the domain that the users will accessing Unfetter from. For local development, that will be localhost.
Select the "api" and "read_user" Scopes, and hit "Save Application".
After the application is registered, Gitlab will display the Client ID and Client Secret to you.
When you build Unfetter for the first time using Ansible, the playbook will know that you do not have your UAC settings and will ask you for the above information
You may always reconfigure your private settings by running
ansible-playbook task-reconfigure-private-vol.yml
Note: This is relevant to situations where the Unfetter server/API is deployed in an environment with a proxy, not the clients.
GitHub UAC is built on top of OAuth2, and OAuth2 requires special handling for proxies.
To configure Unfetter to run properly when deployed behind a proxy, you can set the proxy's URL in the docker-compose file you're using. This is under the environment: for unfetter-discover-api:.
# If deployed in a proxy, add the proxy's URL here
- HTTPS_PROXY_URL=
Please note that setting this variable when not behind a proxy will cause errors.
Unfetter's Sign In button will drop down a menu of login choices for each service (Github and Gitlab, for example) that you configured above. After clicking a menu choice, if necessary, you will be automatically redirected to the service's login page, and/or authorize Unfetter to accept their sign in.
The first time a user signs into Unfetter, he/she will be routed to the Unfetter registration page. After registration is complete, the user will be registered but not approved. The user will only be able to use the site after approval.
There is a python 2 script to handle user approval and role promotion at unfetter-store/unfetter-utils/user_promotion_tool.py. This scripts requires an additional python package, PyMongo. This may be installed via pip using pip install -r requirements.txt from the unfetter-store/unfetter-utils directory; any other method to install PyMongo will also work.
This script is intended only to be used after a user has registered.
It is recommended to use this tool to designate at least one admin. This is currently the only way to promote people to admin.
Once a user promoted to admin, further approvals may be done through the admin dashboard, found at https://(domain)/#/admin/approve-users. Anyone that registers to the application will be placed into this dashboard, with the admin able to approve or block the user.
Made by NSA Information Assurance