Skip to content

Commit

Permalink
GITBOOK-30: No subject
Browse files Browse the repository at this point in the history
  • Loading branch information
gitbook-bot committed Oct 6, 2024
1 parent 00b25d7 commit addb356
Show file tree
Hide file tree
Showing 24 changed files with 655 additions and 215 deletions.
2 changes: 1 addition & 1 deletion docs/development/deployment/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
23 changes: 1 addition & 22 deletions docs/development/deployment/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -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>

6 changes: 3 additions & 3 deletions docs/development/requirements.md
Original file line number Diff line number Diff line change
Expand Up @@ -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/)
2 changes: 1 addition & 1 deletion docs/development/specs.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 2 additions & 0 deletions docs/development/user-interface.md
Original file line number Diff line number Diff line change
Expand Up @@ -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" %}
Expand Down Expand Up @@ -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" %}
Expand Down
4 changes: 2 additions & 2 deletions docs/README.md → docs/docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
58 changes: 58 additions & 0 deletions docs/docs/SUMMARY.md
Original file line number Diff line number Diff line change
@@ -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)
190 changes: 190 additions & 0 deletions docs/docs/api-endpoints/api-endpoints.md
Original file line number Diff line number Diff line change
@@ -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"
}
```
9 changes: 9 additions & 0 deletions docs/docs/authentication/api-documentation.md
Original file line number Diff line number Diff line change
@@ -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.
15 changes: 15 additions & 0 deletions docs/docs/authentication/authentication-guide.md
Original file line number Diff line number Diff line change
@@ -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.
16 changes: 16 additions & 0 deletions docs/docs/authentication/customizing-authentication.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
# Customizing Authentication

You can modify the default behavior of the Authority authentication system by extending the authentication logic.

### Custom OAuth Providers

To add a custom OAuth provider, modify the `OAuth::Client` configuration in the `src/auth.cr` file:

```crystal
OAuth::Client.new do |config|
config.client_id = ENV["CUSTOM_OAUTH_CLIENT_ID"]
config.client_secret = ENV["CUSTOM_OAUTH_CLIENT_SECRET"]
end
```

This allows you to connect to other OAuth providers or implement custom authentication logic.
Loading

0 comments on commit addb356

Please sign in to comment.