GoActivityPub Documentation Wiki

The authorize stand alone application provides OAuth2 user authorization mechanisms compatible with the FedBOX storage backends.

The OAuth2 endpoints a FedBOX actor exposes are meant to be handled by this service.

{
	// For actor https://social.example.com/actors/11111111-2222-3333-4444-555555555555
	"endpoints": {
		"oauthAuthorizationEndpoint": "https://social.example.com/actors/11111111-2222-3333-4444-555555555555/oauth/authorize",
		"oauthTokenEndpoint": "https://social.example.com/actors/11111111-2222-3333-4444-555555555555/oauth/token",
		"proxyUrl": "https://social.example.com/proxyUrl"
	}
}

Features

The service provides the following authorization and client registration mechanisms:

• OAuth2 authorization for Person actors with the Authorization Code grant.
• OAuth2 authorization for Application, Group and Service actors using the legacy Password grant.
• Dynamically create OAuth2 clients (which in turn creates associated Application actors for them):
  • Using the RFC7591 and RFC8414 mechanisms. (The Authorization Server Metadata is provided by the .well-known service.)
  • Using the OAuth2 CIMD mechanism.
• Client to Server ProxyUrl support from FedBOX. Any client can proxy a request to a third-party ActivityPub instance through the proxyUrl mechanism specified by the ActivityPub specification.

Authorization flow

The way the authorization flow for an actor on a FedBOX instance works is as follows:

1. Using the Actor’s ID, the actor object is fetched from FedBOX.
2. The Authorization Server Metadata is fetched from its /.well-known/oauth-authorization-server path. The server supports fetching the information for specific Actors by using the multi issuers per host mechanism.

• Using the registration_endpoint for the Actor issuer, the client can send an Dynamic Client Registration Request.
• If at point 2 the Metadata document included a client_id_metadata_document_supported value of true the client can use instead the CIMD mechanism for dynamic registration.

3. Once the client application was created successfully an OAuth2 authorization flow can be attempted using the Actor’s OAuth2 endpoints.

Installation

Similarly to FedBOX we do not currently provide pre-compiled binaries for this service, but we do have docker compatible images.

For steps for compiling and setting up the application from source see the installation instructions.

The docker images can be found on the GoActivityPub quay.io page.

Running the server

The authorize server accepts the same configuration .env file as FedBOX and accepts it as a --config argument in the command line.

Configuration with the .env file

$ authorize --config /storage/.env

The environment variables it recognizes and uses from that file are STORAGE, STORAGE_PATH and ENV. They are described in the FedBOX .env.dist file.

ENV

The environment that the authorize server will run as. The values are prod, qa, and dev.

STORAGE

The STORAGE env variable represents the storage type, currently we support the same ones as described in the storage modules list.

• fs - file system
• sqlite - sqlite single file database
• boltdb - BoltDB key-value store
• badger - Badger key-value store

STORAGE_PATH

The STORAGE_PATH represents the path on disk to the storage directory.

It supports some conveniences placeholders that are replaced with corresponding values:

• If a path starts with ‘~’, it gets replaced with the current user’s home directory, if the HOME environment variable is present in the running environment.
• If a path contains ‘%env%’ it gets replaced with the current ENV value.
• If a path contains ‘%storage%’ it gets replaced with the current STORAGE value.

Configuration using a storage path directly

$ authorize --path fs:///storage/example.com/qa

The storage path logic can be circumvented by using directly a custom dsn that has the following structure: type:///actual/disk/path, where type is the storage type described above, and /actual/disk/path is the actual path on disk of the storage directory.

Running the server together with FedBOX

To be able to have a setup with a mixed configuration, where the authorize server runs alongside FedBOX, you get the additional requirement that the requests done to the OAuth2 authorization endpoints are proxied to the correct service.

Here’s an example using Caddy:

# actors oauth endpoints
handle /actors/*/oauth/* {
	reverse_proxy http://authorize-service:1234 {
		transport http
	}
}
# root service oauth endpoints
handle /oauth/* {
	reverse_proxy http://authorize-service:1234 {
		transport http
	}
}