aducret / wolmo-authentication-ios

Wolmo - Wolox Mobile SDK Authentication library for iOS

WolMo - Authentication iOS

Wolmo - Authentication iOS is an authentication framework for Swift, designed to take care of some basic steps present in almost every iOS app:

• Signup
• Login
• Login with Facebook and generic services
• Login with Google, Twitter and other services (in a future version)
• Recover password (in a future version)

It provides logic as well as default views with plenty extensibility points.

Table of Contents

• Installation
  • Carthage
  • Manually
• Bootstrap
• Dependencies
• Usage
  • How to initialize the AuthenticationCoordinator?
    • Session Service
    • Authentication Components Factory
  • Getting started
• Contributing
  • Reporting Issues
  • Creating a Pull Request
• About
• License
• Change Log

Installation

Carthage

Carthage is a dependency manager that builds your dependencies and provides you with binary frameworks that you can include in your project.

You can install Carthage with Homebrew using the following command:

brew update
brew install carthage

To download wolmo-authentication-iOS, add this to your Cartfile:

github "Wolox/wolmo-authentication-ios" ~> 0.1.0

Manually

Bootstrap the project and then drag it to your workspace.

Bootstrap

1. Clone the project.

With SSH:

git clone [e-mail]:Wolox/wolmo-authentication-ios.git

2. Run the bootstrap script that comes with it.

cd wolmo-authentication-ios
script/bootstrap

Dependencies

• WolmoCore: Framework with useful basic extensions.
• ReactiveSwift: Framework inspired by functional reactive programming.
• FacebookSDKSwift: Framework for authenticating with Facebook.

Usage

For more information about the framework's structure and concepts, see the Framework Overview.

There is an example application in this project called AuthenticationDemo in which the basic usage of the framework is shown.

To use anything the framework offers, after installing it you just need to add import Authentication to your code, as you would do with any other library.

The framework provides an AuthenticationCoordinator class that takes care of managing the authentication process and starting your app.

So in your AppDelegate.swift file you will need to

1. create the AuthenticationCoordinator
2. trigger its start method

and that's all !

This will start the authentication process or redirect to your app if there is no need to authenticate.

How to initialize the AuthenticationCoordinator?

The AuthenticationCoordinator needs four things to be initialized:

1. The UIWindow where the app will be shown.
2. Which authentication screen you want to be shown first (login or signup).
3. A session service with which the framework interacts for managing the user session.
4. A component factory that provides the components for the framework to work with.

Session Service

You must provide a session service that comforms to the SessionServiceType protocol, which basically stores the current user and provides functions for logging in and signing up with certain information (acquired by the framework from the final user).

Authentication Components Factory

There are many components that the framework will use, and you can configure many things about them. The AuthenticationComponentsFactoryType protocol ensures a factory method for each of this components.

Almost all of the components have a default implementation, except for a few that are intrinsic to your app:

• MainViewController: The UIViewController to show when the authentication is completed. This will be the entry point of your app.
• LoginViewConfiguration: Stores the logo and the color and font palettes to style the authentication login screen.
• SignupViewConfiguration: Stores the color and font palettes to style the authentication signup screen, but also the URL where to find your terms and services and the textfields you want to use for signup (email and password are mandatory but username and password confirmation are optional).

There is an AuthenticationComponentsFactory that provides a way to use all default implementations and easily configure these 3 required elements.

Getting started

With all we've learned, we can start playing with the framework just by including the following code in your AppDelegate class.

var authenticationCoordinator: AuthenticationCoordinator<MyUser, MySessionService>!

func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {
    let sessionService = MySessionService()
    let logo = UIImage(named: "logo")!
    let termsAndServices = NSURL(string: "https://www.hackingwithswift.com")!
    let componentsFactory = AuthenticationComponentsFactory(logo: logo, termsAndServicesURL: termsAndServices) { return MyMainViewController() }
    authenticationCoordinator = AuthenticationCoordinator(sessionService: sessionService, window: window!, componentsFactory: componentsFactory)
    authenticationCoordinator.start()
    return true
}

You should have declared appropriate MyUser, MySessionService and MyMainViewController.

You can see how this works in the basic Demo Application example this project includes.

Contributing

Anyone can contribute to this project by reporting issues or proposing solutions and enhancements through Pull Requests.

Reporting Issues

Issues may serve for reporting bugs, requesting features or discussing implemented features.

1. Search through existing issues to make sure you are not duplicating one.
2. Write an appropriate title (think of how you would search for something like that).
3. Write an appropriate comment that includes the following details:
   • Short summary
   • Piece of code causing the bug (if it's a bug report)
   • Context or problem identified that could be solved/improved (if it's a feature request or feature modification)
   • Expected result
   • Actual result

Creating a Pull Request

1. Fork this repository.
2. Bootstrap the forked repository (instead of Wolox/wolmo-core-ios.git, use your-user/wolmo-core-ios.git).
3. Create your feature branch (git checkout -b my-new-feature).
4. Commit your changes (git commit -am 'Add some feature').
5. Run tests (./script/test).
6. Push your branch (git push origin my-new-feature).
7. Create a new Pull Request with an appropriate description that includes the following details:
   • Short summary
   • Context or problem identified that is solved/improved
   • Expected result
   • Actual result

Change Log

You can check the file CHANGELOG.md for detailed information.

About

This project is maintained by Daniela Paula Riesgo and it is written by Wolox.

License

WolMo - Authentication iOS is available under the MIT license.

Copyright (c) [2016] Daniela Paula Riesgo: <[e-mail]>

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.