🎈 boca-auth

Table of Contents

• What Is BOCA?
• Why boca-auth?
• How Does It Work?
• Requirements
• Quick Start
• How To Add Custom Configuration
  • LDAP Authentication
  • Google Authentication
  • Relevant Information
• How To Patch Features To BOCA
• How To Contribute
• License
• Support

What Is BOCA?

The BOCA Online Contest Administrator, commonly referred to as BOCA, is a robust administrative system designed for orchestrating programming contests following the ACM-ICPC rules, particularly the Maratona SBC de Programação. BOCA represents a powerful tool for streamlining the administration of programming contests, making it a valuable asset for contest organizers and participants. For more in-depth information, please visit the official repository at https://github.com/cassiopc/boca.

In order to grant access to the system, it is imperative to ascertain whether the user attempting to connect possesses the necessary credentials. At present, BOCA's sole authentication method mandates that a user's provided password undergo encryption before transmission across the connection and storage in the database. This encryption process employs cryptographic hashing, which is widely regarded as a secure means of safeguarding sensitive data. Its primary objective is to thwart any attempts at password interception on untrusted connections, although it is worth noting that SSL certificate authentication may represent a more robust alternative.

Why boca-auth?

The boca-auth project exemplifies the practical application of alternative authentication methods to elevate user convenience, foster inclusivity, and alleviate the burden of password fatigue, which often plagues users managing multiple accounts. Through extensive reverse engineering efforts, we have devised a method that empowers administrators to configure BOCA's authentication settings conveniently via environment variables, thereby extending support for both LDAP and Google authentication methods.

This work started as part of the undergraduate final year project carried out by Aryelle Gomes Siqueira under supervision of Prof. Dr. Rodrigo Laiola Guimaraes at Universidade Federal do Espirito Santo (UFES).

How Does It Work?

Default Authentication

LDAP Authentication

Google OAuth 2.0 Authentication

Requirements

• Install Docker Desktop;
• Install Git.

Quick Start

• Open a Terminal window and make sure the Docker engine is up and running:

  # List docker images
  docker image ls
  # List containers
  docker container ls -a

• Clone this repo and run the following commands:

  git clone https://github.com/aryellesiqueira/boca-auth.git
  cd boca-auth
  docker compose -f docker-compose.ldap.yml up -d --build

• Voilà! The application should be running now. Open a web browser and visit the URL http://localhost:8001/boca. First, create and activate a BOCA contest (user: professorum | password: professorum). Then, login as admin (user: professordois | password: professordois) to manage users, problems, languages etc.;

• To stop the application (considering that the shell is in the same directory):

  docker compose -f docker-compose.ldap.yml down

NOTE: In order to try out the default authentication method refer to the docker-compose.password.yml file, while for the Google OAuth 2.0 authentication use the docker-compose.google.yml (it needs to be modified as indicated below).

How To Add Custom Configuration

The configuration of the authentication method hinges on a collection of environment variables in BOCA's web server.

Method 1: LDAP Authentication

• Defining Environment Variables:

Name	Values	Description
BOCA_AUTH_METHOD	ldap	Defines the authentication method as LDAP.
BOCA_SYSTEM_USER	<ldap_user_uid>	Optional. Defines a single user with system type permissions that can create and activate programming contests. Provide the user name (UID) of an user capable of authenticating with the LDAP server. Valid characters are: a-z,A-Z,0-9, @.-_. For instance, that would be professorum for a LDAP user defined as uid=professorum,ou=professor,dc=inf,dc=ufes,dc=br. If the variable is set and the value also included in BOCA_LOCAL_USERS, the user will be created and authenticate with the default method (password). If not set, the regular system user with the local password authentication applies.
BOCA_ADMIN_USER	<ldap_user_uid>	Optional. Defines a single user with admin type permissions that can manage programming contests. Provide the user name (UID) of an user capable of authenticating with the LDAP server. Valid characters are: a-z,A-Z,0-9, @.-_. For instance, that would be professordois for a LDAP user defined as uid=professordois,ou=professor,dc=inf,dc=ufes,dc=br. If the variable is set and the value also included in BOCA_LOCAL_USERS, the user will be created and authenticate with the default method (password). If not set, the regular admin user with the local password authentication applies.
BOCA_LOCAL_USERS	<user1,user2,...,userN>	Optional. Defines a list of comma-separated users that will authenticate using the default method (password). Length and characters restrictions may apply (see Relevant Information). Useful for cases in which you want to register a user who does not have an account in the institution's LDAP server or when you want to have a view of another type of user for testing purposes. Keep in mind that these users will not be created automatically (must be inserted manually by the administrator), unless the user name is the same used in the BOCA_SYSTEM_USER or BOCA_ADMIN_USER environment variables.
LDAP_SERVER	ldap://<ldap_url>:<ldap_port>	LDAP server URL and port.
LDAP_BASE_DN	<ldap_base_dn>	LDAP server Base DN. For example, dc=inf,dc=ufes,dc=br.
LDAP_USER	<ldap_user>	User with read permissions on the LDAP server. For instance, cn=admin,dc=inf,dc=ufes,dc=br.
LDAP_PASSWORD	<ldap_user_password>	Password of the user with read permissions on the LDAP server.

Method 2: Google OAuth 2.0 Authentication

1. Creating a Project in Google Console:

   • Go to the Google Console and create a new project;
   • In the project settings page, click on APIs & Services, and then on OAuth consent screen. Fill in the form accordingly;
   • Click on Credentials, then on Create credentials and select OAuth client ID;
   • Choose Web application and fill in the Name and Authorized JavaScript origins fields with the address of the server where BOCA will be deployed;
   • Fill in the Authorized redirect URIs field with the address of the server where BOCA will be deployed, followed by the path /boca/index.php, for example: http://localhost:8001/boca/index.php;
   • Click Create, copy the Client ID and Client Secret, and use to set the respective environment variables.

2. Defining Environment Variables:

Name	Values	Description
BOCA_AUTH_METHOD	google	Defines the authentication method as Google.
BOCA_SYSTEM_USER	<email_username>	Optional. Defines a single user with system type permissions that can create and activate programming contests. Provide the email username (part before the "at" sign) of an user capable of authenticating with Google. For instance, that would be john_doe for [email protected]. If the variable is set and the value also included in BOCA_LOCAL_USERS, the user will be created and authenticate with the default method (password). If not set, the regular system user with the local password authentication applies.
BOCA_ADMIN_USER	<email_username>	Optional. Defines a single user with admin type permissions that can manage programming contests. Provide the email username (part before the "at" sign) of an user capable of authenticating with Google. For instance, that would be john_doe for [email protected]. If the variable is set and the value also included in BOCA_LOCAL_USERS, the user will be created and authenticate with the default method (password). If not set, the regular admin user with the local password authentication applies.
BOCA_LOCAL_USERS	<user1,user2,...,userN>	Optional. Defines a list of comma-separated users that will authenticate using the default method (password). Length and characters restrictions may apply (see Relevant Information). Useful for cases in which you want to register a user who does not have an account in the institution's LDAP server or when you want to have a view of another type of user for testing purposes. Keep in mind that these users will not be created automatically (must be inserted manually by the administrator), unless the user name is the same used in the BOCA_SYSTEM_USER or BOCA_ADMIN_USER environment variables.
BOCA_AUTH_ALLOWED_DOMAINS	<domain_1,domain_2,...>	Optional. Defines a list of comma-separated domains using Google OAuth 2.0 to authenticate users (e.g., an university domain). If not set the application will consider as default the gmail.com.
GOOGLE_CLIENT_ID	<client_id>	Client ID generated in Google Console.
GOOGLE_CLIENT_SECRET	<client_secret>	Client Secret generated in Google Console.

Relevant Information

• If BOCA_AUTH_METHOD is undefined or set as password, the default authentication method applies and the LDAP and Google environment variables are ignored;

• If BOCA_SYSTEM_USER and/or BOCA_ADMIN_USER are undefined, set with the default values (system and admin, respectively) or have their values also included in the BOCA_LOCAL_USERS, these users will be created automatically and will authenticate using the default method (password). This means that these variables must be used carefully as they can bypass the value in the BOCA_AUTH_METHOD env variable;

• BOCA_SYSTEM_USER and BOCA_ADMIN_USER must be different because BOCA does not allow for users to accumulate multiple roles;

• The BOCA_LOCAL_USERS env variable implicitly contains the regular system and admin users;

• The initial password for system, admin, and all the users listed in the BOCA_LOCAL_USERS env variable is given by the optional environment variable BOCA_PASSWORD, which can be specified in the boca-web service (see documentation here). If not set, the default value is used (boca). These passwords can be individually updated later on via the web interface;

• When using LDAP authentication, user's credentials will be sent to the server in the body of the request in plain text format. Therefore, it is recommended to use this method only when the connection between client and server is secure, for example, using SSL certificates. To add a LDAP server's SSL certificate to BOCA, simply map it using volumes to the following path inside the container:

  ...
    # web app
    boca-web:
      ...
      volumes:
        ...
        - ./ldap_server_cert.pem:/etc/ssl/certs/ca-certificates.crt
      ...
  ...

• There is a size restriction for the username in the BOCA database, limiting it to a maximum of 20 characters. This puts a contraint particularly on the use of the full email address in the Google authentication method. Therefore, only the email username (part before the "at" sign) is considered. This design decision is not ideal for scenarios in which BOCA users come from different domains. For example, suppose BOCA allows the domains edu.ufes.br and ufes.br. If a student has an email address like [email protected], she will be registered as alunoum. Nonetheless, there might exist a [email protected], which belongs to a different person, and as a result, two distinct accounts can be used to authenticate the same BOCA user. Some potential issues: (1) if the email accounts belong to two different students in the same course, it will not be possible to create accounts for both as BCOA usernames are unique; (2) if the email accounts belong to two different students, with only one of them being registered in the course, it will be possible for an unauthorized user to authenticate. That said, use the BOCA_AUTH_ALLOWED_DOMAINS env variable wisely;

How To Patch Features To BOCA

• Run the following commands to 1) git pull the master branch from the boca-auth repository and 2) generate and patch apply changes in the master branch of the boca repository:

  git clone https://github.com/cassiopc/boca.git && \
  cd boca && \
  # Make sure that there are no unstaged changes in the BOCA repository
  git status && \
  git remote add boca-auth_fork https://github.com/aryellesiqueira/boca-auth.git && \
  git fetch boca-auth_fork master && \
  git checkout -b boca-auth_branch boca-auth_fork/master && \
  git branch -a && \
  git diff --diff-filter=ACMRT master boca-auth_branch src/ > ../patchfile_boca-auth && \
  git checkout master && \
  git apply ../patchfile_boca-auth && \
  rm ../patchfile_boca-auth

  NOTE: If you do not need/want to track future changes in the boca-auth repository run git remote remove boca-auth_fork.

• Finally, install the dependencies when deploying on the web server (it might require superuser privileges):

  apt-get -y update && \
  apt-get -y install \
    curl \
    php-curl \
    php-ldap \
    unzip && \
  curl -sS https://getcomposer.org/installer -o composer-setup.php && \
  php composer-setup.php --install-dir=/usr/local/bin --filename=composer && \
  composer self-update && \
  composer require google/apiclient && \
  rm -rf /var/lib/apt/lists/*

How To Contribute

If you would like to help contribute to this project, please see CONTRIBUTING.

Before submitting a PR consider building and testing a Docker image locally and checking your code with Super-Linter:

docker run --rm \
           -e ACTIONS_RUNNER_DEBUG=true \
           -e RUN_LOCAL=true \
           --env-file ".github/super-linter.env" \
           -v "$PWD":/tmp/lint \
           ghcr.io/super-linter/super-linter:latest

License

Copyright Universidade Federal do Espirito Santo (Ufes)

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.

This program is released under license GNU GPL v3+ license.

Support

Please report any issues with boca-auth at https://github.com/aryellesiqueira/boca-auth/issues