Auth0 and AngularJS
Deprecation Notice
This SDK is for use with Lock v9. For use with Lock 10, see the angular-lock and angular-auth0 wrappers.
This AngularJS module will help you implement client-side and server-side (API) authentication. It can be used together with Auth0 to add support for username/password authentication, enterprise identity providers like Active Directory or SAML and also for social identity providers like Google, Facebook or Salesforce among others to your web, API and native mobile apps.
Auth0 is a cloud service that provides a turn-key solution for authentication, authorization and single sign-on.
Key Features
- User login & signup: This module lets you easily sign in and sign up your users with any Social Provider, Enterprise Provider or Username and password. You can use the UI supplied by Auth0 or create your own
- Authenticated API calls: JWTs are automatically added to every request made to your API after the user is authenticated
- Events/Promise based services:
auth0-angular
supports events and promised-based actions - Token management: Using
auth0-angular
together withangular-storage
andangular-jwt
can handle the complete token lifecycle, including storing, expiration and renewal.
Installation
Bower
bower install auth0-angular
NPM
npm install auth0-angular
CDN
Warning: If you use a CDN or download these scripts manually, be sure to include the versions of
auth0-lock
orauth0.js
that match the versions specified in thebower.json
.
TL;DR: Quick start guide
Add module dependency and configure it
angular ;
Displaying the signin popup and retrieving user information
// LoginCtrl.jsangular;
Showing user information
// UserInfo.jsangular;
<!-- userInfo.html -->{{profile.name}} {{profile.email}}
Keeping the user logged in, saving the token and using a refresh token.
There're many more things that you can do with auth0-angular
in conjunction with angular-storage and angular-jwt.
- Keeping the user logged in by saving their token and profile
- Sending a JWT in every request made to an API
- Using a refresh token after the user's JWT has expired
Getting Started Guide
Preface: Authentication Modes
There are three modes to handle authentication with all the providers (e.g. Facebook, Linkedin, GitHub, AD, LDAP) that Auth0 can handle: redirect, popup, and resource owner (/oauth/ro
) CORS calls.
When using redirect mode, the user will be redirected to the provider's login page for authentication. After authenticating, the user will be redirected back to the application with the requested user information in the hash fragment, which can be handled with Angular events. This implies that the application will be reloaded completely when the authentication flow is initiated.
Popup mode will open a popup window displaying the provider's login page. After authentication, the popup will close and return control to the application. The requested user information will be available through a callback function and will not reload the page.
Database connection users can be authenticated by making a CORS call to /oauth/ro
, passing a username and password.
Does not reload the page.
Dependencies
auth0-angular depends on either auth0.js
or auth0-lock.js
.
If you want to use Auth0's beautiful Lock UI, you need to include auth0-lock.js
. This lets you configure Title and Icons, but the UI is taken care for you. For all the customization properties, please check out this link
Otherwise, if you'll use a custom UI, you need to include auth0.js
.
It's important to note that these scripts must be included before auth0-angular.
If you're using bower
or npm
, these scripts are set as dependencies of auth0-angular so that you choose the best for you. Otherwise, you can include them from the CDN:
<!-- Either this --><!-- or -->
SDK API
Parameters between []
are optional.
auth.signin(options[, successCallback, errorCallback])
Logs in a user, returning tokens and their profile information.
Lock will be displayed if included, otherwise a login will be performed with the specified identity provider (connection
).
If success and error callback functions are supplied, popup mode will be used. This will not reload the page.
auth
A connection
parameter can be passed to log in a user without displaying Lock.
When using database connections, username
and password
can be passed as well.
The snippet below will perform a to a call to /oauth/ro
:
auth
Redirect mode will be used when not passing success or error callbacks. In this case, login success and failure are handled with events:
// app.jsmodule;
// LoginCtrl.jsauth;
The complete Lock API is documented here.
auth.signup(options[, successCallback, errorCallback])
Displays Lock in signup mode, and logs the user in immediately after a successful signup.
Accepts the same options and parameters as auth.signin
.
auth.reset(options[, successCallback, errorCallback])
Performs the "forgot your password" flow.
If using auth0.js
, it will send an email to confirm the password change. See the documentation here.
If using Lock, the widget will be displayed in "reset password" mode.
In this case, this method accepts the options and parameters as auth.signin
.
auth.signout()
This logs the user out locally by deleting their token from local storage.
auth.authenticate(profile, idToken[, accessToken, state, refreshToken])
Reauthenticates the user by using a stored profile and token without going through the login flow. You can read more about this subject in this article.
auth.profile
Once a user has successfully logged in, this property will contain their profile.
If you want to use information from auth.profile
only after the user is logged in, you can just do a $watch
on this property to wait until it's set.
auth.profilePromise
Same as auth.profile
, but as a promise.
If the user has not attempted a login yet, this will be null
.
auth.isAuthenticated
This flag returns whether there's a user authenticated or not.
auth.linkAccount(token, profile, options, successCallback, errCallback)
API to link multiple accounts to primary account
Note that options.connection
must be provided because it tells Auth0 which account to link to
auth.id_token, auth.access_token, auth.state
These properties contain the tokens returned after the user is logged in. Mostly for internal usage.
auth.hookEvents()
auth0-angular
hooks to internal Angular events so that a user will be redirected to the login page if trying to visit a restricted resource.
For that, you need to hook auth0-angular
to all of these events on application run.
First, configure the restricted routes:
// Using ngRoutemodule // Using ui-routermodule;
Then, call hookEvents
in the run
method:
module;
To learn more about routing and using ngRoute
or ui-router
, please read this tutorial.
auth.getToken(options)
This method does a token delegation request, which means exchanging the current token for another one.
There are two cases:
- Auth0 has several addons which let you obtain tokens for third-party services (e.g. Firebase or AWS) from an Auth0 token. For example, to obtain a Firebase token:
auth
- When using multiple Auth0 applications, a token for one application can be used to obtain a token for another application.
Tokens retrieved in this way will be issued by the target application (
iss
claim) and signed with its client secret. Returns a promise.
auth
To learn more about delegated access, please refer to the authorization API documentation.
auth.renewIdToken([id_token])
JSON Web Tokens have an expiration date, indicated by the exp
claim. If you don't want your user to log in again, the current token can be refreshed. Refreshing a token means using that token before it has expired in order to obtain a new one with a later expiration date.
For example, suppose you have a token valid for 10 hours. After 9 hours, you could refresh the token to get a new token which will be valid for another 10 hours.
The renewed token will be requested with the same scopes as the original token, by using a special passthrough
scope. To request different scopes, use getToken()
. Returns a promise.
auth.refreshIdToken([refresh_token])
Given an id_token
which might have expired, use the refresh_token
to get a renewed id_token
.
authProvider.init(options) || auth.init(options)
You use this method to configure the auth service. It can be used either from the provider in the config
method of your app, or anywhere else in the application from the auth
service by calling auth.init
. You can set the following options:
- domain: The domain you have from your Auth0 account.
- clientId: The identifier for the application you've created. This can be found in the settings for your app on Auth0.
- sso: If you have more than one application and you want Single Sign On on your apps, just set this to
true
. This will mean that if a user signs in to app 1, when he tries to use app 2, he will be already logged in. - loginUrl: Set this to the login url if you're using ngRoute.
- loginState: Set this to the login state if you're using ui-router.
authProvider.on(event, handler)
The following events can be handled:
- authenticated: The user was successfully authenticated by calling
auth.authenticate
. In the handler, you can inject any service you want. - loginSuccess: The user has successfully logged in . In the handler, you can inject any service you want besides the
profileProfile
andidToken
from the user. - loginFailure: There was an error trying to authenticate the user. In the handler, you can inject any service you want besides the
error
which was thrown. - logout: The user has successfully logged out.
- ssoLogin: An SSO login is happening.
- forbidden: An unauthorized request was made to an API, which returned an HTTP 401 response. This can mean that the user attempted to access a restricted resource, or that their token has expired.
When using redirect mode, it's mandatory to handle login events in this way.
In the case of popup mode, events can be handled this way or by using a promise on auth.signin
.
Tutorials & Examples
This is the list of all of the available tutorials & samples.
Using Auth0 Lock (no need to build a custom UI)
Using your own login UI
Integrating to routes (ui-router and ngRoute)
Token delegation
Signup with custom fields
Single sign-on (SSO)
Changelog
Check the CHANGELOG file to see the changes from version to version.
Contributing
Read here how to run auth0-angular tests
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, among 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
- Go to Auth0 and click Sign Up.
- Use Google, GitHub or Microsoft Account to login.
Issue Reporting
If you have found a bug or if you have a feature request, please report them at this repository issues section. Please do not report security vulnerabilities on the public GitHub issue tracker. The Responsible Disclosure Program details the procedure for disclosing security issues.
Author
License
This project is licensed under the MIT license. See the LICENSE file for more info.