Soapbox Legacy is federated, therefore you can't be expected to manually register your application on all potential servers your users might want to login on. For this reason, there is an open app registration API, so obtaining OAuth 2 credentials for OAuth 2 authorization can be automated.
Make sure that you allow your users to specify the domain they want to connect to before login. Use that domain to acquire a client id/secret for OAuth 2 and then proceed with normal OAuth 2 also using that domain to build the URLs.
Soapbox Legacy supports the following OAuth 2 flows:
- Authorization code flow: For end-users
- Password grant flow: For bots and other single-user applications
- Client credentials flow: For applications that do not act on behalf of users
OAuth 2 endpoints¶
The following descriptions are taken from the Doorkeeper documentation. Soapbox Legacy uses Doorkeeper to implement OAuth 2.
Redirect here with
scope, and optional
state. Displays an authorization form to the user. If approved, it will create and return an authorization code, then redirect to the desired
redirect_uri, or show the authorization code if
urn:ietf:wg:oauth:2.0:oob was requested.
Post here with
authorization_code for authorization code grant type or
password for password grant type. Returns an access token. This corresponds to the token endpoint, section 3.2 of the OAuth 2 RFC.
Post here with client credentials (in basic auth or in params
client_secret) to revoke an access token. This corresponds to the token endpoint, using the OAuth 2.0 Token Revocation RFC (RFC 7009).
Example authorization code flow¶
client_secretfrom your local cache. If you don't have the two, you need to register the application. Store
client_secretin your local cache for next time. We actually don't need the
idreturned from this call.
- Tell the user to visit
client_id, and optionally a randomly-generated
stateparameter. The user clicks on the URL and gets shown a page asking them to authorize your app for the scopes you requested. If the user clicks on the right button, they are redirected back to your
codeparam in the query string. That is the authorization code. If you provided a
statevalue in the previous step, that will be passed along as well.
- Send a POST request to
/oauth/tokenwith the parameters
redirect_uri. Save the
access_tokenyou get back in your local cache. Note that an authorization code can only be used once. If it has been used already, you need to repeat step two to get a new one.
Once you have the access token, add the HTTP header
Authorization: Bearer ... to any API call.
- The OAuth param name is
scope, but when registering the application using Soapbox Legacy's REST API, the param name is
scopes. The OAuth param can be a subset of the scopes you registered initially, but cannot include anything that wasn't in the original set.
- The OAuth param name is
redirect_uri, but when registering the application using Soapbox Legacy's REST API, the param name is
redirect_uris. The latter can actually consist of multiple allowed URIs, separated by newlines.
redirect_uriin all OAuth requests must either be the same as the one registered with the application, or one of them, if you registered multiple URIs separated by newlines with the application.