Auth0.iOS 1.3.0

Auth0.iOS 1.3.0

TestsTested
LangLanguage Obj-CObjective C
License MIT
ReleasedLast Release Dec 2014

Maintained by Hernan Zalazar.



 
Depends on:
libextobjc~> 0.4
CocoaLumberjack~> 1.9
ObjectiveSugar~> 1.1
 

Auth0.iOS 1.3.0

  • By
  • Martin Gontovnikas and Hernan Zalazar

Auth0 is an authentication broker that supports social identity providers as well as enterprise identity providers such as Active Directory, LDAP, Google Apps and Salesforce.

Key features

  • Integrates your iOS app with Auth0
  • Provides a beautiful native UI to log your users in
  • Provides support for Social Providers (Facebook, Twitter, etc.), Enterprise Providers (AD, LDAP, etc.) and Username & Password
  • Provides the ability to do SSO with 2 or more mobile apps similar to Facebook and Messenger apps.

iOS Gif

Requierements

iOS 7+. If you need to use our SDK in an earlier version please use our previous SDK pod Auth0Client or check the branch old-sdk of this repo.

Install

The Auth0.iOS pod is available through CocoaPods. To install it, simply add the following line to your Podfile:

pod "Auth0.iOS", "~> 1.3"

Then in your project's Info.plist file add the following entries:

  • Auth0ClientId: YOUR_AUTH0_APP_CLIENT_ID
  • Auth0Tenant: YOUR_AUTH0_TENANT_NAME

For example:

Auth0 plist

Usage

You can use Auth0.iOS with our native widget to handle authentication for you. It fetches your Auth0 app configuration and configures itself accordingly.

To get started, import this file in your AppDelegate.m file.

#import <Auth0.iOS/Auth0.h>

And add the following methods:

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  A0TwitterAuthenticator *twitter = [A0TwitterAuthenticator newAuthenticationWithKey:@"???" andSecret:@"????"];
  A0FacebookAuthenticator *facebook = [A0FacebookAuthenticator newAuthenticationWithDefaultPermissions];
  [[A0IdentityProviderAuthenticator sharedInstance] registerSocialAuthenticatorProviders:@[twitter, facebook]];
  return YES;
}

- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation {
    return [[A0IdentityProviderAuthenticator sharedInstance] handleURL:url sourceApplication:sourceApplication];
}

For more information on how to configure Facebook & Twitter go to Identity Provider Authentication

Import the following header files in the class where you want to display our native widget:

#import <Auth0.iOS/Auth0.h>
#import <libextobjc/EXTScope.h>

And to present our widget as a modal view controller:

A0AuthenticationViewController *controller = [[A0AuthenticationViewController alloc] init];
@weakify(self);
controller.onAuthenticationBlock = ^(A0UserProfile *profile, A0Token *token) {
    @strongify(self);
    // Do something with token & profile. e.g.: save them.
    // Auth0.iOS will not save the Token and the profile for you. Please read below
    // And dismiss the ViewController
    [self dismissViewControllerAnimated:YES completion:nil];
};
[self presentViewController:controller animated:YES completion:nil];

If you need to save and refresh the user's JWT token, please read the following guide in our Wiki.

Also you can check our Swift and Objective-C example apps. For more information on how to use Auth0.iOS with Swift please check this guide

Identity Provider Authentication

Before using authentication from other identity providers, e.g. Twitter or Facebook, you'll need to follow some steps.

First in your AppDelegate.m, add the following method:

- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation {
    return [[A0SocialAuthenticator sharedInstance] handleURL:url sourceApplication:sourceApplication];
}

This will allow Auth0.iOS to handle a successful login from Facebook, Twitter and any other Identity Providers. And finally you need to define a new URL Type for Auth0 that has a Custom Scheme with the following format: a0${AUTH0_CLIENT_ID}, you can do it in your app's target inside Xcode (Under the Info section) or directly in your application's info plist file. This custom scheme is used by Auth0.iOS to handle all authentication that requires the use a web browser (Safari or UIWebView).

By default Auth0.iOS includes Twitter & Facebook integration (and its dependencies) but you can discard what you don't need . If you only want Facebook auth just add this to your Podfile:

pod "Auth0.iOS/Core"
pod "Auth0.iOS/Facebook"
pod "Auth0.iOS/UI"

Facebook

Auth0.iOS uses Facebook iOS SDK to obtain user's access token so you'll need to configure it using your Facebook App info:

First, add the following entries to the Info.plist:

  • FacebookAppId: YOUR_FACEBOOK_APP_ID
  • FacebookDisplayName: YOUR_FACEBOOK_DISPLAY_NAME

Register a custom URL Type with the format fb<FacebookAppId>. For more information please check Facebook Getting Started Guide.

Here's an example of how the entries should look like:

FB plist

Finally, you need to register Auth0 Facebook Provider somewhere in your application. You can do that in the AppDelegate.m file, for example:

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  A0FacebookAuthenticator *facebook = [A0FacebookAuthenticator newAuthenticationWithDefaultPermissions];
  [[A0SocialAuthenticator sharedInstance] registerSocialAuthenticatorProvider:facebook];
}

Twitter

Twitter authentication is done using Reverse Auth in order to obtain a valid access_token that can be sent to Auth0 Server and validate the user. By default we use iOS Twitter Integration but we support OAuth Web Flow (with Safari) as a fallback mechanism in case a user has no accounts configured in his/her Apple Device.

To support Twitter authentication you need to configure the Twitter authentication provider:

NSString *twitterApiKey = ... //Remember to obfuscate your api key
NSString *twitterApiSecret = ... //Remember to obfuscate your api secret
A0TwitterAuthenticator *twitter = [A0TwitterAuthenticator newAuthenticationWithKey:twitterApiKey                                                                            andSecret:twitterApiSecret];
[[A0SocialAuthenticator sharedInstance] registerSocialAuthenticatorProvider:twitter];

We need your twitter app's key & secret in order to sign the reverse auth request. For more info please read the Twitter documentation related to Authorizing Requests and Reverse Auth.

SSO

A very cool thing you can do with Auth0.iOS is use SSO. Imagine you want to create 2 apps. However, you want that if the user is logged in in app A, he will be already logged in in app B as well. Something similar to what happens with Messenger and Facebook as well as Foursquare and Swarm.

Read this guide to learn how to accomplish this with this library.

API

A0AuthenticationViewController

A0AuthenticationViewController#init

- (instancetype)init;

Initialise 'A0AuthenticationViewController' using Auth0ClientId & Auth0Tenant from info plist file.

A0AuthenticationViewController *controller = [[A0AuthenticationViewController alloc] init];

A0AuthenticationViewController#onAuthenticationBlock

@property (copy, nonatomic) void(^onAuthenticationBlock)(A0UserProfile *profile, A0Token *token);

Block that is called on successful authentication. It has two parameters profile and token, which will be non-nil unless login is disabled after signup.

controller.onAuthenticationBlock = ^(A0UserProfile *profile, A0Token *token) {
  NSLog(@"Auth successful: profile %@, token %@", profile, token);
};

A0AuthenticationViewController#onUserDismissBlock

@property (copy, nonatomic) void(^onUserDismissBlock)();

Block that is called on when the user dismisses the Login screen. Only when closable property is YES.

controller.onUserDismissBlock = ^() {
  NSLog(@"User dismissed login screen.");
};

A0AuthenticationViewController#usesEmail

@property (assign, nonatomic) BOOL usesEmail;

Enable the username to be treated as an email (and validated as one too) in all Auth0 screens. Default is YES

controller.usesEmail = NO;

A0AuthenticationViewController#closable

@property (assign, nonatomic) BOOL closable;

Allows the A0AuthenticationViewController to be dismissed by adding a button. Default is NO

controller.closable = YES;

A0AuthenticationViewController#loginAfterSignup

@property (assign, nonatomic) BOOL loginAfterSignUp;

After a successful Signup, A0AuthenticationViewController will attempt to login the user if this property is YES otherwise will call onAuthenticationBlock with both parameters nil. Default value is YES

controller.loginAfterSignup = NO;

A0AuthenticationViewController#authenticationParameters

@property (assign, nonatomic) A0AuthParameters *authenticationParameters;

List of optional parameters that will be used for every authentication request with Auth0 API. By default it only has 'openid' and 'offline_access' scope values. For more information check out our Wiki

controller.authenticationParameters.scopes = @[A0ScopeOfflineAccess, A0ScopeProfile];

A0AuthenticationViewController#signupDisclaimerView

@property (strong, nonatomic) UIView *signUpDisclaimerView;

View that will appear in the bottom of Signup screen. It should be used to show Terms & Conditions of your app.

UIView *view = //..
controller.signupDisclaimerView = view;

A0AuthenticationViewController#useWebView

@property (assign, nonatomic) BOOL useWebView;

When the authentication requires to open a web login, for example Linkedin, it will use an embedded UIWebView instead of Safari if it's YES. We recommend using Safari for Authentication since it will always save the User session. This means that if he's already signed in, for example in Linkedin, and he clicks in the Linkedin button, it will just work. Default values is NO

controller.useWebView = YES

Logging

Auth0.iOS logs serveral useful debugging information using CocoaLumberjack. By default all log messages are disabled but you can enable them following these steps:

Go to A0Logging.h and change the auth0LogLevel variable with the Log Level you'll want to see. for example:

static const int auth0LogLevel = LOG_LEVEL_ALL;

And then you'll need to configure CocoaLumberjack (if you haven't done it for your app). You need to do it once so we recommend doing it in your AppDelegate:

#import <CocoaLumberjack/DDASLLogger.h>
#import <CocoaLumberjack/DDTTYLogger.h>
#import <CocoaLumberjack/DDLog.h>

@implementation A0AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [DDLog addLogger:[DDASLLogger sharedInstance]];
    [DDLog addLogger:[DDTTYLogger sharedInstance]];
    return YES;
}

@end

What is Auth0?

Auth0 helps you to:

  • Add authentication with multiple authentication sources, either social like Google, Facebook, Microsoft Account, LinkedIn, GitHub, Twitter, Box, Salesforce, amont others, or enterprise identity systems like Windows Azure AD, Google Apps, Active Directory, ADFS or any SAML Identity Provider.
  • Add authentication through more traditional username/password databases.
  • Add support for linking different user accounts with the same user.
  • Support for generating signed Json Web Tokens to call your APIs and flow the user identity securely.
  • Analytics of how, when and where users are logging in.
  • Pull data from other sources and add it to the user profile, through JavaScript rules.

Create a free account in Auth0

  1. Go to Auth0 and click Sign Up.
  2. Use Google, GitHub or Microsoft Account to login.

Author

Auth0

License

Auth0.iOS is available under the MIT license. See the LICENSE file for more info.