Client Credentials REST Host

Of the 2 hosts available in the SDK, the Client Credentials REST Host is the most straight forward and easy to use.   It can be instantiated traditionally with the required information as constructor arguments or it can use an application configuration file to store information.  It is also the only shipped host that can be used outside of a web-based application.  The Client Credentials REST Host is primarily meant to be used for utility applications, not integrations.

Setup

If you installed the SDK via NuGet then a communityserver_SDK.config file and an oauth.ashx file were installed.  If you only plan on using the Client Credentials REST Host then you can delete these files as they are not used.

The Client Credentials REST Host requires you create an OAuth client in your community site.  This client should use the client credentials grant type and be a confidential client.  For more information on creating OAuth clients and using grant types see REST API Authentication.  Record your client Id and client secret.

This host requires 4 pieces of information to work:

• deafaultUsername: The user that will be primarily used by the host when not impersonating
• communityUrl: The fully qualified domain name of your community
• clientId: The client ID of the Oauth client you created
• clientSecret: The Oauth client secret from the client you created.

You have 2 options for creating the host.  The first option is just to instantiate it like any other class passing in the required arguments above:

    var host = new ClientCredentialsRestHost("admin"
        ,"http://yourcommunityurl.com"
        , "[Your Client Id]"
        , "[Your Client Secret]");

The second is to use an application configuration file.  Locate your web.config or app.config file in your solution or add one if one does not exist.  If the <AppSettings /> node is not present add it and then add the following information using values you recored from your Oauth client setup:

<appSettings>
    <add key="communityUrl" value="[http://yourcommunityurl.com]" />
    <add key="defaultUsername" value="admin" />
    <add key="clientId" value="[Oauth Client Id]" />
    <add key="clientSecret" value="[Oauth Client Secret]" />
</appSettings>

You will get errors if you try to instantiate the host using its default constructor if you have not setup the values in configuration.

Lifecycle

The Client Credentials REST Host is like any other class and survives based on the scope it was created in.   It is not expensive to create a Client Credentials REST Host however it is also not necessary to do so often.   Generally you only need to create this host once per application.  You can create multiple hosts if so needed for additional communities or alternate configurations, however only 1 host can use the application config to store values, all the others must use the constructor.

Authentication and Impersonation

As mentioned previously the Client Credentials REST Host uses Oauth to authenticate, specifically a client credentials grant.   This means that when it is using the default user it requests an access token for that user and it is used to authenticate all non-impersonated REST requests.  If you are impersonating it will obtain a token for that user and use it for the scope of the impersonation.  To avoid multiple token requests the host will cache the users it gets tokens for. Because a user can be cached and the token may have expired, the host will also handle getting refresh tokens as well.

Impersonation

Impersonation in this host requires 2 steps.  First you must use a host specific method called Impersonate which is an action that will allow requests made within the scope of that action to be run as another user.

 var host = new ClientCredentialsRestHost(); //Assumes config values arein the config file
 host.Impersonate("userA", (h) =>
 {
    //Stuff in here runs as userA
 });

Additionally all requests must set the enableImpersonation argument of the call to true(default).   Setting it to false would be a way to opt-out of the impersonation while still in the scope of the action.

var host = new ClientCredentialsRestHost(); //Assumes config values arein the config file
host.Impersonate("userA", (h) =>
{
    //This will run as userA
    dynamic impersonatedResponse = host.GetToDynamic(2, "info.json",true);
    //This will run as the default user
    dynamic notImpersonatedResponse = host.GetToDynamic(2, "info.json", false);
});