diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index b9093b6..9567aee 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -2,8 +2,22 @@ name: CI on: push: branches: [develop] + paths-ignore: + - '**.md' + - 'docs/**' + - 'tutorials/**' + - 'examples/**/README.md' + - 'LICENSE' + - '.gitignore' pull_request: branches: [develop, main] + paths-ignore: + - '**.md' + - 'docs/**' + - 'tutorials/**' + - 'examples/**/README.md' + - 'LICENSE' + - '.gitignore' workflow_dispatch: inputs: triggered-by: @@ -13,10 +27,5 @@ on: jobs: build: uses: fireflyframework/.github/.github/workflows/java-ci.yml@main - permissions: - packages: read - contents: read - actions: write with: java-version: '25' - secrets: inherit diff --git a/README.md b/README.md index 7eef94d..3d68517 100644 --- a/README.md +++ b/README.md @@ -1,159 +1,95 @@ -# Firefly Framework - IDP Library +# Firefly Framework - Identity Provider (IDP) [![CI](https://github.com/fireflyframework/fireflyframework-idp/actions/workflows/ci.yml/badge.svg)](https://github.com/fireflyframework/fireflyframework-idp/actions/workflows/ci.yml) +[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE) +[![Java](https://img.shields.io/badge/Java-21%2B-orange.svg)](https://openjdk.org) +[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.x-green.svg)](https://spring.io/projects/spring-boot) -A small, provider-agnostic interface to standardize Identity Provider (IdP) operations across platforms such as Keycloak, AWS Cognito, Okta, Auth0, and others. It exposes a consistent, reactive API so your application code remains clean and portable, while concrete implementations translate calls into provider‑specific requests. +> Identity provider abstraction layer defining contracts for user management, authentication, and token operations. + +--- ## Table of Contents -- [1. Overview](#1-overview) -- [2. Features](#2-features) -- [3. Technology Stack](#3-technology-stack) -- [4. Installation](#4-installation) -- [5. Quick Start](#5-quick-start) -- [6. API Summary](#6-api-summary) -- [7. Implementation Notes](#7-implementation-notes) -- [8. Versioning](#8-versioning) -- [9. Contributing](#9-contributing) -- [10. License](#10-license) - -## 1. Overview -This library defines a single adapter interface, `IdpAdapter`, and a set of DTOs to model common identity workflows: -- User authentication (login/refresh/logout) -- Token introspection and user info retrieval -- User management (create user, change/reset password) -- MFA (challenge and verification) -- Session and role management - -By targeting this interface, you can swap identity providers without changing the application logic. - -## 2. Features -- Unified interface for common IdP operations -- Reactive return types using Reactor `Mono` for async/non-blocking flows -- DTOs tailored to typical OAuth2/OIDC and MFA scenarios -- Spring-friendly responses via `ResponseEntity` - -## 3. Technology Stack -- Java 25 (default, Java 21+ compatible) -- Reactor Core / Spring WebFlux (`Mono`, `ResponseEntity`) -- Lombok for DTO boilerplate reduction -- Maven build - -## 4. Installation -Add the dependency to your Maven project. Replace the version as appropriate. + +- [Overview](#overview) +- [Features](#features) +- [Requirements](#requirements) +- [Installation](#installation) +- [Quick Start](#quick-start) +- [Configuration](#configuration) +- [Documentation](#documentation) +- [Contributing](#contributing) +- [License](#license) + +## Overview + +Firefly Framework IDP defines the port (adapter) contracts for identity provider integration across the Firefly ecosystem. It provides the `IdpAdapter` interface with comprehensive user management, authentication, token, and role management operations that concrete providers must implement. + +The module includes DTOs for all IDP operations including user creation, login, logout, token refresh, MFA challenges, role management, scope management, and session introspection. It is designed as a pure contract library with no implementation, serving as the dependency for all IDP provider modules. + +Provider implementations (AWS Cognito, Keycloak, Internal DB) are published as separate modules that implement the `IdpAdapter` interface. + +## Features + +- `IdpAdapter` interface defining all identity provider operations +- User management DTOs: create, update, change password +- Authentication DTOs: login, logout, token response, refresh +- MFA support: challenge response, verification +- Role and scope management contracts +- Session introspection and token validation +- Provider-agnostic design enabling swappable IDP backends + +## Requirements + +- Java 21+ +- Spring Boot 3.x +- Maven 3.9+ + +## Installation ```xml org.fireflyframework fireflyframework-idp - 1.0.0-SNAPSHOT + 26.01.01 ``` -If you are using Gradle (Kotlin DSL): -```kotlin -implementation("org.fireflyframework:fireflyframework-idp:1.0.0-SNAPSHOT") -``` - -Note: This module provides only the abstraction (interface + DTOs). You will need an implementation module for your chosen provider. - -## 5. Quick Start -1) Implement the `IdpAdapter` for your target IdP (e.g., Keycloak): +## Quick Start ```java -public class KeycloakIdpAdapter implements IdpAdapter { - @Override - public Mono> login(LoginRequest request) { - // Call Keycloak token endpoint and map response - return Mono.empty(); - } - - @Override - public Mono> refresh(RefreshRequest request) { return Mono.empty(); } +import org.fireflyframework.idp.adapter.IdpAdapter; +import org.fireflyframework.idp.dtos.*; - @Override - public void logout(String accessToken) { /* call provider logout/revoke */ } +@Service +public class AuthService { - @Override - public Mono> introspect(String accessToken) { return Mono.empty(); } + private final IdpAdapter idpAdapter; - @Override - public Mono> getUserInfo(String accessToken) { return Mono.empty(); } - - @Override - public Mono> createUser(CreateUserRequest request) { return Mono.empty(); } + public Mono login(LoginRequest request) { + return idpAdapter.login(request); + } - @Override - public void changePassword(ChangePasswordRequest request) { } + public Mono register(CreateUserRequest request) { + return idpAdapter.createUser(request); + } +} +``` - @Override - public void resetPassword(String username) { } +## Configuration - @Override - public Mono> mfaChallenge(String username) { return Mono.empty(); } +No configuration is required for the contracts module. Configuration is provided by the specific IDP provider implementation. - @Override - public void mfaVerify(MfaVerifyRequest request) { } +## Documentation - @Override - public void revokeRefreshToken(String refreshToken) { } +No additional documentation available for this project. - @Override - public Mono>> listSessions(String userId) { return Mono.empty(); } +## Contributing - @Override - public void revokeSession(String sessionId) { } +Contributions are welcome. Please read the [CONTRIBUTING.md](CONTRIBUTING.md) guide for details on our code of conduct, development process, and how to submit pull requests. - @Override - public Mono>> getRoles(String userId) { return Mono.empty(); } -} -``` +## License -2) Inject and use your implementation wherever needed: -```java -Mono> result = idpAdapter.login( - LoginRequest.builder() - .username("alice") - .password("password123") - .clientId("my-client") - .scope("openid profile email") - .build() -); -``` +Copyright 2024-2026 Firefly Software Solutions Inc. -## 6. API Summary -The main entry point is `org.fireflyframework.idp.adapter.IdpAdapter`. - -Basic operations: -- `Mono> login(LoginRequest request)` -- `Mono> refresh(RefreshRequest request)` -- `void logout(String accessToken)` -- `Mono> introspect(String accessToken)` -- `Mono> getUserInfo(String accessToken)` -- `Mono> createUser(CreateUserRequest request)` - -Advanced operations: -- `void changePassword(ChangePasswordRequest request)` -- `void resetPassword(String username)` -- `Mono> mfaChallenge(String username)` -- `void mfaVerify(MfaVerifyRequest request)` -- `void revokeRefreshToken(String refreshToken)` -- `Mono>> listSessions(String userId)` -- `void revokeSession(String sessionId)` -- `Mono>> getRoles(String userId)` - -DTOs are located under `org.fireflyframework.idp.dtos` and cover requests and responses for the above methods. - -## 7. Implementation Notes -- Error Handling: Return appropriate HTTP status codes in `ResponseEntity` (e.g., 401 for invalid credentials, 400 for invalid requests, 500 for unexpected provider errors). Wrap provider errors consistently. -- Security: Never log secrets (passwords, client secrets, tokens). Consider encrypting at rest and masking logs. -- Threading: Since the API is reactive, avoid blocking calls. If the provider SDK is blocking, delegate to bounded elastic schedulers or use non-blocking HTTP clients. -- Portability: Keep provider-specific objects within your implementation; expose only the DTOs defined in this library. - -## 8. Versioning -This project follows semantic versioning as much as possible during its evolution. Breaking changes in interfaces or DTOs will result in a major version increment. - -## 9. Contributing -Contributions are welcome. Please open an issue to discuss proposed changes before submitting a PR. Ensure code compiles and includes documentation updates when necessary. - -## 10. License -This project is licensed under the terms of the LICENSE file included in the repository. +Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for details.