saml2

package module
Version: v0.3.3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 7, 2020 License: Apache-2.0 Imports: 18 Imported by: 8

README

gosaml2

Build Status GoDoc

SAML 2.0 implemementation for Service Providers 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
  • Auth0
  • Shibboleth
  • Ipsilon
  • OneLogin

Documentation

Index

Constants

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

Oft-used messages

View Source
const (
	ResponseTag                = "Response"
	AssertionTag               = "Assertion"
	EncryptedAssertionTag      = "EncryptedAssertion"
	SubjectTag                 = "Subject"
	NameIdTag                  = "NameID"
	SubjectConfirmationTag     = "SubjectConfirmation"
	SubjectConfirmationDataTag = "SubjectConfirmationData"
	AttributeStatementTag      = "AttributeStatement"
	AttributeValueTag          = "AttributeValue"
	ConditionsTag              = "Conditions"
	AudienceRestrictionTag     = "AudienceRestriction"
	AudienceTag                = "Audience"
	OneTimeUseTag              = "OneTimeUse"
	ProxyRestrictionTag        = "ProxyRestriction"
	IssuerTag                  = "Issuer"
	StatusTag                  = "Status"
	StatusCodeTag              = "StatusCode"
)
View Source
const (
	DestinationAttr  = "Destination"
	VersionAttr      = "Version"
	IdAttr           = "ID"
	MethodAttr       = "Method"
	RecipientAttr    = "Recipient"
	NameAttr         = "Name"
	NotBeforeAttr    = "NotBefore"
	NotOnOrAfterAttr = "NotOnOrAfter"
	CountAttr        = "Count"
)
View Source
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"

	AuthnContextPasswordProtectedTransport = "urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport"

	AuthnPolicyMatchExact   = "exact"
	AuthnPolicyMatchMinimum = "minimum"
	AuthnPolicyMatchMaximum = "maximum"
	AuthnPolicyMatchBetter  = "better"

	StatusCodeSuccess = "urn:oasis:names:tc:SAML:2.0:status:Success"

	BindingHttpPost     = "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
	BindingHttpRedirect = "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
)
View Source
const (
	SAMLAssertionNamespace = "urn:oasis:names:tc:SAML:2.0:assertion"
	SAMLProtocolNamespace  = "urn:oasis:names:tc:SAML:2.0:protocol"
)
View Source
const (
	SubjMethodBearer = "urn:oasis:names:tc:SAML:2.0:cm:bearer"
)

Well-known methods of subject confirmation

Variables

View Source
var (
	ErrMissingAssertion = ErrMissingElement{Tag: AssertionTag}
)

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

Functions

func DecodeUnverifiedBaseResponse added in v0.3.0

func DecodeUnverifiedBaseResponse(encodedResponse string) (*types.UnverifiedBaseResponse, error)

DecodeUnverifiedBaseResponse decodes several attributes from a SAML response for the purpose of determining how to validate the response. This is useful for Service Providers which expose a single Assertion Consumer Service URL but consume Responses from many IdPs.

Types

type AssertionInfo

type AssertionInfo struct {
	NameID                     string
	Values                     Values
	WarningInfo                *WarningInfo
	AuthnInstant               *time.Time
	SessionNotOnOrAfter        *time.Time
	Assertions                 []types.Assertion
	ResponseSignatureValidated bool
}

type AuthNRequest

type AuthNRequest struct {
	ID                          string `xml:",attr"`
	Version                     string `xml:",attr"`
	ProtocolBinding             string `xml:",attr"`
	AssertionConsumerServiceURL string `xml:",attr"`

	IssueInstant time.Time `xml:",attr"`

	Destination string `xml:",attr"`
	Issuer      string
}

AuthNRequest is the go struct representation of an authentication request

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 ErrSaml

type ErrSaml struct {
	Message string
	System  error
}

func (ErrSaml) Error

func (serr ErrSaml) Error() string

type ErrVerification

type ErrVerification struct {
	Cause error
}

func (ErrVerification) Error

func (e ErrVerification) Error() string

type ProxyRestriction

type ProxyRestriction struct {
	Count    int
	Audience []string
}

type RequestedAuthnContext

type RequestedAuthnContext struct {
	// The RequestedAuthnContext comparison policy to use. See the section 3.3.2.2.1
	// of the SAML 2.0 specification for details. Constants named AuthnPolicyMatch*
	// contain standardized values.
	Comparison string

	// Contexts will be passed as AuthnContextClassRefs. For example, to force password
	// authentication on some identity providers, Contexts should have a value of
	// []string{AuthnContextPasswordProtectedTransport}, and Comparison should have a
	// value of AuthnPolicyMatchExact.
	Contexts []string
}

RequestedAuthnContext controls which authentication mechanisms are requested of the identity provider. It is generally sufficient to omit this and let the identity provider select an authentication mechansim.

type SAMLServiceProvider

type SAMLServiceProvider struct {
	IdentityProviderSSOURL string
	IdentityProviderIssuer string

	AssertionConsumerServiceURL string
	ServiceProviderIssuer       string

	SignAuthnRequests              bool
	SignAuthnRequestsAlgorithm     string
	SignAuthnRequestsCanonicalizer dsig.Canonicalizer

	// RequestedAuthnContext allows service providers to require that the identity
	// provider use specific authentication mechanisms. Leaving this unset will
	// permit the identity provider to choose the auth method. To maximize compatibility
	// with identity providers it is recommended to leave this unset.
	RequestedAuthnContext   *RequestedAuthnContext
	AudienceURI             string
	IDPCertificateStore     dsig.X509CertificateStore
	SPKeyStore              dsig.X509KeyStore // Required encryption key, default signing key
	SPSigningKeyStore       dsig.X509KeyStore // Optional signing key
	NameIdFormat            string
	ValidateEncryptionCert  bool
	SkipSignatureValidation bool
	AllowMissingAttributes  bool
	ScopingIDPProviderId    string
	ScopingIDPProviderName  string
	Clock                   *dsig.Clock
	// contains filtered or unexported fields
}

func (*SAMLServiceProvider) AuthRedirect

func (sp *SAMLServiceProvider) AuthRedirect(w http.ResponseWriter, r *http.Request, relayState string) (err error)

AuthRedirect takes a ResponseWriter and Request from an http interaction and redirects to the SAMLServiceProvider's configured IdP, including the relayState provided, if any.

func (*SAMLServiceProvider) BuildAuthRequest

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

BuildAuthRequest builds <AuthnRequest> for identity provider

func (*SAMLServiceProvider) BuildAuthRequestDocument

func (sp *SAMLServiceProvider) BuildAuthRequestDocument() (*etree.Document, error)

func (*SAMLServiceProvider) BuildAuthRequestDocumentNoSig

func (sp *SAMLServiceProvider) BuildAuthRequestDocumentNoSig() (*etree.Document, error)

func (*SAMLServiceProvider) BuildAuthURL

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

BuildAuthURL builds redirect URL to be sent to principal

func (*SAMLServiceProvider) BuildAuthURLFromDocument

func (sp *SAMLServiceProvider) BuildAuthURLFromDocument(relayState string, doc *etree.Document) (string, error)

func (*SAMLServiceProvider) BuildAuthURLRedirect

func (sp *SAMLServiceProvider) BuildAuthURLRedirect(relayState string, doc *etree.Document) (string, error)

func (*SAMLServiceProvider) GetEncryptionCertBytes

func (sp *SAMLServiceProvider) GetEncryptionCertBytes() ([]byte, error)

func (*SAMLServiceProvider) GetEncryptionKey

func (sp *SAMLServiceProvider) GetEncryptionKey() dsig.X509KeyStore

func (*SAMLServiceProvider) GetSigningCertBytes

func (sp *SAMLServiceProvider) GetSigningCertBytes() ([]byte, error)

func (*SAMLServiceProvider) GetSigningKey

func (sp *SAMLServiceProvider) GetSigningKey() dsig.X509KeyStore

func (*SAMLServiceProvider) Metadata

func (sp *SAMLServiceProvider) Metadata() (*types.EntityDescriptor, 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) SignAuthnRequest

func (sp *SAMLServiceProvider) SignAuthnRequest(el *etree.Element) (*etree.Element, error)

SignAuthnRequest takes a document, builds a signature, creates another document and inserts the signature in it. According to the schema, the position of the signature is right after the Issuer [1] then all other children.

[1] https://docs.oasis-open.org/security/saml/v2.0/saml-schema-protocol-2.0.xsd

func (*SAMLServiceProvider) SigningContext

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

func (*SAMLServiceProvider) Validate

func (sp *SAMLServiceProvider) Validate(response *types.Response) error

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

func (*SAMLServiceProvider) ValidateEncodedResponse

func (sp *SAMLServiceProvider) ValidateEncodedResponse(encodedResponse string) (*types.Response, 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(assertion *types.Assertion) (*WarningInfo, error)

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

type Values

type Values map[string]types.Attribute

Values is a convenience wrapper for a map of strings to Attributes, which can be used for easy access to the string values of Attribute lists.

func (Values) Get

func (vals Values) Get(k string) string

Get is a safe method (nil maps will not panic) for returning the first value for an attribute at a key, or the empty string if none exists.

type WarningInfo

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

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
t or T : Toggle theme light dark auto
y or Y : Canonical URL