Authentication with SignalR and OAuth Bearer Token

Authentication with SignalR and OAuth Bearer Token

Authenticating connections to SignalR is not as easy as you would expect. In many scenarios authentication mechanisms use the Authorize header in HTTP request. The problem is, that SignalR does not explicitly support headers, because Web Sockets – one of the transports used in browsers – does not support them. So if your authentication mechanism requires any form of headers being sent, you need to go another way with SignalR.

In this post I would like to describe a way to use the OAuth Bearer Token authentication with SignalR by passing the token over a cookie into SignalR pipeline. To show how to do this, I’m going to create a chat application (as if world needs another SignalR chat sample!) The application requires user to authenticate in order to send messages. If not authenticated, the user can see only fragments of messages sent by other people, and he is not able to see who the sender is.

When anonymous:

After signing in:

You can find full sample code here.

We’re going to use the Microsoft’s OWIN Security and ASP.NET Identity libraries for this sample. The easiest way to get started is to create new ASP.NET project in VS 2013 and include the WebAPI and Individual Accounts security option. Then add SignalR NuGet package. This gives us:

• User management system with REST API access
• Bearer OAuth flow for authentication
• Possibility to use external login providers (although I’m not going to cover this scenario in the sample)
• And of course possibility to use SignalR

Now let’s implement the SignalR hub:

public class ChatHub : Hub
{
    public override Task OnConnected()
    {
        AssignToSecurityGroup();
        Greet();

        return base.OnConnected();
    }

    private void AssignToSecurityGroup()
    {
        if (Context.User.Identity.IsAuthenticated)
            Groups.Add(Context.ConnectionId, "authenticated");
        else
            Groups.Add(Context.ConnectionId, "anonymous");
    }

    private void Greet()
    {
        var greetedUserName = Context.User.Identity.IsAuthenticated ?
            Context.User.Identity.Name :
            "anonymous";

        Clients.Client(Context.ConnectionId).OnMessage(
            "[server]", "Welcome to the chat room, " + greetedUserName);
    }

    public override Task OnDisconnected()
    {
        RemoveFromSecurityGroups();
        return base.OnDisconnected();
    }

    private void RemoveFromSecurityGroups()
    {
        Groups.Remove(Context.ConnectionId, "authenticated");
        Groups.Remove(Context.ConnectionId, "anonymous");
    }

    [Authorize]
    public void SendMessage(string message)
    {
        if(string.IsNullOrEmpty(message))
            return;

        BroadcastMessage(message);
    }

    private void BroadcastMessage(string message)
    {
        var userName = Context.User.Identity.Name;

        Clients.Group("authenticated").OnMessage(userName, message);

        var excerpt = message.Length <= 3 ? message : message.Substring(0, 3) + "...";
        Clients.Group("anonymous").OnMessage("[someone]", excerpt);
    }
}

The hub utilizes the OnConnect and OnDisconnect methods to assign a connection to one of the security groups: authenticated or anonymous. When broadcasting a message, anonymous connections get limited information,  while authenticated ones get the whole thing. User context can be accessed via Context.User property which retrieves current IPrincipal from OWIN context. The SendMessage hub method is only available to authenticated connections, because of the Authorize attribute.

Please note, that when using SignalR groups for security purposes, you may have to handle reconnect scenarios as described here.

We’re going to assume, that some users are already registered in the application. See the auto-generated API help page for information on how to do this. Now, in order to authenticate the connection, we need to:

• Call the token endpoint to get the bearer token for username / password combination.
• Use the token when connecting to SignalR hub.

We’re going to implement the second part by using a cookie. The cookie approach has a problem: when opening a new browser tab, the same cookie will be used. You can’t sign in as two different users with one browser by default. Another approach would be to pass the token in a query string. Query string removes the cookie limitation, but can pose a security threat: query strings tend to be stored in web server logs (or exposed in other ways even when using SSL). There is a risk of  someone intercepting the tokens. You need to select an approach that fits your scenario best.

The default OAuth bearer flow implementation you get from OWIN Security only looks at the Authorization HTTP header to find the bearer token. Fortunately you can plug some additional logic by implementing the OAuthBearerAuthenticationProvider.

public class ApplicationOAuthBearerAuthenticationProvider 
    : OAuthBearerAuthenticationProvider
{
    public override Task RequestToken(OAuthRequestTokenContext context)
    {
        if (context == null) throw new ArgumentNullException("context");

        // try to find bearer token in a cookie 
        // (by default OAuthBearerAuthenticationHandler 
        // only checks Authorization header)
        var tokenCookie = context.OwinContext.Request.Cookies["BearerToken"];
        if (!string.IsNullOrEmpty(tokenCookie))
            context.Token = tokenCookie;
        return Task.FromResult<object>(null);
    }

}

In the RequestToken method override we look for cookie named “BearerToken”. This cookie will be set by the client code, which I’ll show in a bit.

// EDIT: There is also ValidateIdentity override copied over from ApplicationOAuthBearerProvider private class within OWIN Security components (not sure why it is private in the first place). So basically we replicate the functionality of validating the identity, while including additional token lookup in cookies. The ValidateIdentity method is not relevant for the presented scenario

Now, to use the new component, in Startup.Auth.cs we will change implementation of the ConfigureAuth method:

public void ConfigureAuth(IAppBuilder app)
{
    //app.UseCookieAuthentication(new CookieAuthenticationOptions());
    //app.UseExternalSignInCookie(DefaultAuthenticationTypes.ExternalCookie);

    //app.UseOAuthBearerTokens(OAuthOptions);

    app.UseOAuthAuthorizationServer(OAuthOptions);

    app.UseOAuthBearerAuthentication(new OAuthBearerAuthenticationOptions
    {
        Provider = new ApplicationOAuthBearerAuthenticationProvider(),
    });
}

First, we turn off cookie based authentication. You may want to leave it on for MVC support. For this example, it’s not needed. Then we turn off external sign in providers, as this is not supported by the sample. In order to pass our own instance of OAuthBearerAuthenticationProvider, we have to ommit the UseOAuthBearerToken helper method, as it uses the private class implementation I mentioned earlier by default. Instead, we do two things:

• configure authorization server (it is responsible for issuing tokens)
• and configure bearer authentication passing in a new instance of our provider class

We’re good on the server side now. What about the client side?

First the function that is responsible for getting the token:

function signIn(userName, password) {
    return $.post("/token", { grant_type: "password", username: userName, password: password })
        .done(function(data) {
            if (data && data.access_token) {
                chatHub.useBearerToken(data.access_token);
                toastr.success("Login successful");
            }
        })
        .fail(function(xhr) {
            if (xhr.status == 400) {
                toastr.error("Invalid user name or password");
            } else {
                toastr.error("Unexpected error while signing in");
            }
        });
}

We need to do an URL encoded form post with grant_type field set to “password” and  also include the username and password. If login fails, we get HTTP 400 status. If it is successful however, we get JSON response with access_token containing the bearer token.  That token is passed into the chat hub wrapper class, which looks like this:

var ChatHubWrapper = function() {
    var self = this;
    var chat = null;
    var isStarted = false;
    var onMessageCallback = function() {};

    self.start = function() {
        chat = $.connection.chatHub;
        chat.client.onMessage = onMessageCallback;
        return $.connection.hub.start()
            .done(function() { isStarted = true; });

    };

    self.stop = function() {
        isStarted = false;
        chat = null;
        return $.connection.hub.stop();
    };

    self.sendMessage = function(message) {
        if (isStarted) {
            chat.server.sendMessage(message);
        };
    };

    self.onMessage = function(callback) {
        onMessageCallback = callback;
        if (isStarted)
            chat.client.onMessage = onMessageCallback;
    };


    self.useBearerToken = function (token) {
        var wasStarted = isStarted;

        if (isStarted)
            // restart, so that connection is assigned to correct group
            self.stop();

        setTokenCookie(token);

        if (wasStarted)
            self.start();
    };

    function setTokenCookie(token) {
        if (token)
            document.cookie = "BearerToken=" + token + "; path=/";
    }

    self.clearAuthentication = function () {
        document.cookie = "BearerToken=; path=/; expires=" + new Date(0).toUTCString();
    }

};

This class wraps chat hub functionality and facilitates creation of the authentication cookie with the bearer token. OWIN Security components will take care of  authenticating connections based on the token. As you can see, the connection to the hub needs to be restarted, so that it is put into “authenticated” group. There is one small problem: here we don’t actually wait for the hub to stop before we start it again. That may case some internal HTTP 403 errors in SignalR since it detects change of authentication status on an existing connection. However this error is not surfaced to the user. In order to get rid of this, you need to implement waiting for the disconnect to complete.

And this is pretty much it.  We have an authenticated connection to SignalR using a OAuth Bearer Token. The same token can be used to authenticate WebAPI calls (in this case you can use the Authorization HTTP header). Please bear in mind, that in this sample I used the default token expiration time, which is 14 days (this is what new project wizard generates in VS 2013). Also refresh token is not supported in this sample. For more advanced scenarios you may want to implement refresh token support and shorten the expiration period.

You can find the full sample on Github.