Creating Integrations

Problem

You want to enable content access to third-party protected resources on behalf of the user.

Solution

Configure an external OAuth application that controls access to protected resources. Create an integration with the external OAuth application in Connect. Associate the integration with content to facilitate protected resource access on behalf of users.

Warning

You must have administrator privileges to create an integration.

Python

Use the client.oauth.integrations.create() method to create integrations.

from posit import connect

AUTHORIZATION_ENDPOINT = "https://example.com/TENANT_ID/oauth2/authorize"
TOKEN_ENDPOINT = "https://example.com/TENANT_ID/oauth2/token"

CLIENT_ID = "2c0223d0-1036-421a-b710-9b6ddfd28034"
CLIENT_SECRET = "client-S3cr3t!4dbc4222baf9"

client = connect.Client()
integration = client.oauth.integrations.create(
        name="name",
        description="description",
        template="custom",
        config={
                "auth_mode": "Confidential",
                "authorization_uri": AUTHORIZATION_ENDPOINT,
                "client_id": CLIENT_ID,
                "client_secret": CLIENT_SECRET,
                "scopes": "scope1 scope2 scope3",
                "token_endpoint_auth_method": "client_secret_post",
                "token_uri": TOKEN_ENDPOINT
        },
)

The created integration object includes an internal id, a globally unique guid to identify the integration, and created_time and updated_time timestamps.

Note that the integration object does not include the client_secret attribute for security reasons.

>>> import json
>>> print(json.dumps(integration, indent=4))
{
    "id": "60",
    "guid": "ccfe80c0-3036-4b26-8e75-485a9605f252",
    "created_time": "2024-09-10T14:39:50Z",
    "updated_time": "2024-09-10T14:39:50Z",
    "name": "name",
    "description": "description",
    "template": "custom",
    "config": {
        "auth_mode": "Confidential",
        "authorization_uri": "https://example.com/TENANT_ID/oauth2/authorize",
        "client_id": "2c0223d0-1036-421a-b710-9b6ddfd28034",
        "scopes": "scope1 scope2 scope3",
        "token_endpoint_auth_method": "client_secret_post",
        "token_uri": "https://example.com/TENANT_ID/oauth2/token"
    }
}

R

Use the connectapi client to make a direct call to the integrations endpoint.

library(jsonlite)
library(connectapi)

client <- connect()

json_payload <- toJSON(list(
  name = "name",
  description = "description",
  template = "custom",
  config = list(
    auth_mode = "Confidential",
    authorization_uri = "https://example.com/TENANT_ID/oauth2/authorize",
    client_id = "2c0223d0-1036-421a-b710-9b6ddfd28034",
    client_secret = "client-S3cr3t!4dbc4222baf9",
    scopes = "scope1 scope2 scope3",
    token_endpoint_auth_method = "client_secret_post",
    token_uri = "https://example.com/TENANT_ID/oauth2/token"
  )
), auto_unbox = TRUE)

integration <- client$POST("v1/oauth/integrations", body = json_payload)

The created integration object includes an internal id, a globally unique guid to identify the integration, and created_time and updated_time timestamps.

Note that the integration object does not include the client_secret attribute for security reasons.

> toJSON(integration, pretty = TRUE, auto_unbox = TRUE)
{
  "id": "62",
  "guid": "4210098e-6794-42cd-8e98-868bd451ed22",
  "created_time": "2024-09-15T20:40:20Z",
  "updated_time": "2024-09-15T20:40:20Z",
  "name": "name",
  "description": "description",
  "template": "custom",
  "config": {
    "auth_mode": "Confidential",
    "authorization_uri": "https://example.com/TENANT_ID/oauth2/authorize",
    "client_id": "client-id",
    "scopes": "scope1 scope2 scope3",
    "token_endpoint_auth_method": "client_secret_post",
    "token_uri": "https://example.com/TENANT_ID/oauth2/token"
  }
} 

Discussion

Before creating the integration:

• Ensure that an OAuth application exists on the third-party platform.
• Talk to the third-party platform administrator and obtain the required configuration values for your integration. See this section of the Admin Guide for more information.

See also

• For more details about the data returned in this recipe, see Create an OAuth integration in the API Reference.
• See OAuth Integrations in the User Guide to learn more about how publishers and viewers interact with OAuth integrations.
• See OAuth Integrations in the Admin Guide to for more detailed information on how to configure OAuth integrations.