wsfed

README

go-wsfed

The wsfed package provides functionality for:

• Generating a redirect url to an IDP
• Parsing Tokens generated by an IDP (currently only SAML v1.1 Tokens are supported since that was my specific use case, but it wouldn't take much work to add other Tokens)

Install

go get github.com/casdoor/go-wsfed

Examples

Configuration

  config = wsfed.Config{}
  // set the metatdata url for the IDP (alternatively set the IDPEndpoint)
	config.MetadataURL = "https://idp.example.com/wsfederation/metadata"
  // trust the certs in the metadata (alternatively set the TrustedCerts)
	config.MetadataCertsAreTrusted = true
  // poll the metadata once a week to check for any new certificates.
  // the default is 0 seconds, which never refreshes after the initial poll
	config.MetadataRefreshIntervalSeconds = 604800
  // set your realm
	config.Realm = "http://realm.example.com"
  // use your config to create a new WSFed object
	sso = wsfed.New(&config)

Get the Request URL for the IDP

// get the default request parameters (wa, wtrealm, wct) or create your own
rp := sso.GetDefaultRequestParameters()
// pass the RequestParameters to GetRequestURL
url, err := sso.GetRequestURL(rp)

Parse Claims asserted by the IDP

// get the wresult parameter from the IDP POST
wresult := r.PostFormValue("wresult")
// pass the wresult to ParseResponse
claims, err := sso.ParseResponse(wresult)

Contributions

Contributions are welcome. Just fork the repo and send a pull request.

Documentation

Overview

Package wsfed provides functionality for generating a redirect url to an IDP, and parsing Tokens returned from the IDP.

Index

• type Attribute
• type Claims
• type Config
  • func (c *Config) AddTrustedCert(cert x509.Certificate)
• type RequestParameters
• type SAMLv11
  • func (s *SAMLv11) GetClaims() (claims Claims, err error)
  • func (s *SAMLv11) Validate() error
• type Subject
• type Token
• type WSFed
  • func New(config *Config) *WSFed
  • func (w *WSFed) GetDefaultRequestParameters() RequestParameters
  • func (w *WSFed) GetRequestURL(params RequestParameters) (requestURL string, err error)
  • func (w *WSFed) ParseResponse(wresult string) (claims Claims, err error)

Types

type Attribute

type Attribute struct {
	Name   string
	Values []string
}

Attribute holds the names and values of the requestor's claims

type Claims

type Claims struct {
	Subject    Subject
	Attributes []Attribute
}

Claims holds the assertion data from the WS-Fed response

type Config

type Config struct {
	IDPEndpoint                    string
	MetadataURL                    string
	MetadataCertsAreTrusted        bool
	MetadataRefreshIntervalSeconds time.Duration
	Realm                          string
	TrustedCerts                   []x509.Certificate
	// contains filtered or unexported fields
}

Config maintains the configuration for sending/receiving WSFed messages.

Either an IDPEndpoint or MetadataURL should be specified.

If MetadataURL is provided, it will be parsed for a PassiveRequestorEndpoint. The certificates in the metadata can optionally be added to the TrustedCerts, or the certs can be specified directly.

If MetadataRefreshIntervalSeconds is set, the metadata will be polled at that frequency to update the configuration. This is usefull for certificate rotation when the metadata certs are trusted (MetadataCertsAreTrusted).

func (*Config) AddTrustedCert

func (c *Config) AddTrustedCert(cert x509.Certificate)

AddTrustedCert adds a cert to Config.TrustedCerts. If the cert already exists in the array, then no action is taken.

type RequestParameters

type RequestParameters struct {
	Wa      string
	Wtrealm string
	Wreply  string
	Wctx    string
	Wct     string
	Wfresh  string
}

RequestParameters holds the paramter values for the WSFed GET/POST request

type SAMLv11

type SAMLv11 struct {
	XMLDoc *etree.Document
	Realm  string
}

SAMLv11 is an implentation of the Token interface for SAML v1.1 tokens

func (*SAMLv11) GetClaims

func (s *SAMLv11) GetClaims() (claims Claims, err error)

GetClaims returns a Claims object populated with data from the token

func (*SAMLv11) Validate

func (s *SAMLv11) Validate() error

Validate verifies that the expiration and audience are valid

type Subject

type Subject struct {
	ID     string
	Format string
}

Subject holds the unique identifier for the authenticated requestor

type Token

type Token interface {
	Validate() error
	GetClaims() (Claims, error)
}

Token abstracts the different assertions available for WS-Fed

type WSFed

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

WSFed provides request and response handling for WS-Federation messages

func New

func New(config *Config) *WSFed

New returns a config initialized *WSFed

func (*WSFed) GetDefaultRequestParameters

func (w *WSFed) GetDefaultRequestParameters() RequestParameters

GetDefaultRequestParameters returns a RequestParameters object with wa set to "wsignin1.0" and Wtrealm set to the WSFed.config.Realm

func (*WSFed) GetRequestURL

func (w *WSFed) GetRequestURL(params RequestParameters) (requestURL string, err error)

GetRequestURL constructs the url that the requestor can be sent to for authentication

func (*WSFed) ParseResponse

func (w *WSFed) ParseResponse(wresult string) (claims Claims, err error)

ParseResponse validates the xml digest and signature, and returns the claims