Heimdall is an OAuth 2.0 client specifically designed for easy usage. It currently only supports the resource owner password credentials grant flow as well as refreshing an access token.
If you are familiar with ReactiveCocoa, also check out ReactiveHeimdall!
Before requesting an access token, the client must be configured appropriately:
let tokenURL = NSURL(string: "http://example.com/oauth/v2/token")!
let heimdall = Heimdall(tokenURL: tokenURL)On login, the resource owner's password credentials are used to request an access token:
heimdall.requestAccessToken(username: "johndoe", password: "A3ddj3w") { result in
switch result {
case .Success:
println("success")
case .Failure(let error):
println("failure: \(error.unbox.localizedDescription)")
}
}Heimdall automatically persists the access token. Afterwards, any NSURLRequest can be easily authenticated using the received access token:
var session: NSURLSession!
var request: NSURLRequest!
heimdall.authenticateRequest(request) { result
switch result {
case .Success(let request):
let task = session.dataTaskWithRequest(request.unbox) { data, response, error in
// ...
}
task.resume()
case .Failure(let error):
println("failure: \(error.unbox.localizedDescription)")
}
}Carthage is a simple, decentralized dependency manager for Cocoa. You can install it with Homebrew using the following commands:
$ brew update
$ brew install carthage
- Add Heimdall to your Cartfile:
github "rheinfabrik/Heimdall.swift" ~> 1.0
-
Run
carthage updateto actually fetch Heimdall and its dependencies. -
On your application target's "General" settings tab, in the "Linked Frameworks and Libraries" section, add the following frameworks from the Carthage/Build folder on disk:
Heimdall.framework
- On your application target's "Build Phases" settings tab, click the "+" icon and choose "New Run Script Phase". Create a Run Script with the following contents:
/usr/local/bin/carthage copy-frameworks
and add the paths to all relevant frameworks under "Input Files":
$(SRCROOT)/Carthage/Build/iOS/LlamaKit.framework
$(SRCROOT)/Carthage/Build/iOS/Runes.framework
$(SRCROOT)/Carthage/Build/iOS/Argo.framework
$(SRCROOT)/Carthage/Build/iOS/KeychainAccess.framework
$(SRCROOT)/Carthage/Build/iOS/Heimdall.framework
This script works around an App Store submission bug triggered by universal binaries.
The client credentials, consisting of the client's identifier and optionally its secret, are used for authenticating with the token endpoint:
var identifier: String!
var secret: String!
let credentials = OAuthClientCredentials(id: identifier)
// OAuthClientCredentials(id: identifier, secret: secret)Please note that native applications are considered to be public clients.
An access token store is used to (persistently) store an access token received from the token endpoint. It must implement the following storage and retrieval methods:
protocol OAuthAccessTokenStore {
func storeAccessToken(accessToken: OAuthAccessToken?)
func retrieveAccessToken() -> OAuthAccessToken?
}Heimdall ships with an already built-in persistent Keychain-based access token store, using KeychainAccess. The service is configurable:
var service: String!
let accessTokenStore = OAuthAccessTokenKeychainStore(service: service)An HTTP client that can be used by Heimdall for requesting access tokens. It must implement the following sendRequest method:
protocol HeimdallHTTPClient {
func sendRequest(request: NSURLRequest, completion: (data: NSData!, response: NSURLResponse!, error: NSError?) -> ())
}For convenience, a default HTTP client named HeimdallHTTPClientNSURLSession and based on NSURLSession is provided. It may be configured with an NSURLSession:
var urlSession: NSURLSession!
let httpClient = HeimdallHTTPClientNSURLSession(urlSession: session)Heimdall must be initialized with the token endpoint URL and can optionally be configured with client credentials, an access token store and an HTTP client:
var tokenURL: NSURL!
let heimdall = Heimdall(tokenURL: tokenURL)
// Heimdall(tokenURL: tokenURL, credentials: credentials)
// Heimdall(tokenURL: tokenURL, credentials: credentials, accessTokenStore: accessTokenStore)
// Heimdall(tokenURL: tokenURL, credentials: credentials, accessTokenStore: accessTokenStore, httpClient: httpClient)
// Heimdall(tokenURL: tokenURL, credentials: credentials, accessTokenStore: accessTokenStore, httpClient: httpClient, resourceRequestAuthenticator: resourceRequestAuthenticator)Whether the client's access token store currently holds an access token can be checked using the hasAccessToken property. It's not checked whether the stored access token, if any, has already expired.
The authorize method takes the resource owner's password credentials as parameters and uses them to request an access token from the token endpoint:
var username: String!
var password: String!
heimdall.requestAccessToken(username: username, password: password) { result in
// ...
}The completion closure may be invoked on any thread.
Once successfully authorized, any NSURLRequest can be easily altered to include authentication via the received access token:
var request: NSURLRequest!
heimdall.authenticateRequest(request) { result
// ...
}If the access token has already expired and a refresh token is available, Heimdall will automatically refresh the access token. Refreshing requires network I/O. The completion closure may be invoked on any thread.
By default, Heimdall authenticates a request by setting the HTTP header field Authorization. This behavior can be changed by passing another resource request authenticator implementing HeimdallResourceRequestAuthenticator to the initializer.
Heimdall was built by Rheinfabrik 🏭