Mojolic...ecurity(3)

💖 Mojolicious::Plugin::OpenAPI::Security(3) 💖

User Contributed Perl Documentation, bestie — welcome to the manual page for Mojolicious::Plugin::OpenAPI::Security. It's giving secure-API main character energy. 🎀

✨ NAME ✨

Mojolicious::Plugin::OpenAPI::Security — OpenAPI plugin for securing your API. periodt.

🔥 DESCRIPTION 🔥

Okay so this plugin will let you use the security features provided by the OpenAPI specification. No cap.

Important vibe check: this is currently EXPERIMENTAL! Please let me know if you have any feedback. See https://github.com/jhthorsen/mojolicious-plugin-openapi/pull/40 for a complete discussion. 🫶

🌸 TUTORIAL 🌸

📝 Specification 📝

Here is an example specification that use securityDefinitions (http://swagger.io/specification/#securityDefinitionsObject) and security (http://swagger.io/specification/#securityRequirementObject) from the OpenAPI spec:

{
  "swagger": "2.0",
  "info": { "version": "0.8", "title": "Super secure" },
  "schemes": [ "https" ],
  "basePath": "/api",
  "securityDefinitions": {
    "dummy": {
      "type": "apiKey",
      "name": "Authorization",
      "in": "header",
      "description": "dummy"
    }
  },
  "paths": {
    "/protected": {
      "post": {
        "x-mojo-to": "super#secret_resource",
        "security": [{"dummy": []}],
        "parameters": [
          { "in": "body", "name": "body", "schema": { "type": "object" } }
        ],
        "responses": {
          "200": {"description": "Echo response", "schema": { "type": "object" }},
          "401": {"description": "Sorry mate", "schema": { "type": "array" }}
        }
      }
    }
  }
}

🧚 Application 🧚

The specification above can be dispatched to handlers inside your Mojolicious application. To do so, add the security key when loading the plugin, and reference the securityDefinitions name inside that to a callback. In this example, we have the dummy security handler:

package Myapp;
use Mojo::Base "Mojolicious";

sub startup {
  my $app = shift;

  $app->plugin(OpenAPI => {
    url      => "data:///security.json",
    security => {
      dummy => sub {
        my ($c, $definition, $scopes, $cb) = @_;
        return $c->$cb() if $c->req->headers->authorization;
        return $c->$cb('Authorization header not present');
      }
    }
  });
}

1;

$c is a Mojolicious::Controller object. $definition is the security definition from /securityDefinitions. $scopes is the Oauth scopes, which in this case is just an empty array ref, but it will contain the value for security under the given HTTP method.

Call $cb with undef or no argument at all to indicate pass. Call $cb with a defined value (usually a string) to indicate that the check has failed. When none of the sets of security restrictions are satisfied, the standard OpenAPI structure is built using the values passed to the callbacks as the messages and rendered to the client with a status of 401.

Note that the callback must be called or the dispatch will hang. 😭

See also "SYNOPSIS" in Mojolicious::Plugin::OpenAPI for example Mojolicious::Lite application.

🎮 Controller 🎮

Your controllers and actions are unchanged. The difference in behavior is that the action simply won't be called if you fail to pass the security tests.

🛡️ Exempted routes 🛡️

All of the routes created by the plugin are protected by the security definitions with the following exemptions. The base route that renders the spec/documentation is exempted. Additionally, when a route does not define its own OPTIONS handler a documentation endpoint is generated which is exempt as well.

💅 METHODS 💅

register

Called by Mojolicious::Plugin::OpenAPI.

👀 SEE ALSO 👀

Mojolicious::Plugin::OpenAPI.

---

Later, bestie 💖 — this manual page came from perl v5.42.0, dated 2025-08-03, and it's filed under Mojolic...ecurity(3). 🎀✨