From 5cdd1db625b8fee5ebbc0fcba4dcaa9b86fbe02b Mon Sep 17 00:00:00 2001 From: Michael Bui <25263378+MaikuB@users.noreply.github.com> Date: Sat, 10 Aug 2024 11:46:12 +1000 Subject: [PATCH] updated documentation (#521) --- flutter_appauth/CHANGELOG.md | 2 ++ flutter_appauth/README.md | 8 ++++++-- flutter_appauth/lib/src/flutter_appauth.dart | 14 ++++++++++++-- flutter_appauth_platform_interface/CHANGELOG.md | 1 + .../lib/src/end_session_request.dart | 1 + .../lib/src/end_session_response.dart | 1 + .../lib/src/flutter_appauth_platform.dart | 10 ++++++++++ 7 files changed, 33 insertions(+), 4 deletions(-) diff --git a/flutter_appauth/CHANGELOG.md b/flutter_appauth/CHANGELOG.md index 505c8089..abf95f18 100644 --- a/flutter_appauth/CHANGELOG.md +++ b/flutter_appauth/CHANGELOG.md @@ -2,6 +2,8 @@ * **Breaking change** all methods have now been made to return non-nullable types * [iOS][macOS] bumped AppAuth iOS dependency to 1.7.5 +* Updated API docs with more details +* Updated readme with more details on essential knowledge and links to OAuth 2.0 specifications # 7.0.0-dev.2 diff --git a/flutter_appauth/README.md b/flutter_appauth/README.md index 93c08e06..76bdb6c9 100644 --- a/flutter_appauth/README.md +++ b/flutter_appauth/README.md @@ -18,8 +18,7 @@ A Flutter bridge for AppAuth (https://appauth.io) used authenticating and author ## Getting Started -Please see the example that demonstrates how to sign into the demo IdentityServer instance (https://demo.duendesoftware.com). It has also been tested with Azure B2C and Google Sign-in. It is suggested that developers check the documentation of the identity provider they are using to see what capabilities it supports e.g. how to logout, what values of the `prompt` parameter it supports etc. API docs can be found [here](https://pub.dartlang.org/documentation/flutter_appauth/latest/) - +Please see the example that demonstrates how to sign into the demo IdentityServer instance (https://demo.duendesoftware.com). It has also been tested with Azure B2C, Auth0, FusionAuth and Google Sign-in. Developers should check the documentation of the identity provider they are using to see what capabilities it supports (e.g. how to logout, what values of the `prompt` parameter it supports etc) and how to configure/register their application with the identity provider. Understanding [OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc6749) is also essential, especially when it comes to [best practices for native mobile apps](https://datatracker.ietf.org/doc/html/rfc8252). The first step is to create an instance of the plugin @@ -220,6 +219,11 @@ Go to the `Info.plist` for your iOS/macOS app to specify the custom scheme so th Note: iOS apps generate a file called `cache.db` which contains the table `cfurl_cache_receiver_data`. This table will contain the access token obtained after the login is completed. If the potential data leak represents a threat for your application then you can disable the information caching for the entire iOS app (ex. https://kunalgupta1508.medium.com/data-leakage-with-cache-db-2d311582cf23). + +## API docs + +API docs can be found [here](https://pub.dartlang.org/documentation/flutter_appauth/latest/) + ## FAQs **When connecting to Azure B2C or Azure AD, the login request redirects properly on Android but not on iOS. What's going on?** diff --git a/flutter_appauth/lib/src/flutter_appauth.dart b/flutter_appauth/lib/src/flutter_appauth.dart index 2bca7718..1b326325 100644 --- a/flutter_appauth/lib/src/flutter_appauth.dart +++ b/flutter_appauth/lib/src/flutter_appauth.dart @@ -9,16 +9,26 @@ class FlutterAppAuth { return FlutterAppAuthPlatform.instance.authorizeAndExchangeCode(request); } - /// Sends an authorization request + /// Sends an authorization request. + /// + /// This is done by sending a request to the authorization server's + /// [authorization endpoint](https://datatracker.ietf.org/doc/html/rfc6749#section-3.1). Future authorize(AuthorizationRequest request) { return FlutterAppAuthPlatform.instance.authorize(request); } - /// For exchanging tokens + /// For exchanging tokens. + /// + /// This is done by sending a request to the authorization server's + /// [token endpoint](https://datatracker.ietf.org/doc/html/rfc6749#section-3.2). Future token(TokenRequest request) { return FlutterAppAuthPlatform.instance.token(request); } + /// Performs an end session/logout request. + /// + /// This is done by sending a request to the authorization server's + /// end session endpoint per the [RP-initiated logout spec](https://openid.net/specs/openid-connect-rpinitiated-1_0.html). Future endSession(EndSessionRequest request) { return FlutterAppAuthPlatform.instance.endSession(request); } diff --git a/flutter_appauth_platform_interface/CHANGELOG.md b/flutter_appauth_platform_interface/CHANGELOG.md index fd55b61d..3dc57125 100644 --- a/flutter_appauth_platform_interface/CHANGELOG.md +++ b/flutter_appauth_platform_interface/CHANGELOG.md @@ -1,6 +1,7 @@ ## [7.0.0-dev.3] * **Breaking change** all methods have now been made to return non-nullable types +* Updated API docs with more details ## [7.0.0-dev.2] diff --git a/flutter_appauth_platform_interface/lib/src/end_session_request.dart b/flutter_appauth_platform_interface/lib/src/end_session_request.dart index f4ac6ddc..4f5f1d32 100644 --- a/flutter_appauth_platform_interface/lib/src/end_session_request.dart +++ b/flutter_appauth_platform_interface/lib/src/end_session_request.dart @@ -1,6 +1,7 @@ import 'package:flutter_appauth_platform_interface/flutter_appauth_platform_interface.dart'; import 'package:flutter_appauth_platform_interface/src/accepted_authorization_service_configuration_details.dart'; +/// Represents an end session request. class EndSessionRequest with AcceptedAuthorizationServiceConfigurationDetails { EndSessionRequest({ this.idTokenHint, diff --git a/flutter_appauth_platform_interface/lib/src/end_session_response.dart b/flutter_appauth_platform_interface/lib/src/end_session_response.dart index 2516e5aa..67c08677 100644 --- a/flutter_appauth_platform_interface/lib/src/end_session_response.dart +++ b/flutter_appauth_platform_interface/lib/src/end_session_response.dart @@ -1,3 +1,4 @@ +/// Represents the response from performing an end session/logout request. class EndSessionResponse { EndSessionResponse(this.state); diff --git a/flutter_appauth_platform_interface/lib/src/flutter_appauth_platform.dart b/flutter_appauth_platform_interface/lib/src/flutter_appauth_platform.dart index e4db0092..0985727a 100644 --- a/flutter_appauth_platform_interface/lib/src/flutter_appauth_platform.dart +++ b/flutter_appauth_platform_interface/lib/src/flutter_appauth_platform.dart @@ -40,15 +40,25 @@ abstract class FlutterAppAuthPlatform extends PlatformInterface { } /// Sends an authorization request. + /// + /// This is done by sending a request to the authorization server's + /// [authorization endpoint](https://datatracker.ietf.org/doc/html/rfc6749#section-3.1). Future authorize(AuthorizationRequest request) { throw UnimplementedError('authorize() has not been implemented'); } /// For exchanging tokens. + /// + /// This is done by sending a request to the authorization server's + /// [token endpoint](https://datatracker.ietf.org/doc/html/rfc6749#section-3.2). Future token(TokenRequest request) { throw UnimplementedError('token() has not been implemented'); } + /// Performs an end session/logout request. + /// + /// This is done by sending a request to the authorization server's + /// end session endpoint per the [RP-initiated logout spec](https://openid.net/specs/openid-connect-rpinitiated-1_0.html). Future endSession(EndSessionRequest request) { throw UnimplementedError('endSession() has not been implemented'); }