github.com/vmware/go-vcloud-director/v2@v2.24.0/README.md (about)

     1  # go-vcloud-director [![GoDoc](https://godoc.org/github.com/vmware/go-vcloud-director?status.svg)](http://godoc.org/github.com/vmware/go-vcloud-director) [![Chat](https://img.shields.io/badge/chat-on%20slack-brightgreen.svg)](https://vmwarecode.slack.com/messages/CBBBXVB16)
     2  
     3  This repo contains the `go-vcloud-director` package which implements
     4  an SDK for VMware Cloud Director. The project serves the needs of Golang
     5  developers who need to integrate with VMware Cloud Director. It is also the
     6  basis of the [vCD Terraform
     7  Provider](https://github.com/vmware/terraform-provider-vcd).
     8  
     9  ## Contributions ##
    10  
    11  Contributions to `go-vcloud-director` are gladly welcome and range
    12  from participating in community discussions to submitting pull
    13  requests.  Please see the [contributing guide](CONTRIBUTING.md) for
    14  details on joining the community.
    15  
    16  ### Install and Build ###
    17  
    18  This project started using Go [modules](https://github.com/golang/go/wiki/Modules)
    19  starting with version 2.1 and `vendor` directory is no longer bundled.
    20  
    21  As per the [modules documentation](https://github.com/golang/go/wiki/Modules)
    22  you no longer need to use `GOPATH`. You can clone the branch in any directory
    23  you like and go will fetch dependencies specified in the `go.mod` file:
    24  ```
    25  cd ~/Documents/mycode
    26  git clone https://github.com/vmware/go-vcloud-director.git
    27  cd go-vcloud-director/govcd
    28  go build
    29  ```
    30  
    31  **Note** Do not forget to set `GO111MODULE=on` if you are in your GOPATH.
    32  [Read more about this.](https://github.com/golang/go/wiki/Modules#how-to-install-and-activate-module-support)
    33  
    34  #### Example code ####
    35  
    36  To show the SDK in action run the example:
    37  ```
    38  mkdir ~/govcd_example
    39  go mod init govcd_example
    40  go get github.com/vmware/go-vcloud-director/v2@main
    41  go build -o example
    42  ./example user_name "password" org_name vcd_IP vdc_name 
    43  ```
    44  
    45  Here's the code:
    46  ```go
    47  package main
    48  
    49  import (
    50  	"fmt"
    51  	"net/url"
    52  	"os"
    53  
    54  	"github.com/vmware/go-vcloud-director/v2/govcd"
    55  )
    56  
    57  type Config struct {
    58  	User     string
    59  	Password string
    60  	Org      string
    61  	Href     string
    62  	VDC      string
    63  	Insecure bool
    64  }
    65  
    66  func (c *Config) Client() (*govcd.VCDClient, error) {
    67  	u, err := url.ParseRequestURI(c.Href)
    68  	if err != nil {
    69  		return nil, fmt.Errorf("unable to pass url: %s", err)
    70  	}
    71  
    72  	vcdclient := govcd.NewVCDClient(*u, c.Insecure)
    73  	err = vcdclient.Authenticate(c.User, c.Password, c.Org)
    74  	if err != nil {
    75  		return nil, fmt.Errorf("unable to authenticate: %s", err)
    76  	}
    77  	return vcdclient, nil
    78  }
    79  
    80  func main() {
    81  	if len(os.Args) < 6 {
    82  		fmt.Println("Syntax: example user password org VCD_IP VDC ")
    83  		os.Exit(1)
    84  	}
    85  	config := Config{
    86  		User:     os.Args[1],
    87  		Password: os.Args[2],
    88  		Org:      os.Args[3],
    89  		Href:     fmt.Sprintf("https://%s/api", os.Args[4]),
    90  		VDC:      os.Args[5],
    91  		Insecure: true,
    92  	}
    93  
    94  	client, err := config.Client() // We now have a client
    95  	if err != nil {
    96  		fmt.Println(err)
    97  		os.Exit(1)
    98  	}
    99  	org, err := client.GetOrgByName(config.Org)
   100  	if err != nil {
   101  		fmt.Println(err)
   102  		os.Exit(1)
   103  	}
   104  	vdc, err := org.GetVDCByName(config.VDC, false)
   105  	if err != nil {
   106  		fmt.Println(err)
   107  		os.Exit(1)
   108  	}
   109  	fmt.Printf("Org URL: %s\n", org.Org.HREF)
   110  	fmt.Printf("VDC URL: %s\n", vdc.Vdc.HREF)
   111  }
   112  
   113  ```
   114  
   115  ## Authentication
   116  
   117  You can authenticate to the vCD in five ways:
   118  
   119  * With a System Administration user and password (`administrator@system`)
   120  * With an Organization user and password (`tenant-admin@org-name`)
   121  
   122  For the above two methods, you use: 
   123  ```go
   124  	err := vcdClient.Authenticate(User, Password, Org)
   125  	// or
   126  	resp, err := vcdClient.GetAuthResponse(User, Password, Org)
   127  ```
   128  
   129  * With an authorization token
   130  ```go
   131  	err := vcdClient.SetToken(Org, govcd.AuthorizationHeader, Token)
   132  ```
   133  The file `scripts/get_token.sh` provides a handy method of extracting the token
   134  (`x-vcloud-authorization` value) for future use.
   135  
   136  * With a service account token (the file needs to have `r+w` rights)
   137  ```go
   138  	err := vcdClient.SetServiceAccountApiToken(Org, "tokenfile.json")
   139  ```
   140  
   141  * SAML user and password (works with ADFS as IdP using WS-TRUST endpoint
   142    "/adfs/services/trust/13/usernamemixed"). One must pass `govcd.WithSamlAdfs(true,customAdfsRptId)`
   143    and username must be formatted so that ADFS understands it ('user@contoso.com' or
   144    'contoso.com\user') You can find usage example in
   145    [samples/saml_auth_adfs](/samples/saml_auth_adfs). 
   146  ```go
   147  vcdCli := govcd.NewVCDClient(*vcdURL, true, govcd.WithSamlAdfs(true, customAdfsRptId))
   148  err = vcdCli.Authenticate(username, password, org)
   149  ```
   150  
   151  More information about inner workings of SAML auth flow in this codebase can be found in
   152  `saml_auth.go:authorizeSamlAdfs(...)`. Additionaly this flow is documented in [vCD
   153  documentation](https://code.vmware.com/docs/10000/vcloud-api-programming-guide-for-service-providers/GUID-335CFC35-7AD8-40E5-91BE-53971937A2BB.html).