Authentication and authorization

Authentication and authorization in ServiceStack

General

ServiceStack supports basic authentication and OAuth authentication out of the box. There exists a project template/example which shows, what you have to do, to enable OAuth and basic authentication.

• http://en.wikipedia.org/wiki/Basic_access_authentication
• http://en.wikipedia.org/wiki/OAuth

public class CustomCredentialsAuthProvider : CredentialsAuthProvider
{
    public override bool TryAuthenticate(IServiceBase authService, string userName, string password)
    {
        //Add here your custom auth logic (database calls etc)
        //Return true if credentials are valid, otherwise false
    }

    public override void OnAuthenticated(IServiceBase authService, IAuthSession session, IOAuthTokens tokens, Dictionary<string, string> authInfo)
    {
        //Fill the IAuthSession with data which you want to retrieve in the app eg:
        session.FirstName = "some_firstname_from_db"
        //...
            
        //Important: You need to save the session!
        authService.SaveSession(session);
    }
}

Then you need to register your custom credentials auth provider:

    //Register all Authentication methods you want to enable for this web app.
    AuthService.Init(this, () => new AuthUserSession()
        new IAuthProvider[] {
	    new CustomCredentialsAuthProvider(), //HTML Form post of UserName/Password credentials
    });

Afer that you need to register the routes for authentication in your AppHost:

Routes
//Using ServiceStack's built-in Auth and Registration services
    .Add<Auth>("/auth")

---

POST localhost:60339/auth?provider=credentials?format=json

{
    "UserName": "admin",
    "Password": "test"
    "RememberMe": true
}

When the client now tries to authenticate with the request above and the auth succeeded, the client will retrieve some cookies with a session id which identify the client on each webservice call.

But how does ServiceStack remember which session id belongs to which client?
For this purpose, ServiceStack uses an ICacheClient. A cache client is actually a simple key/value-store. When the cache client is used to save client session, the key is the session id and the value is an instance of the interface IAuthSession.

The IAuthSession can be accessed inside a ServiceStack service:

public class SecuredService : RestServiceBase<Secured>
{
    public override object OnGet(Secured request)
    {
        AuthUserSession session = this.GetSession();
        return new SecuredResponse() { Test = "You're" + session.FirstName };
    }
}

ServiceStack uses the CacheClient which was registered in the IoC container:

//Register a external dependency-free 
container.Register<ICacheClient>(new MemoryCacheClient() { FlushOnDispose = false });
//Configure an alt. distributed peristed cache that survives AppDomain restarts. e.g Redis
//container.Register<IRedisClientsManager>(c => new PooledRedisClientManager("localhost:6379"));

Tip: If you've got multiple server which run the same ServiceStack service, you can use Redis to share the sessions between these servers.

---

Please look at SocialBootstrapApi to get a full example.

Of course you can also implement your own - custom - authentication mechanism. You aren't forced to use the built-in ServiceStack auth mechanism.

The Authenticate attribute

But how does ServiceStack know, which service needs authentication? This happens with the AuthenticateAttribute.

You simply have to mark your request dto with this attribute:

//Authentication for all HTTP methods (GET, POST...) required
[Authenticate()]
public class Secured
{
    public bool Test { get; set; }
}

Now this service can only be accessed if the client is authenticated:

public class SecuredService : RestServiceBase<Secured>
{
    public override object OnGet(Secured request)
    {
        IOAuthSession session = this.GetSession();
        return new SecuredResponse() { Test = "You're" + session.FirstName };
    }

    public override object OnPut(Secured request)
    {
        return new SecuredResponse() { Test = "Valid!" };
    }

    public override object OnPost(Secured request)
    {
        return new SecuredResponse() { Test = "Valid!" };
    }

    public override object OnDelete(Secured request)
    {
        return new SecuredResponse() { Test = "Valid!" };
    }
}

If you want, that authentication is only required for GET and PUT requests for example, you have to provide some extra parameters to the Authenticate attribute.

[Authenticate(ApplyTo.Get | ApplyTo.Put)] 

Of course Authenticate can also be placed on top of a service instead on top of a DTO, because it's a normal filter attribute.

The RequiredPermission attribute

ServiceStack also includes a built-in permission based authorization mechanism. To activate the permission mechanism you first need to init it in the app host:

PermissionHandler.Init(this);

Your request dto which requires specific permissions:

[Authenticate()]
//All HTTP (GET, POST...) methods need "CanAccess"
[RequiredPermission("CanAccess")
[RequiredPermission(ApplyTo.Put | ApplyTo.Post, "CanAdd")]
[RequiredPermission(ApplyTo.Delete, "AdminRights", "CanDelete")]
public class Secured
{
    public bool Test { get; set; }
} 

Now the client needs the permissions...

• "CanAccess" to make a GET request
• "CanAccess", "CanAdd" to make a PUT/POST request
• "CanAccess", "AdminRights" and "CanDelete" to make a DELETE request

Normally ServiceStack calls the method bool HasPermission(string permission) in IAuthSession. This method checks if the list List<string> Permissions in IAuthSession contains the required permission.

IAuthSession is stored in a cache client as explained above

You can fill this list in the method OnAuthenticated you've overriden in the first part of this tutorial.

As Authenticate, you can mark services (instead of DTO) with RequiredPermission, too.