github.com/miguelangel-nubla/oauth2commander@v0.3.7/README.md (about)

     1  # OAuth2Commander
     2  
     3  Bridge the gap between command-line and web interfaces with OAuth2Commander. This tool transforms CLI workflows into web actions while leveraging the security of OAuth2.0 and OIDC.
     4  
     5  ## Features
     6  
     7  1. **Your CLI on the Web**: Convert command-line tasks into web actions, making powerful commands accessible to non-tech-savvy users.
     8    
     9  2. **Robust Security**: OAuth2.0 and OIDC integration ensure the secure execution of web-based commands.
    10  
    11  3. **Dynamic Endpoints**: The server adapts web endpoints to commands via a JSON configuration, ensuring flexibility without altering the core code.
    12  
    13  4. **Interactive Feedback**: Get HTML feedback for every command executed through the web, enhancing the user experience.
    14  
    15  ## Why Choose OAuth2Commander?
    16  
    17  1. **Simplify for Users**: Make intricate tasks user-friendly by transitioning them from the CLI to the web.
    18  
    19  2. **Unified Command Management**: Update commands centrally, maintaining consistency for all users.
    20  
    21  3. **Safety First**: OAuth2 and OIDC-backed authentication ensure the safety of every command.
    22  
    23  4. **Scalable**: Seamlessly incorporate new CLI tasks into the web interface via dynamic endpoints.
    24  
    25  Consider OAuth2Commander if you're looking to expand your CLI operations to a wider audience securely and efficiently.
    26  
    27  ---
    28  
    29  ## Quickstart:
    30  
    31  For those who like a straightforward setup without the need for containerization, here's a guide to quickly get `oauth2commander` operational:
    32  
    33  ### Step 1: Install `oauth2commander`
    34  
    35  You have two options:
    36  
    37  **Option A: From GitHub Releases**
    38  
    39  1. Visit the [GitHub releases page](https://github.com/miguelangel-nubla/oauth2commander/releases).
    40  2. Depending on your operating system and architecture, download the appropriate release asset. For instance:
    41     - For macOS with arm64: `oauth2commander_Darwin_arm64.tar.gz`
    42     - For Linux with x86_64: `oauth2commander_Linux_x86_64.tar.gz`
    43     ... and so on.
    44  3. Extract the downloaded file.
    45  4. Move the binary to a location in your system's `$PATH`, or you can execute it directly from the extracted folder.
    46  
    47  **Option B: Using Go**
    48  
    49  If you have Go installed, you can directly install the package:
    50  
    51  ```bash
    52  go install github.com/miguelangel-nubla/oauth2commander@latest
    53  ```
    54  
    55  Ensure your `$GOPATH/bin` directory is in your `$PATH` to run the installed binary from anywhere.
    56  
    57  ### Step 2: Set Up Configuration
    58  
    59  In the directory where `oauth2commander` is installed or your working directory, you'll find a sample `config.json` configuration file. Tailor this file to your environment:
    60  
    61  Ensure you update the OAuth2 endpoint URLs, client credentials, and define any custom commands as needed.
    62  
    63  Use the provided /public endpoint that runs `echo Hello world!` as a starting point.
    64  
    65  ### Step 3: Launch `oauth2commander`
    66  
    67  With everything configured, you can start `oauth2commander`:
    68  
    69  ```bash
    70  oauth2commander
    71  ```
    72  
    73  ### Step 4: Access the Web Interface
    74  
    75  Open a browser and navigate to the `oauth2commander` web interface:
    76  
    77  ```
    78  http://localhost:8080  # Make sure to adjust the port if you've modified it in config.json
    79  ```
    80  
    81  Then, follow the on-screen guidance to authenticate and execute your defined commands.
    82  
    83  ---
    84  
    85  ## Docker Deployment
    86  
    87  Sample config.json is provided in the repository. Deploy with:
    88  
    89  ```bash
    90  docker run \
    91      -p 8080:8080 \
    92      -v $PWD/config.json:/config.json \
    93      ghcr.io/miguelangel-nubla/oauth2commander:latest
    94  ```
    95  
    96  ### Initialization Script for Custom Tools
    97  
    98  In scenarios where `oauth2commander`'s custom commands require special tools or setups, you can introduce an initialization script that runs before the main program.
    99  
   100  1. Prepare your initialization script. For instance, name it `custom-init.sh`.
   101     
   102  2. Launch the Docker container, mounting your script and setting `INIT_SCRIPT_PATH``:
   103      ```bash
   104      docker run \
   105          -p 8080:8080 \
   106          -v $PWD/config.json:/config.json \
   107          -v /path/to/your/custom-init.sh:/custom-init.sh \
   108          -e INIT_SCRIPT_PATH=/custom-init.sh \
   109          ghcr.io/miguelangel-nubla/oauth2commander
   110      ```
   111  
   112  Your script will execute before `oauth2commander`, ensuring the necessary tools or configurations are in place.
   113  
   114  ### Custom CA Certificates
   115  
   116  `OAuth2Commander` might interact with services using certificates from a private/internal CA. For smooth, secure interactions, trust these certificates.
   117  
   118  For Docker deployments, mount your CA certificates at `/trusted-ca-certs`:
   119  
   120  ```bash
   121  docker run \
   122      -p 8080:8080 \
   123      -v $PWD/config.json:/config.json \
   124      -v /path/to/your/ca/certs:/trusted-ca-certs \
   125      ghcr.io/miguelangel-nubla/oauth2commander
   126  ```
   127  
   128  ## Contributing
   129  
   130  Enhance OAuth2Commander through documentation improvements, added features, or issue resolutions. Your contributions are valued!