diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..ce144bf --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,8 @@ +# Code of Conduct + +This project follows the ownCloud Code of Conduct. + +Please read the full Code of Conduct at: +**** + +By participating in this project, you agree to abide by its terms. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..65c9915 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,9 @@ +# Contributing + +Thank you for your interest in contributing to this project! + +Please read the full contributing guidelines at: +**** + +For development setup, coding standards, and pull request process, +see the README in this repository. diff --git a/README.md b/README.md index b144852..82c63f4 100644 --- a/README.md +++ b/README.md @@ -1,52 +1,126 @@ -# 🔐 OAuth 2.0 -[![Build Status](https://drone.owncloud.com/api/badges/owncloud/oauth2/status.svg?branch=master)](https://drone.owncloud.com/owncloud/oauth2) -[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=owncloud_oauth2&metric=alert_status)](https://sonarcloud.io/dashboard?id=owncloud_oauth2) -[![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=owncloud_oauth2&metric=security_rating)](https://sonarcloud.io/dashboard?id=owncloud_oauth2) -[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=owncloud_oauth2&metric=coverage)](https://sonarcloud.io/dashboard?id=owncloud_oauth2) +# OAuth2 -This app implements the [OAuth 2.0 Authorization Code Flow](https://tools.ietf.org/html/rfc6749#section-4.1). + -## Installing the app -Place the content of this repository in **owncloud/apps/oauth2**. +[![License](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](COPYING) [![ownCloud OSPO](https://img.shields.io/badge/OSPO-ownCloud-blue)](https://kiteworks.com/opensource) [![Docker Hub](https://img.shields.io/docker/pulls/owncloud)](https://hub.docker.com/r/owncloud/server) -## Using the app +An ownCloud Server app that implements the OAuth 2.0 Authorization Code Flow (RFC 6749) for secure token-based authentication. It allows registered client applications (desktop, mobile, and web) to obtain access and refresh tokens for API access without handling user passwords directly. + +## Getting Started + +Follow the steps below to install and configure the OAuth2 app. + +### Installation + +Place the app in `owncloud/apps/oauth2` and enable it: + +```bash +occ app:enable oauth2 +``` + +### Client Registration + +Register clients in the admin settings: `/index.php/settings/admin?sectionid=additional#oauth2` ### Endpoints -* Authorization URL: `/index.php/apps/oauth2/authorize` -* Access Token URL: `/index.php/apps/oauth2/api/v1/token` - -### Protocol Flow -1. [Client registration](https://tools.ietf.org/html/rfc6749#section-2): First the clients have to be registered in the admin settings: `/index.php/settings/admin?sectionid=additional#oauth2`. You need to specify a name for the client (the name is unrelated to the OAuth 2.0 protocol and is just used to recognize it later) and the redirection URI. A client identifier and client secret is being generated when adding a new client. They both consist of 64 characters. - -2. [Authorization Request](https://tools.ietf.org/html/rfc6749#section-4.1.1): For every registered client an Authorization Request can be made. The client redirects the resource owner to the [Authorization URL](#endpoints) and requests authorization. The following URL parameters have to be specified: - 1. `response_type` (required): needs to be `code` because at this time only the Authorization Code Flow is implemented. - 2. `client_id` (required): the client identifier obtained when registering the client. - 3. `redirect_uri` (required): the redirection URI specified when registering the client. - 4. `state` (optional): can be set by the client "to maintain state between the request and callback" ([RFC 6749](https://tools.ietf.org/html/rfc6749#section-4.1.1)). - 5. `user` (optional): can be set to indicate the username of the resource owner - -3. [Authorization Response](https://tools.ietf.org/html/rfc6749#section-4.1.2): After the resource owner's authorization the app redirects to the `redirect_uri` specified in the Authorization Request and adds the Authorization Code as URL parameter `code`. An Authorization Code is valid for 10 minutes. - -4. [Access Token Request](https://tools.ietf.org/html/rfc6749#section-4.1.3): With the Authorization Code the client can request an Access Token using the [Access Token URL](#endpoints). [Client Authentication](https://tools.ietf.org/html/rfc6749#section-2.3) is done using Basic Auth with the client identifier as username and the client secret as password. The following URL parameters have to be specified: - 1. `grant_type `: Either `authorization_code` or `refresh_token`. - 2. `code` and `redirect_uri` (if the grant type `authorization_code` is used). - 3. `refresh_token` (if the grant type `refresh_token` is used). - -5. [Access Token Response](https://tools.ietf.org/html/rfc6749#section-4.1.4): The app responses to a valid Access Token Request with an JSON response like the following. An Access Token is valid for 1 hour and can be refreshed with a Refresh Token. - -```json -{ - "access_token" : "1vtnuo1NkIsbndAjVnhl7y0wJha59JyaAiFIVQDvcBY2uvKmj5EPBEhss0pauzdQ", - "token_type" : "Bearer", - "expires_in" : 3600, - "refresh_token" : "7y0wJuvKmj5E1vjVnhlPBEhha59JyaAiFIVQDvcBY2ss0pauzdQtnuo1NkIsbndA", - "user_id" : "admin", - "message_url" : "https://www.example.org/owncloud/index.php/apps/oauth2/authorization-successful" -} + +- Authorization URL: `/index.php/apps/oauth2/authorize` +- Access Token URL: `/index.php/apps/oauth2/api/v1/token` + +### Run Tests + +```bash +make test-php-unit +make test-php-style ``` -## Limitations -Since no user passwords are handled by the app at all only master key encryption is working (similiar to the Shibboleth app). +## Documentation + +- [OAuth 2.0 Authorization Code Flow (RFC 6749)](https://tools.ietf.org/html/rfc6749#section-4.1) +- [ownCloud Server Admin Manual](https://doc.owncloud.com/server/latest/admin_manual/) + +## Part of ownCloud Server (Classic) + +This app extends [ownCloud Server 10](https://github.com/owncloud/core) with OAuth 2.0 support. It is used by the desktop and mobile clients for secure authentication. + +> **Note:** Only master key encryption is supported when using OAuth2 (similar to the Shibboleth app). + +The ownCloud Server is available on [Docker Hub](https://hub.docker.com/r/owncloud/server). + +## Community & Support + +**[Star](https://github.com/owncloud/oauth2)** this repo and **Watch** for release notifications! + +- [ownCloud Website](https://owncloud.com) +- [Community Discussions](https://github.com/orgs/owncloud/discussions) +- [Matrix Chat](https://app.element.io/#/room/#owncloud:matrix.org) +- [Documentation](https://doc.owncloud.com) +- [Enterprise Support](https://owncloud.com/contact-us/) +- [OSPO Home](https://kiteworks.com/opensource) + +## Contributing + +We welcome contributions! Please read the [Contributing Guidelines](CONTRIBUTING.md) +and our [Code of Conduct](CODE_OF_CONDUCT.md) before getting started. + +### Workflow + +- **Rebase Early, Rebase Often!** We use a rebase workflow. Always rebase on the target branch before submitting a PR. +- **Dependabot**: Automated dependency updates are managed via Dependabot. Review and merge dependency PRs promptly. +- **Signed Commits**: All commits **must** be PGP/GPG signed. See [GitHub's signing guide](https://docs.github.com/en/authentication/managing-commit-signature-verification). +- **DCO Sign-off**: Every commit must carry a `Signed-off-by` line: + ``` + git commit -s -S -m "your commit message" + ``` +- **GitHub Actions Policy**: Workflows may only use actions that are (a) owned by `owncloud`, (b) created by GitHub (`actions/*`), or (c) verified in the GitHub Marketplace. + +## Translations + +Help translate this project on Transifex: +**** + +Please submit translations via Transifex -- do not open pull requests for translation changes. + +## Security + +**Do not open a public GitHub issue for security vulnerabilities.** + +Report vulnerabilities at **** -- see [SECURITY.md](SECURITY.md). + +Bug bounty: [YesWeHack ownCloud Program](https://yeswehack.com/programs/owncloud-bug-bounty-program) + +## License + +This project is licensed under the [AGPL-3.0](COPYING). + +## About the ownCloud OSPO + +The [Kiteworks Open Source Program Office](https://kiteworks.com/opensource), operating under +the [ownCloud](https://owncloud.com) brand, launched on May 5, 2026, to steward the open source +ecosystem around ownCloud's products. The OSPO ensures transparent governance, license compliance, +community health, and sustainable collaboration between the open source community and +[Kiteworks](https://www.kiteworks.com), which acquired ownCloud in 2023. + +- **OSPO Home**: +- **GitHub**: +- **ownCloud**: + +For questions about the OSPO or licensing, contact ospo@kiteworks.com. + +### License Migration to Apache 2.0 + +The OSPO is driving a strategic relicensing of ownCloud repositories toward the +[Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0), following +the [Apache Software Foundation's third-party license policy](https://www.apache.org/legal/resolved.html). + +Individual repositories will migrate as their audit is completed. The LICENSE file +in each repo reflects its **current** license status (not the target). + +**Current license: AGPL-3.0** (Category X per Apache policy -- cannot be included in Apache-2.0 works). + +Migration prerequisites for this repository: -## Possible improvements -- [ ] Add option for using different [scopes](https://tools.ietf.org/html/rfc6749#section-3.3). +- **CLA/DCO coverage**: All past contributors must have signed agreements permitting relicensing +- **Copyleft dependency audit**: All AGPL/GPL dependencies must be replaced or isolated +- **KDE heritage review**: Any code with KDE-era copyrights requires legal analysis +- **Complete relicensing**: AGPL-3.0 is a strong copyleft license; migration requires full relicensing of all files, not just a header change diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..78094ae --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,11 @@ +# Security Policy + +## Reporting a Vulnerability + +**Do NOT open a public GitHub issue for security vulnerabilities.** + +Please report security issues responsibly via: +**** + +You can also report vulnerabilities through our YesWeHack bug bounty program: +**** diff --git a/SUPPORT.md b/SUPPORT.md new file mode 100644 index 0000000..d87c0ca --- /dev/null +++ b/SUPPORT.md @@ -0,0 +1,10 @@ +# Support + +For support with this project, please use the following channels: + +- **Enterprise Support**: +- **Community discussions**: https://github.com/orgs/owncloud/discussions +- **Matrix Chat**: +- **Documentation**: + +Please do not use GitHub issues for general support questions. diff --git a/agents.md b/agents.md new file mode 100644 index 0000000..91e4d51 --- /dev/null +++ b/agents.md @@ -0,0 +1,61 @@ +# agents.md -- OAuth2 + +## Repository Overview + +ownCloud Server app implementing OAuth 2.0 Authorization Code Flow (RFC 6749). Licensed under AGPL-3.0. Used by desktop and mobile clients for token-based authentication. + +## Architecture & Key Paths + +- `lib/` -- PHP application logic +- `js/` -- Frontend JavaScript +- `css/` -- Stylesheets +- `templates/` -- Server-side templates +- `appinfo/` -- ownCloud app metadata +- `l10n/` -- Translation files +- `tests/` -- Unit tests +- `Makefile` -- Build and test automation +- `composer.json` -- PHP dependencies + +## Development Conventions + +- PHP code follows ownCloud coding standards (phpcs) +- Static analysis with Phan + +## Build & Test Commands + +```bash +make dist # Build distribution +make test-php-unit # Run PHP unit tests +make test-php-style # Check PHP code style +make test-php-phan # Run Phan static analysis +make clean # Clean build artifacts +``` + +## Important Constraints + +- Licensed under AGPL-3.0 (copyleft). Apache 2.0 migration planned. +- Only master key encryption is supported (no per-user encryption). +- All contributions require a DCO sign-off. + + +## OSPO Policy Constraints + +### GitHub Actions +- **Only** use actions owned by `owncloud`, created by GitHub (`actions/*`), verified on the GitHub Marketplace, or verified by the ownCloud Maintainers. +- Pin all actions to their full commit SHA (not tags): `uses: actions/checkout@ # vX.Y.Z` +- Never introduce actions from unverified third parties. + +### Dependency Management +- Dependabot is configured for automated dependency updates. +- Review and merge Dependabot PRs as part of regular maintenance. +- Do not introduce new dependencies without discussion in an issue first. + +### Git Workflow +- **Rebase policy**: Always rebase; never create merge commits. Use `git pull --rebase` and `git rebase` before pushing. +- **Signed commits**: All commits **must** be PGP/GPG signed (`git commit -S -s`). +- **DCO sign-off**: Every commit needs a `Signed-off-by` line (`git commit -s`). +- **Conventional Commits & Squash Merge**: Use the [Conventional Commits](https://www.conventionalcommits.org/) format where the repository enforces it. Many repos use squash merge, where the PR title becomes the commit message on the default branch — apply Conventional Commits format to PR titles as well. A reusable GitHub Actions workflow enforces this. + +## Context for AI Agents + +This app registers OAuth2 clients and manages authorization codes, access tokens, and refresh tokens. Authorization codes expire after 10 minutes; access tokens after 1 hour. The app does not handle user passwords directly.