{"id":13414057,"url":"https://github.com/koltyakov/gosip","last_synced_at":"2025-04-10T02:28:38.629Z","repository":{"id":46042824,"uuid":"167668490","full_name":"koltyakov/gosip","owner":"koltyakov","description":"⚡️ SharePoint SDK for Go","archived":false,"fork":false,"pushed_at":"2024-02-27T19:01:03.000Z","size":1911,"stargazers_count":133,"open_issues_count":10,"forks_count":31,"subscribers_count":8,"default_branch":"master","last_synced_at":"2024-04-14T23:12:09.789Z","etag":null,"topics":["api","authentication","client","fluent-api","go","golang","golang-library","rest","sharepoint","sharepoint-online"],"latest_commit_sha":null,"homepage":"https://go.spflow.com","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/koltyakov.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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":"2019-01-26T08:48:48.000Z","updated_at":"2024-06-18T15:36:50.101Z","dependencies_parsed_at":"2024-06-18T15:36:47.895Z","dependency_job_id":"36035def-1cdd-492e-8a48-871f929d2bea","html_url":"https://github.com/koltyakov/gosip","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","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/koltyakov%2Fgosip/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/koltyakov%2Fgosip/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/koltyakov%2Fgosip/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/koltyakov","download_url":"https://codeload.github.com/koltyakov/gosip/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248143947,"owners_count":21054850,"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","client","fluent-api","go","golang","golang-library","rest","sharepoint","sharepoint-online"],"created_at":"2024-07-30T20:01:56.494Z","updated_at":"2025-04-10T02:28:38.594Z","avatar_url":"https://github.com/koltyakov.png","language":"Go","funding_links":[],"categories":["Third-party APIs","第三方api","第三方API","Utility","第三方API`第三方API 汇总`"],"sub_categories":["Utility/Miscellaneous","Fail injection","实用程序/Miscellaneous","查询语","HTTP Clients"],"readme":"# Gosip - SharePoint SDK for Go (Golang)\n\n\u003e Authentication, HTTP client \u0026 fluent API wrapper\n\n![Build Status](https://koltyakov.visualstudio.com/SPNode/_apis/build/status/gosip?branchName=master)\n[![Go Report Card](https://goreportcard.com/badge/github.com/koltyakov/gosip)](https://goreportcard.com/report/github.com/koltyakov/gosip)\n[![GoDoc](https://godoc.org/github.com/koltyakov/gosip?status.svg)](https://godoc.org/github.com/koltyakov/gosip)\n[![License](https://img.shields.io/github/license/koltyakov/gosip.svg)](https://github.com/koltyakov/gosip/blob/master/LICENSE)\n[![codecov](https://codecov.io/gh/koltyakov/gosip/branch/master/graph/badge.svg)](https://codecov.io/gh/koltyakov/gosip)\n[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Fkoltyakov%2Fgosip.svg?type=shield)](https://app.fossa.io/projects/git%2Bgithub.com%2Fkoltyakov%2Fgosip?ref=badge_shield)\n[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go)\n\n\u003c!--suppress HtmlDeprecatedAttribute --\u003e\n\u003cdiv align=\"center\"\u003e\n  \u003cimg alt=\"Gosip\" src=\"https://raw.githubusercontent.com/koltyakov/gosip-docs/master/.gitbook/assets/gosip.png\" /\u003e\n\u003c/div\u003e\n\n## Main features\n\n- Unattended authentication using different strategies.\n- Fluent API syntax for SharePoint object model.\n- Simplified API consumption (REST, CSOM, SOAP).\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\n  - Azure Certificate (App Only) [🔗](https://go.spflow.com/auth/strategies/azure-certificate-auth)\n  - Azure Username/Password [🔗](https://go.spflow.com/auth/strategies/azure-creds-auth)\n  - Azure Device Flow [🔗](https://go.spflow.com/auth/strategies/azure-device-flow)\n  - SAML based with user credentials\n  - Add-In only permissions\n  - ADFS user credentials (automatically detects in SAML strategy)\n  - On-Demand auth [🔗](https://github.com/koltyakov/gosip-sandbox/tree/master/strategies/ondemand)\n\n- SharePoint On-Premises 2019/2016/2013:\n  - User credentials (NTLM)\n  - ADFS user credentials (ADFS, WAP -\u003e Basic/NTLM, WAP -\u003e ADFS)\n  - Behind a reverse proxy (Forefront TMG, WAP -\u003e Basic/NTLM, WAP -\u003e ADFS)\n  - Form-based authentication (FBA)\n  - On-Demand auth [🔗](https://github.com/koltyakov/gosip-sandbox/tree/master/strategies/ondemand)\n\n## Installation\n\n```bash\ngo get github.com/koltyakov/gosip\n```\n\n## Usage insights\n\n1\\. 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\"` subpackage should be used.\n\n```golang\npackage main\n\nimport (\n\t\"github.com/koltyakov/gosip\"\n\t\"github.com/koltyakov/gosip/api\"\n\tstrategy \"github.com/koltyakov/gosip/auth/addin\"\n)\n```\n\n2\\. Initiate an authentication object.\n\n```golang\nauth := \u0026strategy.AuthCnfg{\n\tSiteURL:      os.Getenv(\"SPAUTH_SITEURL\"),\n\tClientID:     os.Getenv(\"SPAUTH_CLIENTID\"),\n\tClientSecret: os.Getenv(\"SPAUTH_CLIENTSECRET\"),\n}\n```\n\nAuthCnfg 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.\n\n```golang\nconfigPath := \"./config/private.json\"\nauth := \u0026strategy.AuthCnfg{}\n\nerr := auth.ReadConfig(configPath)\nif err != nil {\n\tfmt.Printf(\"Unable to get config: %v\\n\", err)\n\treturn\n}\n```\n\n3\\. Bind auth client with Fluent API.\n\n```golang\nclient := \u0026gosip.SPClient{AuthCnfg: auth}\n\nsp := api.NewSP(client)\n\nres, err := sp.Web().Select(\"Title\").Get()\nif err != nil {\n\tfmt.Println(err)\n}\n\nfmt.Printf(\"%s\\n\", res.Data().Title)\n```\n\n## Usage samples\n\n### Fluent API client\n\nFluent API gives a simple way of constructing API endpoint calls with IntelliSense and chainable syntax.\n\n![Fluent Sample](https://raw.githubusercontent.com/koltyakov/gosip-docs/master/.gitbook/assets/fluent.gif)\n\n```golang\npackage main\n\nimport (\n\t\"encoding/json\"\n\t\"fmt\"\n\t\"log\"\n\n\t\"github.com/koltyakov/gosip\"\n\t\"github.com/koltyakov/gosip/api\"\n\tstrategy \"github.com/koltyakov/gosip/auth/addin\"\n)\n\nfunc main() {\n\t// Getting auth params and client\n\tclient, err := getAuthClient()\n\tif err != nil {\n\t\tlog.Fatalln(err)\n\t}\n\n\t// Binding SharePoint API\n\tsp := api.NewSP(client)\n\n\t// Custom headers\n\theaders := map[string]string{\n\t\t\"Accept\": \"application/json;odata=minimalmetadata\",\n\t\t\"Accept-Language\": \"de-DE,de;q=0.9\",\n\t}\n\tconfig := \u0026api.RequestConfig{Headers: headers}\n\n\t// Chainable request sample\n\tdata, err := sp.Conf(config).Web().Lists().Select(\"Id,Title\").Get()\n\tif err != nil {\n\t\tlog.Fatalln(err)\n\t}\n\n\t// Response object unmarshalling (struct depends on OData mode and API method)\n\tres := \u0026struct {\n\t\tValue []struct {\n\t\t\tID    string `json:\"Id\"`\n\t\t\tTitle string `json:\"Title\"`\n\t\t} `json:\"value\"`\n\t}{}\n\n\tif err := json.Unmarshal(data, \u0026res); err != nil {\n\t\tlog.Fatalf(\"unable to parse the response: %v\", err)\n\t}\n\n\tfor _, list := range res.Value {\n\t\tfmt.Printf(\"%+v\\n\", list)\n\t}\n\n}\n\nfunc getAuthClient() (*gosip.SPClient, error) {\n\tconfigPath := \"./config/private.spo-addin.json\"\n\tauth := \u0026strategy.AuthCnfg{}\n\tif err := auth.ReadConfig(configPath); err != nil {\n\t\treturn nil, fmt.Errorf(\"unable to get config: %v\", err)\n\t}\n\treturn \u0026gosip.SPClient{AuthCnfg: auth}, nil\n}\n```\n\n### Generic HTTP client helper\n\nProvides generic GET/POST helpers for REST operations, reducing the amount of `http.NewRequest` scaffolded code, can be used for custom or not covered with Fluent API endpoints.\n\n```golang\npackage main\n\nimport (\n\t\"fmt\"\n\t\"log\"\n\n\t\"github.com/koltyakov/gosip\"\n\t\"github.com/koltyakov/gosip/api\"\n\tstrategy \"github.com/koltyakov/gosip/auth/ntlm\"\n)\n\nfunc main() {\n\tconfigPath := \"./config/private.ntlm.json\"\n\tauth := \u0026strategy.AuthCnfg{}\n\n\tif err := auth.ReadConfig(configPath); err != nil {\n\t\tlog.Fatalf(\"unable to get config: %v\\n\", err)\n\t}\n\n\tsp := api.NewHTTPClient(\u0026gosip.SPClient{AuthCnfg: auth})\n\n\tendpoint := auth.GetSiteURL() + \"/_api/web?$select=Title\"\n\n\tdata, err := sp.Get(endpoint, nil)\n\tif err != nil {\n\t\tlog.Fatalf(\"%v\\n\", err)\n\t}\n\n\t// sp.Post(endpoint, body, nil) // generic POST\n\t// sp.Delete(endpoint, nil) // generic DELETE helper crafts \"X-Http-Method\"=\"DELETE\" header\n\t// sp.Update(endpoint, nil) // generic UPDATE helper crafts \"X-Http-Method\"=\"MERGE\" header\n\t// sp.ProcessQuery(endpoint, body) // CSOM helper (client.svc/ProcessQuery)\n\n\tfmt.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 an HTTP request, response, and http.Client parameters. The client is used internally but rarely required in consumer code.\n\n```golang\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\tfmt.Printf(\"Unable to request api: %v\", err)\n\treturn\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## Authentication strategies\n\nAuth strategy should be selected corresponding to your SharePoint environment and its configuration.\n\nImport path `strategy \"github.com/koltyakov/gosip/auth/{strategy}\"`. Where `/{strategy}` stands for a strategy auth package.\n\nAzure AD based strategies (recommended production use with SharePoint Online):\n\n| `/{strategy}` | Description                                       | Credentials sample(s)                                                   |\n| ------------- | ------------------------------------------------- | ------------------------ |\n| `/azurecert`  | Azure AD Certificate authentication               | [details](https://go.spflow.com/auth/strategies/azure-certificate-auth) |\n| `/azurecreds` | Azure AD authorization with username and password | [details](https://go.spflow.com/auth/strategies/azure-creds-auth) |\n| `/azureenv`   | Azure AD environment-based authentication         | [details](https://go.spflow.com/auth/strategies/azure-environment-auth) |\n| `/device`     | Azure AD Device Token authentication              | [details](https://go.spflow.com/auth/strategies/azure-device-flow) |\n\nOther strategies:\n\n| `/{strategy}` | SPO | On-Prem | Credentials sample(s)                                                                                                                                          |\n| ------------- | --- | ------- | ------------------ |\n| `/saml`       | ✅  | ❌      | [details](https://go.spflow.com/auth/strategies/saml) |\n| `/addin`      | ✅  | ❌      | [details](https://go.spflow.com/auth/strategies/addin) |\n| `/ntlm`       | ❌  | ✅      | [details](https://go.spflow.com/auth/strategies/ntlm) |\n| `/adfs`       | ✅  | ✅      | [details](https://go.spflow.com/auth/strategies/adfs) |\n| `/fba`        | ❌  | ✅      | [details](https://go.spflow.com/auth/strategies/fba) |\n| `/tmg`        | ❌  | ✅      | [details](https://go.spflow.com/auth/strategies/tmg) |\n| `/ondemand`   | ✅  | ✅      | [details](https://go.spflow.com/auth/custom-auth/on-demand) |\n\nEnvironment should configured for a specific auth strategy. E.g. you won't succeed with `adfs` in SPO if it has not setup properly.\n\nBelow are the most commonly authentication methods in more details:\n\n### Azure AD application authentication\n\nAzure AD application authentication is a recommended way for production use with SharePoint Online. It's based on OAuth 2.0 protocol and uses AAD application credentials for authentication.\n\nDepending on an application type, there are different authentication strategies:\n\n- Azure AD Certificate authentication: for headless applications, which are not able to provide user interaction, like a background service or a daemon. It uses a certificate to authenticate an application.\n- Azure AD authorization with username and password: for applications which are able to provide user interaction, like a desktop application or CLI with credentials prompt. It uses a username and password to authenticate a user.\n- Azure AD device token authentication: for applications which are able to provide user interaction, like a desktop application or CLI. It uses a device code to authenticate a user. It also supports multi-factor authentication.\n\n### SAML Auth (SharePoint Online user credentials authentication)\n\nThis authentication option uses Microsoft Online Security Token Service `https://login.microsoftonline.com/extSTS.srf` and SAML tokens in order to obtain an authentication cookie.\n\n```golang\n// AuthCnfg - SAML auth config structure\ntype AuthCnfg struct {\n\t// SPSite or SPWeb URL, which is the context target for the API calls\n\tSiteURL string `json:\"siteUrl\"`\n\t// Username for SharePoint Online, for example `[user]@[company].onmicrosoft.com`\n\tUsername string `json:\"username\"`\n\t// User or App password\n\tPassword string `json:\"password\"`\n}\n```\n\n### AddIn Only Auth\n\nThis type of authentication uses AddIn Only policy and OAuth bearer tokens for authenticating HTTP requests.\n\n```golang\n// AuthCnfg - AddIn Only auth config structure\ntype AuthCnfg struct {\n\t// SPSite or SPWeb URL, which is the context target for the API calls\n\tSiteURL string `json:\"siteUrl\"`\n\t// Client ID obtained when registering the AddIn\n\tClientID string `json:\"clientId\"`\n\t// Client Secret obtained when registering the AddIn\n\tClientSecret string `json:\"clientSecret\"`\n\t// Your SharePoint Online tenant ID (optional)\n\tRealm string `json:\"realm\"`\n}\n```\n\nRealm can be left empty or filled in, which will add small performance improvement. The easiest way to find the tenant is to open SharePoint Online site collection, click `Site Settings` -\u003e `Site App Permissions`. Taking any random app, the tenant ID (realm) is the GUID part after the `@`.\n\nSee more details of [AddIn Configuration and Permissions](https://github.com/s-kainet/node-sp-auth/wiki/SharePoint-Online-addin-only-authentication).\n\n### NTLM Auth (NTLM handshake)\n\nThis type of authentication uses an HTTP NTLM handshake to obtain an authentication header.\n\n```golang\n// AuthCnfg - NTLM auth config structure\ntype AuthCnfg struct {\n\t// SPSite or SPWeb URL, which is the context target for the API calls\n\tSiteURL  string `json:\"siteUrl\"`\n\tDomain   string `json:\"domain\"`   // AD domain name\n\tUsername string `json:\"username\"` // AD user name\n\tPassword string `json:\"password\"` // AD user password\n}\n```\n\nGosip uses `github.com/Azure/go-ntlmssp` NTLM negotiator, however, a custom one also can be [provided](https://github.com/koltyakov/gosip/issues/14) in case of demand.\n\n## Secrets encoding\n\nWhen storing credential in local `private.json` files, which can be handy in local development scenarios, we strongly recommend to encode secrets such as `password` or `clientSecret` using [cpass](./cmd/cpass/README.md). Class converts a secret to an encrypted representation, which can only be decrypted on the same machine where it was generated. That reduces accidental leaks, e.g. together with git commits.\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## 📚 [Documentation](https://go.spflow.com)\n\n## 📦 [Samples](https://github.com/koltyakov/gosip-sandbox/tree/master/samples)\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","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkoltyakov%2Fgosip","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkoltyakov%2Fgosip/lists"}