feat!: Implement Enterprise SCIM - EnterpriseService.ListProvisionedSCIMGroups

github/enterprise_scim.go

@@ -0,0 +1,99 @@
+// Copyright 2025 The go-github AUTHORS. All rights reserved.
+//
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package github
+
+import (
+	"context"
+	"fmt"
+)
+
+// SCIMSchemasURINamespacesGroups is the SCIM schema URI namespace for group resources.
+// This constant represents the standard SCIM core schema for group objects as defined by RFC 7643.
+const SCIMSchemasURINamespacesGroups = "urn:ietf:params:scim:schemas:core:2.0:Group"
+
+// SCIMSchemasURINamespacesListResponse is the SCIM schema URI namespace for list response resources.
+// This constant represents the standard SCIM namespace for list responses used in paginated queries, as defined by RFC 7644.
+const SCIMSchemasURINamespacesListResponse = "urn:ietf:params:scim:api:messages:2.0:ListResponse"
+
+// SCIMEnterpriseGroupAttributes represents supported SCIM Enterprise group attributes.
+//
+// GitHub API docs: https://docs.github.com/enterprise-cloud@latest/rest/enterprise-admin/scim#supported-scim-group-attributes
+type SCIMEnterpriseGroupAttributes struct {
+	DisplayName *string                           `json:"displayName,omitempty"` // Human-readable name for a group.
+	Members     []*SCIMEnterpriseDisplayReference `json:"members,omitempty"`     // List of members who are assigned to the group in SCIM provider
+	ExternalID  *string                           `json:"externalId,omitempty"`  // This identifier is generated by a SCIM provider. Must be unique per user.
+	// Bellow: Only populated as a result of calling SetSCIMInformationForProvisionedGroup:
+	Schemas []string            `json:"schemas,omitempty"` // The URIs that are used to indicate the namespaces of the SCIM schemas.
+	ID      *string             `json:"id,omitempty"`      // The internally generated id for the group object.
+	Meta    *SCIMEnterpriseMeta `json:"meta,omitempty"`    // The metadata associated with the creation/updates to the group.
+}
+
+// SCIMEnterpriseDisplayReference represents a JSON SCIM (System for Cross-domain Identity Management) resource reference.
+type SCIMEnterpriseDisplayReference struct {
+	Value   string  `json:"value"`             // The local unique identifier for the member (e.g., user ID or group ID).
+	Ref     string  `json:"$ref"`              // The URI reference to the member resource (e.g., https://api.github.com/scim/v2/Users/{id}).
+	Display *string `json:"display,omitempty"` // The display name associated with the member (e.g., user name or group name).
+}
+
+// SCIMEnterpriseMeta represents metadata about the SCIM resource.
+type SCIMEnterpriseMeta struct {
+	ResourceType string     `json:"resourceType"`           // A type of a resource (`User` or `Group`).
+	Created      *Timestamp `json:"created,omitempty"`      // A date and time when the user was created.
+	LastModified *Timestamp `json:"lastModified,omitempty"` // A date and time when the user was last modified.
+	Location     *string    `json:"location,omitempty"`     // A URL location of an object
+}
+
+// SCIMEnterpriseGroups represents the result of calling ListProvisionedSCIMGroups.
+type SCIMEnterpriseGroups struct {
+	Schemas      []string                         `json:"schemas,omitempty"`
+	TotalResults *int                             `json:"totalResults,omitempty"`
+	Resources    []*SCIMEnterpriseGroupAttributes `json:"Resources,omitempty"`
+	StartIndex   *int                             `json:"startIndex,omitempty"`
+	ItemsPerPage *int                             `json:"itemsPerPage,omitempty"`
+}
+
+// ListProvisionedSCIMGroupsEnterpriseOptions represents query parameters for ListProvisionedSCIMGroups.
+//
+// GitHub API docs: https://docs.github.com/enterprise-cloud@latest/rest/enterprise-admin/scim#list-provisioned-scim-groups-for-an-enterprise--parameters
+type ListProvisionedSCIMGroupsEnterpriseOptions struct {
+	// If specified, only results that match the specified filter will be returned.
+	// Possible filters are `externalId`, `id`, and `displayName`. For example, `externalId eq "a123"`.
+	Filter string `url:"filter,omitempty"`
+	// Excludes the specified attribute from being returned in the results.
+	ExcludedAttributes string `url:"excludedAttributes,omitempty"`
+	// Used for pagination: the starting index of the first result to return when paginating through values.
+	// Default: 1.
+	StartIndex int `url:"startIndex,omitempty"`
+	// Used for pagination: the number of results to return per page.
+	// Default: 30.
+	Count int `url:"count,omitempty"`
+}
+
+// ListProvisionedSCIMGroups lists provisioned SCIM groups in an enterprise.
+//
+// GitHub API docs: https://docs.github.com/enterprise-cloud@latest/rest/enterprise-admin/scim#list-provisioned-scim-groups-for-an-enterprise
+//
+//meta:operation GET /scim/v2/enterprises/{enterprise}/Groups
+func (s *EnterpriseService) ListProvisionedSCIMGroups(ctx context.Context, enterprise string, opts *ListProvisionedSCIMGroupsEnterpriseOptions) (*SCIMEnterpriseGroups, *Response, error) {
+	u := fmt.Sprintf("scim/v2/enterprises/%v/Groups", enterprise)
+	u, err := addOptions(u, opts)
+	if err != nil {
+		return nil, nil, err
+	}
+
+	req, err := s.client.NewRequest("GET", u, nil)
+	if err != nil {
+		return nil, nil, err
+	}
+
+	groups := new(SCIMEnterpriseGroups)
+	resp, err := s.client.Do(ctx, req, groups)
+	if err != nil {
+		return nil, resp, err
+	}
+
+	return groups, resp, nil
+}

github/enterprise_scim_test.go

@@ -0,0 +1,201 @@
+// Copyright 2025 The go-github AUTHORS. All rights reserved.
+//
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package github
+
+import (
+	"net/http"
+	"testing"
+
+	"github.com/google/go-cmp/cmp"
+)
+
+func TestSCIMEnterpriseGroups_Marshal(t *testing.T) {
+	t.Parallel()
+	testJSONMarshal(t, &SCIMEnterpriseGroups{}, "{}")
+
+	u := &SCIMEnterpriseGroups{
+		Schemas:      []string{SCIMSchemasURINamespacesListResponse},
+		TotalResults: Ptr(1),
+		ItemsPerPage: Ptr(1),
+		StartIndex:   Ptr(1),
+		Resources: []*SCIMEnterpriseGroupAttributes{{
+			DisplayName: Ptr("gn1"),
+			Members: []*SCIMEnterpriseDisplayReference{{
+				Value:   "idm1",
+				Ref:     "https://api.github.com/scim/v2/enterprises/ee/Users/idm1",
+				Display: Ptr("m1"),
+			}},
+			Schemas:    []string{SCIMSchemasURINamespacesGroups},
+			ExternalID: Ptr("eidgn1"),
+			ID:         Ptr("idgn1"),
+			Meta: &SCIMEnterpriseMeta{
+				ResourceType: "Group",
+				Created:      &Timestamp{referenceTime},
+				LastModified: &Timestamp{referenceTime},
+				Location:     Ptr("https://api.github.com/scim/v2/enterprises/ee/Groups/idgn1"),
+			},
+		}},
+	}
+
+	want := `{
+		"schemas": ["` + SCIMSchemasURINamespacesListResponse + `"],
+        "totalResults": 1,
+        "itemsPerPage": 1,
+        "startIndex": 1,
+        "Resources": [{
+            "schemas": ["` + SCIMSchemasURINamespacesGroups + `"],
+            "id": "idgn1",
+            "externalId": "eidgn1",
+            "displayName": "gn1",
+            "meta": {
+                "resourceType": "Group",
+                "created": ` + referenceTimeStr + `,
+                "lastModified": ` + referenceTimeStr + `,
+                "location": "https://api.github.com/scim/v2/enterprises/ee/Groups/idgn1"
+            },
+            "members": [{
+                "value": "idm1",
+                "$ref": "https://api.github.com/scim/v2/enterprises/ee/Users/idm1",
+                "display": "m1"
+            }]
+        }]
+    }`
+
+	testJSONMarshal(t, u, want)
+}
+
+func TestSCIMEnterpriseGroupAttributes_Marshal(t *testing.T) {
+	t.Parallel()
+	testJSONMarshal(t, &SCIMEnterpriseGroupAttributes{}, "{}")
+
+	u := &SCIMEnterpriseGroupAttributes{
+		DisplayName: Ptr("dn"),
+		Members: []*SCIMEnterpriseDisplayReference{{
+			Value:   "v",
+			Ref:     "r",
+			Display: Ptr("d"),
+		}},
+		ExternalID: Ptr("eid"),
+		ID:         Ptr("id"),
+		Schemas:    []string{"s1"},
+		Meta: &SCIMEnterpriseMeta{
+			ResourceType: "rt",
+			Created:      &Timestamp{referenceTime},
+			LastModified: &Timestamp{referenceTime},
+			Location:     Ptr("l"),
+		},
+	}
+
+	want := `{
+        "schemas": ["s1"],
+        "externalId": "eid",
+		"displayName": "dn",
+        "members" : [{
+            "value": "v",
+            "$ref": "r",
+            "display": "d"
+        }],
+        "id": "id",
+		"meta": {
+			"resourceType": "rt",
+			"created": ` + referenceTimeStr + `,
+			"lastModified": ` + referenceTimeStr + `,
+			"location": "l"
+		}
+	}`
+
+	testJSONMarshal(t, u, want)
+}
+
+func TestEnterpriseService_ListProvisionedSCIMEnterpriseGroups(t *testing.T) {
+	t.Parallel()
+	client, mux, _ := setup(t)
+
+	mux.HandleFunc("/scim/v2/enterprises/ee/Groups", func(w http.ResponseWriter, r *http.Request) {
+		testMethod(t, r, "GET")
+		testFormValues(t, r, values{
+			"startIndex":         "1",
+			"excludedAttributes": "members,meta",
+			"count":              "3",
+			"filter":             `externalId eq "914a"`,
+		})
+		w.WriteHeader(http.StatusOK)
+		_, _ = w.Write([]byte(`{
+			"schemas": ["` + SCIMSchemasURINamespacesListResponse + `"],
+            "totalResults": 1,
+            "itemsPerPage": 1,
+            "startIndex": 1,
+            "Resources": [{
+                "schemas": ["` + SCIMSchemasURINamespacesGroups + `"],
+                "id": "914a",
+                "externalId": "de88",
+                "displayName": "gn1",
+                "meta": {
+                    "resourceType": "Group",
+                    "created": ` + referenceTimeStr + `,
+                    "lastModified": ` + referenceTimeStr + `,
+                    "location": "https://api.github.com/scim/v2/enterprises/ee/Groups/914a"
+                },
+                "members": [{
+                    "value": "e7f9",
+                    "$ref": "https://api.github.com/scim/v2/enterprises/ee/Users/e7f9",
+                    "display": "d1"
+                }]
+            }]
+        }`))
+	})
+
+	ctx := t.Context()
+	opts := &ListProvisionedSCIMGroupsEnterpriseOptions{
+		StartIndex:         1,
+		ExcludedAttributes: "members,meta",
+		Count:              3,
+		Filter:             `externalId eq "914a"`,
+	}
+	groups, _, err := client.Enterprise.ListProvisionedSCIMGroups(ctx, "ee", opts)
+	if err != nil {
+		t.Errorf("Enterprise.ListProvisionedSCIMGroups returned error: %v", err)
+	}
+
+	want := SCIMEnterpriseGroups{
+		Schemas:      []string{SCIMSchemasURINamespacesListResponse},
+		TotalResults: Ptr(1),
+		ItemsPerPage: Ptr(1),
+		StartIndex:   Ptr(1),
+		Resources: []*SCIMEnterpriseGroupAttributes{{
+			ID: Ptr("914a"),
+			Meta: &SCIMEnterpriseMeta{
+				ResourceType: "Group",
+				Created:      &Timestamp{referenceTime},
+				LastModified: &Timestamp{referenceTime},
+				Location:     Ptr("https://api.github.com/scim/v2/enterprises/ee/Groups/914a"),
+			},
+			DisplayName: Ptr("gn1"),
+			Schemas:     []string{SCIMSchemasURINamespacesGroups},
+			ExternalID:  Ptr("de88"),
+			Members: []*SCIMEnterpriseDisplayReference{{
+				Value:   "e7f9",
+				Ref:     "https://api.github.com/scim/v2/enterprises/ee/Users/e7f9",
+				Display: Ptr("d1"),
+			}},
+		}},
+	}
+
+	if diff := cmp.Diff(want, *groups); diff != "" {
+		t.Errorf("Enterprise.ListProvisionedSCIMGroups diff mismatch (-want +got):\n%v", diff)
+	}
+
+	const methodName = "ListProvisionedSCIMGroups"
+	testBadOptions(t, methodName, func() (err error) {
+		_, _, err = client.Enterprise.ListProvisionedSCIMGroups(ctx, "\n", opts)
+		return err
+	})
+
+	testNewRequestAndDoFailure(t, methodName, client, func() (*Response, error) {
+		_, r, err := client.Enterprise.ListProvisionedSCIMGroups(ctx, "o", opts)
+		return r, err
+	})
+}