With a new year comes another exciting release of the Stormpath .NET SDK. In this release, we’ve knocked down another big milestone: full support for token-based authentication. But that’s not all! This release also includes support for JSON Web Tokens (JWTs), and contains plenty of improvements along the way.

Why OAuth and Token-Based Authentication Is Awesome For .NET Apps

OAuth and token-based authentication are a common point of confusion and frustration for web developers. OAuth is not Single Sign-On, but it’s often confused with SSO because many login providers (such as Google and Facebook) use a flavor of OAuth to handle external login. At the most basic level, OAuth means generating access and refresh tokens when users log into your application. And tokens are awesome!

Let me explain why.

Think of an access token as representing the identity of a user who is logged into your application. The access token is sent to the server with every request. On the server, the token is examined and verified to ensure the request is valid and authorized. After a period of time, the token expires and is no longer valid.

When an access token expires, the refresh token is used to generate a fresh access token. Typically, access tokens are short-lived and refresh tokens are long-lived. If the access token is compromised, it can be revoked, which forces the generation of a new access token via the user’s refresh token. Likewise, if a refresh token is compromised, it can be revoked so it cannot be used to generate new access tokens.

Why are tokens awesome? In short: scalability and security.

HTTP is stateless, so there’s no built-in way to store session or user information between requests. In the past, .NET developers had to rely on cookies and session variables to maintain state on the server, but this can be insecure. And if you’re planning on hosting your application on multiple servers behind a load balancer, making sure sessions are correctly shared between your machines can be a huge pain.

Token-based authentication is stateless, just like HTTP. Access and refresh tokens (in the form of JSON Web Tokens) are stored client-side and represent the user’s identity and authorization claims. Nothing is stored on the server to represent the session, so it’s easier to scale horizontally on multiple machines.

A cryptographic signature is used to ensure that the token isn’t compromised. An ID claim can be included in each token to prevent replay attacks. Additionally, if you know a user or token has been compromised, you can revoke their tokens immediately and prevent any future requests. This improves the security of the application.

In this release of the Stormpath .NET SDK, we’ve added rich support for the token management features already available in the Stormpath REST API.

Install the .NET SDK

Installing the SDK in a new project is as simple as:

install-package Stormpath.SDK

If you’re already using the SDK, this release should be a drop-in upgrade without any breaking changes:

update-package Stormpath.SDK

For a full list of changes, see the changelog on Github.

How Stormpath Makes Token Management In .NET Easy

With the Stormpath .NET SDK, it’s easy to:

  • Set policies for access and refresh token expiry
  • Generate access tokens and refresh tokens when users log into your application
  • Verify that an access token hasn’t been revoked or tampered with
  • Use a refresh token to generate a new access token
  • List tokens for an account and application
  • Revoke access and refresh tokens
  • Configure Access and Refresh Token Policies

    Each Application has an OAuth Policy, which can be retrieved by calling GetOauthPolicyAsync:

    These values can be updated by the appropriate Set methods, and then calling SaveAsync:

    The maximum duration for access and refresh tokens is 180 days. Refresh tokens are optional; to disable refresh token generation, set the Refresh Token TTL to TimeSpan.Zero.

    Generate OAuth Tokens for a User

    Token generation should happen when a user logs into your application. In OAuth parlance, your application will issue a Password Grant request to Stormpath containing the user’s credentials. If the credentials are valid, Stormpath will generate access and refresh tokens for the user.

    Given a set of user credentials, you can generate tokens with a few lines of code:

    In a web application, you can use the Set-Cookie HTTP header to pass the access and refresh token JWTs back to the user’s browser, or return them in a JSON response. (See Where to Store your JWTs – Cookies vs HTML5 Web Storage.)

    Verify Access Tokens

    When a user makes a request to your application with an access token, it must be validated. The Stormpath .NET SDK supports two validation modes: local and remote.

    Local validation can be performed without making a network request, and ensures the following:

  • Token hasn’t been tampered with
  • Token hasn’t expired
  • Issuer is Stormpath
  • Remote validation makes a request to the Stormpath API, and ensures all of the above plus:

  • Token hasn’t been revoked
  • Account hasn’t been disabled, and hasn’t been deleted
  • Issuing application is still enabled, and hasn’t been deleted
  • Account is still in an account store for the issuing application
  • The choice of using local or remote validation depends on the needs of your application.

    Remote validation looks like this:

    Local validation is identical, except for a call to WithLocalValidation:

    Refresh Access Tokens

    When an access token expires, it’s straightforward to issue a Refresh Grant request to obtain a fresh token:

    Generating a new access token does not modify the expiration time of the refresh token. Once the refresh token expires, the user must authenticate again to get new access and refresh tokens.

    List Tokens for an Account

    You can query or list an account’s access and refresh tokens via the appropriate collection resource:

    It’s also possible to restrict the query to a particular Application, given the Application’s href:

    Revoke Access and Refresh Tokens

    Revoking the access and refresh tokens for an account is necessary in some situations, such as:

  • The user has explicitly logged out
  • The user’s device or client has been compromised, and you need to force them to re-authenticate
  • Revoking tokens is a simple manner of deleting the appropriate resource:

    Create and Parse JSON Web Tokens (JWTs) in .NET

    At the heart of token authentication is the JSON Web Token, which is a standard and compact way of storing identity and claims as a string, with an optional cryptographic signature to prevent tampering. Access and refresh token strings are JWTs that have been Base64-encoded to make them URL-safe.

    This SDK release includes built-in support for constructing, signing, parsing, and validating JWTs that use the HMAC SHA-256 (HS256) algorithm.

    Construct and Sign JWTs

    The IClient interface exposes a builder that can construct JWTs:

    The IJwt interface represents a constructed or parsed JWT, and includes a deserialized body (payload):

    The result of IJwt.ToString() is Base64-encoded and guaranteed to be URL-safe.

    Parse and Validate JWTs

    Likewise, IClient also exposes a JWT parser and validator:

    If validation fails, the appropriate exception derived from InvalidJwtException will be thrown. By default, the signature and lifetime (Expiration and Not-Before claims) are validated when parsing any JWT. You can add additional validation requirements with the Require methods:

    That’s all there is to it!

    Token-based authentication and JSON Web Tokens are powerful tools for building modern web and mobile applications that are secure and scalable. The Stormpath .NET SDK simplifies the process of creating and managing tokens, so you can focus your effort on building your application.

    What’s Next for the .NET SDK?

    There’s plenty more to come! Here’s what’s on the roadmap:

  • Integration with ASP.NET
  • SAML support
  • Is there something specific you want to see? Report bugs and feature requests on Github or shoot us an email.