iOS/Pods/OAuthSwift/README.md

   1 <p align="center">
   2   <img src="Assets/OAuthSwift-icon.png?raw=true" alt="OAuthSwift"/>
   3 </p>
   4
   5 # OAuthSwift
   6
   7 Swift based OAuth library for iOS and macOS.
   8
   9 ## Support OAuth1.0, OAuth2.0
  10
  11 Twitter, Flickr, Github, Instagram, Foursquare, Fitbit, Withings, Linkedin, Dropbox, Dribbble, Salesforce, BitBucket, GoogleDrive, Smugmug, Intuit, Zaim, Tumblr, Slack, Uber, Gitter, Facebook, Spotify, Typetalk, SoundCloud, etc
  12
  13 ## Sponsored by Auth0 <span><img src="https://user-images.githubusercontent.com/1801923/31792116-d4fca9ec-b512-11e7-92eb-56e8d3df8e70.png" height="28" align="top"></span>
  14 If you want to easily add authentication to Swift apps, feel free to check out Auth0's Swift SDK and free plan at [auth0.com/overview](https://auth0.com/overview?utm_source=GHsponsor&utm_medium=GHsponsor&utm_campaign=oauthswift&utm_content=auth)
  15
  16 ## Installation
  17
  18 OAuthSwift is packaged as a Swift framework. Currently this is the simplest way to add it to your app:
  19
  20 * Drag OAuthSwift.xcodeproj to your project in the Project Navigator.
  21 * Select your project and then your app target. Open the Build Phases panel.
  22 * Expand the Target Dependencies group, and add OAuthSwift framework.
  23 * import OAuthSwift whenever you want to use OAuthSwift.
  24
  25 ### Support Carthage
  26
  27 * Install Carthage (https://github.com/Carthage/Carthage)
  28 * Create Cartfile file
  29 ```
  30 github "OAuthSwift/OAuthSwift" ~> 1.2.0
  31 ```
  32 * Run `carthage update`.
  33 * On your application targets’ “General” settings tab, in the “Embedded Binaries” section, drag and drop OAuthSwift.framework from the Carthage/Build/iOS folder on disk.
  34
  35 ### Support CocoaPods
  36
  37 * Podfile
  38
  39 ```
  40 platform :ios, '10.0'
  41 use_frameworks!
  42
  43 pod 'OAuthSwift', '~> 1.2.0'
  44 ```
  45
  46 ### swift 3
  47
  48 Use the `swift3` branch, or the tag `1.1.2` on main branch
  49
  50 ## How to
  51 ### Setting URL Schemes
  52 In info tab of your target
  53 ![Image](Assets/URLSchemes.png "Image")
  54 Replace oauth-swift by your application name
  55
  56 ### Handle URL in AppDelegate
  57 - On iOS implement `UIApplicationDelegate` method
  58 ```swift
  59 func application(_ app: UIApplication, open url: URL, options: [UIApplicationOpenURLOptionsKey : Any] = [:]) -> Bool {
  60   if (url.host == "oauth-callback") {
  61     OAuthSwift.handle(url: url)
  62   }
  63   return true
  64 }
  65 ```
  66 :warning: Any other application may try to open a URL with your url scheme. So you can check the source application, for instance for safari controller :
  67 ```
  68 if (options[.sourceApplication] as? String == "com.apple.SafariViewService") {
  69 ```
  70
  71 - On macOS you must register an handler on `NSAppleEventManager` for event type `kAEGetURL` (see demo code)
  72 ```swift
  73 func applicationDidFinishLaunching(_ aNotification: NSNotification) {
  74     NSAppleEventManager.shared().setEventHandler(self, andSelector:#selector(AppDelegate.handleGetURL(event:withReplyEvent:)), forEventClass: AEEventClass(kInternetEventClass), andEventID: AEEventID(kAEGetURL))
  75 }
  76 func handleGetURL(event: NSAppleEventDescriptor!, withReplyEvent: NSAppleEventDescriptor!) {
  77     if let urlString = event.paramDescriptor(forKeyword: AEKeyword(keyDirectObject))?.stringValue, let url = URL(string: urlString) {
  78         OAuthSwift.handle(url: url)
  79     }
  80 }
  81 ```
  82
  83 ### Authorize with OAuth1.0
  84 ```swift
  85 // create an instance and retain it
  86 oauthswift = OAuth1Swift(
  87     consumerKey:    "********",
  88     consumerSecret: "********",
  89     requestTokenUrl: "https://api.twitter.com/oauth/request_token",
  90     authorizeUrl:    "https://api.twitter.com/oauth/authorize",
  91     accessTokenUrl:  "https://api.twitter.com/oauth/access_token"
  92 )
  93 // authorize
  94 let handle = oauthswift.authorize(
  95     withCallbackURL: URL(string: "oauth-swift://oauth-callback/twitter")!,
  96     success: { credential, response, parameters in
  97       print(credential.oauthToken)
  98       print(credential.oauthTokenSecret)
  99       print(parameters["user_id"])
 100       // Do your request
 101     },
 102     failure: { error in
 103       print(error.localizedDescription)
 104     }
 105 )
 106 ```
 107 ### OAuth1 without authorization
 108 No urls to specify here
 109 ```swift
 110 // create an instance and retain it
 111 oauthswift = OAuth1Swift(
 112     consumerKey:    "********",
 113     consumerSecret: "********"
 114 )
 115 // do your HTTP request without authorize
 116 oauthswift.client.get("https://api.example.com/foo/bar",
 117     success: { response in
 118         //....
 119     },
 120     failure: { error in
 121         //...
 122     }
 123 )
 124 ```
 125
 126 ### Authorize with OAuth2.0
 127 ```swift
 128 // create an instance and retain it
 129 oauthswift = OAuth2Swift(
 130     consumerKey:    "********",
 131     consumerSecret: "********",
 132     authorizeUrl:   "https://api.instagram.com/oauth/authorize",
 133     responseType:   "token"
 134 )
 135 let handle = oauthswift.authorize(
 136     withCallbackURL: URL(string: "oauth-swift://oauth-callback/instagram")!,
 137     scope: "likes+comments", state:"INSTAGRAM",
 138     success: { credential, response, parameters in
 139       print(credential.oauthToken)
 140       // Do your request
 141     },
 142     failure: { error in
 143       print(error.localizedDescription)
 144     }
 145 )
 146
 147 ```
 148
 149 See demo for more examples
 150
 151 ### Handle authorize URL
 152 The authorize URL allows the user to connect to a provider and give access to your application.
 153
 154 By default this URL is opened into the external web browser (ie. safari), but apple does not allow it for app-store iOS applications.
 155
 156 To change this behavior you must set an `OAuthSwiftURLHandlerType`, simple protocol to handle an `URL`
 157 ```swift
 158 oauthswift.authorizeURLHandler = ..
 159 ```
 160 For instance you can embed a web view into your application by providing a controller that displays a web view (`UIWebView`, `WKWebView`).
 161 Then this controller must implement `OAuthSwiftURLHandlerType` to load the URL into the web view
 162 ```swift
 163 func handle(_ url: NSURL) {
 164   let req = URLRequest(URL: targetURL)
 165   self.webView.loadRequest(req)
 166   ...
 167 ```
 168 and present the view (`present(viewController`, `performSegue(withIdentifier: `, ...)
 169 *You can extend `OAuthWebViewController` for a default implementation of view presentation and dismiss*
 170
 171 #### Use the SFSafariViewController (iOS9)
 172 A default implementation of `OAuthSwiftURLHandlerType` is provided using the `SFSafariViewController`, with automatic view dismiss.
 173 ```swift
 174 oauthswift.authorizeURLHandler = SafariURLHandler(viewController: self, oauthSwift: oauthswift)
 175 ```
 176 Of course you can create your own class or customize the controller by setting the variable `SafariURLHandler#factory`.
 177
 178 ### Make signed request
 179
 180 Just call HTTP functions of `oauthswift.client`
 181
 182 ```swift
 183 oauthswift.client.get("https://api.linkedin.com/v1/people/~",
 184       success: { response in
 185         let dataString = response.string
 186         print(dataString)
 187       },
 188       failure: { error in
 189         print(error)
 190       }
 191 )
 192 // same with request method
 193 oauthswift.client.request("https://api.linkedin.com/v1/people/~", .GET,
 194       parameters: [:], headers: [:],
 195       success: { ...
 196 ```
 197
 198 See more examples in the demo application: [ViewController.swift](/Demo/Common/ViewController.swift)
 199
 200 ## OAuth provider pages
 201
 202 * [Twitter](https://dev.twitter.com/oauth)
 203 * [Flickr](https://www.flickr.com/services/api/auth.oauth.html)
 204 * [Github](https://developer.github.com/v3/oauth/)
 205 * [Instagram](http://instagram.com/developer/authentication)
 206 * [Foursquare](https://developer.foursquare.com/overview/auth)
 207 * [Fitbit](https://dev.fitbit.com/build/reference/web-api/oauth2/)
 208 * [Withings](http://oauth.withings.com/api)
 209 * [Linkedin](https://developer.linkedin.com/docs/oauth2)
 210 * [Dropbox](https://www.dropbox.com/developers/core/docs)
 211 * [Dribbble](http://developer.dribbble.com/v1/oauth/)
 212 * [Salesforce](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/)
 213 * [BitBucket](https://confluence.atlassian.com/bitbucket/oauth-on-bitbucket-cloud-238027431.html)
 214 * [GoogleDrive](https://developers.google.com/drive/v2/reference/)
 215 * [Smugmug](https://smugmug.atlassian.net/wiki/display/API/OAuth)
 216 * [Intuit](https://developer.intuit.com/docs/0100_accounting/0060_authentication_and_authorization/oauth_management_api)
 217 * [Zaim](https://dev.zaim.net/home/api/authorize)
 218 * [Tumblr](https://www.tumblr.com/docs/en/api/v2#auth)
 219 * [Slack](https://api.slack.com/docs/oauth)
 220 * [Uber](https://developer.uber.com/docs/ride-requests/guides/authentication/introduction#oauth-20)
 221 * [Gitter](https://developer.gitter.im/docs/authentication)
 222 * [Facebook](https://developers.facebook.com/docs/facebook-login)
 223 * [Spotify](https://developer.spotify.com/web-api/authorization-guide/)
 224 * [Trello](https://developers.trello.com/authorize)
 225 * [Buffer](https://buffer.com/developers/api/oauth)
 226 * [Goodreads](https://www.goodreads.com/api/documentation#oauth)
 227 * [Typetalk](http://developer.nulab-inc.com/docs/typetalk/auth)
 228 * [SoundCloud](https://developers.soundcloud.com/docs/api/guide#authentication)
 229 * [Doper](https://doper.io/developer/oauth)
 230 * [NounProject](http://api.thenounproject.com/getting_started.html#authentication)
 231
 232 ## Images
 233
 234 ![Image](Assets/Services.png "Image")
 235 ![Image](Assets/TwitterOAuth.png "Image")
 236 ![Image](Assets/TwitterOAuthTokens.png "Image")
 237
 238 ## Contributing
 239  See [CONTRIBUTING.md](.github/CONTRIBUTING.md)
 240
 241 [Add a new service in demo app](https://github.com/OAuthSwift/OAuthSwift/wiki/Demo-application#add-a-new-service-in-demo-app)
 242
 243
 244 ## Integration
 245 OAuthSwift could be used with others frameworks
 246
 247 You can sign [Alamofire](https://github.com/Alamofire/Alamofire) request with [OAuthSwiftAlamofire](https://github.com/OAuthSwift/OAuthSwiftAlamofire)
 248
 249 To achieve great asynchronous code you can use one of these integration frameworks
 250 - [OAuthSwiftFutures](https://github.com/OAuthSwift/OAuthSwiftFutures) - [BrightFutures](https://github.com/Thomvis/BrightFutures)
 251 - [OAuthRxSwift](https://github.com/OAuthSwift/OAuthRxSwift) - [RxSwift](https://github.com/ReactiveX/RxSwift)
 252 - [OAuthReactiveSwift](https://github.com/OAuthSwift/OAuthReactiveSwift) - [ReactiveSwift](https://github.com/ReactiveCocoa/ReactiveSwift)
 253
 254 ## License
 255
 256 OAuthSwift is available under the MIT license. See the LICENSE file for more info.
 257
 258 [![License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat
 259             )](http://mit-license.org) [![Platform](https://img.shields.io/badge/platform-iOS_OSX_TVOS-lightgrey.svg?style=flat
 260              )](https://developer.apple.com/resources/) [![Language](https://img.shields.io/badge/language-swift-orange.svg?style=flat
 261              )](https://developer.apple.com/swift) [![Cocoapod](https://img.shields.io/cocoapods/v/OAuthSwift.svg?style=flat)](http://cocoadocs.org/docsets/OAuthSwift/)
 262 [![Carthage compatible](https://img.shields.io/badge/Carthage-compatible-4BC51D.svg?style=flat)](https://github.com/Carthage/Carthage)