Oauth Applications And Token Management

As you integrate Oauth server capabilities into an application, you probably will generate client applications credentials for your client yourself, either in db directly or through irb:

DB[:oauth_applications).returning.insert client_id: SecureRandom.hex(32), \
  client_secret: SecureRandom.hex(32), \
  name: "Awesome client", \
  description: "bakes cakes", \
  redirect_uri: "https://awesome.com/oauth-callback", \
  scopes: "profile.read,profile.write"
# now send the resulting data through signal/whatsapp/please-dont-use-email-for-this....

However, there will come a point where this will not scale well, and you’ll need to productize this management, along with revoking tokens, observability…

rodauth-oauth already comes with a ready-to-use management dashboard.

Who is it for

If you want to integrate client application management in your application from the get-go.

How to enable it

In the roda app, after you load rodauth. However, make sure you protect access to it, as it does not require authentication by default!


# on roda app
route do |r|
  r.rodauth

  r.require_authentication(:admin)
  r.oauth_applications
end

Routes

Calling r.oauth_applications will generate the following URLs:

  • GET /oauth-applications: returns the OAuth applications dashboard;
  • GET /oauth-applications/{application_id}: returns an OAuth application page;
  • GET /oauth-applications/{application_id}/oauth-tokens: returns the OAuth tokens from an OAuth application page;
  • GET /oauth-applications/new: returns a new OAuth application form;
  • POST /oauth-applications: processes a new OAuth application request;

Views

As with the authorization form, you have to bundle the following erb/html views:

  • oauth_applications.(erb|str|...): the list of OAuth applications;
  • oauth_application.(erb|str|...): the OAuth application page;
  • new_oauth_application.(erb|str|...): the new OAuth application form;
  • oauth_tokens.(erb|str|...): the list of OAuth tokens from an application;

Client Secret Security

This setup also allows you to do something very important from the security perspective: not store the client secret in the OAuth Server.

If the OAuth application form contains a client_secret input, then the application owner can generate a random token locally, store it, and submit it in the form; rodauth-oauth will therefore store the hash of the client secret, using bcrypt.

This will limit exposure of applications to potential database leaks.

Example

the roda example app is a good place to start.

Rodauth Options

  • oauth_application_scopes: the scopes an application is able to request;
  • oauth_application_default_scope: the scope which applications will request by default;
  • oauth_application_required_params (default: %w[name description scopes homepage_url redirect_uri client_secret]) : the params which the OAuth application form needs to submit;
    • also, for each of these params, there’ll be a respective param options, i.e. for "name", there is a oauth_application_name_param;
  • oauth_application_client_id_param: the client id param (default: "client_id");
  • oauth_applications_path (default: "oauth-application"): the resource sub URL path for oauth applications;
  • oauth_tokens_path (default: "oauth-tokens"): the resource sub URL path for oauth tokens;
  • oauth_applications_id_pattern(default: Integer): the pattern to filter the client application if from the URL (in case you don’t go with auto-increment integers for the primary key, this is what you’ll need to change);
  • oauth_valid_uri_schemes (default: ["https"]): accepted URI schemes for redirect URI of client applications;

Home