Creating a Group Using a Remote Authentication Provider (LDAP)

Problem

You need to create a group on Connect from a group that already exists in your LDAP authentication provider (the “remote group”).

Solution

Create a group on Connect from the corresponding remote group. You need to know the remote group’s name.

Note

This recipe is very similar to the one to Creating a User Using LDAP. If you also need to create users, combining these two or doing them in sequence might be helpful.

Python
R

Find the remote group to add

First, search your LDAP authentication provider for the group you wish to create.

from posit import connect
import polars as pl

GROUP_PREFIX = "Data Science"

client = connect.Client()

response = client.get("v1/groups/remote", params={"prefix": GROUP_PREFIX})
remote_groups_df = pl.DataFrame(response.json()["results"])

The resulting DataFrame contains information on LDAP remote groups whose name matches the prefix Data Science. The guid column indicates the GUID of the corresponding group on Connect, if any exists. Groups with a null GUID have no group on Connect.

>>> remote_groups_df
shape: (2, 3)
┌──────────────────────────────┬─────────────────────────────────┬─────────────────────────────────┐
│ name                         ┆ guid                            ┆ temp_ticket                     │
│ ---                          ┆ ---                             ┆ ---                             │
│ str                          ┆ str                             ┆ str                             │
╞══════════════════════════════╪═════════════════════════════════╪═════════════════════════════════╡
│ Data Science                 ┆ 51a3747a-88c9-4d6c-a791-17c194… ┆ jcmyc+C5owWnbOax/DIMNKCjAitdKY… │
│ Data Science Apprentices     ┆ null                            ┆ oBDwIisVy03JhjNI/VYwWy4KrXQe7V… │
└──────────────────────────────┴─────────────────────────────────┴─────────────────────────────────┘

In this example, the Data Science group has a GUID, which means that it already has a group on Connect, but the Data Science Apprentices group’s GUID is null, which means it does not have a corresponding group on Connect.

Included in the API response for each group is a temp_ticket value, which can be used to create the group in Connect. In the example above, the second group, Data Science Apprentices, does not exist in Connect, so you need the temp_ticket for this group to create the group in Connect.

temp_ticket = remote_groups_df["temp_ticket"][1]

Create the group on Connect

Next, using the temp_ticket value from the previous section, create a Connect group with a request to the PUT /v1/groups endpoint:

# The 'temp_ticket' value comes from an earlier /groups/remote search.
response = client.put("v1/groups", json={"temp_ticket": temp_ticket})

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

pl.DataFrame(response.json())
┌─────────────────────────────────┬──────────────────────────────┬────────────┐
│ guid                            ┆ name                         ┆ owner_guid │
│ ---                             ┆ ---                          ┆ ---        │
│ str                             ┆ str                          ┆ null       │
╞═════════════════════════════════╪══════════════════════════════╪════════════╡
│ f13a7792-7b6e-4fc9-9843-90b291… ┆ Data Science Apprentices     ┆ null       │
└─────────────────────────────────┴──────────────────────────────┴────────────┘

If the group already exists in Connect, the request errors:

ClientError: A group using the same unique ID already exists

The connectapi package’s function groups_create_remote() searches the remote authentication provider for a group with the specified prefix, and creates a corresponding group on Connect.

groups_create_remote(client, prefix = "Data Science Apprentices")

The function prints a message indicating the status of the request, and returns a data frame showing the newly-created group with, with a non-NULL GUID.

Creating remote group: Data Science Apprentices
Done creating remote groups
# A tibble: 1 × 3
  guid                                 name                     owner_guid
  <chr>                                <chr>                    <chr>
1 b806d590-5d52-478e-a9d8-491228b090e7 Data Science Apprentices NA

If the group already exists in Connect, the same data is returned, but a different message is printed.

At least one group with name prefix 'Data Science Apprentices' already exists
# A tibble: 1 × 3
  guid                                 name                     owner_guid
  <chr>                                <chr>                    <chr>
1 b806d590-5d52-478e-a9d8-491228b090e7 Data Science Apprentices NA

You can use the exact parameter to change the behavior of the prefix parameter, matching only groups whose name is exactly the parameter passed. For instance, you could use this to create a "Data Science" group, when "Data Science Apprentices" already exists.

Note

Use of the exact parameter requires connectapi version 0.4.0 or later.

> groups_create_remote(client, prefix = "Data Science", exact = TRUE)
Creating remote group: Data Science
Done creating remote groups
# A tibble: 1 × 3
  guid                                 name                     owner_guid
  <chr>                                <chr>                    <chr>
1 64ab5b36-bfba-4bf9-8a1e-a39f34421e11 Data Science Apprentices NA