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:

platform.createClient();

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).

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.

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

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.

In place of the client secret, we check the incoming domain URL to identify the application. The domainUrls array lets us define valid domain URLs on which the application may be running.

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

Update a Client

To update, all you have to do is make changes to your Client and fire away.

// 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());
});

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

Delete a Client

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.

Thus, the effect is pretty much instantaneous.

authgrant.del();

Disabling

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.

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

Read a Client

You can read a Client by its _doc ID field.

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

platform.readClient(clientId);

List Clients

You can retrieve a list of Clients for your platform quite easily. The following code hands back the full list.

platform.listAuthenticationGrants();

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

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

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 paginate your call and retrieve a subset of the total list at a time.

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 title field in a descending sequence.

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

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

Query Clients

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.

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

Here is that same query followed by an iteration over the result map.

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

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 title.

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"));
});