Configuring client applications

The Client Applications page of SafeShare Administration (below) allows:

• The registration of client applications with the Cocoon Data Platform.
• Registered client applications on the Cocoon Data Platform to be:
  • edited - for example, to modify a client application's permitted grant types, as well as
  • disabled or re-enabled - for example, to block a client application's access to the Cocoon Data Platform's resources (by 'disabling' that application).

Integrators can use the Cocoon Data Platform's API to develop their own applications that directly leverage Cocoon Data's powerful data-centric security features.

A SafeShare administrator can configure the access that their integrators' applications have to their Cocoon Data Platform's resources, by 'registering' these applications on their Cocoon Data Platform instance. Access to these resources is based on the OAuth 2.0 Authorisation Framework, which the Cocoon Data Platform uses for authentication and authorisation.

From the Cocoon Data Platform's perspective, an integrator's application is a 'client application', regardless of whether this application is:

• A server-side web application,
• Designed to run natively on a mobile device such as a tablet or phone,
• Designed to run natively on any other operating system (e.g. destkop/laptop computers) or
• User agent-based (e.g. runs client-side in a web browser).

A client application cannot access any resources on the Cocoon Data Platform until it has first been registered with the Cocoon Data Platform.

Registering a new client application

To register a new client application with the Cocoon Data Platform:

1. Ensure you are signed in to SafeShare Administration.
2. Click the Client Apps option on the left of the SafeShare Administration interface to open the Client Applications page.
3. Click the Add New button.
4. In the Add Client Application dialog box, complete the fields (described in detail in the table below) to register the client application.
5. Click Save and the client application will appear as a new entry on the Client Applications page.

The following table describes all mandatory fields that must be completed to register a client application on the Cocoon Data Platform.

Tip: Integrators developing client applications using the Cocoon Data Platform's API may find the information provided in the following table useful.

Field	Description
Application Name	The name of the client application which will appear to Cocoon Data users (when they attempt to authenticate to the Cocoon Data Platform from this client application).
Client ID	The 'client ID'/'client identifier' value of the client application. This value, along with the Client Secret (below), form the application's 'client credentials' which are required for OAuth 2.0 authentication and authorisation when a Cocoon Data user authenticates (with their own 'user credentials') to the Cocoon Data Platform. For more information about these terms, see the definition for grant type ** (below). When a SafeShare administrator registers a new client application, the Cocoon Data Platform automatically generates a client ID based on a Universally Unique Identifier (UUID). The SafeShare administrator, however, can override this client ID value. Notes: The client ID value: Is usually hard-coded into the client application, since this value is passed to the Cocoon Data Platform during most OAuth 2.0 user authentication and authorisation events. Must be unique amongst all client applications registered on the Cocoon Data Platform. For more information about client IDs and their use in client applications, see the Client Types and Client Identifier sections of the OAuth 2.0 Authorisation Framework specification. In this specification, a 'client' refers to a client application and the 'authorisation server' refers to the Cocoon Data Platform.
Client Secret	The 'client secret' value of the client application. This value, along with the Client ID (above), form the application's 'client credentials' which are required for OAuth 2.0 authentication and authorisation when a Cocoon Data user authenticates (with their own 'user credentials') to the Cocoon Data Platform. For more information about these terms, see the definition for grant type ** (below). When a SafeShare administrator registers a new client application, the Cocoon Data Platform automatically generates a client secret based on a Universally Unique Identifier (UUID). The SafeShare administrator, however, can override this client secret value. Note: Like the client ID, the client secret value is also usually hard-coded into the client application, since this value is passed to the Cocoon Data Platform during most OAuth 2.0 user authentication and authorisation events. The exception to this is the OAuth 2.0 implicit grant type, where only the client ID value of the application's client credentials is passed to the Cocoon Data Platform during user authentication and authorisation. For more information about client secrets and their use in client applications, see the Client Types section and Client Password subsection (within Client Authentication) of the OAuth 2.0 Authorisation Framework specification. In this specification, a 'client' refers to a client application and the 'authorisation server' refers to the Cocoon Data Platform.
Access Token Validity	The number of seconds that an access token issued by the Cocoon Data Platform to a client application is valid for. (Access tokens are explained in more detail in the Grant types description below.) Upon expiry of the access token, the client application would need to either: Submit a valid refresh token to the Cocoon Data Platform in exchange for a fresh access token, or Request the Cocoon Data user to re-authenticate to the Cocoon Data Platform (with their user credentials) to obtain a fresh access token. Note: To maximise security, it is recommended that access tokens have relatively short life spans (expiring within minutes, for example, up to a maximum of 10 minutes).
Grant Types	The grant type/s (also known as authorisation grant/s) that the Cocoon Data Platform permits the client application to use to issue the application with an access token. An access token: Represents resources on the Cocoon Data Platform that are available to an authenticated Cocoon Data user by virtue of their roles (configurable by either a SafeShare administrator or an Organisation administrator). These resources could include: Any file (i.e. file object/Secure Object) or folder (i.e. collection) which the user: With the Originator role has created, such that this user becomes the item's owner, or With the Originator, Collaborator or Ad hoc role can access because the owner of the item has shared it with this user. Features of SafeShare Administration available to users with the SafeShare administrator role. Features of Organisation Administration available to users with the Organisation administrator role (within their specific organisation/s). Is issued by the Cocoon Data Platform to the client application to grant the client application access to the Cocoon Data user's resources on the Cocoon Data Platform. Has a limited life span. Once the access token expires, the client application loses its access to the Cocoon Data Platform's resources until the user re-authenticates to the Cocoon Data Platform or a refresh token is used to obtain a fresh access token. A refresh token can initially be issued to a client application by the Cocoon Data Platform following successful OAuth 2.0 authentication and authorisation. When the current access token expires, this refresh token is exchanged by the client application for a fresh access token from the Cocoon Data Platform (without the user having to re-authenticate). The Cocoon Data Platform supports the following OAuth 2.0 grant types ** , listed in order from most secure down to least secure (along with the types of client applications best suited to implement these grant types): Authorisation Code - Best suited for the following types of client applications: Server-side web applications. Native desktop/laptop or mobile device applications.       For more information about this grant type, see the Grant type details table below. Implicit - Best suited for user agent-based applications, such as one that runs client-side in a web browser.       For more information about this grant type, see the Grant type details table below. Password - Best suited for the following types of client applications: Native desktop/laptop or mobile device applications. Administrator/system-run services (e.g. a scheduled job).       For more information about this grant type, see the Grant type details table below. The Add/Edit Client Application dialog box also indicates the following options within the Grant Types section. While these options are not OAuth 2.0 grant types themselves, they support the OAuth 2.0 grant types (above): Allow Refresh Token - Determines if the Cocoon Data Platform can issue refresh tokens to the client application, which the client application can then use to request for (a) new access token/s. This allows a Cocoon Data user's session to continue (potentially indefinitely), without requiring the user to sign in again beyond the expiry of their access token. This option is only applicable when the Authorisation Code and/or Password grant type option/s (above) is/are selected. Allow Device Registration - Determines if the client application (running on a specific device - typically on a mobile device platform such as iOS or Android) can authenticate a specific Cocoon Data user with a passcode. Once a Cocoon Data user authenticates (with their email address and password) to the Cocoon Data Platform through a client application running on the device, the user can then set a passcode that can be utilised to authenticate themselves to the Cocoon Data Platform (without the need for email address/password credentials). To maximise security, a passcode is tied to a specific Cocoon Data user and device. ** In the context of Cocoon Data technologies, a grant type/authorisation grant is a credential representing a Cocoon Data user's authorisation to access that user's protected resources on the Cocoon Data Platform. This credential is used by the client application to obtain an access token. The following concepts are key components which are required to complete/obtain a grant type: User credentials - credentials that consist of a Cocoon Data user's email address and password (which the Cocoon Data user either had received in their original 'account created' email notification when their account was added through Organisation Administration or SafeShare Administration, or had changed themselves). Client credentials - credentials that consist of both the client ID and client secret.
Refresh Token Validity	The number of seconds that a refresh token issued by the Cocoon Data Platform to a client application is valid for. This value must be greater than the access token validity value above. If a refresh token expires, the client application requires a Cocoon Data user to re-authenticate in order to continue accessing the Cocoon Data Platform's resources (which are available to that user). Note: This field is only applicable (and available) when the Allow Refresh Token option (of Grant Types above) is selected, which in turn is only available when the Authorisation Code and/or Password grant type option/s is/are also selected.
Registered redirect URI(s)	A list of one or more valid Uniform Resource Identifiers (URIs) which the Cocoon Data Platform uses to verify the value of the redirect URI (also known as a redirection endpoint) parameter sent by the client application to the Cocoon Data Platform (during an OAuth 2.0 authentication and authorisation request to obtain an access token). If any part of the redirect URI sent by the client application (from the start of this URI) does not match one of the registered redirect URIs specified in this field, then the Cocoon Data Platform terminates the OAuth 2.0 authentication and authorisation process. Notes: This field is only applicable (and available) when the Authorisation Code and/or Implicit grant type option/s (of Grant Types above) is/are selected, since these grant types require users to authenticate directly through a web interface/user agent served by the Cocoon Data Platform. The client application's 'redirect URI/redirection endpoint' is what the Cocoon Data Platform redirects this user agent to after the authentication step. If communication between the client application and Cocoon Data Platform occurs over the Internet and the client application's redirect URI (to which the Cocoon Data Platform sends its response containing the access token) is based on the HTTP protocol, then for security reasons, ensure that: This redirect URI has been configured to use HTTPS (not just HTTP). The registered redirect URIs specified in this field are prefixed with https:// - i.e. no URIs in this field should be prefixed by http://.

Grant type details

The following table provides details about the OAuth 2.0 grant types that the Cocoon Data Platform can permit a client application to use (i.e. to issue that application with an access token). See Grant Types (above) for an explanation about access tokens issued by the Cocoon Data Platform.

These details below explain the types of information conveyed between the client application and Cocoon Data Platform, as well as the mode by which this information is conveyed and hence, the security implications associated with implementing these grant types in a client application.

Grant type	Details
Authorisation Code	The authorisation code grant type securely handles the conveyance of user credentials, client credentials and access/refresh tokens between the client application and Cocoon Data Platform. The Cocoon Data Platform authenticates both the user and client application with their respective credentials. User credentials are never exposed to the client application, since users authenticate directly through a web interface served by the Cocoon Data Platform. After successful user authentication, access/refresh tokens can then be sent securely by the Cocoon Data Platform to the client application, without these tokens being exposed to the browser (i.e. the 'user agent'). Therefore: This is the most secure (and hence, recommended) OAuth 2.0 grant type to implement in a client application. The authorisation code grant type should be implemented by client applications that are server-side web applications, since these types of applications can keep their source code (and hence, client credentials) private. Since the secrecy of client credentials can be maintained by the client application itself, these types of applications are known as 'confidential clients'. This grant type can also be implemented by client applications that are 'native', such as mobile or desktop applications. However, it is assumed that client credentials are not secure in these types of applications and are capable of being extracted. Since the secrecy of client credentials cannot be maintained by the client application, these types of applications are known as 'public clients'. Note: Relying on client credentials as a security measure in native applications is not recommended, for the following reason: Since a native client application is a 'public client', if the application's client credentials are extracted and implemented in an unauthorised client application, then the Cocoon Data Platform is unable to verify the authenticity of the genuine client application based on these credentials. If the credentials of a Cocoon Data user (who accesses the genuine client application) were procured through some other means (e.g. phishing) and then utilised to authenticate to the Cocoon Data Platform through the unauthorised client application, then the unauthorised application could gain access to the Cocoon Data Platform's resources (which are available to that user). If an integrator relies on client credentials for security in their native application (which is not recommended) and suspicion arises that these credentials have been stolen, then to immediately address this security breach, the integrator's client application would need to be disabled to deny access to the Cocoon Data Platform of all unauthorised client applications (which have implemented these stolen client credentials). Unfortunately, this action denies access to all genuine client application installations too. Therefore, after re-configuring the registered client application with new client credentials (as well as rebuilding and rolling out a new version of the genuine client application containing these new client credentials), the client application can then be re-enabled on the Cocoon Data Platform.
Implicit	The implicit grant type securely handles the conveyance of user credentials between the client application and Cocoon Data Platform. The Cocoon Data Platform authenticates the user with their credentials. However, as part of the OAuth 2.0 protocol, the client application is not authenticated with this grant type; the Cocoon Data Platform only verifies the identity of the client application through the client ID. While a user's credentials are never exposed to the client application (because users authenticate directly through a web interface served by the Cocoon Data Platform); unlike the authorisation code grant type, the access token is sent directly by the Cocoon Data Platform to the client application in a URI fragment. Therefore: This OAuth 2.0 grant type is a less secure to implement in a client application (than authorisation code above) for the following reasons: Since the Cocoon Data Platform does not authenticate the client application, the Cocoon Data Platform cannot verify the authenticity of the client application. The availability of the access token in the URI fragment sent by the Cocoon Data Platform can expose the access token to unauthorised parties for malicious use - including an attack via an authenticated Cocoon Data user (for example, by means of phishing). As a result of this grant type's inherent risk in exposing access tokens to unauthorised parties, refresh tokens are not issued when using the implicit grant type. The implicit grant type is typically implemented by client applications that are 'user agent-based', such as web browser applications where the executable code is downloaded and runs in the browser itself (rather than on a server), since the client credentials are available to the Cocoon Data user. The implementation of the implicit grant type in a web browser application can allow for the seamless integration of Cocoon Data user authentication and authorisation with OAuth 2.0, whilst keeping the user credentials secure.
Password	The password grant type delegates the handling of user credentials to the client application itself. Both the user and client credentials are sent from the client application to the Cocoon Data Platform for authentication. Access/refresh tokens sent by the Cocoon Data Platform to the client application (after successful user authentication) can then be captured by the client application, reducing the ability of the Cocoon Data user to access the access/refresh tokens themselves. Be aware that: This OAuth 2.0 grant type is less secure to implement in a client application (than both authorisation code and implicit above), because the delegated handling of user credentials to the client application increases the possibility of these credentials being exposed to unauthorised parties for malicious use. Exposure of user credentials to the client application is minimised by the fact that these credentials need only be used once (for a single request by the client application) and exchanged for an access token; since this grant type allows client applications to submit refresh tokens (which is recommended) in exchange for fresh access tokens, there is no need for client applications to store user credentials. The password grant type should only be implemented by native client applications (i.e. mobile or desktop applications), when a high level of trust between the Cocoon Data user and the client application itself can be assured. These are client applications which: Are a part of the operating system they run on (i.e. client applications developed by the same organisation/group who developed the operating system it runs on), Execute with a high level of privilege, or Were developed by Cocoon Data. Assuming the client application meets this criterion of trust, the password grant type could also be implemented by such a client application when the more secure authorisation code is neither available nor appropriate to implement.

Editing a registered client application

To edit a registered client application on the Cocoon Data Platform:

1. Ensure you are signed in to SafeShare Administration.
2. Click the Client Apps option on the left of the SafeShare Administration interface to open the Client Applications page.
3. Scroll to the relevant client application (if necessary) and click its Edit link.
4. In the Edit Client Application dialog box, modify the registered client application's fields, which are described in detail in the table (above).
5. Click Save and the registered client application will be updated.

Disabling and re-enabling a client application

Disabling a registered client application prevents any installations of the client application from accessing the Cocoon Data Platform. This is useful when a client application's access to the Cocoon Data Platform needs to be disabled (either temporarily or permanently), or suspicion arises that the client application's credentials have been stolen.

To disable, enable or re-enable a registered client application on the Cocoon Data Platform:

1. Ensure you are signed in to SafeShare Administration.
2. Click the Client Apps option on the left of the SafeShare Administration interface to open the Client Applications page.
3. To:
   • Disable the client application - click its green Enabled button (in the State column towards the right of the page), until this button changes red and indicates Disabled.
   • Enable or re-enable the client application - click its red Disabled button (in the State column) until the button changes green and indicates Enabled.

Note: When a client application is disabled it can still be edited. This feature allows a registered client application to be configured before access to the Cocoon Data Platform is enabled.