client

Documentation

Overview

Package client implements HTTP primitives for talking with and authenticating with the Apple DEP APIs.

Index

• Constants
• Variables
• func DoAuth(client Doer, req *http.Request, tokens *OAuth1Tokens) (string, error)
• func GetName(ctx context.Context) string
• func NewAuthError(r *http.Response) error
• func NewClient(client *http.Client, transport http.RoundTripper) *http.Client
• func NewRequestWithContext(ctx context.Context, name string, store ConfigRetriever, method, path string, ...) (*http.Request, error)
• func RetrieveAndResolveURL(ctx context.Context, name string, store ConfigRetriever, path string) (*url.URL, error)
• func SetAuthorizationHeader(tokens *OAuth1Tokens, req *http.Request) error
• func TeeReadCloser(rc io.ReadCloser, w io.Writer) io.ReadCloser
• func WithName(ctx context.Context, name string) context.Context
• type AuthError
  • func (e *AuthError) Error() string
• type AuthTokensRetriever
• type Config
• type ConfigRetriever
• type DefaultConfigRetreiver
  • func NewDefaultConfigRetreiver(next ConfigRetriever) *DefaultConfigRetreiver
  • func (c *DefaultConfigRetreiver) RetrieveConfig(ctx context.Context, name string) (*Config, error)
• type Doer
• type OAuth1Tokens
  • func (t *OAuth1Tokens) Valid() bool
• type SessionStore
• type Transport
  • func NewTransport(t http.RoundTripper, c Doer, tokens AuthTokensRetriever, s SessionStore) *Transport
  • func (t *Transport) RoundTrip(req *http.Request) (*http.Response, error)

Constants

const (
	// HTTP header names
	ADMAuthSession        = "X-ADM-Auth-Session"
	ServerProtocolVersion = "X-Server-Protocol-Version"

	DefaultServerProtocolVersion = "7"

	SessionEndpoint = "/session"
)

const DefaultBaseURL = "https://mdmenrollment.apple.com/"

Variables

var ErrEmptyAuthSessionToken = errors.New("empty auth session token")

ErrEmptyAuthSessionToken occurs with a valid JSON session response but contains an empty session token.

var ErrMissingName = errors.New("transport: missing DEP name in HTTP request context")

ErrMissingName is returned when an HTTP context is missing the DEP name.

Functions

func DoAuth

func DoAuth(client Doer, req *http.Request, tokens *OAuth1Tokens) (string, error)

DoAuth performs OAuth1 authentication to the Apple DEP server and returns the 'auth_session_token' from the JSON response.

func GetName

func GetName(ctx context.Context) string

GetName retrieves the DEP name from ctx.

func NewAuthError

func NewAuthError(r *http.Response) error

NewAuthError creates and returns a new AuthError from r. Note this reads r.Body and you are responsible for Closing it.

func NewClient

func NewClient(client *http.Client, transport http.RoundTripper) *http.Client

NewClient is a helper that returns a copy of client with transport set.

func NewRequestWithContext

func NewRequestWithContext(ctx context.Context, name string, store ConfigRetriever, method, path string, body io.Reader) (*http.Request, error)

NewDEPRequestWithContext creates a new request for a DEP name. Note that path is the relative path of the DEP endpoint name like "account".

func RetrieveAndResolveURL

func RetrieveAndResolveURL(ctx context.Context, name string, store ConfigRetriever, path string) (*url.URL, error)

RetrieveAndResolveURL retrieves the base URL for a DEP name using store and resolves the full DEP request URL using path.

func SetAuthorizationHeader

func SetAuthorizationHeader(tokens *OAuth1Tokens, req *http.Request) error

SetAuthorizationHeader sets the OAuth1 Authorization HTTP request header using the supplied DEP tokens. Intended for the DEP /session endpoint. See https://developer.apple.com/documentation/devicemanagement/device_assignment/authenticating_with_a_device_enrollment_program_dep_server

func TeeReadCloser

func TeeReadCloser(rc io.ReadCloser, w io.Writer) io.ReadCloser

TeeReadCloser returns an io.ReadCloser that writes to w what it reads from rc. See also io.TeeReader as we simply wrap it under the hood here.

func WithName

func WithName(ctx context.Context, name string) context.Context

WithName creates a new context from ctx with the DEP name associated.

Types

type AuthError

type AuthError struct {
	Body       []byte
	Status     string
	StatusCode int
}

AuthError encapsulates an HTTP response error from the /session endpoint. The API returns error information in the request body.

func (*AuthError) Error

func (e *AuthError) Error() string

type AuthTokensRetriever

type AuthTokensRetriever interface {
	RetrieveAuthTokens(ctx context.Context, name string) (*OAuth1Tokens, error)
}

type Config

type Config struct {
	BaseURL string `json:"base_url,omitempty"`
}

Config represents the configuration of a DEP name.

type ConfigRetriever

type ConfigRetriever interface {
	// RetrieveConfig reads the JSON DEP config of a DEP name.
	//
	// Returns (nil, nil) if the DEP name does not exist, or if the config
	// for the DEP name does not exist.
	RetrieveConfig(ctx context.Context, name string) (*Config, error)
}

type DefaultConfigRetreiver

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

DefaultConfigRetreiver wraps a ConfigRetriever to return a default configuration.

func NewDefaultConfigRetreiver

func NewDefaultConfigRetreiver(next ConfigRetriever) *DefaultConfigRetreiver

func (*DefaultConfigRetreiver) RetrieveConfig

func (c *DefaultConfigRetreiver) RetrieveConfig(ctx context.Context, name string) (*Config, error)

RetrieveConfig retrieves the Config from the wrapped retreiver and returns it. If the config is empty a default config is returned.

type Doer

type Doer interface {
	Do(*http.Request) (*http.Response, error)
}

Doer executes an HTTP request.

type OAuth1Tokens

type OAuth1Tokens struct {
	ConsumerKey       string    `json:"consumer_key"`
	ConsumerSecret    string    `json:"consumer_secret"`
	AccessToken       string    `json:"access_token"`
	AccessSecret      string    `json:"access_secret"`
	AccessTokenExpiry time.Time `json:"access_token_expiry"`
}

OAuth1Tokens represents the token Apple DEP OAuth1 authentication tokens.

func (*OAuth1Tokens) Valid

func (t *OAuth1Tokens) Valid() bool

Valid performs sanity checks to make sure t appears to be valid DEP server OAuth 1 tokens.

type SessionStore

type SessionStore interface {
	SetSessionToken(context.Context, string, string) error
	GetSessionToken(context.Context, string) (string, error)
}

type Transport

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

Transport is an http.RoundTripper that transparently handles Apple DEP API authentication and session token management. See the RoundTrip method for more details.

func NewTransport

func NewTransport(t http.RoundTripper, c Doer, tokens AuthTokensRetriever, s SessionStore) *Transport

NewTransport creates a new Transport which wraps and calls to t for the actual HTTP calls. We call c for executing the authentication endpoint /session. The sessions are stored and retrieved using s while auth tokens are retrieved using tokens. If t is nil then http.DefaultTransport is used. If c is nil then http.DefaultClient is used. If s is nil then local-only session management is used. A panic will ensue if tokens is nil.

func (*Transport) RoundTrip

func (t *Transport) RoundTrip(req *http.Request) (*http.Response, error)

RoundTrip transparently handles DEP server authentication and session token management. Practically speaking this means we make up to three individual requests for a given single request: the initial request attempt, a possible authentication request followed by a re-try of the original, now authenticated, request. Note also that we try to be helpful and inject the `X-Server-Protocol-Version` into the request headers if it is missing. See https://developer.apple.com/documentation/devicemanagement/device_assignment/authenticating_with_a_device_enrollment_program_dep_server