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.

Property

Type

Default

Read-Only

Description

key

text

(auto-generated)

Read-Only

The authentication grant key.

secret

text

(auto-generated)

The authentication grant secret.

principalDomainId

text

The id of the domain of the principal to be authenticated. The domain must be a domain on the current platform.

principalId

text

The id of the principal to be authenticated.

clientId

text

The id of the client that must be authenticated in order to apply this grant.

allowOpenDriverAuthentication

boolean

Whether to allow "open-driver" authentication against this grant.

enabled

boolean

true

Whether this grant is enabled

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:

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.

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.

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.

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.