Groups#

Create a Posit Connect Group from LDAP#

The following snippets search for a group in LDAP and then create a Posit Connect group for that LDAP group.

Workflow#

There are three steps:

Search for the group via the GET /v1/groups/remote endpoint.

Note

A group that does not exist on Connect will lack a guid.
Note the temp_ticket for the desired group.
Use the PUT /v1/groups endpoint with the temp_ticket to create a corresponding group on Posit Connect.

Search for a Group#

First, search for a group via the GET /v1/groups/remote endpoint:

library(httr)

# The connectServer URL must have a trailing slash.
connectServer <- Sys.getenv("CONNECT_SERVER")
connectAPIKey <- Sys.getenv("CONNECT_API_KEY")

# set the search parameter
prefix <- "accounting"

# make the query request
response <- GET(
  paste0(connectServer, "__api__/v1/groups/remote"),
  add_headers(Authorization = paste("Key", connectAPIKey)),
  query = list(prefix = prefix)
)

results <- content(response)$results

# print the results of the API call
formatGuid <- function(guid) {
  if (is.null(guid)) {
    "NULL"
  } else {
    guid
  }
}

cat(sprintf("NAME\tGUID\n"))
for (group in results) {
  cat(sprintf("%s\t%s\n", group$name, formatGuid(group$guid)))
}

The output looks like the following:

NAME          GUID
accounting1   15f5f51d-08ff-4e5b-beba-4ccf24e248dd
accounting2   NULL

Let's break this down:

In this particular case, there are two groups matching the search for the prefix accounting:
- accounting1
- accounting2
The group accounting1 has a GUID value, which means that this group already exists in Posit Connect.
The group accounting2 does not have a GUID value, which means that this group does not have a corresponding group in Posit Connect.

Included in the API response for each group is a temp_ticket value that can be used to create the group in Posit Connect. In the example above, the second group, accounting2, does not exist in Posit Connect, so you will need the temp_ticket for this group:

tempTicket <- results[[2]]$temp_ticket

You can use this tempTicket value in the next section to create the group.

Create a Posit Connect Group#

Using the tempTicket value from the previous section, you can create a Posit Connect group with a PUT /v1/groups:

library(httr)

# The connectServer URL must have a trailing slash.
connectServer <- Sys.getenv("CONNECT_SERVER")
connectAPIKey <- Sys.getenv("CONNECT_API_KEY")

# The 'tempTicket' value comes from an earlier /groups/remote search.

response <- PUT(
  paste0(connectServer, "__api__/v1/groups"),
  add_headers(Authorization = paste("Key", connectAPIKey)),
  body = list(temp_ticket = tempTicket),
  encode = "json"
)

print(content(response))

When the call succeeds, the response will contain a non-NULL guid value, which is a unique identifier for the group.

If the group already exists in Connect, the response will contain an error:

$error
[1] "The requested group name is already in use."

Search for content based on group ownership#

The GET /v1/experimental/groups/:guid/content endpoint can be used to return a list of all the content items a given group has access to. This can be useful for auditing access control lists for content on your server, or validating that the various groups you manage have access to all the content they should.

Note

Administrator credentials are needed in order to perform this action.

library(httr)

# The connectServer URL must have a trailing slash.
connectServer <- Sys.getenv("CONNECT_SERVER")
connectAPIKey <- Sys.getenv("CONNECT_API_KEY")

# set the desired group GUID about which you want to query
myGroupGUID <- "1430d192-3f25-42d4-90c0-1e07ccaacf37"

# make the query request
response <- GET(
  paste0(connectServer, "__api__/v1/experimental/groups/", myGroupGUID, "/content"),
  add_headers(Authorization = paste("Key", connectAPIKey))
)

content <- content(response)
response_error <- http_error(response)

if (response_error) {
  stop(content$error)
}

# print the results of the API call

cat("NAME\tGUID\tACCESS TYPE\n")
for (item in content) {
  cat(sprintf("%s\t%s\t%s\n", item$content_name, item$content_guid, item$access_type))

  cat("|\n|   NAME\tGUID\tROLE\tTYPE\n")

  for (principal in item$permissions) {
    cat(sprintf(
      "+-- %s\t%s\t%s\t%s\n",
      principal$principal_name,
      principal$principal_guid,
      principal$principal_role,
      principal$principal_type
    ))
  }

  cat("\n")
}

This endpoint will return all users and groups that are bound to the content via ACL (Access Control List) roles, as well as basic metadata for the content item (name, GUID, etc.). At a minimum, the list will contain the content author and the query group.

Output from running the script above might look like this:

NAME       GUID                                   ACCESS TYPE
content1   782f4fc1-8bd3-4cfc-ad09-4353da86eb60   acl
|
|   NAME     GUID                                   ROLE        TYPE
+-- user1    24997773-289e-4839-9970-aff6a710ba1d   author      user
+-- user2    a9798855-e0fd-495c-9543-9eb76b56385e   viewer      user
+-- group1   1430d192-3f25-42d4-90c0-1e07ccaacf37   publisher   group

content2   3fa42812-fec5-4d09-aca4-7aab1c3d3a63   acl
|
|   NAME     GUID                                   ROLE     TYPE
+-- user1    24997773-289e-4839-9970-aff6a710ba1d   author   user
+-- group1   1430d192-3f25-42d4-90c0-1e07ccaacf37   viewer   group