App manifest

CloudBees SDM is a preview, with early access for select preview members. Product features and documentation are frequently updated. If you find an issue or have a suggestion, please contact CloudBees Support. Learn more about the preview program.

An app manifest defines a CloudBees app. Each app is associated with an app manifest that describes its ID, public keys, extensions it provides and the settings for how the App is displayed in the UI.

How this works

  • When a developer wants to create a new app, they need to define a manifest for their app. The App SDKs provide some tooling to help with creating and maintaining the manifest

  • To register an app with the platform, the app registration API is executed and the manifest is passed as a parameter.

  • The settings in the app manifest define how the app appears in the app directory (name, description, icons, screenshot tabs, etc.).

  • When the app is installed, the extensions declared in the manifest become visible to the organization profile and features that support the relevant extension points will leverage these installed extensions.

Application authentication is provided for registered applications. Before an application can authenticate, it must first be registered by a POST request of the application manifest to the /platform/api/a/{account}/app/registrations endpoint.

App manifest explained

An application manifest currently consists of the following:

{
  "url": "http://app.example.com",
  "name": "Example application",
  "private": false,
  "publicKeys": [
    "-----BEGIN PUBLIC KEY-----\nMFYwEAYHKoZIzj0CAQYFK4EEAAoDQgAEMM0E3v8/FE0J5gRt1bsznI4j3nUL7jQ6\nBzcLz5pNzgsROj0DHnwTXahHHjUIqXsVkmLVzP6sg0Npcl67zMWgjw==\n-----END PUBLIC KEY-----"
  ],
  "extensions": {
    "com.cloudbees.sdm.DataType": {
      "widgets": {
        "schema": "type Widget @queryable { id: ID! }"
      }
    }
  },
  "iconUrl": "http://app.example.com/icon",
  "tags": [
    "tag_1",
    "tag_2",
    "tag_3"
  ],
  "description": "Sample description",
  "releaseNotesUrl": "http://app.example.com/releasenotes",
  "screenshots": [
    {
      "url": "http://app.example.com/screenshot/1",
      "width": "200",
      "height": "300"
    },
    {
      "url": "http://app.example.com/screenshot/2",
      "width": "200",
      "height": "300"
    }
  ],
  "appVersion": "v0.0.1"
}
url

The URL of the application, will probably become one of either the display URL or the callback URL.

name

The display name of the application.

private

Flag to determine whether the application is private to the owning organization profile or publicly available for installation in any organization.

publicKeys

The public keys that can be used to verify application issued JWT tokens.

Supported keys and JWT signature algorithms

The following keys and JSON web tokens (JWT) signature algorithms are supported:

+

  • RSA keys up to 4096 bits for signing JWT tokens with SHA-256 / SHA-384 / SHA-512 RSAAAS-PSS algorithms.

  • ECDSA keys from the P-256 curve to sign JWT tokens with the SHA-256 algorithm.

  • ECDSA keys from the P-384 curve to sign JWT tokens with the SHA-384 algorithm.

  • ECDSA keys from the P-521 curve to sign JWT tokens with the SHA-512 algorithm.

+ This field supports multiple keys in order to allow an application to perform a rolling key upgrade without downtime. It is recommended that only one key is provided except during a rolling key upgrade. extensions:: The extensions that should be made available in accounts into which the applications is installed. Expressed as a map of maps where the keys of the outer map are extension points, the keys of the inner map are extension IDs, and the values are JSON content as defined by the given extension point. The extensions available in an account can then be queried with the endpoint /platform/api/a/{account}/extensions or, filtered by extension point, at /platform/api/a/{account}/extensions/{point}. iconUrl:: The URL for the applications icon. tags:: A list of tags for the application. description:: A description of the application. releaseNotesUrl:: The URL for the release notes of the application. screenshots:: A list of screenshot objects composing of the URL for the specific screenshot along with the width and height dimensions. appVersion:: The current version of the application.

Registering an application manifest

The response for registering an application manifest is the application registration details, for example:

{
  "id": "12456",
  "url": "http://app.example.com",
  "name": "Example application"
}

The registered application can then be installed in any account by the account admin making a PUT request to /platform/api/a/{account}/app/installations/{id}, removal is a DELETE request to the same URL.

Application registration lifecycle

App registration lifecycle

App installation lifecycle

App installation lifecycle