From a5feafc80d9d111702fef58c2facb402fbfb56bf Mon Sep 17 00:00:00 2001 From: Eric Chiang Date: Wed, 9 Dec 2015 15:19:39 -0800 Subject: [PATCH] connector: document Connector and ConnectorConfig interfaces closes #203 --- connector/interface.go | 26 +++++++++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) diff --git a/connector/interface.go b/connector/interface.go index 36d0dcc6..b7ca0139 100644 --- a/connector/interface.go +++ b/connector/interface.go @@ -14,8 +14,18 @@ import ( var ErrorNotFound = errors.New("connector not found in repository") type Connector interface { + // ID returns the ID of the ConnectorConfig used to create the Connector. ID() string + + // LoginURL returns the backend's authorization URL for a sessionKey + // and OAuth2 prompt type. LoginURL(sessionKey, prompt string) (string, error) + + // Register allows connectors to register a callback handler with the + // dex server. + // + // Connectors should register with a path that extends the namespace + // URL provided when the Connector is instantiated. Register(mux *http.ServeMux, errorURL url.URL) // Sync triggers any long-running tasks needed to maintain the @@ -23,7 +33,8 @@ type Connector interface { // repeatedly caching any remote resources for local use. Sync() chan struct{} - // TrustedEmailProvider indicates whether or not we can trust that email claims coming from this provider. + // TrustedEmailProvider indicates whether or not we can trust that email + // claims coming from this provider. TrustedEmailProvider() bool health.Checkable @@ -31,8 +42,21 @@ type Connector interface { //go:generate genconfig -o config.go connector Connector type ConnectorConfig interface { + // ConnectorID returns a unique end user facing identifier. For example "google". ConnectorID() string + + // ConnectorType returns an implementation specific identifier. For example "oidc". ConnectorType() string + + // Connector is invoked by the dex server and returns a Connector configured + // to use the provided arguments. URL namespace is used to register callbacks. + // loginFunc is used to associate remote identies with dex session keys. + // + // The returned Connector must call loginFunc once upon successful + // identification of a user. + // + // Additional templates are passed for connectors that require rendering HTML + // pages, such as the "local" connector. Connector(ns url.URL, loginFunc oidc.LoginFunc, tpls *template.Template) (Connector, error) }