This repository has been archived on 2023-08-14. You can view files and clone it, but cannot push or open issues or pull requests.
dex/connector/connector.go

100 lines
4.0 KiB
Go
Raw Normal View History

2016-07-25 20:00:28 +00:00
// Package connector defines interfaces for federated identity strategies.
package connector
import (
"context"
"net/http"
)
2016-07-25 20:00:28 +00:00
// Connector is a mechanism for federating login to a remote identity service.
//
// Implementations are expected to implement either the PasswordConnector or
// CallbackConnector interface.
type Connector interface{}
// Scopes represents additional data requested by the clients about the end user.
type Scopes struct {
// The client has requested a refresh token from the server.
OfflineAccess bool
// The client has requested group information about the end user.
Groups bool
2016-07-25 20:00:28 +00:00
}
// Identity represents the ID Token claims supported by the server.
type Identity struct {
UserID string
Username string
Email string
EmailVerified bool
Groups []string
// ConnectorData holds data used by the connector for subsequent requests after initial
// authentication, such as access tokens for upstream provides.
//
// This data is never shared with end users, OAuth clients, or through the API.
ConnectorData []byte
}
// PasswordConnector is an interface implemented by connectors which take a
// username and password.
// Prompt() is used to inform the handler what to display in the password
// template. If this returns an empty string, it'll default to "Username".
2016-07-25 20:00:28 +00:00
type PasswordConnector interface {
Prompt() string
Login(ctx context.Context, s Scopes, username, password string) (identity Identity, validPassword bool, err error)
2016-07-25 20:00:28 +00:00
}
// CallbackConnector is an interface implemented by connectors which use an OAuth
// style redirect flow to determine user information.
2016-07-25 20:00:28 +00:00
type CallbackConnector interface {
// The initial URL to redirect the user to.
//
// OAuth2 implementations should request different scopes from the upstream
// identity provider based on the scopes requested by the downstream client.
// For example, if the downstream client requests a refresh token from the
// server, the connector should also request a token from the provider.
//
// Many identity providers have arbitrary restrictions on refresh tokens. For
// example Google only allows a single refresh token per client/user/scopes
// combination, and wont return a refresh token even if offline access is
// requested if one has already been issues. There's no good general answer
// for these kind of restrictions, and may require this package to become more
// aware of the global set of user/connector interactions.
LoginURL(s Scopes, callbackURL, state string) (string, error)
// Handle the callback to the server and return an identity.
HandleCallback(s Scopes, r *http.Request) (identity Identity, err error)
2016-07-25 20:00:28 +00:00
}
2016-12-21 01:24:17 +00:00
// SAMLConnector represents SAML connectors which implement the HTTP POST binding.
// RelayState is handled by the server.
2016-12-21 01:24:17 +00:00
//
// See: https://docs.oasis-open.org/security/saml/v2.0/saml-bindings-2.0-os.pdf
// "3.5 HTTP POST Binding"
2016-12-21 01:24:17 +00:00
type SAMLConnector interface {
// POSTData returns an encoded SAML request and SSO URL for the server to
// render a POST form with.
//
// POSTData should encode the provided request ID in the returned serialized
// SAML request.
POSTData(s Scopes, requestID string) (sooURL, samlRequest string, err error)
2016-12-21 01:24:17 +00:00
// HandlePOST decodes, verifies, and maps attributes from the SAML response.
// It passes the expected value of the "InResponseTo" response field, which
// the connector must ensure matches the response value.
2016-12-21 01:24:17 +00:00
//
// See: https://www.oasis-open.org/committees/download.php/35711/sstc-saml-core-errata-2.0-wd-06-diff.pdf
// "3.2.2 Complex Type StatusResponseType"
HandlePOST(s Scopes, samlResponse, inResponseTo string) (identity Identity, err error)
2016-12-21 01:24:17 +00:00
}
// RefreshConnector is a connector that can update the client claims.
type RefreshConnector interface {
// Refresh is called when a client attempts to claim a refresh token. The
// connector should attempt to update the identity object to reflect any
// changes since the token was last refreshed.
Refresh(ctx context.Context, s Scopes, identity Identity) (Identity, error)
2016-07-25 20:00:28 +00:00
}