Introduction

​
 ​
​ ​
​ ​
​ ​
​​
Main features
Unattended authentication using different strategies.
​Fluent API syntax for SharePoint object model.
Simplified API consumption (REST, CSOM, SOAP, etc.).
SharePoint-aware embedded features (retries, header presets, error handling).
Supported SharePoint versions
SharePoint Online (SPO).
On-Premises (2019/2016/2013).
Supported auth strategies
SharePoint Online:
​Azure Certificate (App Only)​
​Azure Username/Password​
​SAML based with user credentials
​Add-In only permissions
ADFS user credentials (automatically detects in SAML strategy)
​Azure Device flow​
​On-Demand authentication​
SharePoint On-Premises 2019/2016/2013:
​User credentials (NTLM)
​ADFS user credentials (ADFS, WAP -> Basic/NTLM, WAP -> ADFS)
Behind a reverse proxy (Forefront TMG, WAP -> Basic/NTLM, WAP -> ADFS)
​Form-based authentication (FBA)
​On-Demand authentication​
Installation
1
go get github.com/koltyakov/gosip
Copied!
Usage insights
Understand SharePoint environment type and authentication strategy
Let's assume it's SharePoint Online and Add-In Only permissions. Then strategy "github.com/koltyakov/gosip/auth/addin" sub package should be used.
1
package main
2
​
3
import (
4
  "github.com/koltyakov/gosip"
5
  "github.com/koltyakov/gosip/api"
6
  strategy "github.com/koltyakov/gosip/auth/addin"
7
)
Copied!
Initiate authentication object
1
auth := &strategy.AuthCnfg{
2
  SiteURL:      os.Getenv("SPAUTH_SITEURL"),
3
  ClientID:     os.Getenv("SPAUTH_CLIENTID"),
4
  ClientSecret: os.Getenv("SPAUTH_CLIENTSECRET"),
5
}
Copied!
AuthCnfg's from different strategies contains different options relevant for a specified auth type.
The authentication options can be provided explicitly or can be read from a configuration file (see more).
1
configPath := "./config/private.json"
2
auth := &strategy.AuthCnfg{}
3
​
4
err := auth.ReadConfig(configPath)
5
if err != nil {
6
  fmt.Printf("Unable to get config: %v\n", err)
7
  return
8
}
Copied!
Bind auth client with Fluent API
1
client := &gosip.SPClient{AuthCnfg: auth}
2
​
3
sp := api.NewSP(client)
4
​
5
res, err := sp.Web().Select("Title").Get()
6
if err != nil {
7
  fmt.Println(err)
8
}
9
​
10
fmt.Printf("%s\n", res.Data().Title)
Copied!
Usage samples
Fluent API client
Provides a simple way of constructing API endpoint calls with IntelliSense and chainable syntax.
1
package main
2
​
3
import (
4
  "encoding/json"
5
  "fmt"
6
  "log"
7
​
8
  "github.com/koltyakov/gosip"
9
  "github.com/koltyakov/gosip/api"
10
  strategy "github.com/koltyakov/gosip/auth/addin"
11
)
12
​
13
func main() {
14
  // Getting auth params and client
15
  client, err := getAuthClient()
16
  if err != nil {
17
    log.Fatalln(err)
18
  }
19
​
20
  // Binding SharePoint API
21
  sp := api.NewSP(client)
22
​
23
  // Custom headers
24
  headers := map[string]string{
25
    "Accept": "application/json;odata=minimalmetadata",
26
    "Accept-Language": "de-DE,de;q=0.9",
27
  }
28
  config := &api.RequestConfig{Headers: headers}
29
​
30
  // Chainable request sample
31
  data, err := sp.Conf(config).Web().Lists().Select("Id,Title").Get()
32
  if err != nil {
33
    log.Fatalln(err)
34
  }
35
​
36
  // Response object unmarshalling
37
  // (struct depends on OData mode and API method)
38
  res := &struct {
39
    Value []struct {
40
      ID    string `json:"Id"`
41
      Title string `json:"Title"`
42
    } `json:"value"`
43
  }{}
44
​
45
  if err := json.Unmarshal(data, &res); err != nil {
46
    log.Fatalf("unable to parse the response: %v", err)
47
  }
48
​
49
  for _, list := range res.Value {
50
    fmt.Printf("%+v\n", list)
51
  }
52
​
53
}
54
​
55
func getAuthClient() (*gosip.SPClient, error) {
56
  configPath := "./config/private.spo-addin.json" // <- file with creds
57
  auth := &strategy.AuthCnfg{}
58
  if err := auth.ReadConfig(configPath); err != nil {
59
    return nil, fmt.Errorf("unable to get config: %v", err)
60
  }
61
  return &gosip.SPClient{AuthCnfg: auth}, nil
62
}
Copied!
Generic HTTP-client helper
Provides 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.
1
package main
2
​
3
import (
4
  "fmt"
5
  "log"
6
​
7
  "github.com/koltyakov/gosip"
8
  "github.com/koltyakov/gosip/api"
9
  strategy "github.com/koltyakov/gosip/auth/ntlm"
10
)
11
​
12
func main() {
13
  configPath := "./config/private.ntlm.json"
14
  auth := &strategy.AuthCnfg{}
15
​
16
  if err := auth.ReadConfig(configPath); err != nil {
17
    log.Fatalf("unable to get config: %v\n", err)
18
  }
19
​
20
  sp := api.NewHTTPClient(&gosip.SPClient{AuthCnfg: auth})
21
​
22
  endpoint := auth.GetSiteURL() + "/_api/web?$select=Title"
23
​
24
  data, err := sp.Get(endpoint, nil)
25
  if err != nil {
26
    log.Fatalf("%v\n", err)
27
  }
28
​
29
  // sp.Post(endpoint, []byte(body), nil) // generic POST
30
​
31
  // generic DELETE helper crafts "X-Http-Method"="DELETE" header
32
  // sp.Delete(endpoint, nil)
33
​
34
  // generic UPDATE helper crafts "X-Http-Method"="MERGE" header
35
  // sp.Update(endpoint, nil)
36
​
37
  // CSOM helper (client.svc/ProcessQuery)
38
  // sp.ProcessQuery(endpoint, []byte(body))
39
​
40
  fmt.Printf("response: %s\n", data)
41
}
Copied!
Low-level HTTP-client usage
Low-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.
1
client := &gosip.SPClient{AuthCnfg: auth}
2
​
3
var req *http.Request
4
// Initiate API request
5
// ...
6
​
7
resp, err := client.Execute(req)
8
if err != nil {
9
  fmt.Printf("Unable to request api: %v", err)
10
  return
11
}
Copied!
SPClient has Execute method which is a wrapper function injecting SharePoint authentication and ending up calling http.Client's Do method.
Reference
Many auth flows have been "copied" from node-sp-auth library (used as a blueprint), which we intensively use in Node.js ecosystem for years.
Fluent API and wrapper syntax are inspired by PnPjs which is also the first-class citizen on almost all our Node.js and front-end projects with SharePoint involved.
License
​​
​​

FAQ

Last modified 6mo ago

Export as PDF

Copy link

Contents

Main features

Supported SharePoint versions

Supported auth strategies

Installation

Usage insights

Understand SharePoint environment type and authentication strategy

Initiate authentication object

Bind auth client with Fluent API

Usage samples

Fluent API client

Generic HTTP-client helper

Low-level HTTP-client usage

Reference

License