diff --git a/docs/ows/index.md b/docs/ows/index.md new file mode 100644 index 0000000..1048c7b --- /dev/null +++ b/docs/ows/index.md @@ -0,0 +1,47 @@ +--- +title: Introduction +description: OWS Introduction +sidebar_position: 1 +--- + +# Introduction +GitHub Actions Workflow Status GitHub Actions Workflow Status GitHub License GitHub issues + +

+ + +OpenWebServices is the UF Open Source Club's Microservices project. It currently implements a custom OAuth2 server, SMTP relay, and account management dashboard. It hopes to establish a common set of developer and project infrastructure services for use across the Open Source Club's projects. All microservices integrate with Kubernetes. + +## Install + +This project uses the [Go compiler](https://go.dev/) and [NodeJS](https://nodejs.org/en). +```bash +git clone https://github.com/ufosc/OpenWebServices.git +cd OpenWebservices/dashboard +npm i +``` + +## Quick Start +The project consists of three components: the authentication (Oauth2) server, the dashboard frontend, and the websmtp relay server. To get started, begin by launching the auth server: +```bash +cd oauth2 +go run ./... +``` + +In a separate terminal, launch the NextJS dashboard: +```bash +cd dashboard +npm run dev +``` + +## Maintainers +Maintained by the UF Open Source Club, can be contacted via [Discord](https://discord.gg/j9g5dqSVD8) + +Current Maintainers: +- Michail Zeipekki @zeim839 +- Daniel Wildsmith @danielwildsmith + +## License +[AGPL-3.0](https://github.com/ufosc/OpenWebServices/blob/main/LICENSE) + +Copyright (C) 2024 Open Source Club diff --git a/docs/ows/kubernetes.md b/docs/ows/kubernetes.md new file mode 100644 index 0000000..7346639 --- /dev/null +++ b/docs/ows/kubernetes.md @@ -0,0 +1,70 @@ +--- +title: Kubernetes +description: OWS Kubernetes +sidebar_position: 3 +--- + +# Kubernetes + +OpenWebServices is deployed on Kubernetes. This section describes the process for provision deployments for the OAuth2, dashboard, WebSMTP, and [Club Website](https://github.com/ufosc/Club_Website_2) microservices. After installing the repository, you may find deployment scripts in the `deploy` directory. + +## Dependencies +1. [Docker](https://www.docker.com/). +2. [Google Kubernetes Engine](https://cloud.google.com/kubernetes-engine?hl=en) (GKE) + * Alternatively, you may use a local K8s environment like [Minikube](https://minikube.sigs.k8s.io/docs/) or use the Kubernetes environment that ships with [Docker Desktop](https://docs.docker.com/desktop/kubernetes/). +3. [GCloud CLI](https://cloud.google.com/sdk/gcloud) (if using GKE). + +## Building + +Before applying any Kubernetes script, you'll need to generate artifacts from each package. If you're using docker, this is accomplished by navigating to the desired directory (in this case, one of: OAuth2, dashboard, or the Club_Website_2 repository) and running: +```bash +docker build --tag . +``` + +Where `` is the name you wish to attach with the associated project (e.g. "oauth2-dashboard" or "oauth2-server"). + +### Submitting Artifacts to Google Cloud +Assuming you've installed [gcloud CLI](https://cloud.google.com/sdk/gcloud) and have a [cluster already set up](https://cloud.google.com/kubernetes-engine/docs/deploy-app-cluster), the first step to submitting a build is to create an artifact repository: +```bash +gcloud artifacts repositories create --project --repository-format=docker --location= --description="Docker repository" +``` + +Where `` will be the name of your new repository (can be anything you want), `` is the name of the Google Cloud project associated with your cluster, and `` should generally be set to the same location as your cluster: e.g. `us-central1`, `us-west2`, etc. + +Then, navigate to each of the Oauth2, dashboard directories, as well as the Club_Weebsite_2 repository, and run the following command for each: +```bash +gcloud builds submit --region= --tag us-central1-docker.pkg.dev/>PROJECT-NAME>//: +``` + +Where ``, ``, and `` must specify the same values as in the repository-creation command.`` and `` are the names you give to the underlying artifact, e.g. `osc-website:v1.0.1` or `oauth2-server:v0.0.1`, etc. + +## Secrets +Secrets are specified in the `deploy/secrets.yml` file. They are omitted, but the document format is preserved. When deploying, you'll need to specify your own values (which must be base64 encoded). + +## Obtaining an IP Address +The scripts are configured such that they expect a global static IP address. This may be accomplished as follows: +```bash +gcloud compute addresses create --global +``` + +Where `` can be any name you wish to give it (note, this has no effect on the IP address, it will be randomly assigned by Google). It may take some time for the address to register, but you may monitor available addresses as follows: +```bash +gcloud compute addresses list +``` + +## Deploying +If using Google Cloud, ensure that you've [authenticated](https://cloud.google.com/docs/authentication/gcloud) your gcloud install and connected to your cluster. Apply the scripts in the following order: +```bash +kubectl apply -f secrets.yml +kubectl apply -f mongodb.yml +kubectl apply -f oauth2.yml +kubectl apply -f website.yml +kubectl apply -f ingress.yml +``` + +### Deploying Locally +If using a local environment, you may skip applying `ingress.yml` (unless you have a dedicated [ingress controller](https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/)), and instead use NodePort services to expose applications: navigate to `oauth2.yml`, `website.yml` and uncomment the `type: NodePort` and `nodePort: ...` attributes. + +Depending on your environment, you may have issues provisioning a PersistentVolumeClaim in `mongodb.yml`. In that case, you can remove the PersistentVolumeClaim resource and comment out the `volumeMounts` and `volumes` attributes in the mongodb deployment. + +Running the whole microservice stack requires a moderately powerful machine. As a consequence of OS preemption, you may notice API calls being dropped. In that case, concentrating every container into a single deployment seems to significantly improve performance. However, it would be a lot wiser (and less painful) to just set up a cloud-hosted testing environment or run each service directly on your machine (as opposed to a container). diff --git a/docs/ows/usage/_category_.json b/docs/ows/usage/_category_.json new file mode 100644 index 0000000..3cc6ed9 --- /dev/null +++ b/docs/ows/usage/_category_.json @@ -0,0 +1,6 @@ +{ + "position": 2, + "label": "Usage", + "collapsible": true, + "collapsed": true, +} diff --git a/docs/ows/usage/oauth2.md b/docs/ows/usage/oauth2.md new file mode 100644 index 0000000..ae61780 --- /dev/null +++ b/docs/ows/usage/oauth2.md @@ -0,0 +1,363 @@ +--- +title: Integrating with OAuth2 +description: OWS OAuth2 +sidebar_position: 1 +--- + +# Integrating with OAuth2 + +One of the goals of OpenWebServices is to establish a common authentication service for use across Open Source Club and UF projects. The OAuth2 implementation allows project developers to authenticate users using their Open Source Club credentials. This enables interaction, state management, and data sharing among various projects. + +OpenWebServices is [RFC6749](https://datatracker.ietf.org/doc/html/rfc6749) compliant, meaning that developers can access a user's private resources by (1) first, asking the user for their permission, and (2) without accessing the user's password. + +:::warning IMPORTANT +You will need the Open Source Club's permission to register a client. Please contact a team member via the [discord](https://discord.gg/Gsxej6u) server or [contact form](https://ufosc.org/#contact). +::: + +## Definitions + * Resource Owner (user): "An entity capable of granting access to a protected resource" [RFC6749](https://datatracker.ietf.org/doc/html/rfc6749), a.k.a an end-user. + * Resources: information and privilidges owned by users, for example: their first and last name, email address, permission to access a service, etc. + * Client: the third-party application that attempts to access the user's resources, i.e. the program that the user is trying to log into. + +## Creating an OWS Account +Clients are owned by users, so the first step to creating a client is registering an OWS account. This can be accomplished through the [sign-up page](https://auth.ufosc.org): + + +You can access the page by clicking [here](https://auth.ufosc.org). You can then enter your details in the form: + + +Once done, you'll be prompted to verify your email. Check your inbox (and spam folders) for an email containing the verification URL, and then open the URL in your browser. + +## Registering a Client +:::warning +This section is work in progress. To register a client, contact a member of OSC. +::: + +Once registered, you will be provided with the following information: +```json +{ + "message": "success", + "id": "", + "pkey": "" +} +``` + +Your private key `pkey` must be kept secret. It will be used to authenticate your client in the authorization grant scheme (see Authorization Schemes). If you're using the implicit grant scheme, the private key is not necessary. + +You must take note of the client id - unlike the private key, the client id does not have to be secret. You'll be using the client id to authorize users. + +## Authorization Schemes +Authorization scheme refers to the means by which a user and client interact to enable authorization. Two distinct schemes are described: the authorization grant and implicit grant schemes. + +Authorization grants are used by clients that can securely store client access tokens. This entails having a dedicated, isolated backend server. Clients that choose to use the authorization grant scheme have more resource access privilidges and are more likely to be granted access to users' sensitive data. Additionally, your client will be issued a refresh token, which means you can continue processing user information even after the original access token expires. If your project uses ExpressJS, Springboot (backend), or some other dedicated backend server, then you're eligible for the authorization grant scheme. +

+Implicit grants are for clients without the capabilities necessary to reliably secure access tokens, e.g. website frontends (without a backend server). Pure-frontend websites expose private information to the browser. XSS attacks, browser history APIs, CORS vulnerabilities, or anything with access to the DOM can potentially leak client access tokens. These types of clients are restricted to only (a) identifying the user and (b) accessing their publicly available information. + +### Deciding between Implicit & Authorization Grant Schemes +If your client application does not implement a dedicated server backend, then your only choice is implicit grant. However, there are situations in which a project with a dedicated backend may not want to use the authorization grant scheme. You should use authorization grant if: + * You want to keep accessing the user's resources for longer than 20 minutes. + * You need access to private user information. + +If your sole intent is to identify a user (i.e. verify that they exist, access their full name and unique ID, and differentiate them from other users), then the implicit grant scheme will suffice. Implicit grant clients will need to ask the user to re-authenticate every 20 minutes. + +### Implicit Grant Scheme +``` ++----------+ +| Resource | +| Owner | +| | ++----------+ + ^ + | + (B) ++----|-----+ Client Identifier +---------------+ +| -+----(A)-- & Redirection URI --->| | +| User- | | Authorization | +| Agent -|----(B)-- User authenticates -->| Server | +| | | | +| |<---(C)--- Redirection URI ----<| | +| | with Access Token +---------------+ +| | in Fragment +| | +---------------+ +| |----(D)--- Redirection URI ---->| Web-Hosted | +| | without Fragment | Client | +| | | Resource | +| (F) |<---(E)------- Script ---------<| | +| | +---------------+ ++-|--------+ + | | + (A) (G) Access Token + | | + ^ v ++---------+ +| | +| Client | +| | ++---------+ +``` + +In the implicit grant scheme, you redirect users to the OWS authentication website. Your client's information is passed along with the request, in the form of URL parameters (more on this later). The user enters their email address/password and is asked to acknowledge their consent to use your client. Once the user accepts, the OWS website HTTP-redirects the user back to your client website. An access token is embedded into the redirect URL, which your client may now use to access the user's information. + +You may begin the authorization flow by creating an HTML button that redirects users to the OWS authentication website. The choice of how to redirect the user is left up to you to decide, but a minimal example is illustrated below: +```html +