OAuth2 for iOS

OpenAuth is a light framework for iOS written in swift 4. It provides an easy way to integrate OAuth2.0 in your iOS apps.

Installation

Installation with CocoaPods

We recommend using CocoaPods which automates and simplifies the process of using 3rd-party libraries like OpenAuth in your projects. You can install it with the following command:

$ gem install cocoapods

Podfile

To integrate OpenAuth into your Xcode project using CocoaPods, specify it in your Podfile:

pod 'OpenAuth'

Then, run the following command:

$ pod install

Manual installation

Skip this section if you used CocoaPods to link OpenAuth to your project.

• Download the SDK located under OpenAuth/OpenAuth.framework
• Add OpenAuth.framework file to your project and add it to Embedded Binaries.

Congratulations, the framework is fully integrated to the app and you can start using it.

Supported grant flows

OpenAuth uses generic types for GrantType, OpenAuth is an authorization manager that implements the Code Grant flow. The following is the list of all implemented flows:

At this point, once you pick the Grant Flow your app will implement, all requests to OpenAuth should be specified using a Grant Type flow. You can declare a typealias on top of OpenAuth specifying the Grant flow you want to use. For the rest of documentation, we will use the Code Grant Flow:

	typealias Auth = OpenAuth<CodeGrant>

Enable the logger

Optionally, you can enable to the logger. Use the following code to set a logging level to the logger:

	Auth.logger.level = .verbose

You can choose one of the following logging levels:

• verbose
• info
• warning
• error
• none

Add your OAuth2 configuration

Info.plist file

OpenAuth loads automatically your OAuth2 configuration from your app Info.plist file. Add a new row in Info.plist. Name it OpenAuthConfiguration and set its type to Dictionary. The following is a description of all configurations you can put in the created dictionary

Note

For KEYCHAIN_ACCESS_MODE, possible values are:

• kSecAttrAccessibleWhenUnlocked: Item data can only be accessed while the device is unlocked. This is recommended for items that only need be accesible while the application is in the foreground. Items with this attribute will migrate to a new device when using encrypted backups.
• kSecAttrAccessibleAfterFirstUnlock: Item data can only be accessed once the device has been unlocked after a restart. This is recommended for items that need to be accesible by background applications. Items with this attribute will migrate to a new device when using encrypted backups.
• kSecAttrAccessibleAlways: Item data can always be accessed regardless of the lock state of the device. This is not recommended for anything except system use. Items with this attribute will migrate to a new device when using encrypted backups.
• kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly: Item data can only be accessed while the device is unlocked. This is recommended for items that only need to be accessible while the application is in the foreground and requires a passcode to be set on the device. Items with this attribute will never migrate to a new device, so after a backup is restored to a new device, these items will be missing. This attribute will not be available on devices without a passcode. Disabling the device passcode will cause all previously protected items to be deleted.
• kSecAttrAccessibleWhenUnlockedThisDeviceOnly: Item data can only be accessed while the device is unlocked. This is recommended for items that only need be accesible while the application is in the foreground. Items with this attribute will never migrate to a new device, so after a backup is restored to a new device, these items will be missing.
• kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly: Item data can only be accessed once the device has been unlocked after a restart. This is recommended for items that need to be accessible by background applications. Items with this attribute will never migrate to a new device, so after a backup is restored to a new device these items will be missing.
• kSecAttrAccessibleAlwaysThisDeviceOnly: Item data can always be accessed regardless of the lock state of the device. This option is not recommended for anything except system use. Items with this attribute will never migrate to a new device, so after a backup is restored to a new device, these items will be missing.

Minimal Viable Configuration

You can download here a plist file with the minimum required configuration or copy the XML in your Project Info.plist resource

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
	<dict>
	<key>OpenAuthConfiguration</key>
	<dict>
    	<key>CLIENT_ID</key>
		<string></string>
		<key>AUTHORIZE_URI</key>
		<string></string>
		<key>TOKEN_URI</key>
		<string></string>
		<key>REDIRECT_URIS</key>
		<array>
			<string></string>
		</array>
	</dict>
	</dict>
</plist>

Full Configuration

You can download here a plist file with all available keys for an advanced configuration or copy the XML in your Project Info.plist resource

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
	<dict>
	<key>OpenAuthConfiguration</key>
	<dict>
		<key>CLIENT_ID</key>
		<string></string>
		<key>AUTHORIZE_URI</key>
		<string></string>
		<key>TOKEN_URI</key>
		<string></string>
		<key>REDIRECT_URIS</key>
		<array>
			<string></string>
		</array>
		<key>CLIENT_SECRET</key>
		<string></string>
		<key>CLIENT_NAME</key>
		<string></string>
		<key>LOGO_URI</key>
		<string></string>
		<key>REGISTRATION_URI</key>
		<string></string>
		<key>SCOPE</key>
		<string></string>
		<key>SECRET_IN_BODY</key>
		<false/>
		<key>HEADERS</key>
		<dict/>
		<key>PARAMETERS</key>
		<dict/>
		<key>TOKEN_ASSUME_UNEXPIRED</key>
		<true/>
		<key>ENABLE_KEYCHAIN</key>
		<false/>
		<key>TOKENS_KEYCHAIN_ACCOUNT</key>
		<string></string>
		<key>CLIENT_KEYCHAIN_ACCOUNT</key>
		<string></string>
		<key>KEYCHAIN_ACCESS_MODE</key>
		<string>kSecAttrAccessibleWhenUnlocked</string>
		<key>KEYCHAIN_ACCESS_GROUP</key>
		<string></string>
	</dict>
	</dict>
</plist>

Handle Redirect URL

On your AppDelegate.swift file, import OpenAuth and implement the following method

	
	func application(_ app: UIApplication, open url: URL, options: [UIApplicationOpenURLOptionsKey : Any] = [:]) -> Bool {
		Auth.shared.handleRedirect(url: url)
		return true
	}

Acquire the token

To acquire the access token, import OpenAuth in your code and call the following function

	Auth.acquireToken(success: { (token: String) in
            //Use your token here
        }) { (error: Error) in
            //Handle error here
        }

To force OpenAuth to display a safari view controller embedded in your app, set the embedded Boolean attribute to true and provide a context from which OpenAuth will display the safari controller. The context can be the current view controller, a navigation view controller or any other view controller based objects

	Auth.acquireToken(authorizeContext: context, embedded: true, success: { (token: String) in
           //Use your token here
        }) { (error: Error) in
           //Handle error here
        }

Optionally, you can pass custom parameters to be added to the Authorize request:

	let params = ["key1": "value1",
                 "key2": "value2"]
        
   	Auth.acquireToken(success: { (token: String) in
            //use your token here
        }, failure: { (error: Error) in
            //handle error here
        }, params: params,
           embedded: false,
           authorizeContext: nil)

Logout

To logout, use the logout function as indicated in the following snippet code. OpenAuth will forget all tokens and remove any stored cookies related to its flows.

	Auth.logout()

Credit

All credits go to Pascal Pfiffner. Most of the SDK is inspired by p2.OAuth2 swift librairy.

License

OpenAuth is released under an Apache 2.0 license. See LICENSE for more details.