-
-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
00b25d7
commit addb356
Showing
24 changed files
with
655 additions
and
215 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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" | ||
} | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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. |
Oops, something went wrong.