quarterdeck

func (*Server) APIKeyCreate ¶

func (s *Server) APIKeyCreate(c *gin.Context)

Create an API Key for the specified project with the specified permissions. Most of the fields on an APIKey cannot be updated (with the exception of the API Key name). This method is the only way a user can set a keys projectID, createdBy, source, and permissions fields. All other fields are managed by Quarterdeck.

NOTE: a response to this request is the only time the key secret is exposed publicly. The secret is stored as an argon2 derived key so it is impossible for Quarterdeck to return the key to the user at any point after this method is called. The client must be responsible for recording the key and warning the user that this is the one time that it will be displayed. If the user loses the key, they will have to revoke (delete) the key and generate a new one.

func (*Server) APIKeyDelete ¶

func (s *Server) APIKeyDelete(c *gin.Context)

Delete an APIKey by its ID. This endpoint allows user to revoke APIKeys so that they can no longer be used for authentication with Quarterdeck. The APIKey is deleted if its ID can be parsed, it is found in the database, and the user OrgID claims match the organization the APIKey is assigned to. Otherwise this endpoint will return a 404 Not Found error if it cannot correctly retrieve the key. If the API Key is successfully deleted, this endpoint returns a 204 No Content response.

func (*Server) APIKeyDetail ¶

func (s *Server) APIKeyDetail(c *gin.Context)

Retrieve an APIKey by its ID. Most fields of the APIKey object are read-only, though some components, such as the APIKey secret, are not returned at all even on detail. An APIKey is returned if the ID can be parsed, it is found in the database, and the user OrgID claims match the organization the APIKey is assigned to. Otherwise this endpoint will return a 404 Not Found error if it cannot correctly retrieve the key.

NOTE: the APIKey Secret should never be returned from this endpoint!

func (*Server) APIKeyList ¶

func (s *Server) APIKeyList(c *gin.Context)

List the API Keys for organization of the authenticated user, optionally filtered by project ID. The list response returns a subset of the fields in the APIKey object, to get more information about the API Key use the Detail endpoint. This endpoint returns a paginated response, limited by a default page size of 100 if one is not specified by the user (and a maximum page size of 5000). If there is another page of APIKeys the NextPageToken field will be populated, which can be used to make a subsequent request for the next page. Note that the page size or the projectID filter should not be changed between requests and that the NextPageToken will expire after 24 hours and can no longer be used.

NOTE: the APIKey Secret should never be returned from this endpoint!

func (*Server) APIKeyUpdate ¶

func (s *Server) APIKeyUpdate(c *gin.Context)

Update an APIKey to change it's description. Most fields on the APIKey object are read-only; in order to "change" fields such as permissions it is necessary to delete the key and create a new one. The APIKey is updated if the ID can be parsed, it is found in the database, and the user OrgID claims match the organization the APIKey is assigned to. Otherwise this endpoint will return a 404 Not Found error.

NOTE: the APIKey Secret should never be returned from this endpoint!

func (*Server) AccessToken ¶ added in v0.2.0

func (s *Server) AccessToken(claims *tokens.Claims) string

AccessToken returns a token that can be used in tests and is only available if the server is in testing mode, otherwise an empty string is returned.

func (*Server) Authenticate ¶

func (s *Server) Authenticate(c *gin.Context)

Authenticate is oriented to machine users that have an API key with a client ID and secret for authentication (whereas login is used for human access using an email and password). Authenticate verifies the client secret submitted is correct by looking up the api key by the key ID and using the argon2 derived key verification process to confirm the secret matches. Upon authentication, an access and refresh token with the authorized claims of the keys are returned. These tokens can be used to authenticate with ensign systems and the claims used for authorization. The access and refresh tokens work the same way the user tokens work and the refresh token can be used to fetch a new key pair without having to transmit a secret again.

This method primarily uses read queries so should be highly available. The only write is the update of the last time the key was used, but it does this in a go routine to ensure that this endpoint is not blocked by Quarterdeck Raft replication. TODO: add rate limiting on a per-ip basis to prevent Quarterdeck DOS.

func (*Server) Available ¶

func (s *Server) Available() gin.HandlerFunc

Available is middleware that uses healthy boolean to return a service unavailable http status code if the server is shutting down or in maintenance mode. This middleware must be fairly early on in the chain to ensure that complex handling does not slow the shutdown of the server.

func (*Server) Healthy ¶

func (s *Server) Healthy() bool

func (*Server) JWKS ¶ added in v0.1.1

func (s *Server) JWKS(c *gin.Context)

JWKS returns the JSON web key set for the public RSA keys that are currently being used by Quarterdeck to sign JWT acccess and refresh tokens. External callers can use these keys to verify that a JWT token was in fact issued by the Quarterdeck API. TODO: add Cache-Control or Expires header to the response TODO: move the jwks construction to the token manager for easier key management.

func (*Server) Login ¶

func (s *Server) Login(c *gin.Context)

Login is oriented towards human users who use their email and password for authentication (whereas authenticate is used for machine access using API keys). Login verifies the password submitted for the user is correct by looking up the user by email and using the argon2 derived key verification process to confirm the password matches. Upon authentication an access token and a refresh token with the authorized claims of the user (based on role) are returned. The user can use the access token to authenticate to Ensign systems and the claims within for authorization. The access token has an expiration and the refresh token can be used with the refresh endpoint to get a new access token without the user having to log in again. The refresh token overlaps with the access token to provide a seamless authentication experience and the user can refresh their access token so long as the refresh token is valid.

This method primarily uses read queries (fetching the user from the database and fetching the user permissions from the database). It does update the user's last logged in timestamp in the database but should be highly available without Quarterdeck Raft replication in most cases. TODO: add rate limiting on a per-user basis to prevent Quarterdeck DOS.

func (*Server) OpenIDConfiguration ¶ added in v0.1.1

func (s *Server) OpenIDConfiguration(c *gin.Context)

Returns a JSON document with the OpenID configuration as defined by the OpenID Connect standard: https://connect2id.com/learn/openid-connect. This document helps clients understand how to authenticate with Quarterdeck. TODO: once OpenID endpoints have been configured add them to this JSON response

func (*Server) Refresh ¶

func (s *Server) Refresh(c *gin.Context)

TODO: implement the refresh endpoint

func (*Server) Register ¶

func (s *Server) Register(c *gin.Context)

Register creates a new user in the database with the specified password, allowing the user to login to Quarterdeck. This endpoint requires a "strong" password and a valid register request, otherwise a 400 reply is returned. The password is stored in the database as an argon2 derived key so it is impossible for a hacker to get access to raw passwords. By default the user is given the Member role, unless an organization is being created for the user, in which case the user is assigned the Owner role. TODO: add rate limiting to ensure that we don't get spammed with registrations TODO: review and ensure the register methodology is what we want TODO: handle organizations and invites (e.g. with role association).

func (*Server) SecurityTxt ¶ added in v0.1.1

func (s *Server) SecurityTxt(c *gin.Context)

Writes the security.txt file generated from https://securitytxt.org/ and digitally signed with the info@rotational.io PGP keys to alert security researchers to our security policies and allow them to contact us with any security flaws.

func (*Server) Serve ¶

func (s *Server) Serve() (err error)

Serve API requests while listening on the specified bind address.

func (*Server) SetHealth ¶

func (s *Server) SetHealth(health bool)

func (*Server) SetURL ¶

func (s *Server) SetURL(url string)

func (*Server) Shutdown ¶

func (s *Server) Shutdown() (err error)

Shutdown the server gracefully (usually called by OS signal).

func (*Server) Status ¶

func (s *Server) Status(c *gin.Context)

Status handler returns the current healthy status of the server (can't be unhealthy otherwise the Available middleware would have intercepted the request)

func (*Server) URL ¶

func (s *Server) URL() string