Authentication Grant

Why would you want to use an Authentication Grant? Here are a few reasons:

• Authentication Grants provide a way for you to distribute user authentication credentials without actually having to give out the usernames and passwords of your users.
• Authentication Grants are constrained to specific users AND specific clients. Thus, if someone hacks around and manages to figure out your Authentication Grant's key and secret, they are still constrained to only accessing a single platform as a single client and user.
• If your Authentication Grant's key and secret are compromised (i.e. someone hacked around, figured out what the key/secret is and started trying to do malicious things), you can disable the Authentication Grant. This doesn't affect the user or the client. But the Authentication Grant is shut down. Booyah.

Authentication Grants are also configurable so that you can enhance and control their security characteristics.

For example, by chaining to a specific client, you can specify exactly which OAuth2 Authorization Flows an Authentication Grant can participate in (by tightening security around the client). In this way, you could do things like limit access only for those who authorize using the full "authentication code" OAuth2 Flow (which is the most secure, in our view, of all flows).

Or, you might opt to allow for reduced security for certain grants that you know are being used by trusted domains. Authentication Grants can be configured for Open Driver authentication which is a variant of the OAuth2 "password" Flow intended for JavaScript/HTML5 applications.

Configuration

Authentication Grants 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 an Authentication Grant

To create an Authentication Grant, we first have to have a Client and a Domain User. Remember that an Authentication Grant is basically a permission slip that lets someone come along and impersonate the Domain User provided that they are using the right Client.

We just have to provide a few details. It's basically as simple as this:

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

Note that the Authentication Grant key and secret are automatically generated for us. 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).

Update an Authentication Grant

To update, all you have to do is make changes to your Authentication Grant 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 Authentication Grant.

Delete an Authentication Grant

When you delete an Authentication Grant, any users of any applications that were authenticated using the Authentication Grant'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 Authentication Grant. The effect is basically the same but you will have the option to re-enable or reuse the Authentication Grant at some point in the future. It's really up to you.

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

Read an Authentication Grant

You can read an Authentication Grant by its _doc ID field.

// assume we have a branch Id
var authGrantId = "4b5b685c980c10f98beb";

platform.readAuthenticationGrant(authGrantId).then(function() {
    console.log("Authentication Grant ID: " + this.getId());
});

List Authentication Grants

You can retrieve a list of Authentication Grants 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 Authentication Grants

You can run custom queries against your Authentication Grants to find exactly what you're looking for. Here is a query that looks for Authentication Grants 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"));
});