From 5e2f70d12cdcbf7b10d8a9aab544e6990a490dcf Mon Sep 17 00:00:00 2001 From: Ossus Date: Sun, 17 Nov 2019 01:05:18 +0100 Subject: [PATCH] Improve documentation --- README.md | 47 ++++++++++++++--------------------- Sources/Base/OAuth2Base.swift | 1 + Sources/Flows/OAuth2.swift | 1 + 3 files changed, 20 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index 84a65414..76d98e9d 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,6 @@ OAuth2 frameworks for **macOS**, **iOS** and **tvOS** written in Swift 5.0. - [โคต๏ธ Installation](#installation) - [๐Ÿ›  Usage](#usage) - [๐Ÿ–ฅ Sample macOS app][sample] (with data loader examples) -- [๐Ÿ“ฑ Sample iOS app](https://github.com/p2/OAuth2PodApp) (using CocoaPods) - [๐Ÿ“– Technical Documentation](https://p2.github.io/OAuth2) OAuth2 requires Xcode 10.2, the built framework can be used on **OS X 10.11** or **iOS 8** and later. @@ -25,7 +24,7 @@ Code compatible with brand new Swift versions are to be found on a separate feat Usage ----- -To use OAuth2 in your own code, start with `import OAuth2` (use `p2_OAuth2` if you installed _p2.OAuth2_ via CocoaPods) in your source files. +To use OAuth2 in your own code, start with `import OAuth2` in your source files. In OAuth2 there are [**different kinds of _flows_**](https://tools.ietf.org/html/rfc6749#page-2). This library supports all of them, make sure you're using the correct one for your use-case and authorization server. @@ -408,6 +407,7 @@ To customize the _go back_ button when using `OAuth2WebViewController` on iOS 8 oauth2.authConfig.ui.backButton = <# UIBarButtonItem(...) #> +See below for settings about [the keychain](#keychain) and [PKCE](#pkce). Usage with Alamofire -------------------- @@ -457,7 +457,7 @@ dynreg.register(client: oauth2) { params, error in PKCE ---- -PKCE support is controlled by the `useProofKeyForCodeExchange` property, and the "use_pkce" setting. +PKCE support is controlled by the `useProofKeyForCodeExchange` property, and the `use_pkce` key in the settings dictionary. It is disabled by default. When enabled, a new code verifier string is generated for every authorization request. @@ -465,7 +465,7 @@ Keychain -------- This framework can transparently use the iOS and macOS keychain. -It is controlled by the `useKeychain` property, which can be disabled during initialization with the "keychain" setting. +It is controlled by the `useKeychain` property, which can be disabled during initialization with the `keychain` settings dictionary key. Since this is **enabled by default**, if you do _not_ turn it off during initialization, the keychain will be queried for tokens and client credentials related to the authorization URL. If you turn it off _after_ initialization, the keychain will be queried for existing tokens, but new tokens will not be written to the keychain. @@ -475,14 +475,25 @@ If you have dynamically registered your client and want to start anew, you can c Ideally, access tokens get delivered with an "expires_in" parameter that tells you how long the token is valid. If it is missing the framework will still use those tokens if one is found in the keychain and not re-perform the OAuth dance. You will need to intercept 401s and re-authorize if an access token has expired but the framework has still pulled it from the keychain. -This behavior can be turned off by supplying "token_assume_unexpired": false in settings or setting `clientConfig.accessTokenAssumeUnexpired` to false. +This behavior can be turned off by supplying `token_assume_unexpired: false` in settings or setting `clientConfig.accessTokenAssumeUnexpired` to false. +These are the settings dictionary keys you can use for more control: + +- `keychain`: a bool on whether to use keychain or not, true by default +- `keychain_access_mode`: a string value for keychain kSecAttrAccessible attribute, "kSecAttrAccessibleWhenUnlocked" by default, you can change this to e.g. "kSecAttrAccessibleAfterFirstUnlock" if you need the tokens to be available when the phone is locked. +- `keychain_access_group`: a string value for keychain kSecAttrAccessGroup attribute, nil by default +- `keychain_account_for_client_credentials`: the name to use to identify client credentials in the keychain, "clientCredentials" by default +- `keychain_account_for_tokens`: the name to use to identify the tokens in the keychain, "currentTokens" by default Installation ------------ -You can use _git_, _Carthage_ and even _CocoaPods_ to install the framework. -The preferred way is to use _git_ directly or _Carthage_. +You can use the _Swift Package Manager_, _git_ or _Carthage_. +The preferred way is to use the _Swift Package Manager_. + +#### Swift Package Manager + +In Xcode 11 and newer, choose "File" from the Xcode Menu, then "Swift Packages" ยป "Add Package Dependency..." and paste the URL of this repo: `https://github.com/p2/OAuth2.git`. Pick a version and Xcode should do the rest. #### Carthage @@ -514,28 +525,6 @@ These three steps are needed to: 2. Link the framework into your app 3. Embed the framework in your app when distributing -#### CocoaPods - -CocoaPods was nice back in the days for Obj-C and static libraries, but is overkill in the modern days of Swift and iOS frameworks. -You can however still use OAuth2 with Cocoapods. - -Add a `Podfile` that contains at least the following information to the root of your app project, then do `pod install`. -If you're unfamiliar with CocoaPods, read [using CocoaPods](http://guides.cocoapods.org/using/using-cocoapods.html). - -```ruby -platform :ios, '8.0' # or platform :osx, '10.9' -use_frameworks! -target `YourApp` do - pod 'p2.OAuth2', '~> 4.2' -end -``` - -If you want the bleeding edge, use this command for CocoaPods instead โ€“ note the `submodules` flag: without it the library will not compile. - -```ruby -pod 'p2.OAuth2', :git => 'https://github.com/p2/OAuth2', :submodules => true -``` - License ------- diff --git a/Sources/Base/OAuth2Base.swift b/Sources/Base/OAuth2Base.swift index e24178e7..f1a8009f 100644 --- a/Sources/Base/OAuth2Base.swift +++ b/Sources/Base/OAuth2Base.swift @@ -171,6 +171,7 @@ open class OAuth2Base: OAuth2Securable { - secret_in_body (Bool, false by default, forces the flow to use the request body for the client secret) - parameters ([String: String], custom request parameters to be added during authorization) - token_assume_unexpired (Bool, true by default, whether to use access tokens that do not come with an "expires_in" parameter) + - use_pkce (Bool, false by default) - verbose (Bool, false by default, applies to client logging) */ diff --git a/Sources/Flows/OAuth2.swift b/Sources/Flows/OAuth2.swift index a004b81f..ab2886fc 100644 --- a/Sources/Flows/OAuth2.swift +++ b/Sources/Flows/OAuth2.swift @@ -73,6 +73,7 @@ open class OAuth2: OAuth2Base { - secret_in_body (Bool, false by default, forces the flow to use the request body for the client secret) - parameters ([String: String], custom request parameters to be added during authorization) - token_assume_unexpired (Bool, true by default, whether to use access tokens that do not come with an "expires_in" parameter) + - use_pkce (Bool, false by default) - verbose (bool, false by default, applies to client logging) */