ghinstallation

package module
v0.0.6 Latest Latest
Warning

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

 Go to latest Published: May 23, 2024 License: Apache-2.0 Imports: 15 Imported by: 3

README

ghinstallation

GoDoc

This library is forked from bradleyfalzon/ghinstallation, which was created to provide GitHub Apps authentication helpers for google/go-github. This fork is designed to work with octokit/go-sdk.

ghinstallation provides Transport, which implements http.RoundTripper to provide authentication as an installation for GitHub Apps.

See https://developer.github.com/apps/building-integrations/setting-up-and-registering-github-apps/about-authentication-options-for-github-apps/

Installation

Get the package:

go get -u github.com/kfcampbell/ghinstallation

go-sdk example

See go-sdk examples for instructions on usage with the go-sdk library.

Manual usage example

Create or obtain a transport, then wrap it with an Apps transport using your private key, client ID, and installation ID.


existingTransport := http.DefaultTransport

appTransport, err := ghinstallation.NewKeyFromFile(existingTransport, "your-client-ID", yourInstallationIDInt, "path/to/your/pem/file.pem")
if err != nil {
  return nil, fmt.Errorf("failed to create transport from GitHub App using clientID: %v", err)
}
// use the created appTransport in your HttpClient
What are client ID, app ID, and installation ID?

These are fields unique to your application that GitHub uses to identify your App and issue its credentials. Client ID and App ID are interchangeable, and client ID is preferred. Both can be obtained by visiting the App's page > App settings. The URL for your App is "https://github.com/apps/{yourAppName}".

The App page will look something like this, with the App settings link on the right sidebar:

App page

The App settings page will look like this, and allow you to copy the App ID and the client ID:

App settings page

The installation ID is specific to an installation of that App to a specific organization or user. You can find it in the URL when viewing an App's installation, when the URL will look something like this: "https://github.com/organizations/{yourAppName}/settings/installations/{installationID}".

Customizing signing behavior

Users can customize signing behavior by passing in a Signer implementation when creating an AppsTransport. For example, this can be used to create tokens backed by keys in a KMS system.

signer := &myCustomSigner{
  key: "https://url/to/key/vault",
}
appsTransport := NewAppsTransportWithOptions(http.DefaultTransport, "your-client-ID", WithSigner(signer))
transport := NewFromAppsTransport(appsTransport, yourInstallationIDInt)

License

Apache 2.0

Dependencies

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func GetReadWriter 

func GetReadWriter(i interface{}) (io.ReadWriter, error)

GetReadWriter converts a body interface into an io.ReadWriter object.

Types

type AppsTransport 

type AppsTransport struct {
	BaseURL string // BaseURL is the scheme and host for GitHub API, defaults to https://api.github.com
	Client  Client // Client to use to refresh tokens, defaults to http.Client with provided transport
	// contains filtered or unexported fields
}

AppsTransport provides a http.RoundTripper by wrapping an existing http.RoundTripper and provides GitHub Apps authentication as a GitHub App.

Client can also be overwritten, and is useful to change to one which provides retry logic if you do experience retryable errors.

See https://developer.github.com/apps/building-integrations/setting-up-and-registering-github-apps/about-authentication-options-for-github-apps/

func NewAppsTransport 

func NewAppsTransport(tr http.RoundTripper, clientID string, privateKey []byte) (*AppsTransport, error)

NewAppsTransport returns an AppsTransport using private key. The key is parsed and if any errors occur the error is non-nil.

The provided tr http.RoundTripper should be shared between multiple installations to ensure reuse of underlying TCP connections.

The returned Transport's RoundTrip method is safe to be used concurrently.

func NewAppsTransportFromPrivateKey 

func NewAppsTransportFromPrivateKey(tr http.RoundTripper, clientID string, key *rsa.PrivateKey) *AppsTransport

NewAppsTransportFromPrivateKey returns an AppsTransport using a crypto/rsa.(*PrivateKey).

func NewAppsTransportFromPrivateKeyWithAppID added in v0.0.3 

func NewAppsTransportFromPrivateKeyWithAppID(tr http.RoundTripper, appID int64, key *rsa.PrivateKey) *AppsTransport

NewAppsTransportFromPrivateKeyWithAppID returns an AppsTransport using a crypto/rsa.(*PrivateKey) when given an appID instead of a clientID. Deprecated: use NewAppsTransportWithPrivateKey instead

func NewAppsTransportKeyFromFile 

func NewAppsTransportKeyFromFile(tr http.RoundTripper, clientID string, privateKeyFile string) (*AppsTransport, error)

NewAppsTransportKeyFromFile returns an AppsTransport using a private key from file.

func NewAppsTransportKeyFromFileWithAppID added in v0.0.3 

func NewAppsTransportKeyFromFileWithAppID(tr http.RoundTripper, appID int64, privateKeyFile string) (*AppsTransport, error)

NewAppsTransportKeyFromFileWithAppID returns an AppsTransport using a private key from file using the appID instead of the clientID. Deprecated: Use NewAppsTransportKeyFromFile instead.

func NewAppsTransportWithAppIDWithOptions added in v0.0.3 

func NewAppsTransportWithAppIDWithOptions(tr http.RoundTripper, appID int64, opts ...AppsTransportOption) (*AppsTransport, error)

NewAppsTransportWithAppIDWithOptions returns an *AppsTransport configured with the given options when given an appID instead of a clientID. Deprecated: use NewAppsTransportWithAppIDWithOptions instead

func NewAppsTransportWithAppId added in v0.0.3 

func NewAppsTransportWithAppId(tr http.RoundTripper, appID int64, privateKey []byte) (*AppsTransport, error)

NewAppsTransportWithAppId returns an AppsTransport using private key when given an appID instead of clientID. Deprecated: use NewAppsTransport instead The key is parsed and if any errors occur the error is non-nil.

The provided tr http.RoundTripper should be shared between multiple installations to ensure reuse of underlying TCP connections.

The returned Transport's RoundTrip method is safe to be used concurrently.

func NewAppsTransportWithOptions 

func NewAppsTransportWithOptions(tr http.RoundTripper, clientID string, opts ...AppsTransportOption) (*AppsTransport, error)

NewAppsTransportWithAppIDWithOptions returns an *AppsTransport configured with the given options.

func (*AppsTransport) AppID 

func (t *AppsTransport) AppID() int64

AppID returns the appID of the transport Deprecated: prefer ClientID where possible

func (*AppsTransport) ClientID added in v0.0.3 

func (t *AppsTransport) ClientID() string

ClientID returns the clientID of the transport

func (*AppsTransport) RoundTrip 

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

RoundTrip implements http.RoundTripper interface.

type AppsTransportOption 

type AppsTransportOption func(*AppsTransport)

AppsTransportOption is a functional option for configuring an AppsTransport

func WithSigner 

func WithSigner(signer Signer) AppsTransportOption

WithSigner configures the AppsTransport to use the given Signer for generating JWT tokens.

type Client 

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

Client is a HTTP client which sends a http.Request and returns a http.Response or an error.

type HTTPError 

type HTTPError struct {
	Message        string
	RootCause      error
	InstallationID int64
	Response       *http.Response
}

HTTPError represents a custom error for failing HTTP operations. Example in our usecase: refresh access token operation. It enables the caller to inspect the root cause and response.

func (*HTTPError) Error 

func (e *HTTPError) Error() string

func (*HTTPError) Unwrap 

func (e *HTTPError) Unwrap() error

Unwrap implements the standard library's error wrapping. It unwraps to the root cause.

type InstallationTokenOptions added in v0.0.4 

type InstallationTokenOptions struct {
	// The IDs of the repositories that the installation token can access.
	// Providing repository IDs restricts the access of an installation token to specific repositories.
	RepositoryIDs []int64 `json:"repository_ids,omitempty"`

	// The names of the repositories that the installation token can access.
	// Providing repository names restricts the access of an installation token to specific repositories.
	Repositories []string `json:"repositories,omitempty"`

	// The permissions granted to the access token.
	// The permissions object includes the permission names and their access type.
	Permissions *gh.AppPermissions `json:"permissions,omitempty"`
}

InstallationTokenOptions allow restricting a token's access to specific repositories. These options are taken from google/go-github's implementation. See more at https://github.com/google/go-github/blob/8c1232a5960307a6383998e1aa2dd71711343810/github/apps.go

type RSASigner 

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

RSASigner signs JWT tokens using RSA keys.

func NewRSASigner 

func NewRSASigner(method *jwt.SigningMethodRSA, key *rsa.PrivateKey) *RSASigner

func (*RSASigner) Sign 

func (s *RSASigner) Sign(claims jwt.Claims) (string, error)

Sign signs the JWT claims with the RSA key.

type Signer 

type Signer interface {
	// Sign signs the given claims and returns a JWT token string, as specified
	// by [jwt.Token.SignedString]
	Sign(claims jwt.Claims) (string, error)
}

Signer is a JWT token signer. This is a wrapper around jwt.SigningMethod with predetermined key material.

type Transport 

type Transport struct {
	BaseURL string // BaseURL is the scheme and host for GitHub API, defaults to https://api.github.com
	Client  Client // Client to use to refresh tokens, defaults to http.Client with provided transport

	InstallationTokenOptions *InstallationTokenOptions // parameters restrict a token's access
	// contains filtered or unexported fields
}

Transport provides a http.RoundTripper by wrapping an existing http.RoundTripper and provides GitHub Apps authentication as an installation.

Client can also be overwritten, and is useful to change to one which provides retry logic if you do experience retryable errors.

See https://developer.github.com/apps/building-integrations/setting-up-and-registering-github-apps/about-authentication-options-for-github-apps/

func NewFromAppsTransport 

func NewFromAppsTransport(atr *AppsTransport, installationID int64) *Transport

NewFromAppsTransport returns a Transport using an existing *AppsTransport.

func NewKeyFromFile 

func NewKeyFromFile(tr http.RoundTripper, clientID string, installationID int64, privateKeyFile string) (*Transport, error)

NewKeyFromFile returns a Transport using a private key from file.

func NewKeyFromFileWithAppID added in v0.0.3 

func NewKeyFromFileWithAppID(tr http.RoundTripper, appID, installationID int64, privateKeyFile string) (*Transport, error)

NewKeyFromFileWithAppID returns a Transport using a private key from file when given an appID. Deprecated: use NewKeyFromFile instead.

func NewTransport added in v0.0.3 

func NewTransport(tr http.RoundTripper, clientID string, installationID int64, privateKey []byte) (*Transport, error)

NewTransport returns an Transport using private key. The key is parsed and if any errors occur the error is non-nil.

The provided tr http.RoundTripper should be shared between multiple installations to ensure reuse of underlying TCP connections.

The returned Transport's RoundTrip method is safe to be used concurrently. Deprecated: Use NewTransport instead.

func NewTransportFromAppID added in v0.0.3 

func NewTransportFromAppID(tr http.RoundTripper, appID, installationID int64, privateKey []byte) (*Transport, error)

NewTransportFromAppID returns an Transport using private key when given an appID instead of a clientID. Deprecated: Use NewTransport instead. The key is parsed and if any errors occur the error is non-nil.

The provided tr http.RoundTripper should be shared between multiple installations to ensure reuse of underlying TCP connections.

The returned Transport's RoundTrip method is safe to be used concurrently.

func (*Transport) AppID 

func (t *Transport) AppID() int64

AppID returns the app ID associated with the transport Deprecated: use ClientID instead

func (*Transport) ClientID added in v0.0.3 

func (t *Transport) ClientID() string

ClientID returns the clientID associated with the transport

func (*Transport) Expiry 

func (t *Transport) Expiry() (expiresAt time.Time, refreshAt time.Time, err error)

Expiry returns a transport token's expiration time and refresh time. There is a small grace period built in where a token will be refreshed before it expires. expiresAt is the actual token expiry, and refreshAt is when a call to Token() will cause it to be refreshed.

func (*Transport) InstallationID 

func (t *Transport) InstallationID() int64

InstallationID returns the installation ID associated with the transport

func (*Transport) Permissions 

func (t *Transport) Permissions() (gh.AppPermissions, error)

Permissions returns a transport token's GitHub installation permissions.

func (*Transport) Repositories 

func (t *Transport) Repositories() ([]gh.Repository, error)

Repositories returns a transport token's GitHub repositories.

func (*Transport) RoundTrip 

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

RoundTrip implements http.RoundTripper interface.

func (*Transport) Token 

func (t *Transport) Token(ctx context.Context) (string, error)

Token checks the active token expiration and renews if necessary. Token returns a valid access token. If renewal fails an error is returned.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.