Migrating From Stormpath to Passport on IBM Bluemix

DZone 's Guide to

Migrating From Stormpath to Passport on IBM Bluemix

The Stormpath API will be shut down this August. Learn how to export your user data and migrate it to Passport on IBM Bluemix.

· Integration Zone ·
Free Resource

If you’re an IBM Bluemix customer and are currently using the Stormpath API for login or authorization, this information is particularly important for you. If you’re not a Stormpath client, it is still important for you to read and share with anyone using Stormpath.

Okta acquired Stormpath and announced that the Stormpath API will be shut down on August 17th at noon PST.

Image title

This means that Stormpath users must migrate, and they must do it soon.

Passport by Inversoft is a modern take on identity and user management that can be integrated into any platform. Unlike Stormpath, Inversoft is an IBM Business Partner and Passport is available in the IBM Bluemix Catalog and comes with a complete integration tutorial.

Inversoft PassportOut of the box, Passport delivers:

  • Easy to use RESTful APIs.
  • Client libraries written in Python, Ruby, PHP, Node.js, Java, and C#.
  • User registration and login.
  • User management interface.
  • OAuth 2.0.
  • JSON Web Tokens.
  • Single sign-on.
  • Configurable password encryption.
  • Two-factor authentication.
  • Custom user data and user data search.
  • Localized email templates.
  • Transactional webhooks and custom events.
  • Reporting and analytics.

Stormpath to Passport

The following table lists each Stormpath API and the Passport API that provides similar functionality.

Stormpath API Passport API
/tenants N/A – Passport is single tenant solution. Passport supports multiple applications and multiple API keys.
/applications /api/application
/organizations N/A – Organizations and directories are flattened to Applications in Passport.
/directories N/A – Organizations and directories are flattened to Applications in Passport.
/groups In progress, this feature will be available in our next major release. In many cases a Passport Application can be used to provide equivalent functionality.
/accounts /api/users
/accountLinks N/A – Passport users are global to a single customer.
/account/customData /api/user – Custom User Data is part of the Passport user object.
/applications/loginAttempts /api/login
/smtpServers /api/system-configuration
/passwordPolicies /api/system-configuration
/emailTemplates /api/email/template
/accessTokens /api/jwt
/refreshTokens /api/jwt/refresh
N/A /api/webhook
N/A /api/user-action
N/A /api/user-action-reason
N/A /api/report
N/A /api/system/audit-log

Data Migration

Stormpath has documented an export procedure to allow you to extract all of your user data, including hashed passwords, in an encrypted zip file. We’ve built an API to consume this JSON data allowing you to easily import your existing users into Passport.

Note: If you are simply adding Passport to a new application built in Bluemix, just follow this guide and you’ll be up and running in twenty minutes or less.

Authenticating a User

To give you a feel for integrating with Passport, we will show how easy it is to start authenticating users against the Passport API. A common use case for mobile login will be to utilize JSON Web Tokens and a Refresh Token to allow the user to stay authenticated for a longer period of time.

Consider your iOS or Android phone; once you’ve logged into an application you generally don’t need to log in each time you open the app. Our recommended approach for mobile login is to utilize JSON Web Tokens and a Refresh Token to allow the user to stay authenticated for a longer period of time.

In the following example, we’ll demonstrate authenticating a user with the Login API.

[POST] /api/login

  "loginId": "daniel@inversoft.com",
  "password": "setec astronomy",
  "applicationId": "3c219e58-ed0e-4b18-ad48-f4f92793ae32",
  "device": "f58913ff-7860-4c06-8e0b-be0acc32d798",
  "ipAddress": "",
  "metaData": {
"device": {
  "name": "iPhone",
  "type": "MOBILE",
  "description": "Mary’s iPhone"

Authorization Request for a device to receive a Refresh Token.

  "refreshToken": "zEiw4N6L7KOTTu5b0RyTQT30nO8QfVjmDkoonPpS",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0OTE1NDE1MTQsImlhdCI6MTQ5MTUzNzkxNCwiaXNzIjoibm9kZS5pbnZlcnNvZnQuY29tIiwic3ViIjoiMDFlZTJkZmQtZDcxMS00ZjQ2LTgwMWYtM2MwMGRhNzMzODliIiwiYXBwbGljYXRpb25JZCI6IjNjMjE5ZTU4LWVkMGUtNGIxOC1hZDQ4LWY0ZjkyNzkzYWUzMiIsInJvbGVzIjpbImFkbWluIl19.pv5Wkn5chZgbLQTVyWFjaksEF5Xl5jvlKdMOFAWF9tI",
  "user": {
    "active": true,
    "email": "daniel@inversoft.com",
    "firstName": "Daniel",
    "id": "01ee2dfd-d711-4f46-801f-3c00da73389b",
    "insertInstant": 1488563952421,
    "lastLoginInstant": 1491537914514,
    "lastName": "DeGroff",
    "passwordChangeRequired": false,
    "passwordLastUpdateInstant": 1488563952557,
    "registrations": [{
      "applicationId": "3c219e58-ed0e-4b18-ad48-f4f92793ae32",
      "id": "f60c33a9-a74a-449d-8c14-0a4ca5b68bd5",
      "insertInstant": 1488563952749,
      "lastLoginInstant": 1491537914514,
      "roles": [
      "usernameStatus": "ACTIVE"
    "twoFactorEnabled": false,
    "usernameStatus": "ACTIVE",
    "verified": true

Authentication response with Access Token (JWT) and Refresh Token.

In the above example response, note that two tokens were returned on the login response: a JSON Web Token (JWT) and a Refresh Token.

The JWT is a long string that is composed of three discrete values: the header, payload, and signature. Each value is separated by a dot. The Refresh Token is simply a generated token that is unique and remembered by Passport to identify this user and associate them with this device.

This Refresh Token can be used until it has expired or it has been revoked by Passport. A Refresh Token is used to request another Access Token – in this case, a JWT.

The Refresh Token itself provides no ability to authorize the user to services, but only to request another Access Token which can, in turn, be used to request access to secured resources.

In Passport, requesting a new Access Token with a Refresh Token in hand is easy.

[POST] /api/jwt/refresh

  "refreshToken": "zEiw4N6L7KOTTu5b0RyTQT30nO8QfVjmDkoonPpS"

JWT Refresh Request.

  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0ODc5NzU0NTgsImlhdCI6MTQ4Nzk3MTg1OCwiaXNzIjoiYWNtZS5jb20iLCJzdWIiOiI4NThhNGIwMS02MmM4LTRjMmYtYmZhNy02ZDAxODgzM2JlYTciLCJhcHBsaWNhdGlvbklkIjoiM2MyMTllNTgtZWQwZS00YjE4LWFkNDgtZjRmOTI3OTNhZTMyIiwicm9sZXMiOlsiYWRtaW4iXX0.O29_m_NDa8Cj7kcpV7zw5BfFmVGsK1n3EolCj5u1M9hZ09EnkaOl5n68OLsIcpCrX0Ue58qsabag3MCNS6H4ldt6kMnH6k4bVg4TvIjoR8WE-yGcu_xDUObYKZYaHWiNeuDL1EuQQI_8HajQLND-c9juy5ILuz6Fhx8CLfHCziEHX_aQPt7jQ2IIasVzprKkgvWS07Hiv2Oskryx49wqCesl46b-30c6nfttHUDEQrVq9gaepca3Nhjj_cPtC400JgLCN9DOYIbtd69zvD8vDUOvVzMr2HGdWtKthqa35NF-3xMZKD8CShe8ZT74fNd9YZ0WRE-YeIf3T_Hv5p5V2w"

JWT Refresh Response.

If you like what you see, shoot us a note and let us know how we can help. Also, take a look at our API documentation and available client libraries.

api, authentication, ibm bluemix, stormpath

Published at DZone with permission of Kelly Strain . See the original article here.

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}