connection-server

Breadboard Connection Server

A stateless service for coordinating authenticated connections between Breadboard end-user clients and third-party apps/services using OAuth.

Contents

• Background
• APIs
  • GET list/
  • GET grant/
  • GET refresh/
• Configuring Connections
  • Configuring Google Cloud Connections
• Local development
• Production deployment

Background

This README assumes knowledge of terms and concepts from RFC 6749: The OAuth 2.0 Authorization Framework , especially:

• authorization endpoint
• authorization code
• access token
• access token scope
• refresh token

Note the term connection is not a standard OAuth term. We adopt this term to refer to the high level process of an end-user "connecting" their client to a third-party app/service.

APIs

GET list/

List the available connections.

Returns a list of all possible third-party apps/services that the end-user could connect their Breadboard client to. See Configuration Connections for where this list comes from.

Each connection includes an ID (allowing us to distinguish between the various available connections), a display name and description, and a third-party authorization endpoint URL.

GET grant/

Perform first-time authorization for a connection.

Takes a connection ID and a temporary authorization code (generated by the third-party authorization endpoint and returned to the end-user via a redirect).

Returns an access token which can be used to access third-party resources, an expiry duration for that access token, and a long-term refresh token which can be used to automatically acquire new access tokens without user interaction.

GET refresh/

Get a new authorization token for when an earlier one has expired.

Takes a connection ID and a refresh token. Returns a new access token and expiry duration.

Configuring Connections

Note

In the future, connections will also be configurable via the Google Cloud Secret Manager.

Connections are configured by placing a JSON file in this package's secrets/ folder, and setting the CONNECTIONS_FILE environment variable to its path. The format of the JSON file follows this example:

{
  "connections": [
    {
      "id": "cool-service",
      "title": "Cool Service",
      "description": "A cool service for doing cool stuff",
      "oauth": {
        "client_id": "an_oauth_client_id",
        "client_secret": "the_secret_for_this_oauth_client",
        "scopes": ["an_oauth_scope"],
        "auth_uri": "https://example.com/auth",
        "token_uri": "https://example.com/token"
      },
      "icon": "data:image/png;base64,some_base64_bytes_of_a_png"
    }
  ]
}

Important

Connection configuration files should never be checked into GitHub or any other insecure location.

This is because the client_secret field is highly sensitive. It allows any party to impersonate the application it belongs to and intercept user access tokens. The Breadboard Connection Server never reveals this secret over its APIs, and protecting these secrets is the primary reason this server exists.

Configuring Google Cloud Connections

To configure a connection for a Google Cloud project:

1. Follow the documentation at Google Identity > OpenID Connect to create and configure an OAuth 2.0 client.

2. Download the OAuth 2.0 client's JSON configuration with the button shown here:

   

3. Copy the the client_id, client_secret, auth_uri, and token_uri fields from this file into the CONNECTIONS_FILE you have chosen (see above for example).

Local development

cd breadboard/packages/connection-server
npm run dev

This will start the server on localhost:5555. Set the HOST and/or PORT environment variables to customize the address. The server will automatically restart if its implementation or connection configuration files are modified.