7. Using ID Site

7.1. What is an ID Site?

Stormpath ID Site is a set of hosted and pre-built user interface screens that take care of common identity functions for your applications — log in, registration, and password reset. ID Site can be accessed via your own custom domain like id.mydomain.com and shared across multiple applications to create centralized authentication. It supports regular login to your Stormpath Directories, as well as Social and SAML login.

ID Site Screenshot

An example ID Site

The screens and functionality of ID Site are completely customizable. You have full access to the source code of the ID Site screens so you can make simple changes like adding your own logo and changing CSS or more complex changes like adding fields, JavaScript code, screens, removing screens, and even changing how the screens behave.

Why should I use Stormpath ID Site?

Building, securing, and maintaining identity screens for your users is time consuming, full of security concerns, and often more complex than many developers estimate. Stormpath ID Site gives you and your development team peace of mind that you will have best in class user security quickly and easily, with very little code — minimizing risk to your project timeline.

Stormpath ID Site fully decouples your identity screens from your applications, making it incredibly easy to provide the same login / registration pages for multiple applications — achieving centralized user management and authentication with a clean and easy user experience.

Browser Support

ID Site will work in the following web browser environments:

  • Chrome (all versions)
  • Internet Explorer 10+
  • Firefox 23+
  • Safari 8+
  • Android Browser, if Android version is 4.1 (Jellybean) or greater

7.2. How does ID Site Work?

To demonstrate how ID Site works, we’ll use an example. Imagine you are building an application for managing Stormtrooper equipment — like awesome helmets and blasters. The application is “Imperial Exchange”, available at https://imperialxchange.com/, and it uses Stormpath ID Site for login and registration.

Once ImperialXchange.com is rendered by the browser, “Log In” and “Sign Up” links are available for the unauthenticated user. Clicking on these will call your server-side application at specific endpoints. For illustration, the “Log In” link will invoke /login and “Sign Up” will invoke /register. Your application will securely redirect the user to the ID Site along with a cryptographically signed JSON Web Token (JWT) that includes information like the Callback URI, the path to a specific ID Site page, and any State you think is important for your application.

On the ID Site, the user will enter their data and complete the appropriate action, like login. ID Site will automatically detect any Workflow or Social Login configurations set in Stormpath and show the appropriate buttons, messaging, and behavior.

After the user has logged-in successfully, they will be redirected back to your application’s Callback URI. For illustration purposes, this could be https://imperialxchange.com/idSiteResult. When the ID Site redirects back to your application, it will pass a secure JWT that represents the account in Stormpath. Using the Stormpath SDK, your application will handle the request to /idSiteResult, validate that the JWT is correct, and return an ID Site Account Result. The ID Site Account Result will include the Stormpath Account object and additional information, such as any state that was passed by your application or whether or not the Account returned is newly created.

ID Site Flow

The ID Site Flow

7.3. ID Site Set Up

For more information on this topic, please see the Admin Console Guide.

7.4. Using ID Site Via REST

The Stormpath SDKs help developers quickly integrate communication from Stormpath’s ID Site to their application.

However, it is possible to use ID Site without a Stormpath SDK using the REST API.

To use ID Site there are two flows that need to be implemented:

  1. Getting a user to ID Site
  2. Handling the Callback to your Application from ID Site

So, let’s show you how to do exactly that!

Step 1: Getting a User to ID Site

When a user wants to log into, or register for, your application, you will need to redirect them to your ID Site.

A typical set of steps in your application are as follows:

  1. You render your application with a login button
  2. The user clicks the login button which will send a request to your server
  3. Your server will generate a JWT and include the valid information
  4. Your server responds with an HTTP 302 which redirects the user to the ID Site SSO endpoint
  5. Stormpath will redirect the user to your ID Site

ID Site Authentication JWT

First you will have to generate a JWT. Below are language specific JWT libraries that Stormpath has sanity tested with ID Site.

Note

This JWT must be signed with your API Key Secret.

The token itself will contain two parts, a Header and a Body that itself contains claims. You will have to add all of these into the JWT that you generate:

Header

Header Name Required? Valid Value(s)
typ Yes The value must be JWT.
alg Yes The algorithm that was used to sign this key. The only valid value is HS256.

Body

The claims for the JWT body are as follows:

Claim Name Required? Valid Value(s)
iat Yes The “Issued At Time”, which is the time the token was issued, expressed in Unix time.
iss Yes The issuer of the token. You should put your Stormpath API Key ID here.
sub Yes The subject of the token. You should put your Stormpath Application resource’s href here.
cb_uri Yes The callback URI to use once the user takes an action on the ID Site. This must match a Authorized Callback URI on Application resource.
jti Yes A universally unique identifier for the token. This can be generated using a GUID or UUID function of your choice.
path No The path on the ID Site that you want the user to land on. Use / for login page, /#/register for the sign up page, /#/forgot for the forgot password page, /#/reset for the password reset page.
state No The state of the application that you need to pass through ID Site back to your application through the callback. It is up to the developer to serialize/deserialize this value
require_mfa No Use this value to require the user to use a second factor for authentication. If the user has not enrolled in MFA, they will be required to setup a factor. Supports an array of one or more factor types that the user may select from, e.g. ['sms'] or ['google-authenticator']
onk No The string representing the nameKey for an Organization that is an Account Store for your application. This is used for multitenant applications that use ID Site.
sof No A boolean representing if the “Organization” field should show on the forms that ID Site renders.
usd No A boolean indicating whether the ID Site should be redirected to a subdomain based on an Organization nameKey.

Once the JWT is generated by your server, you must respond with or send the browser to:

HTTP/1.1 302 Found
Location: https://api.stormpath.com/sso?jwtRequest=$GENERATED_JWT

The Stormpath /sso endpoint will validate the JWT, and redirect the user to your ID Site.

Step 2: Handling the Callback to your Application from ID Site

Once the user signs up or logs in to your application, they will be redirected back to your application’s configured Callback URI that was set in the JWT. In addition to the Callback URI, ID Site will include a jwtResponse parameter in the query. For example, if the specified Callback URI is https://yourapp.com/dashboard then the user will be redirected to:

https://yourapp.com/dashboard?jwtResponse={GENERATED_ID_SITE_ASSERTION_JWT}

The jwtResponse represents a JWT that provides a signed security assertion about who the user is and what they did on ID Site.

ID Site Assertion JWT

Before you trust any of the information in the JWT, you must:

  • Validate the signature with your API Key Secret from Stormpath. This will prove that the information stored in the JWT has not been tampered with during transit.
  • Validate that the JWT has not expired

Note

If you are using a library to generate a JWT, these usually have methods to help you validate the JWT. Some libraries will only validate the signature, but not the expiration time. Please review your JWT library to verify its capabilities.

The Header and Body claims found in this JWT are as follows:

Header

Claim Name Required? Valid Value(s)
typ Yes The type of token, which will be JWT
alg Yes The algorithm that was used to sign this key. The only possible value is HS256.
kid Yes The ID of the Stormpath API Key that signed this JWT.

Body

Once the user has been authenticated by ID Site or the SAML IdP, you will receive back a JWT response. The JWT contains the following information:

Claim Name Description
iss This will match your ID Site domain and can be used for additional validation of the JWT.
sub The subject of the JWT. This will be an href for the Stormpath Account that signed up or logged into the ID Site / SAML IdP. This href can be queried by using the REST API to get more information about the Account.
aud The audience of the JWT. This will match your API Key ID from Stormpath.
exp The expiration time for the JWT in Unix time.
iat The time at which the JWT was created, in Unix time.
jti A one-time-use-token for the JWT. If you require additional security around the validation of the token, you can store the jti in your application to validate that a particular JWT has only been used once.
irt The jti of the ID Site Authentication JWT that was sent to generate this Assertion JWT.
state The state of your application, if you have chosen to have this passed back.
isNewSub A boolean value indicating whether this is a new Account in Stormpath.
status The status of the request. Valid values for ID Site are AUTHENTICATED, LOGOUT, or REGISTERED.
cb_uri The callback URI for this JWT.

Once the ID Site assertion is validated, you can read information about the user from it.

Exchanging the ID Site JWT for an OAuth Token

In some cases you may wish to exchange the ID Site assertion (JWT) for a Stormpath OAuth 2.0 token.

Note

For background information, please see 4.2. How Token-Based Authentication Works.

In this situation, after the user has been authenticated via ID Site, a developer may want to control their authorization with an OAuth 2.0 Token. This is done by passing the JWT similar to the way we passed the user’s credentials as described in Generating an OAuth 2.0 Access Token. The difference is that instead of using the password grant type and passing credentials, we will use the stormpath_token type and pass the JWT we got from ID Site.

POST /v1/applications/$YOUR_APPLICATION_ID/oauth/token HTTP/1.1
Host: api.stormpath.com
Authorization: Basic MlpG...
Content-Type: application/x-www-form-urlencoded

grant_type=stormpath_token&token={$JWT_FROM_ID_SITE}

Stormpath will validate the JWT (i.e. ensure that it has not been tampered with, is not expired, and the Account that it’s associated with is still valid) and then return an OAuth 2.0 Access Token:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "access_token": "eyJraWQiOiIyWkZNV...TvUt2WBOl3k",
  "refresh_token": "eyJraWQiOiIyWkZNV...8TvvrB7cBEmNF_g",
  "token_type": "Bearer",
  "expires_in": 1800,
  "stormpath_access_token_href": "https://api.stormpath.com/v1/accessTokens/1vHI0jBXDrmmvPqEXaMPle"
}

For more information about Stormpath’s OAuth 2.0 tokens, please see Generating an OAuth 2.0 Access Token.

Step 3: (Optional) Logging Out of ID Site

ID Site will keep a configurable session for authenticated users. When a user is sent from your application to ID Site, it will confirm that the session is still valid for the user. If it is, they will be automatically redirected to the cb_uri. This cb_uri can be the originating application or any application supported by a Stormpath SDK.

To log the user out and remove the session that ID Site creates, you must create a JWT similar to the one that got the user to ID Site, but instead of redirecting to the /sso endpoint, you redirect the user to /sso/logout.

So, once the JWT is generated by your server, you must respond with or send the browser to:

HTTP/1.1 302 Found
Location: https://api.stormpath.com/sso/logout?jwtRequest=%GENERATED_JWT%

Once the user is logged out of ID Site, they are automatically redirected to the cb_uri which was specified in the JWT.

Your application will know that the user logged out because the jwtResponse will contain a status claim of LOGOUT.

Resetting Your Password with ID Site

The Account Management chapter has an overview of Password Reset in Stormpath. In that flow, a user chooses to reset their password, then receives an email with a link to a page on your application that allows them to set a new password.

If you are using ID Site for login, then it stands to reason that you would want them to land on your ID Site for password reset as well. All you have to do is send the user to ID Site with a special path (/#/reset) and a claim containing the password reset token from the email link.

Using a JWT library, you have to generate a new JWT, with all of the usual required claims. The path claim should be set to /#/reset and you will also have to include an additional claim: sp_token. This is the sp_token value that you will have received from the link that the user clicked in their password reset email. This JWT is then passed to the /sso endpoint (as described in Step 1 above), and the user is taken to the Password Reset page on your ID Site.

7.5. Using ID Site for Multi-tenancy

If you are using Organizations to model multi-tenancy, then you will want to map these as Account Stores for your Application.

From that point, ID Site is able to handle either of the multi-tenant user routing methods described in the Multi-tenancy Chapter.

There are specific claims in the ID Site Authentication JWT that allow you mix and match multi-tenancy user routing strategies:

Organization nameKey

onk: Allows you to specify an Organization’s namekey. User is sent to the ID Site for that Organization, and is forced to log in to that Organization.

Show Organization Field

sof: Toggles the “Organization” field on and off on ID Site. Used on its own, it will allow the user to specify the Organization that they would like to log in to.

ID Site with sof toggled on

ID Site with Organization field enabled

If combined with onk, this will pre-populate that field with the Organization’s name.

ID Site with sof and onk toggled on

ID Site with Organization field enabled and prepopulated

Note

Stormpath will only show the field when you have at least one Organization mapped as an Account Store for your Application.

Use Sub-Domain

usd: If combined with onk, will redirect the user to an ID Site with the Organization’s nameKey as a sub-domain in its URL.

Note

This functionality will only work with a custom domain that you’ve properly configured in ID Site as documented here. The claim will not work with the default domain assigned by Stormpath.

For example, if your ID Site configuration is id.mydomain.com and the Organization’s nameKey is home-depot, then the SSO endpoint will resolve the following URL:

https://home-depot.id.mydomain.com/?jwt={GENERATED_JWT}

If you are using a custom domain, you must also make sure to put that domain in the list of Authorized Javascript Origin URLs. You can use the * wildcard for this. In the above example it would be:

https://*.id.mydomain.com

7.6. ID Site & Single Sign-On

One of the areas where ID Site really shines is if you have multiple applications that need to support single sign-on. All you need to do is to ensure that all your Applications have the same Directory mapped as an Account Store, and any time a user in that Directory logs in to one Application via ID Site, they will be able be authenticated for all other Applications.

As an overview, the flow would look like this:

  1. User goes to Application A while unauthenticated with that application and clicks on “Log in”.
  2. User is redirected to ID Site.
  3. User authenticates successfully on ID Site.
  4. ID Site redirects the user back to Application A with an ID Site Assertion for Application A.
  5. At this point you could (optionally) exchange the ID Site JWT for an OAuth token.
  6. User now goes to Application B while unauthenticated with that application and clicks on “Log in”.
  7. User is redirected to ID Site.
  8. ID Site detects the user’s authenticated session and redirects them back to Application B with an ID Site Assertion for Application B.

7.7. ID Site Hosting Guide

For more information about hosting ID Site yourself, please see the Stormpath Admin Console Guide.