scim.go

Documentation: github.com/google/go-github/v55/github

     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/en/rest/scim
    18  type SCIMService service
    19  
    20  // SCIMUserAttributes represents supported SCIM User attributes.
    21  //
    22  // GitHub API docs: https://docs.github.com/en/rest/scim#supported-scim-user-attributes
    23  type SCIMUserAttributes struct {
    24  	UserName    string           `json:"userName"`              // Configured by the admin. Could be an email, login, or username. (Required.)
    25  	Name        SCIMUserName     `json:"name"`                  // (Required.)
    26  	DisplayName *string          `json:"displayName,omitempty"` // The name of the user, suitable for display to end-users. (Optional.)
    27  	Emails      []*SCIMUserEmail `json:"emails"`                // User emails. (Required.)
    28  	Schemas     []string         `json:"schemas,omitempty"`     // (Optional.)
    29  	ExternalID  *string          `json:"externalId,omitempty"`  // (Optional.)
    30  	Groups      []string         `json:"groups,omitempty"`      // (Optional.)
    31  	Active      *bool            `json:"active,omitempty"`      // (Optional.)
    32  	// Only populated as a result of calling ListSCIMProvisionedIdentitiesOptions or GetSCIMProvisioningInfoForUser:
    33  	ID   *string   `json:"id,omitempty"`
    34  	Meta *SCIMMeta `json:"meta,omitempty"`
    35  }
    36  
    37  // SCIMUserName represents SCIM user information.
    38  type SCIMUserName struct {
    39  	GivenName  string  `json:"givenName"`           // The first name of the user. (Required.)
    40  	FamilyName string  `json:"familyName"`          // The family name of the user. (Required.)
    41  	Formatted  *string `json:"formatted,omitempty"` // (Optional.)
    42  }
    43  
    44  // SCIMUserEmail represents SCIM user email.
    45  type SCIMUserEmail struct {
    46  	Value   string  `json:"value"`             // (Required.)
    47  	Primary *bool   `json:"primary,omitempty"` // (Optional.)
    48  	Type    *string `json:"type,omitempty"`    // (Optional.)
    49  }
    50  
    51  // SCIMMeta represents metadata about the SCIM resource.
    52  type SCIMMeta struct {
    53  	ResourceType *string    `json:"resourceType,omitempty"`
    54  	Created      *Timestamp `json:"created,omitempty"`
    55  	LastModified *Timestamp `json:"lastModified,omitempty"`
    56  	Location     *string    `json:"location,omitempty"`
    57  }
    58  
    59  // SCIMProvisionedIdentities represents the result of calling ListSCIMProvisionedIdentities.
    60  type SCIMProvisionedIdentities struct {
    61  	Schemas      []string              `json:"schemas,omitempty"`
    62  	TotalResults *int                  `json:"totalResults,omitempty"`
    63  	ItemsPerPage *int                  `json:"itemsPerPage,omitempty"`
    64  	StartIndex   *int                  `json:"startIndex,omitempty"`
    65  	Resources    []*SCIMUserAttributes `json:"Resources,omitempty"`
    66  }
    67  
    68  // ListSCIMProvisionedIdentitiesOptions represents options for ListSCIMProvisionedIdentities.
    69  //
    70  // Github API docs: https://docs.github.com/en/rest/scim#list-scim-provisioned-identities--parameters
    71  type ListSCIMProvisionedIdentitiesOptions struct {
    72  	StartIndex *int `url:"startIndex,omitempty"` // Used for pagination: the index of the first result to return. (Optional.)
    73  	Count      *int `url:"count,omitempty"`      // Used for pagination: the number of results to return. (Optional.)
    74  	// Filter results using the equals query parameter operator (eq).
    75  	// You can filter results that are equal to id, userName, emails, and external_id.
    76  	// For example, to search for an identity with the userName Octocat, you would use this query: ?filter=userName%20eq%20\"Octocat\".
    77  	// To filter results for the identity with the email octocat@github.com, you would use this query: ?filter=emails%20eq%20\"octocat@github.com\".
    78  	// (Optional.)
    79  	Filter *string `url:"filter,omitempty"`
    80  }
    81  
    82  // ListSCIMProvisionedIdentities lists SCIM provisioned identities.
    83  //
    84  // GitHub API docs: https://docs.github.com/en/rest/scim#list-scim-provisioned-identities
    85  func (s *SCIMService) ListSCIMProvisionedIdentities(ctx context.Context, org string, opts *ListSCIMProvisionedIdentitiesOptions) (*SCIMProvisionedIdentities, *Response, error) {
    86  	u := fmt.Sprintf("scim/v2/organizations/%v/Users", org)
    87  	u, err := addOptions(u, opts)
    88  	if err != nil {
    89  		return nil, nil, err
    90  	}
    91  
    92  	req, err := s.client.NewRequest("GET", u, nil)
    93  	if err != nil {
    94  		return nil, nil, err
    95  	}
    96  
    97  	identities := new(SCIMProvisionedIdentities)
    98  	resp, err := s.client.Do(ctx, req, identities)
    99  	if err != nil {
   100  		return nil, resp, err
   101  	}
   102  
   103  	return identities, resp, nil
   104  }
   105  
   106  // ProvisionAndInviteSCIMUser provisions organization membership for a user, and sends an activation email to the email address.
   107  //
   108  // GitHub API docs: https://docs.github.com/en/rest/scim#provision-and-invite-a-scim-user
   109  func (s *SCIMService) ProvisionAndInviteSCIMUser(ctx context.Context, org string, opts *SCIMUserAttributes) (*Response, error) {
   110  	u := fmt.Sprintf("scim/v2/organizations/%v/Users", org)
   111  	u, err := addOptions(u, opts)
   112  	if err != nil {
   113  		return nil, err
   114  	}
   115  
   116  	req, err := s.client.NewRequest("POST", u, nil)
   117  	if err != nil {
   118  		return nil, err
   119  	}
   120  
   121  	return s.client.Do(ctx, req, nil)
   122  }
   123  
   124  // GetSCIMProvisioningInfoForUser returns SCIM provisioning information for a user.
   125  //
   126  // GitHub API docs: https://docs.github.com/en/rest/scim#supported-scim-user-attributes
   127  func (s *SCIMService) GetSCIMProvisioningInfoForUser(ctx context.Context, org, scimUserID string) (*SCIMUserAttributes, *Response, error) {
   128  	u := fmt.Sprintf("scim/v2/organizations/%v/Users/%v", org, scimUserID)
   129  	req, err := s.client.NewRequest("GET", u, nil)
   130  	if err != nil {
   131  		return nil, nil, err
   132  	}
   133  
   134  	user := new(SCIMUserAttributes)
   135  	resp, err := s.client.Do(ctx, req, &user)
   136  	if err != nil {
   137  		return nil, resp, err
   138  	}
   139  
   140  	return user, resp, nil
   141  }
   142  
   143  // UpdateProvisionedOrgMembership updates a provisioned organization membership.
   144  //
   145  // GitHub API docs: https://docs.github.com/en/rest/scim#update-a-provisioned-organization-membership
   146  func (s *SCIMService) UpdateProvisionedOrgMembership(ctx context.Context, org, scimUserID string, opts *SCIMUserAttributes) (*Response, error) {
   147  	u := fmt.Sprintf("scim/v2/organizations/%v/Users/%v", org, scimUserID)
   148  	u, err := addOptions(u, opts)
   149  	if err != nil {
   150  		return nil, err
   151  	}
   152  
   153  	req, err := s.client.NewRequest("PUT", u, nil)
   154  	if err != nil {
   155  		return nil, err
   156  	}
   157  
   158  	return s.client.Do(ctx, req, nil)
   159  }
   160  
   161  // UpdateAttributeForSCIMUserOptions represents options for UpdateAttributeForSCIMUser.
   162  //
   163  // GitHub API docs: https://docs.github.com/en/rest/scim#update-an-attribute-for-a-scim-user--parameters
   164  type UpdateAttributeForSCIMUserOptions struct {
   165  	Schemas    []string                             `json:"schemas,omitempty"` // (Optional.)
   166  	Operations UpdateAttributeForSCIMUserOperations `json:"operations"`        // Set of operations to be performed. (Required.)
   167  }
   168  
   169  // UpdateAttributeForSCIMUserOperations represents operations for UpdateAttributeForSCIMUser.
   170  type UpdateAttributeForSCIMUserOperations struct {
   171  	Op    string          `json:"op"`              // (Required.)
   172  	Path  *string         `json:"path,omitempty"`  // (Optional.)
   173  	Value json.RawMessage `json:"value,omitempty"` // (Optional.)
   174  }
   175  
   176  // UpdateAttributeForSCIMUser updates an attribute for an SCIM user.
   177  //
   178  // GitHub API docs: https://docs.github.com/en/rest/scim#update-an-attribute-for-a-scim-user
   179  func (s *SCIMService) UpdateAttributeForSCIMUser(ctx context.Context, org, scimUserID string, opts *UpdateAttributeForSCIMUserOptions) (*Response, error) {
   180  	u := fmt.Sprintf("scim/v2/organizations/%v/Users/%v", org, scimUserID)
   181  	u, err := addOptions(u, opts)
   182  	if err != nil {
   183  		return nil, err
   184  	}
   185  
   186  	req, err := s.client.NewRequest("PATCH", u, nil)
   187  	if err != nil {
   188  		return nil, err
   189  	}
   190  
   191  	return s.client.Do(ctx, req, nil)
   192  }
   193  
   194  // DeleteSCIMUserFromOrg deletes SCIM user from an organization.
   195  //
   196  // GitHub API docs: https://docs.github.com/en/rest/scim#delete-a-scim-user-from-an-organization
   197  func (s *SCIMService) DeleteSCIMUserFromOrg(ctx context.Context, org, scimUserID string) (*Response, error) {
   198  	u := fmt.Sprintf("scim/v2/organizations/%v/Users/%v", org, scimUserID)
   199  	req, err := s.client.NewRequest("DELETE", u, nil)
   200  	if err != nil {
   201  		return nil, err
   202  	}
   203  
   204  	return s.client.Do(ctx, req, nil)
   205  }
   206
View as plain text