GITBOOK-30: No subject

Author: gitbook-bot

docs/development/deployment/README.md

@@ -31,7 +31,7 @@ docker-compose up server
 ```
 
 {% hint style="info" %}
-To change the Authority server configuration change the** local.env **file
+To change the Authority server configuration change the **local.env** file
 {% endhint %}
 
 ```yaml

docs/development/deployment/configuration.md

@@ -2,26 +2,5 @@
 
 All server settings are defined using environment variables
 
-|                           |                                                                                                     |                                                                 |
-| ------------------------- | --------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
-| **Environment Variable**  | **Default Value**                                                                                   | **Description**                                                 |
-| **CRYSTAL\_ENV**          | Development                                                                                         |                                                                 |
-| **CRYSTAL\_LOG\_SOURCES** | "\*"                                                                                                |                                                                 |
-| **CRYSTAL\_LOG\_LEVEL**   | debug                                                                                               |                                                                 |
-| **CRYSTAL\_WORKERS**      | 4                                                                                                   | the number of CPU cores to use                                  |
-| **PORT**                  | 4000                                                                                                |                                                                 |
-| **PORT\_REUSE**           | true                                                                                                |                                                                 |
-| **HOST**                  | 0.0;0.0                                                                                             | Binds the server to a particular ip address on the host machine |
-| **DATABASE\_URL**         | postgres://auth\_user:auth\_pass@db:5432/authority\_db?initial\_pool\_size=10\&checkout\_timeout=3P | PostgreSQL database connection URL                              |
-| **SECRET\_KEY**           | secret\_key                                                                                         | The encryption key to use signed JWTs                           |
-| **CODE\_TTL**             | 5                                                                                                   | Duration in seconds                                             |
-| **ACCESS\_TOKEN\_TTL**    | 60                                                                                                  | Duration in seconds                                             |
-| **TEMPLATES\_PATH**       | ./public/templates                                                                                  |                                                                 |
-| **SESSION\_KEY**          | session\_id                                                                                         |                                                                 |
-| **BASE\_URL**             | [http://localhost:4000](http://localhost:4000)                                                      |                                                                 |
-| **DEVICE\_CODE\_TTL**     | 300                                                                                                 | Duration in seconds                                             |
-| **SSL\_CERT**             | ""                                                                                                  |                                                                 |
-| **SSL\_KEY**              | ""                                                                                                  |                                                                 |
-| **SSL\_CA**               | ""                                                                                                  |                                                                 |
-| **SSL\_MODE**             | ""                                                                                                  |                                                                 |
+<table><thead><tr><th width="254.33333333333331"></th><th></th><th></th></tr></thead><tbody><tr><td><strong>Environment Variable</strong></td><td><strong>Default Value</strong></td><td><strong>Description</strong></td></tr><tr><td><strong>CRYSTAL_ENV</strong></td><td>Development</td><td></td></tr><tr><td><strong>CRYSTAL_LOG_SOURCES</strong></td><td>"*"</td><td></td></tr><tr><td><strong>CRYSTAL_LOG_LEVEL</strong></td><td>debug</td><td></td></tr><tr><td><strong>CRYSTAL_WORKERS</strong></td><td>4</td><td>the number of CPU cores to use</td></tr><tr><td><strong>PORT</strong></td><td>4000</td><td></td></tr><tr><td><strong>PORT_REUSE</strong></td><td>true</td><td></td></tr><tr><td><strong>HOST</strong></td><td>0.0;0.0</td><td>Binds the server to a particular ip address on the host machine</td></tr><tr><td><strong>DATABASE_URL</strong></td><td>postgres://auth_user:auth_pass@db:5432/authority_db?initial_pool_size=10&#x26;checkout_timeout=3P</td><td>PostgreSQL database connection URL</td></tr><tr><td><strong>SECRET_KEY</strong></td><td>secret_key</td><td>The encryption key to use signed JWTs</td></tr><tr><td><strong>CODE_TTL</strong></td><td>5</td><td>Duration in seconds</td></tr><tr><td><strong>ACCESS_TOKEN_TTL</strong></td><td>60</td><td>Duration in seconds</td></tr><tr><td><strong>TEMPLATES_PATH</strong></td><td>./public/templates</td><td></td></tr><tr><td><strong>SESSION_KEY</strong></td><td>session_id</td><td></td></tr><tr><td><strong>BASE_URL</strong></td><td><a href="http://localhost:4000">http://localhost:4000</a></td><td></td></tr><tr><td><strong>DEVICE_CODE_TTL</strong></td><td>300</td><td>Duration in seconds</td></tr><tr><td><strong>SSL_CERT</strong></td><td>""</td><td></td></tr><tr><td><strong>SSL_KEY</strong></td><td>""</td><td></td></tr><tr><td><strong>SSL_CA</strong></td><td>""</td><td></td></tr><tr><td><strong>SSL_MODE</strong></td><td>""</td><td></td></tr></tbody></table>
 

docs/development/requirements.md

@@ -2,8 +2,8 @@
 
 This project requires
 
-* **Crystal Language - **find the installation instructions here** **[https://crystal-lang.org/install/](https://crystal-lang.org/install/)
-* **Git - **[https://git-scm.com/book/en/v2/Getting-Started-Installing-Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
+* **Crystal Language -** find the installation instructions here [https://crystal-lang.org/install/](https://crystal-lang.org/install/)
+* **Git -** [https://git-scm.com/book/en/v2/Getting-Started-Installing-Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
 * **PostgreSQL -** [https://www.postgresql.org/docs/current/tutorial-install.html](https://www.postgresql.org/docs/current/tutorial-install.html)
-* **Docker and Docker-Compose **- [https://docs.docker.com/engine/install/](https://docs.docker.com/engine/install/)
+* **Docker and Docker-Compose** - [https://docs.docker.com/engine/install/](https://docs.docker.com/engine/install/)
 * **Geckodriver** - Needed for specs [https://www.softwaretestinghelp.com/geckodriver-selenium-tutorial/](https://www.softwaretestinghelp.com/geckodriver-selenium-tutorial/)

docs/development/specs.md

@@ -4,7 +4,7 @@ The project specifications can be found in the specs directory. Use the director
 
 **Running Specs**
 
-If you have all the requirements installed, running the specs should be fairly simple.** Run the following commands to run the specs locally**
+If you have all the requirements installed, running the specs should be fairly simple. **Run the following commands to run the specs locally**
 
 ```bash
 shards build server

docs/development/user-interface.md

@@ -24,6 +24,7 @@ A template contains **variables** and/or **expressions**, which get replaced wit
 Below is a minimal template that illustrates a few basics using the default Jinja configuration. We will cover the details later in this document:
 
 ```django
+{% raw %}
 {% extends "layout.html" %}
 {% set title = "Signin" %}
 
@@ -52,6 +53,7 @@ Below is a minimal template that illustrates a few basics using the default Jinj
   <div class="text-center small">Don't have an account? <a href="/register">Sign up</a></div>
 </main>
 {% endblock %}
+{% endraw %}
 ```
 
 {% hint style="info" %}

docs/README.md renamed to docs/docs/README.md

@@ -43,8 +43,8 @@ The Authority implements five grants for acquiring an access token:
 
 #### Explore the implementations
 
-{% content-ref url="reference/oauth-2-api/" %}
-[oauth-2-api](reference/oauth-2-api/)
+{% content-ref url="../reference/oauth-2-api/" %}
+[oauth-2-api](../reference/oauth-2-api/)
 {% endcontent-ref %}
 
 The following RFCs are implemented:

docs/docs/SUMMARY.md

@@ -0,0 +1,58 @@
+# Table of contents
+
+* [Introduction](README.md)
+* [In Action](../in-action.md)
+* [Performance at Scale](../performance-at-scale.md)
+* [Roadmap / Features](../roadmap-features.md)
+
+## Getting Started
+
+* [Introduction](getting-started/introduction.md)
+* [Installation](getting-started/installation.md)
+* [Configuration Overview](getting-started/configuration-overview.md)
+
+## Authentication
+
+* [Authentication Guide](authentication/authentication-guide.md)
+* [API Documentation](authentication/api-documentation.md)
+* [Customizing Authentication](authentication/customizing-authentication.md)
+
+## Security & Error Handling
+
+* [Security Considerations](security-and-error-handling/security-considerations.md)
+* [Error Handling & Troubleshooting](security-and-error-handling/error-handling-and-troubleshooting.md)
+
+## Providers
+
+* [Client Providers](providers/client-providers.md)
+* [Owner Providers](providers/owner-providers.md)
+
+## API Endpoints
+
+* [API Endpoints](api-endpoints/api-endpoints.md)
+
+## DEVELOPMENT
+
+* [Requirements](../development/requirements.md)
+* [Database](../development/database.md)
+* [User Interface](../development/user-interface.md)
+* [Specs](../development/specs.md)
+* [Deployment](../development/deployment/README.md)
+  * [Environment Variables](../development/deployment/configuration.md)
+
+## Reference
+
+* [OAuth Terms](../reference/oauth-terms.md)
+* [OAuth 2 Grant Flows](../reference/oauth-2-api/README.md)
+  * [Device Flow](../reference/oauth-2-api/device-flow.md)
+  * [Authorization Flow](../reference/oauth-2-api/authorization-flow.md)
+  * [Client Credentials Flow](../reference/oauth-2-api/client-credentials.md)
+  * [Refreshing Access Tokens](../reference/oauth-2-api/refreshing-access-tokens.md)
+  * [Access Token Response](../reference/oauth-2-api/access-token-response.md)
+  * [Json Web Tokens](../reference/oauth-2-api/json-web-tokens.md)
+  * [Legacy: Implicit grant](../reference/oauth-2-api/implicit-grant.md)
+  * [Legacy: Password](../reference/oauth-2-api/password.md)
+* [Open ID Connect](../reference/open-id-connect/README.md)
+  * [Configuration](../reference/open-id-connect/configuration.md)
+  * [Registering Clients](../reference/open-id-connect/registering-clients.md)
+  * [User Info](../reference/open-id-connect/user-info.md)

docs/docs/api-endpoints/api-endpoints.md

@@ -0,0 +1,190 @@
+# API Endpoints
+
+This section documents all the available API endpoints in the Authority project. Each endpoint serves a specific purpose, such as managing OAuth clients, handling user sessions, or authorizing users.
+
+### 1. Clients Endpoints
+
+The `clients` endpoints manage OAuth clients that represent applications interacting with the Authority system.
+
+*   `POST /clients`: Create a new OAuth client.
+
+    Example Request:
+
+    ```json
+    {
+      "name": "My App",
+      "redirect_uri": "https://myapp.com/callback"
+    }
+    ```
+
+    Example Response:
+
+    ```json
+    {
+      "client_id": "abc123",
+      "client_secret": "xyz789"
+    }
+    ```
+*   `GET /clients`: Retrieve a list of registered OAuth clients.
+
+    \
+    Example Response:
+
+    ```json
+    [
+      {
+        "client_id": "abc123",
+        "name": "My App",
+        "redirect_uri": "https://myapp.com/callback"
+      }
+    ]
+    ```
+
+### 2. Owner Endpoints
+
+The `owner` endpoints manage resource owners, allowing the Authority system to verify and manage access to resources owned by users.
+
+*   `GET /owner`: Retrieve information about the authenticated resource owner.
+
+    Example Response:
+
+    ```json
+    {
+      "id": 1,
+      "name": "John Doe",
+      "email": "johndoe@example.com"
+    }
+    ```
+
+### 3. Sessions Endpoints
+
+The `sessions` endpoints manage user sessions, including login and logout functionality.
+
+*   `POST /sessions/login`: Authenticate a user and create a session.
+
+    Example Request:
+
+    ```json
+    {
+      "email": "user@example.com",
+      "password": "password123"
+    }
+    ```
+
+    Example Response:
+
+    ```json
+    {
+      "access_token": "token123"
+    }
+    ```
+*   `POST /sessions/logout`: Log out the authenticated user and invalidate the session.
+
+    Example Response:
+
+    ```json
+    {
+      "message": "Logged out successfully"
+    }
+    ```
+
+### 4. Authorize Endpoints
+
+The `authorize` endpoints manage the OAuth authorization flow.
+
+* `GET /authorize`: Redirect users to the OAuth provider for authorization.
+  * Example Response: Redirects the user to the OAuth provider's login page.
+*   `POST /authorize`: Handle the authorization code returned by the OAuth provider and exchange it for an access token.
+
+    Example Request:
+
+    ```json
+    {
+      "authorization_code": "code123"
+    }
+    ```
+
+    Example Response:
+
+    ```json
+    {
+      "access_token": "token123"
+    }
+    ```
+
+### 5. Device Endpoints
+
+The `device` endpoints manage device-specific interactions, such as registering or authenticating devices.
+
+*   `POST /device/register`: Register a new device.
+
+    Example Request:
+
+    ```json
+    {
+      "device_id": "device123",
+      "device_name": "John's Phone"
+    }
+    ```
+
+    Example Response:
+
+    ```json
+    {
+      "message": "Device registered successfully"
+    }
+    ```
+
+### 6. Access Token Endpoints
+
+The `access_token` endpoints handle the management of access tokens, including issuing, refreshing, and revoking tokens.
+
+*   `POST /access_token`: Exchange an authorization code for an access token.
+
+    Example Request:
+
+    ```json
+    {
+      "authorization_code": "code123"
+    }
+    ```
+
+    Example Response:
+
+    ```json
+    {
+      "access_token": "token123",
+      "expires_in": 3600
+    }
+    ```
+*   `POST /access_token/revoke`: Revoke an access token.
+
+    Example Request:
+
+    ```json
+    {
+      "access_token": "token123"
+    }
+    ```
+
+    Example Response:
+
+    ```json
+    {
+      "message": "Access token revoked"
+    }
+    ```
+
+### 7. Health Check
+
+The `health_check.cr` endpoint is used to check the health of the Authority service.
+
+*   `GET /health_check`: Returns the status of the service.
+
+    Example Response:
+
+    ```json
+    {
+      "status": "healthy"
+    }
+    ```

docs/docs/authentication/api-documentation.md

@@ -0,0 +1,9 @@
+# API Documentation
+
+Authority exposes several API endpoints for authentication. Below are some key endpoints:
+
+* `POST /auth/login`: Authenticate a user and obtain a token.
+* `GET /auth/user`: Retrieve authenticated user details.
+* `POST /auth/logout`: Log out a user.
+
+Each endpoint accepts and returns JSON data. Ensure that you include the correct OAuth token in the Authorization header for protected routes.

docs/docs/authentication/authentication-guide.md

@@ -0,0 +1,15 @@
+# Authentication Guide
+
+Authority provides a simple yet flexible authentication system using OAuth.
+
+### Setting up OAuth
+
+1. Register your application with the desired OAuth provider.
+2. Obtain the client ID and client secret.
+3. Set these in the environment variables `OAUTH_CLIENT_ID` and `OAUTH_CLIENT_SECRET`.
+
+### OAuth Flow
+
+* Users will be redirected to the OAuth provider for authentication.
+* Once authenticated, the provider will return an authorization code.
+* This code can be exchanged for an access token, which can be used for further API requests.