Drivers

To connect to Cloud CMS, you need to establish two important pieces of information:

• The client that you are connecting as
• The user that you are signing on as

The only way that a remote application can connect to your platform is if it can produce the correct credentials to identify itself as a client that you know about. As the platform administrator, you issue a client key/secret ahead of time. The application then needs to present these credentials to you and prove that it is who it says it is.

Once the server can trust that the application is who it says it is (and not someone who is trying to access your platform independently), the user of your application then needs to log in. The user must present their own credentials (usually something like a username and password) and the server must check things out and then sign them on.

That's basically how it works. However, we've kept things pretty simple. Cloud CMS provides a number of configurations and authentication flows so that you avoid exposing secret credentials and keep things working in a very secure manner.

Simple Connection using OAuth2 "Password" Flow

Let's take a simple example of how you might connect to Cloud CMS using the OAuth2 "password" flow. This flow connects over HTTPS so as to provide a strong guarantee that data won't be picked off by a man-in-the-middle attack. That said, it also hard codes client secret and user password into the source code.

Not a good thing you say? Very astute observation. We cover this below.

Let's take a look at how this might work.

Gitana.connect({
    "clientKey": "<my client key>",
    "clientSecret": "<my client secret>",
    "username": "<username>",
    "password": "<password>"
}, function(err) {

    if (err) {
        // TODO: handle the error
    }

    // all done!
    // "this" is the platform object
});

Since a username and password are provided, this will use the OAuth2 password flow. When the handshake completes, you driver will have an OAuth2 access token and refresh token.

And so, now you can just go crazy with the cheese whiz.

    // all done!
    // "this" is the platform object

    this.listDomains().each(function(domainId) {
        console.log("Behold!  I have a domain with ID: " + domainId);
    });

Access Tokens and Refresh Tokens

When you authenticate using the Gitana driver, the Cloud CMS server issues you an OAuth access token and refresh token. With every subsequent operation that gets performed, the driver will automatically apply your access token as stuff gets sent over the wire.

Eventually, your access token will expire. This is normal. It's actually a safety mechanism built into the OAuth2 protocol. That way, if someone sniffed your access token, there's a short window that they can use it before it becomes invalid.

When your access token invalidates, the Gitana driver will automatically perform another handshake with the Cloud CMS server using your refresh token (via the OAuth2 "refresh" flow). In this way, the Gitana driver will acquire a new access token and begin using it.

This all happens automatically for you behind the scenes. That way, you don't have to manually manage any tokens or handle any weird 401's that pop out of nowhere. It's all taken care of for you.

Security Concerns for JavaScript in the Browser

If you're running JavaScript in the browser, then the example above should really be for testing and nothing more. Why? Well, the main reason is that we're storing the client secret and user password in our source code.

Anyone can view the source of a browser application and find the client secret or password. All you would have to do is "View Source" and there it is.

There are all kinds of tricks and games you can play to try to obfuscate the data but, in the end, it's just a bad practice to expose the client secret or the user password.

Fortunately, Cloud CMS supports all of the OAuth2 Flows. The "password" flow is just one of them. It's really intended for compiled or server-side applications (like Java, Android, iOS, NodeJS or even compiled Appcelerator Titanium apps). In all of those cases, it's really hard to get at the source.

For JavaScript/HTML5 applications running in a browser, we recommend the OAuth2 "code" authorization flow. You can read more about that in the next section.

Gitana Options

There are a few additional options you can specify when instantiating the Gitana driver. Here is a full list of what you can specify: