saml2

README

gosaml2

SAML 2.0 implemementation based on etree and goxmldsig, a pure Go implementation of XML digital signatures.

Installation

Install gosaml2 into your $GOPATH using go get:

$ go get github.com/russellhaering/gosaml2`

Example

See demo.go.

Supported Identity Providers

This library is meant to be a generic SAML implementation. If you find a standards compliant identity provider that it doesn't work with please submit a bug or pull request.

The following identity providers have been tested:

• Okta

Documentation

Index

• Constants
• Variables
• type AssertionInfo
• type DigestMethod
• type EncryptedKey
  • func (ek *EncryptedKey) DecryptSymmetricKey(cert tls.Certificate) (cipher.Block, error)
• type EncryptionMethod
• type ErrInvalidValue
  • func (e ErrInvalidValue) Error() string
• type ErrMissingElement
  • func (e ErrMissingElement) Error() string
• type ErrParsing
  • func (ep ErrParsing) Error() string
• type ProxyRestriction
• type Response
  • func NewResponseFromReader(r io.Reader) (*Response, error)
  • func (sr *Response) Decrypt(cert tls.Certificate) ([]byte, error)
• type SAMLServiceProvider
  • func (sp *SAMLServiceProvider) BuildAuthRequest() (string, error)
  • func (sp *SAMLServiceProvider) BuildAuthURL(relayState string) (string, error)
  • func (sp *SAMLServiceProvider) RetrieveAssertionInfo(encodedResponse string) (*AssertionInfo, error)
  • func (sp *SAMLServiceProvider) SigningContext() *dsig.SigningContext
  • func (sp *SAMLServiceProvider) Validate(el *etree.Element) error
  • func (sp *SAMLServiceProvider) ValidateEncodedResponse(encodedResponse string) (*etree.Element, error)
  • func (sp *SAMLServiceProvider) VerifyAssertionConditions(assertionElement, conditionsStatement *etree.Element) (*WarningInfo, error)
• type WarningInfo

Constants

const (
	MethodRSAOAEP  = "http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p"
	MethodRSAOAEP2 = "http://www.w3.org/2009/xmlenc11#rsa-oaep"
)

Well-known public-key encryption methods

const (
	MethodAES128GCM = "http://www.w3.org/2009/xmlenc11#aes128-gcm"
	MethodAES128CBC = "http://www.w3.org/2001/04/xmlenc#aes128-cbc"
)

Well-known private key encryption methods

const (
	MethodSHA1   = "http://www.w3.org/2000/09/xmldsig#sha1"
	MethodSHA256 = "http://www.w3.org/2000/09/xmldsig#sha256"
	MethodSHA512 = "http://www.w3.org/2000/09/xmldsig#sha512"
)

Well-known hash methods

const (
	ReasonUnsupported = "Unsupported"
	ReasonExpired     = "Expired"
)

Oft-used messages

const (
	ResponseTag                = "Response"
	AssertionTag               = "Assertion"
	SubjectTag                 = "Subject"
	NameIdTag                  = "NameID"
	SubjectConfirmationTag     = "SubjectConfirmation"
	SubjectConfirmationDataTag = "SubjectConfirmationData"
	AttributeStatementTag      = "AttributeStatement"
	AttributeValueTag          = "AttributeValue"
	ConditionsTag              = "Conditions"
	AudienceRestrictionTag     = "AudienceRestriction"
	AudienceTag                = "Audience"
	OneTimeUseTag              = "OneTimeUse"
	ProxyRestrictionTag        = "ProxyRestriction"
)

const (
	DestinationAttr  = "Destination"
	VersionAttr      = "Version"
	IdAttr           = "ID"
	MethodAttr       = "Method"
	RecipientAttr    = "Recipient"
	NameAttr         = "Name"
	NotBeforeAttr    = "NotBefore"
	NotOnOrAfterAttr = "NotOnOrAfter"
	CountAttr        = "Count"
)

const (
	NameIdFormatPersistent      = "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent"
	NameIdFormatTransient       = "urn:oasis:names:tc:SAML:2.0:nameid-format:transient"
	NameIdFormatEmailAddress    = "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"
	NameIdFormatUnspecified     = "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"
	NameIdFormatX509SubjectName = "urn:oasis:names:tc:SAML:1.1:nameid-format:x509SubjectName"
)

const (
	SubjMethodBearer = "urn:oasis:names:tc:SAML:2.0:cm:bearer"
)

Well-known methods of subject confirmation

Variables

var (
	ErrMissingAssertion = ErrMissingElement{Tag: AssertionTag}
)

ErrMissingAssertion indicates that an appropriate assertion element could not be found in the SAML Response

Types

type AssertionInfo

type AssertionInfo struct {
	NameID      string
	Values      map[string]string
	WarningInfo *WarningInfo
}

type DigestMethod

type DigestMethod struct {
	Algorithm string `xml:",attr"`
}

DigestMethod is a digest type specification

type EncryptedKey

type EncryptedKey struct {
	// EncryptionMethod string `xml:"EncryptionMethod>Algorithm"`
	X509Data         string `xml:"KeyInfo>X509Data>X509Certificate"`
	CipherValue      string `xml:"CipherData>CipherValue"`
	EncryptionMethod EncryptionMethod
}

EncryptedKey contains the decryption key data from the saml2 core and xmlenc standards.

func (*EncryptedKey) DecryptSymmetricKey

func (ek *EncryptedKey) DecryptSymmetricKey(cert tls.Certificate) (cipher.Block, error)

DecryptSymmetricKey returns the private key contained in the EncryptedKey document

type EncryptionMethod

type EncryptionMethod struct {
	Algorithm    string `xml:",attr"`
	DigestMethod DigestMethod
}

EncryptionMethod specifies the type of encryption that was used.

type ErrInvalidValue

type ErrInvalidValue struct {
	Key, Expected, Actual string
	Reason                string
}

ErrInvalidValue indicates that the expected value did not match the received value.

func (ErrInvalidValue) Error

func (e ErrInvalidValue) Error() string

type ErrMissingElement

type ErrMissingElement struct {
	Tag, Attribute string
}

ErrMissingElement is the error type that indicates an element and/or attribute is missing. It provides a structured error that can be more appropriately acted upon.

func (ErrMissingElement) Error

func (e ErrMissingElement) Error() string

type ErrParsing

type ErrParsing struct {
	Tag, Value, Type string
}

ErrParsing indicates that the value present in an assertion could not be parsed. It can be inspected for the specific tag name, the contents, and the intended type.

func (ErrParsing) Error

func (ep ErrParsing) Error() string

type ProxyRestriction

type ProxyRestriction struct {
	Count    int
	Audience []string
}

type Response

type Response struct {
	Destination      string           `xml:"Destination,attr"`
	Issuer           string           `xml:"Issuer"`
	Value            string           `xml:",attr"`
	EncryptionMethod EncryptionMethod `xml:"EncryptedAssertion>EncryptedData>EncryptionMethod"`
	Key              EncryptedKey     `xml:"EncryptedAssertion>EncryptedData>KeyInfo>EncryptedKey"`
	Data             string           `xml:"EncryptedAssertion>EncryptedData>CipherData>CipherValue"`
	Signature        string           `xml:"Signature>SignatureValue"`
	Digest           string           `xml:"Signature>SignedInfo>Reference>DigestValue"`
}

Response is an abstraction type for handling the information in a SAML assertion

func NewResponseFromReader

func NewResponseFromReader(r io.Reader) (*Response, error)

NewResponseFromReader returns a Response or error based on the given reader.

func (*Response) Decrypt

func (sr *Response) Decrypt(cert tls.Certificate) ([]byte, error)

Decrypt returns the byte slice contained in the encrypted data.

type SAMLServiceProvider

type SAMLServiceProvider struct {
	IdentityProviderSSOURL      string
	IdentityProviderIssuer      string
	AssertionConsumerServiceURL string
	SignAuthnRequests           bool
	SignAuthnRequestsAlgorithm  dsig.SignatureAlgorithm
	AudienceURI                 string
	IDPCertificateStore         dsig.X509CertificateStore
	SPKeyStore                  dsig.X509KeyStore
	NameIdFormat                string
	SkipSignatureValidation     bool
}

func (*SAMLServiceProvider) BuildAuthRequest

func (sp *SAMLServiceProvider) BuildAuthRequest() (string, error)

func (*SAMLServiceProvider) BuildAuthURL

func (sp *SAMLServiceProvider) BuildAuthURL(relayState string) (string, error)

func (*SAMLServiceProvider) RetrieveAssertionInfo

func (sp *SAMLServiceProvider) RetrieveAssertionInfo(encodedResponse string) (*AssertionInfo, error)

RetrieveAssertionInfo takes an encoded response and returns the AssertionInfo contained, or an error message if an error has been encountered.

func (*SAMLServiceProvider) SigningContext

func (sp *SAMLServiceProvider) SigningContext() *dsig.SigningContext

func (*SAMLServiceProvider) Validate

func (sp *SAMLServiceProvider) Validate(el *etree.Element) error

Validate ensures that the assertion passed is valid for the current Service Provider.

func (*SAMLServiceProvider) ValidateEncodedResponse

func (sp *SAMLServiceProvider) ValidateEncodedResponse(encodedResponse string) (*etree.Element, error)

ValidateEncodedResponse both decodes and validates, based on SP configuration, an encoded, signed response. It will also appropriately decrypt a response if the assertion was encrypted

func (*SAMLServiceProvider) VerifyAssertionConditions

func (sp *SAMLServiceProvider) VerifyAssertionConditions(assertionElement, conditionsStatement *etree.Element) (*WarningInfo, error)

VerifyAssertionConditions inspects an assertion element and makes sure that all SAML2 contracts are upheld.

type WarningInfo

type WarningInfo struct {
	OneTimeUse       bool
	ProxyRestriction *ProxyRestriction
	NotInAudience    bool
	InvalidTime      bool
}