{"id":21655948,"url":"https://github.com/koltyakov/gosip-docs","last_synced_at":"2025-04-11T21:33:02.153Z","repository":{"id":73404505,"uuid":"231556187","full_name":"koltyakov/gosip-docs","owner":"koltyakov","description":"📚 Docs: SharePoint authentication, HTTP client \u0026 fluent API wrapper for Go (Golang)","archived":false,"fork":false,"pushed_at":"2024-07-04T15:28:57.000Z","size":1104,"stargazers_count":9,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-25T17:23:36.714Z","etag":null,"topics":["api","authentication","docs","fluent-api","go","golang","sharepoint"],"latest_commit_sha":null,"homepage":"https://github.com/koltyakov/gosip","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/koltyakov.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"contributing/overview.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-01-03T09:34:05.000Z","updated_at":"2024-07-04T15:29:01.000Z","dependencies_parsed_at":"2024-11-25T08:38:07.500Z","dependency_job_id":"7d5d2280-541e-4b1f-9f9d-fd8c89ad8a07","html_url":"https://github.com/koltyakov/gosip-docs","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/koltyakov%2Fgosip-docs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/koltyakov%2Fgosip-docs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/koltyakov%2Fgosip-docs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/koltyakov%2Fgosip-docs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/koltyakov","download_url":"https://codeload.github.com/koltyakov/gosip-docs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248482991,"owners_count":21111411,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","authentication","docs","fluent-api","go","golang","sharepoint"],"created_at":"2024-11-25T08:37:53.871Z","updated_at":"2025-04-11T21:33:02.131Z","avatar_url":"https://github.com/koltyakov.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"---\ndescription: ⚡️ SharePoint SDK for Go (Golang)\n---\n\n# Introduction\n\n![Build Status](https://koltyakov.visualstudio.com/SPNode/\\_apis/build/status/gosip?branchName=master) [![Go Report Card](https://goreportcard.com/badge/github.com/koltyakov/gosip)](https://goreportcard.com/report/github.com/koltyakov/gosip) [![codecov](https://codecov.io/gh/koltyakov/gosip/branch/master/graph/badge.svg)](https://codecov.io/gh/koltyakov/gosip) [![License](https://img.shields.io/github/license/koltyakov/gosip.svg)](https://github.com/koltyakov/gosip/blob/master/LICENSE) [![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go)\n\n![](.gitbook/assets/gosip.png)\n\n## Main features\n\n* Unattended authentication using different strategies.\n* [Fluent API](api/fluent.md) syntax for SharePoint object model.\n* Simplified API consumption (REST, CSOM, SOAP, etc.).\n* SharePoint-aware embedded features (retries, header presets, error handling).\n\n### Supported SharePoint versions\n\n* SharePoint Online (SPO).\n* On-Premises (2019/2016/2013).\n\n### Supported auth strategies\n\n* SharePoint Online:\n  * [Azure Certificate (App Only)](auth/strategies/azure-certificate-auth.md)\n  * [Azure Username/Password](auth/strategies/azure-creds-auth.md)\n  * [SAML](auth/strategies/saml.md) based with user credentials\n  * [Add-In only](auth/strategies/addin/) permissions\n  * ADFS user credentials (automatically detects in [SAML](auth/strategies/saml.md) strategy)\n  * [Azure Device flow](auth/strategies/azure-device-flow.md)\n  * [On-Demand authentication](auth/strategies/on-demand.md)\n* SharePoint On-Premises 2019/2016/2013:\n  * [User credentials](auth/strategies/ntlm.md) (NTLM)\n  * [ADFS user credentials](auth/strategies/adfs.md) (ADFS, WAP -\u003e Basic/NTLM, WAP -\u003e ADFS)\n  * Behind a reverse proxy ([Forefront TMG](auth/strategies/tmg.md), [WAP -\u003e Basic/NTLM](auth/strategies/adfs.md), [WAP -\u003e ADFS](auth/strategies/adfs.md))\n  * [Form-based authentication](auth/strategies/fba.md) (FBA)\n  * [On-Demand authentication](auth/strategies/on-demand.md)\n\n## Installation\n\n```bash\ngo get github.com/koltyakov/gosip\n```\n\n## Usage insights\n\n### Understand SharePoint environment type and authentication strategy\n\nLet's assume it's SharePoint Online and Add-In Only permissions. Then `strategy \"github.com/koltyakov/gosip/auth/addin\"` sub package should be used.\n\n```go\npackage main\n\nimport (\n  \"github.com/koltyakov/gosip\"\n  \"github.com/koltyakov/gosip/api\"\n  strategy \"github.com/koltyakov/gosip/auth/addin\"\n)\n```\n\n### Initiate authentication object\n\n```go\nauth := \u0026strategy.AuthCnfg{\n  SiteURL:      os.Getenv(\"SPAUTH_SITEURL\"),\n  ClientID:     os.Getenv(\"SPAUTH_CLIENTID\"),\n  ClientSecret: os.Getenv(\"SPAUTH_CLIENTSECRET\"),\n}\n```\n\nAuthCnfg's from different strategies contains different options relevant for a specified auth type.\n\nThe authentication options can be provided explicitly or can be read from a configuration file (see [more](auth/overview.md#authentication-strategies)).\n\n```go\nconfigPath := \"./config/private.json\"\nauth := \u0026strategy.AuthCnfg{}\n\nerr := auth.ReadConfig(configPath)\nif err != nil {\n  fmt.Printf(\"Unable to get config: %v\\n\", err)\n  return\n}\n```\n\n### Bind auth client with Fluent API\n\n```go\nclient := \u0026gosip.SPClient{AuthCnfg: auth}\n\nsp := api.NewSP(client)\n\nres, err := sp.Web().Select(\"Title\").Get()\nif err != nil {\n  fmt.Println(err)\n}\n\nfmt.Printf(\"%s\\n\", res.Data().Title)\n```\n\n## Usage samples\n\n### Fluent API client\n\nProvides a simple way of constructing API endpoint calls with IntelliSense and chainable syntax.\n\n```go\npackage main\n\nimport (\n  \"encoding/json\"\n  \"fmt\"\n  \"log\"\n\n  \"github.com/koltyakov/gosip\"\n  \"github.com/koltyakov/gosip/api\"\n  strategy \"github.com/koltyakov/gosip/auth/addin\"\n)\n\nfunc main() {\n  // Getting auth params and client\n  client, err := getAuthClient()\n  if err != nil {\n    log.Fatalln(err)\n  }\n\n  // Binding SharePoint API\n  sp := api.NewSP(client)\n\n  // Custom headers\n  headers := map[string]string{\n    \"Accept\": \"application/json;odata=minimalmetadata\",\n    \"Accept-Language\": \"de-DE,de;q=0.9\",\n  }\n  config := \u0026api.RequestConfig{Headers: headers}\n\n  // Chainable request sample\n  data, err := sp.Conf(config).Web().Lists().Select(\"Id,Title\").Get()\n  if err != nil {\n    log.Fatalln(err)\n  }\n\n  // Response object unmarshalling\n  // (struct depends on OData mode and API method)\n  res := \u0026struct {\n    Value []struct {\n      ID    string `json:\"Id\"`\n      Title string `json:\"Title\"`\n    } `json:\"value\"`\n  }{}\n\n  if err := json.Unmarshal(data, \u0026res); err != nil {\n    log.Fatalf(\"unable to parse the response: %v\", err)\n  }\n\n  for _, list := range res.Value {\n    fmt.Printf(\"%+v\\n\", list)\n  }\n\n}\n\nfunc getAuthClient() (*gosip.SPClient, error) {\n  configPath := \"./config/private.spo-addin.json\" // \u003c- file with creds\n  auth := \u0026strategy.AuthCnfg{}\n  if err := auth.ReadConfig(configPath); err != nil {\n    return nil, fmt.Errorf(\"unable to get config: %v\", err)\n  }\n  return \u0026gosip.SPClient{AuthCnfg: auth}, nil\n}\n```\n\n### Generic HTTP-client helper\n\nProvides generic GET/POST helpers for REST operations, reducing amount of `http.NewRequest` scaffolded code, can be used for custom or not covered with a Fluent API endpoints.\n\n```go\npackage main\n\nimport (\n  \"fmt\"\n  \"log\"\n\n  \"github.com/koltyakov/gosip\"\n  \"github.com/koltyakov/gosip/api\"\n  strategy \"github.com/koltyakov/gosip/auth/ntlm\"\n)\n\nfunc main() {\n  configPath := \"./config/private.ntlm.json\"\n  auth := \u0026strategy.AuthCnfg{}\n\n  if err := auth.ReadConfig(configPath); err != nil {\n    log.Fatalf(\"unable to get config: %v\\n\", err)\n  }\n\n  sp := api.NewHTTPClient(\u0026gosip.SPClient{AuthCnfg: auth})\n\n  endpoint := auth.GetSiteURL() + \"/_api/web?$select=Title\"\n\n  data, err := sp.Get(endpoint, nil)\n  if err != nil {\n    log.Fatalf(\"%v\\n\", err)\n  }\n\n  // sp.Post(endpoint, []byte(body), nil) // generic POST\n\n  // generic DELETE helper crafts \"X-Http-Method\"=\"DELETE\" header\n  // sp.Delete(endpoint, nil)\n\n  // generic UPDATE helper crafts \"X-Http-Method\"=\"MERGE\" header\n  // sp.Update(endpoint, nil)\n\n  // CSOM helper (client.svc/ProcessQuery)\n  // sp.ProcessQuery(endpoint, []byte(body))\n\n  fmt.Printf(\"response: %s\\n\", data)\n}\n```\n\n### Low-level HTTP-client usage\n\nLow-lever SharePoint-aware HTTP client from `github.com/koltyakov/gosip` package for custom or not covered with a Fluent API client endpoints with granular control for HTTP request, response, and `http.Client` parameters. Used internally but almost never required in a consumer code.\n\n```go\nclient := \u0026gosip.SPClient{AuthCnfg: auth}\n\nvar req *http.Request\n// Initiate API request\n// ...\n\nresp, err := client.Execute(req)\nif err != nil {\n  fmt.Printf(\"Unable to request api: %v\", err)\n  return\n}\n```\n\nSPClient has `Execute` method which is a wrapper function injecting SharePoint authentication and ending up calling `http.Client`'s `Do` method.\n\n## Reference\n\nMany auth flows have been \"copied\" from [node-sp-auth](https://github.com/s-kainet/node-sp-auth) library (used as a blueprint), which we intensively use in Node.js ecosystem for years.\n\nFluent API and wrapper syntax are inspired by [PnPjs](https://github.com/pnp/pnpjs) which is also the first-class citizen on almost all our Node.js and front-end projects with SharePoint involved.\n\n## License\n\n[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Fkoltyakov%2Fgosip.svg?type=large)](https://app.fossa.io/projects/git%2Bgithub.com%2Fkoltyakov%2Fgosip?ref=badge\\_large)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkoltyakov%2Fgosip-docs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkoltyakov%2Fgosip-docs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkoltyakov%2Fgosip-docs/lists"}