stormpath-sdk-angularjs v2.0.1
#Stormpath is Joining Okta We are incredibly excited to announce that Stormpath is joining forces with Okta. Please visit the Migration FAQs for a detailed look at what this means for Stormpath users.
We're available to answer all questions at support@stormpath.com.
Stormpath AngularJS SDK
This module provides services and directives for AngularJS that will allow you to solve common user management tasks using Stormpath, such as login and signup.
Stormpath is a User Management API that reduces development time with instant-on, scalable user infrastructure. Stormpath's intuitive API and expert support make it easy for developers to authenticate, manage and secure users and roles in any application.
Getting Started
Follow these steps to add Stormpath user authentication to your AngularJS app.
Install or Download the Stormpath Angular SDK
If you are using Bower or NPM, you can install this module with the respective command:
npm install stormpath-sdk-angularjs --save
bower install stormpath-sdk-angularjs --save
If you are not using a package manager, you can download the latest source from our Github CDN by using these links:
- stormpath-sdk-angularjs.min.js
stormpath-sdk-angularjs.tpls.min.js
Then include them in your index.html file:
<script src="stormpath-sdk-angularjs.min.js"></script> <script src="stormpath-sdk-angularjs.tpls.min.js"></script>
Add the Module to Your App's Dependencies
Add the
stormpath
module and templates to your app's dependencies in app.js:var app = angular.module('myApp', [..., 'stormpath', 'stormpath.templates']);
Configure Stormpath
The Angular SDK leverages the Stormpath Client API for its authentication needs. Login to your Stormpath Tenant, and find your Client API domain (inside your application's policy section). Add your Client API domain as the
ENDPOINT_PREFIX
setting, via your.config()
function:angular.module('myApp', [..., 'stormpath', 'stormpath.templates']) .config(function (STORMPATH_CONFIG) { // Specify your Client API domain here: STORMPATH_CONFIG.ENDPOINT_PREFIX = 'https://{{clientApiDomainName}}'; });
You will need to tell Stormpath where your front-end application is running, by adding its domain to the list of Authorized Origin URIs on your Stormpath Application. This can be done from the Stormpath Admin Console. For example, if you are developing on a local sever that runs your front-end app at
http://localhost:3000
, you need to add that URI to the listIf this is not done, you will see the error
Origin 'http://localhost:3000' is therefore not allowed access.
in the browser error log.If you will be using social login, you will also need to add this URI to the list of Authorized Callback URIs, otherwise you will see the error
Specified redirect_uri is not in the application's configured authorized callback uri's.
when you attempt social login.
Configure Routing
In your app's
run()
block, configure the login state and the default state after login.For
ngRouter
:angular.module('myApp') .run(function($stormpath){ $stormpath.ngRouter({ forbiddenRoute: '/forbidden', defaultPostLoginRoute: '/home', loginRoute: '/login' }); });
For
uiRouter
:app.run(function($stormpath){ $stormpath.uiRouter({ loginState: 'login', defaultPostLoginState: 'home' }); });
Set
loginState
to your login state. If you don't have one, create one. SetdefaultPostLoginState
to your default state after login.
Insert the Login and Registration Forms
You can use the
sp-login-form
andsp-registration-form
directives to inject these default forms into your application, you should put this in the views/states where you want them to appear:<div sp-login-form></div>
<div sp-registration-form></div>
Add Login and Logout Links
Use the
sp-logout
directive to end the session:<a ui-sref="main" sp-logout>Logout</a>
For the login link, just point the user to your login state:
<a ui-sref="login">Login</a>
Hide Elements When Logged In
Use the
if-user
directive:<a ui-sref="main" sp-logout if-user>Logout</a>
Hide Elements When Logged Out
Use the
if-not-user
directive:<a ui-sref="login" if-not-user>Login</a>
Protect Your States
On all states that you want to protect, add:
sp: { authenticate: true }
For
ngRouter
:angular.module('myApp') .config(function ($routeProvider) { $routeProvider .when('/profile', { templateUrl: 'app/profile/profile.html', controller: 'ProfileCtrl', sp: { authenticate: true } }); });
For
uiRouter
:angular.module('myApp') .config(function ($stateProvider) { $stateProvider .state('profile', { url: '/profile', templateUrl: 'app/profile/profile.html', controller: 'ProfileCtrl', sp: { authenticate: true } }); });
Login!
That's it! You just added user authentication to your app with Stormpath. See the API Documentation for further information on how Stormpath can be used with your AngularJS app.
Looking for social login? Simply configure the directories in your Stormpath tenant, and the buttons will automatically appear in the login form. For more reading, please see the Social Login Product Guide.
Making Authenticated Requests
Once you are able to successfully authenticate (log in) from your application, you will want to authorize access to API endpoints on your server. The Angular SDK provides methods for getting the current authenticated access token, and using it to authenticate requests.
Imagine you have an API on your server, such as
http://localhost:3000/api/subscription
, and you want to authorize requests to this endpoint and know who the user is.If you want to manually construct a request, using the
$http
library, you can use our access token getter to add the access token to the request:StormpathOAuthToken.getAccessToken() .then(function(accessToken){ $http({ url: 'http://localhost:3000/api/subscription', method: 'GET', headers: { Authorization: 'Bearer ' + accessToken } }); }) .catch(function() { // No access token, the user is not logged in });
If you don't want to manually add the access token to every request, you can white-list URLs by expression and the Angular SDK will automatically add this token to all requests that have a matching URL:
angular.module('myApp', [..., 'stormpath', 'stormpath.templates']) .config(function (STORMPATH_CONFIG) { // Automatically add access token to all /api requests STORMPATH_CONFIG.AUTO_AUTHORIZED_URIS.push(new RegExp('/api')); });
Authorizing Requests Server-Side
Once your app has made the request with the access token, your server will need to read the token and make an authorization decision. We provide SDKs for your backend server that make this easy. Please follow one of the following links for a language-specific or framework-specific guide:
Java
Spring Boot developers should make use of our Spring Boot plugin, and see the Token Management Documentation.
.NET
ASP.NET developers can leverage our ASP.NET and ASP.NET Core libraries to achieve authorization in their applications, please see the Authorization section of each guide.
Node.js
Express developers can use our Express-Stormpath library to easily authenticate requests with access tokens and make authorization decisions, please see the Token Authentication documentation.
Node applications can generically use the Stormpath Node SDK to validate tokens, using the JwtAuthenticator.
PHP
Laravel developers can use our Stormpath-Laravel or Stormpath-Lumen libraries and their respective
stormpath.auth
middleware to authenticate requests, please see the User Data section of the documentation for each library.Other
Don't see your environment listed? Not a problem! Our access tokens are simple JWTs, that can be validated with most generic JWT validation libraries. Our product guide can walk you through the process, Validating an Access Token.
Need more assistance? Feel free to contact our support channel, details are below.
Documentation
For all available directives and services, see the API Documentation.
Example
See the example app in this repository for an example application that uses Yeoman as it's boilerplate.
For a simplified example that does not use a boilerplate system, please see this repository:
Stormpath Angular + Express Fullstack Sample Project
If you are hosting your API on a different domain than your Angular application, please see the CORS example app in this repository.
Browserify
This module can be used with Browserify. Please add the following lines to your
package.json
file:
"browser": {
"stormpath": "./node_modules/stormpath-sdk-angularjs/dist/stormpath-sdk-angularjs.js",
"stormpath.templates": "./node_modules/stormpath-sdk-angularjs/dist/stormpath-sdk-angularjs.tpls.js"
}
You should also install the package angular-ui-router
, as our library
currently depends on it.
Then in your application you can use require
to require our modules:
var app = angular.module('todoApp', [
require('angular-ui-router'),
require('stormpath'),
require('stormpath.templates')
]);
Support
We're here to help if you get stuck. There are several ways that you an get in touch with a member of our team:
- Send an email to support@stormpath.com
- Open a Github Issue on this repository.
- Join us on our Slack channel: https://talkstormpath.shipit.xyz/
Contributing
Found something you want to change? Please see the Contribution Guide, we love your input!
License
Apache 2.0, see LICENSE.