Repository navigation
Authorization Service Design
The authorization service provides an OAuth2 implementation built using the Fosite library. To accomplish this, it provides an HTTP interface that maps to internal Fosite calls and a data store adapter to allow authorization and identity data to be persisted to the Cassandra database.
The authorization service is started using the command line interface's host command. This results in the creation of a new App and DataStore and passes them to the HTTPController's constructor.
The HTTP controller is responsible for handling incoming HTTP calls and delegating them to the Fosite library. It uses the configuration passed in by the Authorization Service Command Line Interface.
The token endpoint accepts HTTP calls at the /oauth2/token endpoint. This implements the following OAuth2 grants:
Support for the Authorization Code Grant and Implicit Grant will be added in future releases to offer better support for web applications. This will allow the built-in login endpoint to be used followed by a redirect to the provided client URI.
The underlying implementation of these grants is handled by the Fosite library. This design decision was made to save development time and avoid introducing bugs when implementing the OAuth2 protocol.
The revoke endpoint accepts HTTP calls at /oauth2/revoke. Incoming calls are delegated to the Fosite library which instructs the DataStoreAdapter to remove the access token and associated refresh token from the database.
There are two registration endpoints: Register and SubmitRegistration available as GET and POST requests respectively at /oauth2/register. Register is designed to handle get requests and display a HTML interface for registering new accounts. This design allows for the easy creation of new accounts. However, the purpose of the design was to provide a default login page for use with the Authorization Code Grant. In the future, this will allow the login page to redirect to a URI provided by the developer using the Authorization Service Command Line Interface.
The SubmitRegistration is designed to handle HTTP post requests. This provides an endpoint for developers to use to create new accounts to access protected endpoints for the APIs they are managing using a Kubernetes cluster running Express.
The design of the login endpoints, Login and SubmitLogin is identical to that of the registration endpoints. These endpoints are available as GET and POST requests respectively at /oauth2/login. This design allows for future support for the Authorization Code Grant while still providing support for logging into accounts to access protected endpoints using the SubmitLogin POST handler.
The introspect endpoint is accessible at /oauth2/introspect and allows for access and refresh tokens to be validated. This includes checking both validity of the token and its scopes. This endpoint does not implement the OAuth2 Token Introspection Standard.
The endpoint's design is based on performing token introspection on bearer tokens passed in the Authorization header rather than a POST body as specified in the standard. This design allows for the Express reverse proxy to perform introspection on requests to protected endpoints by stripping the body and forwarding the header to the authorization service. As a result, complete decoupling can be achieved between the APIs deployed using the Express Controller and the internal authorization service used by Express.
The data store adapter implements that data store interface required by the Fosite OAuth2Provider. This includes creation, fetching, and deletion for the following items:
- Users Accounts
- OAuth2 Clients
- Sessions
- Access Tokens
- RefreshTokens
The design of the data store adapter is based on mapping the Fosite calls to Cassandra queries for data persistence. This is done using GoCQLX which provides an object-relational map to eliminate the chance of syntax errors when writing the CQL queries.
The default user, client, and session structures provide an implementation for their corresponding [Fosite](https://github.com/ory/fosite interfaces. This is required for the design because the library does not provide concrete implementations for these interfaces.