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 [email protected].
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.
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:
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 list
If 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.
Set defaultPostLoginState to your default state after login.
-
Insert the Login and Registration Forms
You can use the
sp-login-formandsp-registration-formdirectives 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>
These forms will read their configuration from the Client API and allow you to login or register for your application. You should now be able to use these forms to login to your application.<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.
For all available directives and services, see the API Documentation.
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.
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')
]);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 [email protected]
- Open a Github Issue on this repository.
- Join us on our Slack channel: https://talkstormpath.shipit.xyz/
Found something you want to change? Please see the Contribution Guide, we love your input!
Apache 2.0, see LICENSE.