Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/rsattar/Voucher
A simple library to make authenticating tvOS apps easy via their iOS counterparts.
https://github.com/rsattar/Voucher
Last synced: 17 days ago
JSON representation
A simple library to make authenticating tvOS apps easy via their iOS counterparts.
- Host: GitHub
- URL: https://github.com/rsattar/Voucher
- Owner: rsattar
- License: mit
- Created: 2015-11-08T05:57:24.000Z (about 9 years ago)
- Default Branch: master
- Last Pushed: 2017-03-05T23:35:05.000Z (over 7 years ago)
- Last Synced: 2024-09-15T23:02:17.102Z (about 2 months ago)
- Language: Objective-C
- Size: 84 KB
- Stars: 516
- Watchers: 18
- Forks: 34
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Voucher
The new Apple TV is amazing but the keyboard input leaves a lot to be desired. Instead of making your users type credentials into their TV, you can use Voucher to let them easily sign into the TV app using your iOS app.
### How Does It Work?
Voucher uses [Bonjour](https://developer.apple.com/bonjour/), which is a technology to discover other devices on your network, and what they can do. When active, Voucher on tvOS starts looking in your local network and over [AWDL (Apple Wireless Direct Link)](http://stackoverflow.com/questions/19587701/what-is-awdl-apple-wireless-direct-link-and-how-does-it-work) for any Voucher Server, on iOS.
Once it finds a Voucher Server, it asks it for authentication. Here's the demo app:
The demo iOS app can then show a notification to the user (you can show whatever UI you want, or even no UI):
If the user accepts, then the iOS app can send some authentication data back to the tvOS app (in this case, an auth token string)
## Installation
Voucher is available through [Carthage](https://github.com/Carthage/Carthage) and [CocoaPods](https://cocoapods.org). You can also manually install it, if that's your jam.
### Carthage
```
github "rsattar/Voucher"
```
### CocoaPods
```
pod 'Voucher'
```
### Manual
- Clone the repo to your computer
- Copy only the source files in `Voucher` subfolder over to your project
## Using Voucher
In your tvOS app, when the user wants to authenticate, you should create a `VoucherClient` instance and start it:
### tvOS (Requesting Auth)
When the user triggers a "Login" button, your app should display some UI instructing them to open their iOS App to finish logging in, and then start the voucher client, like below:
```swift
import Voucher
func startVoucherClient() {
let uniqueId = "SomethingUnique";
self.voucher = VoucherClient(uniqueSharedId: uniqueId)
self.voucher.startSearchingWithCompletion { [unowned self] authData, displayName, error in
// (authData is of type NSData)
if authData != nil {
// User granted permission on iOS app!
self.authenticationSucceeded(authData!, from: displayName)
} else {
self.authenticationFailed()
}
}
}
```
### iOS (Providing Auth)
If your iOS app has auth credentials, it should start a Voucher Server, so it can answer any requests for a login. I'd recommend starting the server when (and if) the user is logged in.
```swift
import Voucher
func startVoucherServer() {
let uniqueId = "SomethingUnique"
self.server = VoucherServer(uniqueSharedId: uniqueId)
self.server.startAdvertisingWithRequestHandler { (displayName, responseHandler) -> Void in
let alertController = UIAlertController(title: "Allow Auth?", message: "Allow \"\(displayName)\" access to your login?", preferredStyle: .Alert)
alertController.addAction(UIAlertAction(title: "Not Now", style: .Cancel, handler: { action in
responseHandler(nil, nil)
}))
alertController.addAction(UIAlertAction(title: "Allow", style: .Default, handler: { action in
let authData = "THIS IS AN AUTH TOKEN".dataUsingEncoding(NSUTF8StringEncoding)!
responseHandler(authData, nil)
}))
self.presentViewController(alertController, animated: true, completion: nil)
}
}
```
## Recommendations
### Use tokens, not passwords
While you can send whatever data you like back to tvOS, you should you pass back an **OAuth** token, or better yet, generate some kind of a *single-use token* on your server and send that. [Cluster](https://cluster.co), for example, uses single-use tokens to do auto-login from web to iOS app. Check out this [Medium post](https://library.launchkit.io/how-ios-9-s-safari-view-controller-could-completely-change-your-app-s-onboarding-experience-2bcf2305137f?source=your-stories) that shows how I do it! The same model can apply for iOS to tvOS logins.
### Voucher can't be the only login option
In your login screen, you must still show the manual entry UI according to the [App Store Submission Guidelines](http://www.appstorereviewguidelineshistory.com/articles/2015-10-21-guidelines-updated-for-tvos-apps/) (Section 2.27). Add messaging that, in addition to the on screen form, the user can simply open the iOS app to login.
## Todo / Things I'd Love Your Help With!
* Encryption? Currently Voucher *does not* encrypt any data between the server and the client, so I suppose if someone wanted your credentials (See **Recommendations** section above), they could have a packet sniffer on your local network and access your credentials.
* Make Voucher Server work on `OS X`, and even `tvOS`! Would probably just need new framework targets, and additional test apps.
## Further Reading
Check out [Benny Wong](https://github.com/bdotdub)'s post on [why Apple TV sign in sucks](https://medium.com/@bdotdub/signing-into-apps-on-apple-tv-sucks-d36fd00e6712). He also has a [demo tvOS Authing project](https://github.com/bdotdub/TriplePlay), which you should check out!
## Requirements
* iOS 7.0 and above
* tvOS 9.0
* Xcode 8
## License
`Voucher` is available using an MIT license. See the LICENSE file for more info.
## I'd Love to Know If You're Using Voucher!
[Post to this Github "issue" I made to help us track who's using Voucher](https://github.com/rsattar/Voucher/issues/2) :+1: