github.com/google/go-github/v74@v74.0.0/github/scim.go (about)

     1  // Copyright 2021 The go-github AUTHORS. All rights reserved.
     2  //
     3  // Use of this source code is governed by a BSD-style
     4  // license that can be found in the LICENSE file.
     5  
     6  package github
     7  
     8  import (
     9  	"context"
    10  	"encoding/json"
    11  	"fmt"
    12  )
    13  
    14  // SCIMService provides access to SCIM related functions in the
    15  // GitHub API.
    16  //
    17  // GitHub API docs: https://docs.github.com/rest/scim
    18  type SCIMService service
    19  
    20  // SCIMGroupAttributes represents supported SCIM Group attributes.
    21  //
    22  // GitHub API docs: https://docs.github.com/en/enterprise-cloud@latest/rest/enterprise-admin/scim#list-provisioned-scim-groups-for-an-enterprise
    23  type SCIMGroupAttributes struct {
    24  	DisplayName *string                 `json:"displayName,omitempty"` // The name of the group, suitable for display to end-users. (Optional.)
    25  	Members     []*SCIMDisplayReference `json:"members,omitempty"`     // (Optional.)
    26  	Schemas     []string                `json:"schemas,omitempty"`     // (Optional.)
    27  	ExternalID  *string                 `json:"externalId,omitempty"`  // (Optional.)
    28  	// Only populated as a result of calling ListSCIMProvisionedIdentitiesOptions:
    29  	ID   *string   `json:"id,omitempty"`
    30  	Meta *SCIMMeta `json:"meta,omitempty"`
    31  }
    32  
    33  // SCIMDisplayReference represents a JSON SCIM (System for Cross-domain Identity Management) resource.
    34  type SCIMDisplayReference struct {
    35  	Value   string  `json:"value"`             // (Required.)
    36  	Ref     string  `json:"$ref"`              // (Required.)
    37  	Display *string `json:"display,omitempty"` // (Optional.)
    38  }
    39  
    40  // SCIMUserAttributes represents supported SCIM User attributes.
    41  //
    42  // GitHub API docs: https://docs.github.com/rest/scim#supported-scim-user-attributes
    43  type SCIMUserAttributes struct {
    44  	UserName    string           `json:"userName"`              // Configured by the admin. Could be an email, login, or username. (Required.)
    45  	Name        SCIMUserName     `json:"name"`                  // (Required.)
    46  	DisplayName *string          `json:"displayName,omitempty"` // The name of the user, suitable for display to end-users. (Optional.)
    47  	Emails      []*SCIMUserEmail `json:"emails"`                // User emails. (Required.)
    48  	Schemas     []string         `json:"schemas,omitempty"`     // (Optional.)
    49  	ExternalID  *string          `json:"externalId,omitempty"`  // (Optional.)
    50  	Groups      []string         `json:"groups,omitempty"`      // (Optional.)
    51  	Active      *bool            `json:"active,omitempty"`      // (Optional.)
    52  	// Only populated as a result of calling ListSCIMProvisionedIdentitiesOptions or GetSCIMProvisioningInfoForUser:
    53  	ID   *string   `json:"id,omitempty"`
    54  	Meta *SCIMMeta `json:"meta,omitempty"`
    55  }
    56  
    57  // SCIMUserName represents SCIM user information.
    58  type SCIMUserName struct {
    59  	GivenName  string  `json:"givenName"`           // The first name of the user. (Required.)
    60  	FamilyName string  `json:"familyName"`          // The family name of the user. (Required.)
    61  	Formatted  *string `json:"formatted,omitempty"` // (Optional.)
    62  }
    63  
    64  // SCIMUserEmail represents SCIM user email.
    65  type SCIMUserEmail struct {
    66  	Value   string  `json:"value"`             // (Required.)
    67  	Primary *bool   `json:"primary,omitempty"` // (Optional.)
    68  	Type    *string `json:"type,omitempty"`    // (Optional.)
    69  }
    70  
    71  // SCIMMeta represents metadata about the SCIM resource.
    72  type SCIMMeta struct {
    73  	ResourceType *string    `json:"resourceType,omitempty"`
    74  	Created      *Timestamp `json:"created,omitempty"`
    75  	LastModified *Timestamp `json:"lastModified,omitempty"`
    76  	Location     *string    `json:"location,omitempty"`
    77  }
    78  
    79  // SCIMProvisionedGroups represents the result of calling ListSCIMProvisionedGroupsForEnterprise.
    80  type SCIMProvisionedGroups struct {
    81  	Schemas      []string               `json:"schemas,omitempty"`
    82  	TotalResults *int                   `json:"totalResults,omitempty"`
    83  	ItemsPerPage *int                   `json:"itemsPerPage,omitempty"`
    84  	StartIndex   *int                   `json:"startIndex,omitempty"`
    85  	Resources    []*SCIMGroupAttributes `json:"Resources,omitempty"`
    86  }
    87  
    88  // SCIMProvisionedIdentities represents the result of calling ListSCIMProvisionedIdentities.
    89  type SCIMProvisionedIdentities struct {
    90  	Schemas      []string              `json:"schemas,omitempty"`
    91  	TotalResults *int                  `json:"totalResults,omitempty"`
    92  	ItemsPerPage *int                  `json:"itemsPerPage,omitempty"`
    93  	StartIndex   *int                  `json:"startIndex,omitempty"`
    94  	Resources    []*SCIMUserAttributes `json:"Resources,omitempty"`
    95  }
    96  
    97  // ListSCIMProvisionedIdentitiesOptions represents options for ListSCIMProvisionedIdentities.
    98  //
    99  // GitHub API docs: https://docs.github.com/rest/scim#list-scim-provisioned-identities--parameters
   100  type ListSCIMProvisionedIdentitiesOptions struct {
   101  	StartIndex *int `url:"startIndex,omitempty"` // Used for pagination: the index of the first result to return. (Optional.)
   102  	Count      *int `url:"count,omitempty"`      // Used for pagination: the number of results to return. (Optional.)
   103  	// Filter results using the equals query parameter operator (eq).
   104  	// You can filter results that are equal to id, userName, emails, and external_id.
   105  	// For example, to search for an identity with the userName Octocat, you would use this query: ?filter=userName%20eq%20\"Octocat\".
   106  	// To filter results for the identity with the email octocat@github.com, you would use this query: ?filter=emails%20eq%20\"octocat@github.com\".
   107  	// (Optional.)
   108  	Filter *string `url:"filter,omitempty"`
   109  }
   110  
   111  // ListSCIMProvisionedGroupsForEnterpriseOptions represents options for ListSCIMProvisionedGroupsForEnterprise.
   112  //
   113  // GitHub API docs: https://docs.github.com/en/enterprise-cloud@latest/rest/enterprise-admin/scim#list-provisioned-scim-groups-for-an-enterprise--parameters
   114  type ListSCIMProvisionedGroupsForEnterpriseOptions struct {
   115  	// Filter specifies the matching results to return.
   116  	// Multiple filters are not supported. Possible filters are externalId, id, and displayName.
   117  	// For example: ?filter=externalId eq "9138790-10932-109120392-12321".
   118  	// (Optional.)
   119  	Filter *string `url:"filter,omitempty"`
   120  	// ExcludedAttributes excludes the specified attribute from being returned in the results.
   121  	// Using this parameter can speed up response time. (Optional.)
   122  	ExcludedAttributes *string `url:"excludedAttributes,omitempty"`
   123  	// StartIndex used for pagination: the starting index of the first result to return when paginating through values. (Optional.)
   124  	// Default: 1.
   125  	StartIndex *int `url:"startIndex,omitempty"`
   126  	// Count used for pagination: the number of results to return per page. (Optional.)
   127  	// Default: 30.
   128  	Count *int `url:"count,omitempty"`
   129  }
   130  
   131  // ListSCIMProvisionedIdentities lists SCIM provisioned identities.
   132  //
   133  // GitHub API docs: https://docs.github.com/enterprise-cloud@latest/rest/scim/scim#list-scim-provisioned-identities
   134  //
   135  //meta:operation GET /scim/v2/organizations/{org}/Users
   136  func (s *SCIMService) ListSCIMProvisionedIdentities(ctx context.Context, org string, opts *ListSCIMProvisionedIdentitiesOptions) (*SCIMProvisionedIdentities, *Response, error) {
   137  	u := fmt.Sprintf("scim/v2/organizations/%v/Users", org)
   138  	u, err := addOptions(u, opts)
   139  	if err != nil {
   140  		return nil, nil, err
   141  	}
   142  
   143  	req, err := s.client.NewRequest("GET", u, nil)
   144  	if err != nil {
   145  		return nil, nil, err
   146  	}
   147  
   148  	identities := new(SCIMProvisionedIdentities)
   149  	resp, err := s.client.Do(ctx, req, identities)
   150  	if err != nil {
   151  		return nil, resp, err
   152  	}
   153  
   154  	return identities, resp, nil
   155  }
   156  
   157  // ProvisionAndInviteSCIMUser provisions organization membership for a user, and sends an activation email to the email address.
   158  //
   159  // GitHub API docs: https://docs.github.com/enterprise-cloud@latest/rest/scim/scim#provision-and-invite-a-scim-user
   160  //
   161  //meta:operation POST /scim/v2/organizations/{org}/Users
   162  func (s *SCIMService) ProvisionAndInviteSCIMUser(ctx context.Context, org string, opts *SCIMUserAttributes) (*SCIMUserAttributes, *Response, error) {
   163  	u := fmt.Sprintf("scim/v2/organizations/%v/Users", org)
   164  
   165  	req, err := s.client.NewRequest("POST", u, opts)
   166  	if err != nil {
   167  		return nil, nil, err
   168  	}
   169  
   170  	user := new(SCIMUserAttributes)
   171  	resp, err := s.client.Do(ctx, req, user)
   172  	if err != nil {
   173  		return nil, resp, err
   174  	}
   175  
   176  	return user, resp, nil
   177  }
   178  
   179  // GetSCIMProvisioningInfoForUser returns SCIM provisioning information for a user.
   180  //
   181  // GitHub API docs: https://docs.github.com/enterprise-cloud@latest/rest/scim/scim#get-scim-provisioning-information-for-a-user
   182  //
   183  //meta:operation GET /scim/v2/organizations/{org}/Users/{scim_user_id}
   184  func (s *SCIMService) GetSCIMProvisioningInfoForUser(ctx context.Context, org, scimUserID string) (*SCIMUserAttributes, *Response, error) {
   185  	u := fmt.Sprintf("scim/v2/organizations/%v/Users/%v", org, scimUserID)
   186  	req, err := s.client.NewRequest("GET", u, nil)
   187  	if err != nil {
   188  		return nil, nil, err
   189  	}
   190  
   191  	user := new(SCIMUserAttributes)
   192  	resp, err := s.client.Do(ctx, req, &user)
   193  	if err != nil {
   194  		return nil, resp, err
   195  	}
   196  
   197  	return user, resp, nil
   198  }
   199  
   200  // UpdateProvisionedOrgMembership updates a provisioned organization membership.
   201  //
   202  // GitHub API docs: https://docs.github.com/enterprise-cloud@latest/rest/scim/scim#update-a-provisioned-organization-membership
   203  //
   204  //meta:operation PUT /scim/v2/organizations/{org}/Users/{scim_user_id}
   205  func (s *SCIMService) UpdateProvisionedOrgMembership(ctx context.Context, org, scimUserID string, opts *SCIMUserAttributes) (*Response, error) {
   206  	u := fmt.Sprintf("scim/v2/organizations/%v/Users/%v", org, scimUserID)
   207  	u, err := addOptions(u, opts)
   208  	if err != nil {
   209  		return nil, err
   210  	}
   211  
   212  	req, err := s.client.NewRequest("PUT", u, nil)
   213  	if err != nil {
   214  		return nil, err
   215  	}
   216  
   217  	return s.client.Do(ctx, req, nil)
   218  }
   219  
   220  // UpdateAttributeForSCIMUserOptions represents options for UpdateAttributeForSCIMUser.
   221  //
   222  // GitHub API docs: https://docs.github.com/rest/scim#update-an-attribute-for-a-scim-user--parameters
   223  type UpdateAttributeForSCIMUserOptions struct {
   224  	Schemas    []string                             `json:"schemas,omitempty"` // (Optional.)
   225  	Operations UpdateAttributeForSCIMUserOperations `json:"operations"`        // Set of operations to be performed. (Required.)
   226  }
   227  
   228  // UpdateAttributeForSCIMUserOperations represents operations for UpdateAttributeForSCIMUser.
   229  type UpdateAttributeForSCIMUserOperations struct {
   230  	Op    string          `json:"op"`              // (Required.)
   231  	Path  *string         `json:"path,omitempty"`  // (Optional.)
   232  	Value json.RawMessage `json:"value,omitempty"` // (Optional.)
   233  }
   234  
   235  // UpdateAttributeForSCIMUser updates an attribute for an SCIM user.
   236  //
   237  // GitHub API docs: https://docs.github.com/enterprise-cloud@latest/rest/scim/scim#update-an-attribute-for-a-scim-user
   238  //
   239  //meta:operation PATCH /scim/v2/organizations/{org}/Users/{scim_user_id}
   240  func (s *SCIMService) UpdateAttributeForSCIMUser(ctx context.Context, org, scimUserID string, opts *UpdateAttributeForSCIMUserOptions) (*Response, error) {
   241  	u := fmt.Sprintf("scim/v2/organizations/%v/Users/%v", org, scimUserID)
   242  	u, err := addOptions(u, opts)
   243  	if err != nil {
   244  		return nil, err
   245  	}
   246  
   247  	req, err := s.client.NewRequest("PATCH", u, nil)
   248  	if err != nil {
   249  		return nil, err
   250  	}
   251  
   252  	return s.client.Do(ctx, req, nil)
   253  }
   254  
   255  // DeleteSCIMUserFromOrg deletes SCIM user from an organization.
   256  //
   257  // GitHub API docs: https://docs.github.com/enterprise-cloud@latest/rest/scim/scim#delete-a-scim-user-from-an-organization
   258  //
   259  //meta:operation DELETE /scim/v2/organizations/{org}/Users/{scim_user_id}
   260  func (s *SCIMService) DeleteSCIMUserFromOrg(ctx context.Context, org, scimUserID string) (*Response, error) {
   261  	u := fmt.Sprintf("scim/v2/organizations/%v/Users/%v", org, scimUserID)
   262  	req, err := s.client.NewRequest("DELETE", u, nil)
   263  	if err != nil {
   264  		return nil, err
   265  	}
   266  
   267  	return s.client.Do(ctx, req, nil)
   268  }
   269  
   270  // ListSCIMProvisionedGroupsForEnterprise lists SCIM provisioned groups for an enterprise.
   271  //
   272  // GitHub API docs: https://docs.github.com/enterprise-cloud@latest/rest/enterprise-admin/scim#list-provisioned-scim-groups-for-an-enterprise
   273  //
   274  //meta:operation GET /scim/v2/enterprises/{enterprise}/Groups
   275  func (s *SCIMService) ListSCIMProvisionedGroupsForEnterprise(ctx context.Context, enterprise string, opts *ListSCIMProvisionedGroupsForEnterpriseOptions) (*SCIMProvisionedGroups, *Response, error) {
   276  	u := fmt.Sprintf("scim/v2/enterprises/%v/Groups", enterprise)
   277  	u, err := addOptions(u, opts)
   278  	if err != nil {
   279  		return nil, nil, err
   280  	}
   281  
   282  	req, err := s.client.NewRequest("GET", u, nil)
   283  	if err != nil {
   284  		return nil, nil, err
   285  	}
   286  
   287  	groups := new(SCIMProvisionedGroups)
   288  	resp, err := s.client.Do(ctx, req, groups)
   289  	if err != nil {
   290  		return nil, resp, err
   291  	}
   292  
   293  	return groups, resp, nil
   294  }