egnyte

README

egnyte

Generic Go client for the Egnyte Public API. Policy-free: you name the fields, you interpret the values. Built for SCJ's identity-sync; suitable for general use. Read-only user directory access.

Install

go get github.com/scjalliance/egnyte

Quick start

c, err := egnyte.New(egnyte.Config{Domain: "acme", ClientID: id, ClientSecret: secret})
if err != nil { /* ... */ }
if err := c.Authenticate(ctx, username, password); err != nil { /* ... */ }

users, err := c.ListAllUsers(ctx) // paginates transparently
// one user:
u, err := c.GetUser(ctx, 12345)

Errors are typed — *egnyte.APIError carries the HTTP status and, when present, the X-Mashery-Error-Code.

Docs

• Design spec
• Implementation plan

Documentation

Overview

Package egnyte is a generic, policy-free Go client for the Egnyte Public API.

It provides OAuth2 (resource-owner password grant) authentication, transport, typed errors, retry/backoff, and pagination, plus read access to the user directory. It carries no organization-specific knowledge: callers name the fields they want and interpret the values themselves.

Index

• type APIError
  • func (e *APIError) Error() string
• type Client
  • func New(c Config) (*Client, error)
  • func (c *Client) Authenticate(ctx context.Context, username, password string) error
  • func (c *Client) CreateGroup(ctx context.Context, displayName string, memberIDs []string) (*Group, error)
  • func (c *Client) GetGroup(ctx context.Context, id string) (*Group, error)
  • func (c *Client) GetUser(ctx context.Context, id int) (*User, error)
  • func (c *Client) ListAllGroups(ctx context.Context) ([]Group, error)
  • func (c *Client) ListAllUsers(ctx context.Context) ([]User, error)
  • func (c *Client) ListGroups(ctx context.Context, startIndex, count int) (GroupList, error)
  • func (c *Client) ListUsers(ctx context.Context, startIndex, count int) (UserList, error)
  • func (c *Client) PatchGroupMembers(ctx context.Context, id string, add, remove []string) error
  • func (c *Client) RenameGroup(ctx context.Context, id, newDisplayName string) error
• type Config
• type Group
• type GroupList
• type GroupMember
  • func (m *GroupMember) UnmarshalJSON(data []byte) error
• type Name
• type User
• type UserList

Types

type APIError

type APIError struct {
	Status           int
	Message          string
	MasheryErrorCode string
}

APIError is a non-2xx (or throttle) response from the Egnyte API. MasheryErrorCode carries the X-Mashery-Error-Code header when present.

func (*APIError) Error

func (e *APIError) Error() string

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client talks to the Egnyte Public API. Once authenticated, a Client is safe for concurrent use of its read methods. Authenticate writes the token field unsynchronized and must never run concurrently with any other method call on the same Client, including another Authenticate call.

func New

func New(c Config) (*Client, error)

New validates the config, applies defaults, and returns a Client. Call Authenticate before any API method.

func (*Client) Authenticate

func (c *Client) Authenticate(ctx context.Context, username, password string) error

Authenticate obtains an OAuth2 access token via the resource-owner password grant and stores it on the client. Password-grant tokens carry no refresh token; a later 401 means the caller should Authenticate again.

func (*Client) CreateGroup

func (c *Client) CreateGroup(ctx context.Context, displayName string, memberIDs []string) (*Group, error)

CreateGroup creates an Egnyte group with the given displayName, with memberIDs (Egnyte user ids, decimal strings) inlined so the new group carries its full roster in one call. Returns the created group, including its assigned id.

func (*Client) GetGroup

func (c *Client) GetGroup(ctx context.Context, id string) (*Group, error)

GetGroup fetches one group by its Egnyte group id, with members inlined.

func (*Client) GetUser

func (c *Client) GetUser(ctx context.Context, id int) (*User, error)

GetUser fetches one user by Egnyte's integer id.

func (*Client) ListAllGroups

func (c *Client) ListAllGroups(ctx context.Context) ([]Group, error)

ListAllGroups pages through the whole group directory to exhaustion. Unlike the legacy Make integration, it applies no page cap: it stops only on a short/empty page or once past the server-reported total.

func (*Client) ListAllUsers

func (c *Client) ListAllUsers(ctx context.Context) ([]User, error)

ListAllUsers pages through the whole user directory (active and inactive).

func (*Client) ListGroups

func (c *Client) ListGroups(ctx context.Context, startIndex, count int) (GroupList, error)

ListGroups fetches one page of SCIM groups. startIndex is 1-based (floored to 1); count is clamped to Egnyte's max of 100.

func (*Client) ListUsers

func (c *Client) ListUsers(ctx context.Context, startIndex, count int) (UserList, error)

ListUsers fetches one page of users. startIndex is 1-based (floored to 1); count is clamped to Egnyte's max of 100.

func (*Client) PatchGroupMembers

func (c *Client) PatchGroupMembers(ctx context.Context, id string, add, remove []string) error

PatchGroupMembers adds and/or removes group members by Egnyte user id (decimal strings). Adds carry no operation; removals carry operation "delete". An empty add+remove pair is a no-op that makes no HTTP call.

func (*Client) RenameGroup

func (c *Client) RenameGroup(ctx context.Context, id, newDisplayName string) error

RenameGroup sets a group's displayName. Membership is untouched.

type Config

type Config struct {
	Domain       string       // required; the <x> in https://<x>.egnyte.com (no scheme/slash)
	ClientID     string       // required; Egnyte app key (OAuth client_id)
	ClientSecret string       // required
	BaseURL      string       // default https://{Domain}.egnyte.com; override for tests
	UserAgent    string       // optional
	HTTPClient   *http.Client // default: &http.Client{Timeout: defaultTimeout}
	MaxRetries   *int         // default 3; pointer so 0 is distinguishable from unset
}

Config configures a Client. Domain, ClientID, and ClientSecret are required; the rest default.

type Group

type Group struct {
	ID          string        `json:"id"`
	DisplayName string        `json:"displayName"`
	Members     []GroupMember `json:"members"`
}

Group is an Egnyte SCIM 1.0 group record (identity-relevant fields; other audit/metadata fields returned by the API are tolerated but not surfaced).

type GroupList

type GroupList struct {
	TotalResults int     `json:"totalResults"`
	ItemsPerPage int     `json:"itemsPerPage"`
	StartIndex   int     `json:"startIndex"`
	Resources    []Group `json:"resources"`
}

GroupList is the paged envelope returned by GET /pubapi/v2/groups. It mirrors UserList's SCIM envelope tags.

type GroupMember

type GroupMember struct {
	Value string `json:"value"`
}

GroupMember is a single member entry inside a Group's members list. Value is the member's Egnyte user id (SCIM 1.0 "members":[{"value":...}] shape), normalized to its decimal-string form.

func (*GroupMember) UnmarshalJSON

func (m *GroupMember) UnmarshalJSON(data []byte) error

UnmarshalJSON accepts the SCIM member "value" as either a JSON string or a JSON number. Egnyte returns the numeric user id (matching User.ID), while the SCIM spec nominally types it as a string; tolerate both and normalize to the decimal-string form (== strconv.Itoa(User.ID), the join key consumers rely on). A JSON null (or absent value) yields the empty string.

type Name

type Name struct {
	GivenName  string `json:"givenName"`
	FamilyName string `json:"familyName"`
	Formatted  string `json:"formatted"`
}

Name is an Egnyte user's structured name.

type User

type User struct {
	ID                int    `json:"id"`
	UserName          string `json:"userName"`
	ExternalID        string `json:"externalId"`
	Email             string `json:"email"`
	Name              Name   `json:"name"`
	Active            bool   `json:"active"`
	Locked            bool   `json:"locked"`
	UserType          string `json:"userType"`
	AuthType          string `json:"authType"`
	IdpUserID         string `json:"idpUserId"`
	UserPrincipalName string `json:"userPrincipalName"`
	IsServiceAccount  bool   `json:"isServiceAccount"`
}

User is an Egnyte user directory record (identity-relevant fields; other audit/metadata fields returned by the API are tolerated but not surfaced).

type UserList

type UserList struct {
	TotalResults int    `json:"totalResults"`
	ItemsPerPage int    `json:"itemsPerPage"`
	StartIndex   int    `json:"startIndex"`
	Resources    []User `json:"resources"`
}

UserList is the paged envelope returned by GET /pubapi/v2/users.