Ionic Auth has been deprecated. As of January 31, 2018, we will no longer provide the Ionic Auth user authentication service.

Auth

Summary

User authentication is an essential component of most apps. It allows you to identify your users and provide a unique experience for them.

We take care of the hard stuff for you:

Authentication Providers

Logging in/out, managing user data, and other API features for auth are handled by authentication providers. The setup and usage may vary per provider.

See the setup instructions for each provider below.

Provider Setup & Usage
Email/Password (see below for usage)
Custom In-App Browser
Facebook Native Login (preferred) / In-App Browser
Google Native Login (preferred) / In-App Browser
Twitter In-App Browser
Instagram In-App Browser
LinkedIn In-App Browser
Github In-App Browser

Email/Password Authentication

Email/Password authentication is the easiest and most common. If you’d like to offer other authentication methods, see Authentication Providers above.

Setup

Import Auth and User from the Cloud Client and specify them as dependencies in your component constructor.

  • auth is a service that deals with registration and logging in/out.
  • user is a reference to the current user, whether that user is anonymous or authenticated.
import { Component } from [email protected]/core';
import { Auth, User } from [email protected]/cloud-angular';

@Component( ... )
export class LoginPage {
  constructor(public auth: Auth, public user: User) {
    ...
  }
}

In TypeScript, specifying public before constructor arguments creates what are called parameter properties, which let you create and initialize a class property of the same name as the constructor argument.

This means you can reference the Auth and User services as this.auth and this.user in your class.

Specify ionic.cloud as a dependency for your module. This gives you access to $ionicAuth and $ionicUser.

  • $ionicAuth is a service that deals with registration and logging in/out.
  • $ionicUser is a reference to the current user, whether that user is anonymous or authenticated.
angular.module('myapp.controllers', ['ionic.cloud'])

.controller('MyCtrl', function($scope, $ionicAuth, $ionicUser) {
  ...
})

Signup

For email/password authentication, you’ll need to sign up your users in your app. Email and password are required, but a few other fields are also allowed during registration.

import { Auth, User, UserDetails, IDetailedError } from [email protected]/cloud-angular';

Once the user is signed up, this.user is updated.

let details: UserDetails = {'email': [email protected]', 'password': 'puppies123'};

this.auth.signup(details).then(() => {
  // `this.user` is now registered
}, (err: IDetailedError<string[]>) => {
  for (let e of err.details) {
    if (e === 'conflict_email') {
      alert('Email already exists.');
    } else {
      // handle other errors
    }
  }
});
var details = {'email': [email protected]', 'password': 'puppies123'};

$ionicAuth.signup(details).then(function() {
  // `$ionicUser` is now registered
}, function(err) {
  for (var e of err.details) {
    if (e === 'conflict_email') {
      alert('Email already exists.');
    } else {
      // handle other errors
    }
  }
});

Signup Errors

In the case of signup errors, you can access the use err.details, which in this case is an array of strings which will contain one or more of the following error codes:

Error Code Description
required_email Missing email field
required_password Missing password field
conflict_email A user has already signed up with the supplied email
conflict_username A user has already signed up with the supplied username
invalid_email The email did not pass validation.

Login

In addition to setting basic as the Provider ID, an object with email and password details is required.

let details = {'email': [email protected]', 'password': 'puppies123'};

this.auth.login('basic', details).then( ... );
var details = {'email': [email protected]', 'password': 'puppies123'};

$ionicAuth.login('basic', details).then( ... );

Logout

Logging out clears the current user context.

this.auth.logout();
$ionicAuth.logout();

Password Reset

Your user may need to reset their password if it is lost or forgotten. Resetting a user’s password can be achieved in two ways:

  1. Build the password reset forms and logic in your app and use the client to request and confirm password resets.

    or

  2. Use our hosted password reset forms and direct the user to them to kick off the password resets.

Using the Client

this.auth.requestPasswordReset(email);
$ionicAuth.requestPasswordReset(email);
this.auth.confirmPasswordReset(resetCode, newPassword);
$ionicAuth.confirmPasswordReset(resetCode, newPassword);

Using our Forms

If you don’t want to build your own password reset forms, you can alternatively use ours.

Auth Status

Check if the active user is currently authenticated by calling isAuthenticated():

if (this.auth.isAuthenticated()) {
  // this.user is authenticated!
}
if ($ionicAuth.isAuthenticated()) {
  // $ionicUser is authenticated!
}

User Data

Storing Data

Having the ability to store user data opens up new possiblities for your app. For example, by simply storing the birthdate of your users, you have the ability to send out birthday messages or discounts to your users.

Storing

Write or overwrite data using set():

this.user.set('birthdate', '5/17/1985');
$ionicUser.set('birthdate', '5/17/1985');

You can store strings, numbers, booleans, arrays, and objects.

Retrieving

Read data using get():

this.user.get('birthdate'); // get value of 'birthdate' or null
$ionicUser.get('birthdate'); // get value of 'birthdate' or null

You can also return a default value if no data has been stored:

this.user.get('invites_remaining', 5); // get value of 'invites_remaining' or 5
$ionicUser.get('invites_remaining', 5); // get value of 'invites_remaining' or 5

Removing Data

Delete data using unset():

this.user.unset('birthdate');
$ionicUser.unset('birthdate');

User Details

We store common user data in the details attribute. Unlike your custom data which uses get() and set(), details is just an object with the following properties.

username unique username
email unique email address
password write-only password
name first and last name
image url to identifying image

Examples

this.user.details.name = 'Ionitron';
this.user.details.image = 'https://pbs.twimg.com/profile_images/617058765167329280/9BkeDJlV.png';
this.user.details.password = 'test';
$ionicUser.details.name = 'Ionitron';
$ionicUser.details.image = 'https://pbs.twimg.com/profile_images/617058765167329280/9BkeDJlV.png';
$ionicUser.details.password = 'test';

Saving Changes

When a user is logged in, we issue a token for them that secures communication between their device and our servers, but only for their own data. That means the user will need to be logged in before user data and information can be retrieved or modified.

Save user modifications with save().

this.user.save();
$ionicUser.save();

Changes are local to the device until save() is called, which persists the user to our servers. Local data always overwrites server data.

Refreshing the User

If you make changes to a user via the API, the user on the device will need to be refreshed. Once a user is logged in, you can call load().

this.user.load().then(() => {
  // success!
});
$ionicUser.load().then(function() {
  // success!
});

FAQ

Can I login with a username instead of email?

We do not support authenticating with a username at this time.

How can I login immediately during signup?

If you want to sign up and login a user right away, you can simply call login() in the success callback of the signup promise.

let details: UserDetails = {
  'name': 'Bob',
  'email': [email protected]',
  'password': 'puppies123'
};

this.auth.signup(details).then(() => {
  return this.auth.login('basic', {'email': [email protected]', 'password': 'puppies123'});
});

If you want to sign up and login a user right away, you can simply call $ionicAuth.login() in the success callback of the signup promise.

var details = {
  'name': 'Bob',
  'email': [email protected]',
  'password': 'puppies123'
};

$ionicAuth.signup(details).then(function() {
  return $ionicAuth.login('basic', {'email': [email protected]', 'password': 'puppies123'});
});

Do you support custom OAuth providers?

No, we currently do not support custom OAuth.

How can I require users to login every time the app is opened?

By default, we keep users logged in. If you only want them to be logged in for the duration of the app being opened, you need to set remember: false in your login options.

this.auth.login('basic', details, {'remember': false});
$ionicAuth.login('basic', details, {'remember': false});

Services

    API

      General