jira

Documentation

Overview

Package jira implements OAuth1.0a support for arbitrary JIRA installations.

Index

• Constants
• type AuthRequest
• type AuthResponse
• type Realm
  • func (r *Realm) AuthSession(id string, userID id.UserID, realmID string) types.AuthSession
  • func (r *Realm) ID() string
  • func (r *Realm) Init() error
  • func (r *Realm) JIRAClient(userID id.UserID, allowUnauth bool) (*jira.Client, error)
  • func (r *Realm) OnReceiveRedirect(w http.ResponseWriter, req *http.Request)
  • func (r *Realm) ProjectKeyExists(userID id.UserID, projectKey string) (bool, error)
  • func (r *Realm) Register() error
  • func (r *Realm) RequestAuthSession(userID id.UserID, req json.RawMessage) interface{}
  • func (r *Realm) Type() string
• type Session
  • func (s *Session) Authenticated() bool
  • func (s *Session) ID() string
  • func (s *Session) Info() interface{}
  • func (s *Session) RealmID() string
  • func (s *Session) UserID() id.UserID

Constants

const RealmType = "jira"

RealmType of the JIRA realm

Types

type AuthRequest

type AuthRequest struct {
	// Optional. The URL to redirect to after authentication.
	RedirectURL string
}

AuthRequest is a request for authenticating with JIRA

type AuthResponse

type AuthResponse struct {
	// The URL to visit to perform OAuth on this JIRA installation.
	URL string
}

AuthResponse is a response to an AuthRequest.

type Realm

type Realm struct {

	// The HTTPS URL of the JIRA installation to authenticate with.
	JIRAEndpoint string
	// The desired "Consumer Name" field of the "Application Links" admin page on JIRA.
	// Generally this is the name of the service. Users will need to enter this string
	// into their JIRA admin web form.
	ConsumerName string
	// The desired "Consumer Key" field of the "Application Links" admin page on JIRA.
	// Generally this is the name of the service. Users will need to enter this string
	// into their JIRA admin web form.
	ConsumerKey string
	// The desired "Consumer Secret" field of the "Application Links" admin page on JIRA.
	// This should be a random long string. Users will need to enter this string into
	// their JIRA admin web form.
	ConsumerSecret string
	// A string which contains the private key for performing OAuth 1.0 requests.
	// This MUST be in PEM format. It must NOT have a password. Go-NEB will convert this
	// into a public key in PEM format and return this to users. Users will need to enter
	// the *public* key into their JIRA admin web form.
	//
	// To generate a private key PEM: (JIRA does not support bit lengths >2048):
	//    $ openssl genrsa -out privkey.pem 2048
	//    $ cat privkey.pem
	PrivateKeyPEM string
	// Optional. If supplied, !jira commands will return this link whenever someone is
	// prompted to login to JIRA.
	StarterLink string

	// The server name of the JIRA installation from /serverInfo.
	// This is an informational field populated by Go-NEB post-creation.
	Server string
	// The JIRA version string from /serverInfo.
	// This is an informational field populated by Go-NEB post-creation.
	Version string
	// The public key for the given private key. This is populated by Go-NEB.
	PublicKeyPEM string

	// Internal field. True if this realm has already registered a webhook with the JIRA installation.
	HasWebhook bool
	// contains filtered or unexported fields
}

Realm is an AuthRealm which can process JIRA installations.

Example request:

{
     "JIRAEndpoint": "matrix.org/jira/",
     "ConsumerName": "goneb",
     "ConsumerKey": "goneb",
     "ConsumerSecret": "random_long_string",
     "PrivateKeyPEM": "-----BEGIN RSA PRIVATE KEY-----\r\nMIIEowIBAAKCAQEA39UhbOvQHEkBP9fGnhU+eSObTAwX9req2l1NiuNaPU9rE7tf6Bk\r\n-----END RSA PRIVATE KEY-----"
}

func (*Realm) AuthSession

func (r *Realm) AuthSession(id string, userID id.UserID, realmID string) types.AuthSession

AuthSession returns a JIRASession with the given parameters

func (*Realm) ID

func (r *Realm) ID() string

ID returns the ID of this JIRA realm.

func (*Realm) Init

func (r *Realm) Init() error

Init initialises the private key for this JIRA realm.

func (*Realm) JIRAClient

func (r *Realm) JIRAClient(userID id.UserID, allowUnauth bool) (*jira.Client, error)

JIRAClient returns an authenticated jira.Client for the given userID. Returns an unauthenticated client if allowUnauth is true and no authenticated session is found, else returns an error.

func (*Realm) OnReceiveRedirect

func (r *Realm) OnReceiveRedirect(w http.ResponseWriter, req *http.Request)

OnReceiveRedirect is called when JIRA installations redirect back to NEB

func (*Realm) ProjectKeyExists

func (r *Realm) ProjectKeyExists(userID id.UserID, projectKey string) (bool, error)

ProjectKeyExists returns true if the given project key exists on this JIRA realm. An authenticated client for userID will be used if one exists, else an unauthenticated client will be used, which may not be able to see the complete list of projects.

func (*Realm) Register

func (r *Realm) Register() error

Register is called when this realm is being created from an external entity

func (*Realm) RequestAuthSession

func (r *Realm) RequestAuthSession(userID id.UserID, req json.RawMessage) interface{}

RequestAuthSession is called by a user wishing to auth with this JIRA realm. The request body is of type "jira.AuthRequest". Returns a "jira.AuthResponse".

Request example:

{
    "RedirectURL": "https://somewhere.somehow"
}

Response example:

{
    "URL": "https://jira.somewhere.com/plugins/servlet/oauth/authorize?oauth_token=7yeuierbgweguiegrTbOT"
}

func (*Realm) Type

func (r *Realm) Type() string

Type returns the type of realm this is.

type Session

type Session struct {

	// The secret obtained when requesting an authentication session with JIRA.
	RequestSecret string
	// A JIRA access token for a Matrix user ID.
	AccessToken string
	// A JIRA access secret for a Matrix user ID.
	AccessSecret string
	// Optional. The URL to redirect the client to after authentication.
	ClientsRedirectURL string
	// contains filtered or unexported fields
}

Session represents a single authentication session between a user and a JIRA endpoint. The endpoint is dictated by the realm ID.

func (*Session) Authenticated

func (s *Session) Authenticated() bool

Authenticated returns true if the user has completed the auth process

func (*Session) ID

func (s *Session) ID() string

ID returns the OAuth1 request_token which is used when looking up sessions in the redirect handler.

func (*Session) Info

func (s *Session) Info() interface{}

Info returns nothing

func (*Session) RealmID

func (s *Session) RealmID() string

RealmID returns the JIRA realm ID which created this session.

func (*Session) UserID

func (s *Session) UserID() id.UserID

UserID returns the ID of the user performing the authentication.