Authorization for Connectors

Connectors support various types of authorization to enable secure integration with external systems. This document outlines the process of adding authorization to a Connector and explains the different authorization types available.

Understanding Authorization

When developing your Connector's JavaScript logic, you'll often need to make requests to external APIs. While the runtime.fetch method makes this process straightforward, handling API endpoints that require authorization or authentication can be challenging.

Hardcoding tokens directly into the Connector code is considered bad practice, as these tokens may be accessible to other administrators in your environment. To address this security concern, the Connector CLI provides five different authorization types:

• Static Header Key
• OAuth 2.0 Client Credentials
• OAuth 2.0 Authorization Code
• OAuth 2.0 Resource Owner Password (Password Grant)
• OAuth 2.0 JWT Bearer Token

When a user first accesses a Connector and the code makes a runtime.fetch call, CHILI GraFx automatically runs the required authentication workflow. The authentication result is then cached and added to subsequent requests automatically.

Authorization Limitations

While the Connector framework supports the most common authorization schemes, it's important to note that completely customizable authorization is not possible. If your specific authorization requirements don't align with the five provided types, you may need to develop a workaround solution.

For example, services like GraFx Media and CHILI GraFx do not meet the requirements of any of the supported authorization types. In such cases, you would need to implement an intermediary service that adapts the authorization workflow to work within the Connector framework.

Define Supported Authorization Types

Before implementing authorization, you must define the supported authorization types in your package.json file. This ensures consistency between your CLI commands and your package configuration.

To do so, add or modify the supportedAuth property in your package.json file with the types of authentication your Connector supports.

Example of a package.json supporting Static Header Key and OAuth 2.0 Authorization Code:

{
...
  "config": {
    ...
    "supportedAuth": ["staticKey", "oAuth2AuthorizationCode"]
  }
}

Implement Authorization

To implement authorization in a Connector, you need a published Connector and the Connector CLI tool. Use the following command:

connector-cli set-auth \
    --connectorId <connector-id> \
    -e <environment> \
    -b <base-url> \
    -au <auth-usage> \
    -at <auth-type> \
    --auth-data-file <path-to-auth-file>

Authorization is Optional

By default, no authorization is applied. This allows you to quickly set up and test a Connector without dealing with authentication requirements. However, once authorization is configured for a Connector, it cannot currently be removed using the Connector CLI. If you need to change or remove an existing authorization method, you will need to recreate the Connector.

Proxying and Removing a Header

All POST requests made through a Connector are automatically proxied through CHILI GraFx servers, regardless of whether authorization is configured. If you include an Authorization header in your request via runtime.fetch, that header will be stripped out before it reaches the target API. Please use Static Header Key to set an Authorization header.

Connector ID (--connectorId)

This argument is the ID of your Connector published in your CHILI GraFx environment.

To retrieve all Connectors and look up your ID, use the following API endpoint (with proper authorization header):

GET https://{environment}.chili-publish.online/grafx/api/experimental/environment/{environment}/connectors

Environment (-e)

This argument expects the environment name that your Connector is published in.

Base URL (-b)

This argument expects the base URL for CHILI GraFx API calls, which will be in either of the following formats:

• Production Environments

  https://{environment}.chili-publish.online/grafx
  

• Sandbox Environment

  https://{environment}.chili-publish-sandbox.online/grafx
  

Matching Environment

Ensure that the environment in your base URL matches the environment passed via the -e argument.

Authorization Usage (-au)

This argument expects one of two values that will specify the usage scenario for the authorization.

Expected values:

• browser: Connector authentication to use when GraFx Studio is loaded in the browser for editors (e.g., GraFx Studio UI) or when using the SDK.
• server: Connector authentication to use when CHILI GraFx servers generate output (e.g., PDF, PNG, GIF).

Therefore, you can define different authorization types for each usage, allowing your Connector to use separate authorization methods for browser and server interactions. Of course, you can choose the same authorization type for both usage types.

Authorization Always Happens on the Server

It is important to note that all authorization is enforced server-side. This approach ensures that sensitive credentials—such as tokens, API keys, or other authentication data—are never exposed directly to the client. By processing authorization on the server, CHILI GraFx significantly reduces the risk of accidental credential leakage or malicious interception. When authorization is required, client requests do not communicate directly with the target service. Instead, the requests are securely proxied through CHILI GraFx servers, which handle the authorization process on your behalf.

Cannot Remove Configured Authorization

At this moment there is no way to erase authorization once set. If you run the set-auth command multiple times with the same authorization usage -au value but different -at authorization types, the last one overwrites the previous one.

Authorization Type (-at)

This argument expects one of the supported types of authorization.

Auth Type	Reference	Usage Support	Expected Argument Value
Static Header Key	MDN - Authorization Header	browser and server	staticKey
OAuth 2.0 Client Credentials	OAuth 2.0 - Client Credentials	browser and server	oAuth2ClientCredentials
OAuth 2.0 Authorization Code	OAuth 2.0 - Authorization Code	browser	oAuth2AuthorizationCode
OAuth 2.0 Resource Owner Password	OAuth 2.0 - Password Grant	browser and server	oAuth2ResourceOwnerPassword
OAuth 2.0 JWT Bearer Token	OAuth 2.0 - JWT Bearer Token Flow	browser and server	oAuth2JwtBearer

In addition to specifying the authorization type using the -at argument, you must also define the supported authorization types in your package.json file. See Define Supported Authorization Types.

Browser Only Support

OAuth 2.0 Authorization Code is only supported with browser usage.

OAuth 2.0 Considerations

1. OAuth 2.0 responses must comply with the Access Token Response format, with the exception that expires_in is mandatory.
2. The grant_type for OAuth 2.0 types is automatically set as per the specification and cannot be configured.
3. access_token and refresh_token are cached internally for OAuth 2.0 types. There's currently no way to reset them without deleting the Connector.
4. OAuth 2.0 Authorization Code is user-specific and not useful with an Integration User (used outside CHILI GraFx).
5. OAuth 2.0 Authorization Code is limited to "browser" usage, which may restrict its applicability in certain scenarios.

Authorization Data File Requirements (--auth-data-file)

Each authorization type requires a specific JSON schema. The grant_type for OAuth 2.0 types is predefined by the specifications.

Static Header Key

{
  "key": string,  // HTTP header name
  "value": string // HTTP header value
}

OAuth 2.0 Client Credentials

{
  "clientId": string,     // OAuth 2.0 app client ID
  "clientSecret": string, // OAuth 2.0 app client secret
  "scope": string,        // OAuth 2.0 app scope. Optional
  "tokenEndpoint": string // OAuth 2.0 app token endpoint URL
}

OAuth 2.0 Authorization Code

{
  "clientId": string, // OAuth 2.0 app client ID
  "clientSecret": string, // OAuth 2.0 app client secret
  "scope": string, // OAuth 2.0 app scope. Optional
  "authorizationServerMetadata": {
    "authorization_endpoint": string, // OAuth 2.0 app authorization endpoint URL
    "token_endpoint": string, // OAuth 2.0 app token endpoint URL
    "token_endpoint_auth_methods_supported": ["client_secret_basic", "client_secret_post"] // The way in which "clientId" and "clientSecret" are sent in HTTP requests
  },
  "specCustomization": {
    "codeParameterName": string, // Name of the "code" parameter sent in HTTP requests. Optional, default "code"
    "requestContentType": "applicationJson" | "formUrlEncoded" // Defines which HTTP Content-Type will be used for the request. Optional, default "formUrlEncoded"
  }
}

OAuth 2.0 Resource Owner Password

{
  "clientId": string, // OAuth 2.0 app client ID
  "clientSecret": string, // OAuth 2.0 app client secret
  "scope": string, // OAuth 2.0 app scope. Optional
  "username": string, // User with access to the OAuth 2.0 app
  "password": string, // Password of the user
  "bodyFormat": "applicationJson" | "formUrlEncoded", // Defines which HTTP Content-Type will be used for the token request. Optional, default "formUrlEncoded"
  "tokenEndpoint": string // OAuth 2.0 app token endpoint URL
}

OAuth 2.0 JWT Bearer Token

Depends on the Connector definition

Example: Setting Multiple Authorization Types

This example demonstrates how to set up a Connector with different authorization types for server and browser interactions. In this scenario, we'll use OAuth 2.0 Client Credentials for server interactions and OAuth 2.0 Authorization Code for browser interactions.

Step 1: Prepare Authorization Data Files

First, create two JSON files with the necessary authorization data:

OAuth 2.0 Client Credentials JSON

oauth-client-credentials.json

{
  "clientId": "abc123xyz789",
  "clientSecret": "s3cr3tk3y",
  "scope": "read write",
  "tokenEndpoint": "https://oauth.example.com/token"
}

OAuth 2.0 Authorization Code JSON

oauth-authorization-code.json

{
  "clientId": "client123id",
  "clientSecret": "client123secret",
  "scope": "openid profile",
  "authorizationServerMetadata": {
    "authorization_endpoint": "https://oauth.example.com/authorize",
    "token_endpoint": "https://oauth.example.com/token",
    "token_endpoint_auth_methods_supported": ["client_secret_basic", "client_secret_post"]
  },
  "specCustomization": {
    "codeParameterName": "authCode",
    "requestContentType": "formUrlEncoded"
  }
}

Step 2: Update package.json

Ensure that your package.json file includes both authorization types in the supportedAuth array:

{
  "config": {
    "supportedAuth": ["oAuth2ClientCredentials", "oAuth2AuthorizationCode"]
  }
}

Step 3: Set Authorization for Server Interactions

Use the following command to set OAuth 2.0 Client Credentials for server interactions:

connector-cli set-auth \
    --connectorId your-connector-id \
    -e example \
    -b https://example.chili-publish.online/grafx \
    -au server \
    -at oAuth2ClientCredentials \
    --auth-data-file path/to/oauth-client-credentials.json

Step 4: Set Authorization for Browser Interactions

Use the following command to set OAuth 2.0 Authorization Code for browser interactions:

connector-cli set-auth \
    --connectorId your-connector-id \
    -e example \
    -b https://example.chili-publish.online/grafx \
    -au browser \
    -at oAuth2AuthorizationCode \
    --auth-data-file path/to/oauth-authorization-code.json

By following these steps, we've configured our Connector to use OAuth 2.0 Client Credentials for server-side interactions and OAuth 2.0 Authorization Code for browser-based interactions. This setup allows for secure communication with external APIs in both scenarios.