Client

Configuration

Clients maintain a configuration that you can adjust or consult as you create, update and query for them.

The following table presents you the configuration properties.

Create a Client

You can create as many Clients as you would like. Each Client is essentially a "door" with a lock that lets anyone who has the keys sign on to your platform. Each Client has a public key and a private secret. For a fully-secure authorization flow, the application that aspires to sign on as the Client will need to provide the key and secret during the authorization handshake.

Here is how you create a Client:

<p>
    The key and secret are generated for us.  You cannot specify the key and/or secret by hand.
    In fact, this is a really important detail since the server uses an encryption algorithm to
    generate the secret (using a cipher that is unique per platform).
</p>
<p>
    Here we create a Client that only allows for the "authorization_code" (3-legged) flow.  If an application tries
    to authorize with this Client using any other OAuth2 flow, they'll be rejected.  This example also contains a
    preconfigured redirect uri for a known entry page that we trust.
</p>

platform.createClient({ "authorizedGrantTypes": ["authorization_code"], "registeredRedirectUri": "http://www.myserver.com" });

<p>
    And here is an example of a Client that utilizes the "Open Driver" authentication scheme.  This is a Cloud CMS
    supported variation of the "password" flow whereby we do not require the client secret to authenticate.
    Thus, we don't need the client secret anywhere in the source code of the application.  This is ideal for
    HTML5 and JavaScript applications running in the browser.
    <br/>
    <br/>
    In place of the client secret, we check the incoming domain URL to identify the application.
    The <code>domainUrls</code> array lets us define valid domain URLs on which the application may be running.
</p>

platform.createClient({ "authorizedGrantTypes": ["password"], "allowOpenDriverAuthentication": true, "domainUrls": ["http://www.mycompany.com", "https://www.mycompany.com"] });

<h2 id="update">Update a Client</h2>
<p>
    To update, all you have to do is make changes to your Client and fire away.
</p>

// assume we have a domain user var user = ...;

// assume we have a client var client = ...;

platform.createAuthenticationGrant({ "domainPrincipalId": user.getDomainId(), "principalId": user.getId(), "clientId": client.getId() }).update({ "title": "iPad Application" }).then(function() { console.log("The title of this auth grant is: " + this.getTitle()); });

<p>
    You are not allowed to update the <code>key</code> or <code>secret</code> fields.  These are Read-Only.
    If you'd like to change the key or secret, you must create a new Client.
</p>

<h2 id="delete">Delete a Client</h2>
<p>
    When you delete an Client, any users of any applications that were authenticated using the
    Client's credentials will no longer have access to your platform.  They'll be shut down.  The
    server will additionally clean up any OAuth2 access or refresh tokens.
    <br/>
    <br/>
    Thus, the effect is pretty much instantaneous.
</p>

authgrant.del();

<h3 id="disable">Disabling</h3>
<p>
    As an alternative to deleting, you might opt to disable the Client.  The effect is basically the
    same but you will have the option to re-enable or reuse the Client at some point in the future.
    It's really up to you.
</p>

authgrant.set("enabled", false); authgrant.update();

<h2 id="read">Read a Client</h2>
<p>
    You can read a Client by its <code>_doc</code> ID field.
</p>

// assume we have a client Id var clientId = "4b5b685c980c10f98beb";

platform.readClient(clientId);

<h2 id="list">List Clients</h2>
<p>
    You can retrieve a list of Clients for your platform quite easily.
    The following code hands back the full list.
</p>

platform.listAuthenticationGrants();

<p>
    You can then iterate over the list to pick at what you'd like.
</p>

platform.listAuthenticationGrants().each(function() { console.log("Authentication Grant title: " + this.get("title")); });

<p>
    Retrieving the full list is potentially an expensive operation, depending how many items you have.
    The more your retrieve, the more data goes over the wire and so forth.  Thus, you might wish to
    <i>paginate</i> your call and retrieve a subset of the total list at a time.
    <br/>
    <br/>
    Here is an example that retrieves in pages of size 10.
    It starts on the second page (by skipping to starting index 20).
    It also sorts by the <code>title</code> field in a descending sequence.
</p>

platform.listAuthenticationGrants({ "limit": 10, "skip": 20, "sort": { "title": -1 } }).each(function() { console.log("Authentication Grant title: " + this.get("title")); });

<p>
    You don't have to have all of the pagination parameters (<code>limit</code>, <code>skip</code> and <code>sort</code>).
    You might only want to include one or two.  It's up to you.
</p>

<h2 id="query">Query Clients</h2>
<p>
    You can run custom queries against your Clients to find exactly what you're looking for.
    Here is a query that looks for Clients which are disabled.
</p>

platform.queryAuthenticationGrants({ "enabled": false });

<p>
    Here is that same query followed by an iteration over the result map.
</p>

platform.queryAuthenticationGrants({ "enabled": false }).each(function(id) { console.log("Found an Authentication Grant: " + id + " with title: " + this.get("title")); });

<p>
    Finally, you can mix queries with pagination to reduce data over the wire and speed up performance.
    Here is that same query with some pagination thrown in.
    We limit to pages of size 10 and sort by <code>title</code>.
</p>

platform.queryAuthenticationGrants({ "enabled": false },{ "limit": 10, "skip": 20, "sort": { "title": -1 } }).each(function(id) { console.log("Found an Authentication Grant: " + id + " with title: " + this.get("title")); });