github.com/google/go-github/v69@v69.2.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  // ListSCIMProvisionedIdentities lists SCIM provisioned identities.
   112  //
   113  // GitHub API docs: https://docs.github.com/enterprise-cloud@latest/rest/scim/scim#list-scim-provisioned-identities
   114  //
   115  //meta:operation GET /scim/v2/organizations/{org}/Users
   116  func (s *SCIMService) ListSCIMProvisionedIdentities(ctx context.Context, org string, opts *ListSCIMProvisionedIdentitiesOptions) (*SCIMProvisionedIdentities, *Response, error) {
   117  	u := fmt.Sprintf("scim/v2/organizations/%v/Users", org)
   118  	u, err := addOptions(u, opts)
   119  	if err != nil {
   120  		return nil, nil, err
   121  	}
   122  
   123  	req, err := s.client.NewRequest("GET", u, nil)
   124  	if err != nil {
   125  		return nil, nil, err
   126  	}
   127  
   128  	identities := new(SCIMProvisionedIdentities)
   129  	resp, err := s.client.Do(ctx, req, identities)
   130  	if err != nil {
   131  		return nil, resp, err
   132  	}
   133  
   134  	return identities, resp, nil
   135  }
   136  
   137  // ProvisionAndInviteSCIMUser provisions organization membership for a user, and sends an activation email to the email address.
   138  //
   139  // GitHub API docs: https://docs.github.com/enterprise-cloud@latest/rest/scim/scim#provision-and-invite-a-scim-user
   140  //
   141  //meta:operation POST /scim/v2/organizations/{org}/Users
   142  func (s *SCIMService) ProvisionAndInviteSCIMUser(ctx context.Context, org string, opts *SCIMUserAttributes) (*SCIMUserAttributes, *Response, error) {
   143  	u := fmt.Sprintf("scim/v2/organizations/%v/Users", org)
   144  
   145  	req, err := s.client.NewRequest("POST", u, opts)
   146  	if err != nil {
   147  		return nil, nil, err
   148  	}
   149  
   150  	user := new(SCIMUserAttributes)
   151  	resp, err := s.client.Do(ctx, req, user)
   152  	if err != nil {
   153  		return nil, resp, err
   154  	}
   155  
   156  	return user, resp, nil
   157  }
   158  
   159  // GetSCIMProvisioningInfoForUser returns SCIM provisioning information for a user.
   160  //
   161  // GitHub API docs: https://docs.github.com/enterprise-cloud@latest/rest/scim/scim#get-scim-provisioning-information-for-a-user
   162  //
   163  //meta:operation GET /scim/v2/organizations/{org}/Users/{scim_user_id}
   164  func (s *SCIMService) GetSCIMProvisioningInfoForUser(ctx context.Context, org, scimUserID string) (*SCIMUserAttributes, *Response, error) {
   165  	u := fmt.Sprintf("scim/v2/organizations/%v/Users/%v", org, scimUserID)
   166  	req, err := s.client.NewRequest("GET", u, nil)
   167  	if err != nil {
   168  		return nil, nil, err
   169  	}
   170  
   171  	user := new(SCIMUserAttributes)
   172  	resp, err := s.client.Do(ctx, req, &user)
   173  	if err != nil {
   174  		return nil, resp, err
   175  	}
   176  
   177  	return user, resp, nil
   178  }
   179  
   180  // UpdateProvisionedOrgMembership updates a provisioned organization membership.
   181  //
   182  // GitHub API docs: https://docs.github.com/enterprise-cloud@latest/rest/scim/scim#update-a-provisioned-organization-membership
   183  //
   184  //meta:operation PUT /scim/v2/organizations/{org}/Users/{scim_user_id}
   185  func (s *SCIMService) UpdateProvisionedOrgMembership(ctx context.Context, org, scimUserID string, opts *SCIMUserAttributes) (*Response, error) {
   186  	u := fmt.Sprintf("scim/v2/organizations/%v/Users/%v", org, scimUserID)
   187  	u, err := addOptions(u, opts)
   188  	if err != nil {
   189  		return nil, err
   190  	}
   191  
   192  	req, err := s.client.NewRequest("PUT", u, nil)
   193  	if err != nil {
   194  		return nil, err
   195  	}
   196  
   197  	return s.client.Do(ctx, req, nil)
   198  }
   199  
   200  // UpdateAttributeForSCIMUserOptions represents options for UpdateAttributeForSCIMUser.
   201  //
   202  // GitHub API docs: https://docs.github.com/rest/scim#update-an-attribute-for-a-scim-user--parameters
   203  type UpdateAttributeForSCIMUserOptions struct {
   204  	Schemas    []string                             `json:"schemas,omitempty"` // (Optional.)
   205  	Operations UpdateAttributeForSCIMUserOperations `json:"operations"`        // Set of operations to be performed. (Required.)
   206  }
   207  
   208  // UpdateAttributeForSCIMUserOperations represents operations for UpdateAttributeForSCIMUser.
   209  type UpdateAttributeForSCIMUserOperations struct {
   210  	Op    string          `json:"op"`              // (Required.)
   211  	Path  *string         `json:"path,omitempty"`  // (Optional.)
   212  	Value json.RawMessage `json:"value,omitempty"` // (Optional.)
   213  }
   214  
   215  // UpdateAttributeForSCIMUser updates an attribute for an SCIM user.
   216  //
   217  // GitHub API docs: https://docs.github.com/enterprise-cloud@latest/rest/scim/scim#update-an-attribute-for-a-scim-user
   218  //
   219  //meta:operation PATCH /scim/v2/organizations/{org}/Users/{scim_user_id}
   220  func (s *SCIMService) UpdateAttributeForSCIMUser(ctx context.Context, org, scimUserID string, opts *UpdateAttributeForSCIMUserOptions) (*Response, error) {
   221  	u := fmt.Sprintf("scim/v2/organizations/%v/Users/%v", org, scimUserID)
   222  	u, err := addOptions(u, opts)
   223  	if err != nil {
   224  		return nil, err
   225  	}
   226  
   227  	req, err := s.client.NewRequest("PATCH", u, nil)
   228  	if err != nil {
   229  		return nil, err
   230  	}
   231  
   232  	return s.client.Do(ctx, req, nil)
   233  }
   234  
   235  // DeleteSCIMUserFromOrg deletes SCIM user from an organization.
   236  //
   237  // GitHub API docs: https://docs.github.com/enterprise-cloud@latest/rest/scim/scim#delete-a-scim-user-from-an-organization
   238  //
   239  //meta:operation DELETE /scim/v2/organizations/{org}/Users/{scim_user_id}
   240  func (s *SCIMService) DeleteSCIMUserFromOrg(ctx context.Context, org, scimUserID string) (*Response, error) {
   241  	u := fmt.Sprintf("scim/v2/organizations/%v/Users/%v", org, scimUserID)
   242  	req, err := s.client.NewRequest("DELETE", u, nil)
   243  	if err != nil {
   244  		return nil, err
   245  	}
   246  
   247  	return s.client.Do(ctx, req, nil)
   248  }
   249  
   250  // ListSCIMProvisionedGroupsForEnterprise lists SCIM provisioned groups for an enterprise.
   251  //
   252  // GitHub API docs: https://docs.github.com/enterprise-cloud@latest/rest/enterprise-admin/scim#list-provisioned-scim-groups-for-an-enterprise
   253  //
   254  //meta:operation GET /scim/v2/enterprises/{enterprise}/Groups
   255  func (s *SCIMService) ListSCIMProvisionedGroupsForEnterprise(ctx context.Context, enterprise string, opts *ListSCIMProvisionedIdentitiesOptions) (*SCIMProvisionedGroups, *Response, error) {
   256  	u := fmt.Sprintf("scim/v2/enterprises/%v/Groups", enterprise)
   257  
   258  	req, err := s.client.NewRequest("GET", u, nil)
   259  	if err != nil {
   260  		return nil, nil, err
   261  	}
   262  
   263  	groups := new(SCIMProvisionedGroups)
   264  	resp, err := s.client.Do(ctx, req, groups)
   265  	if err != nil {
   266  		return nil, resp, err
   267  	}
   268  
   269  	return groups, resp, nil
   270  }