1Mojolicious::Plugin::OpUesneArPIC:o:nSterciubruitteydM(o3Pj)eorllicDioocuusm:e:nPtlautgiionn::OpenAPI::Security(3)
2
3
4

NAME

6       Mojolicious::Plugin::OpenAPI::Security - OpenAPI plugin for securing
7       your API
8

DESCRIPTION

10       This plugin will allow you to use the security features provided by the
11       OpenAPI specification.
12
13       Note that this is currently EXPERIMENTAL! Please let me know if you
14       have any feedback. See
15       <https://github.com/jhthorsen/mojolicious-plugin-openapi/pull/40> for a
16       complete discussion.
17

TUTORIAL

19   Specification
20       Here is an example specification that use securityDefinitions
21       <http://swagger.io/specification/#securityDefinitionsObject> and
22       security <http://swagger.io/specification/#securityRequirementObject>
23       from the OpenAPI spec:
24
25         {
26           "swagger": "2.0",
27           "info": { "version": "0.8", "title": "Super secure" },
28           "schemes": [ "https" ],
29           "basePath": "/api",
30           "securityDefinitions": {
31             "dummy": {
32               "type": "apiKey",
33               "name": "Authorization",
34               "in": "header",
35               "description": "dummy"
36             }
37           },
38           "paths": {
39             "/protected": {
40               "post": {
41                 "x-mojo-to": "super#secret_resource",
42                 "security": [{"dummy": []}],
43                 "parameters": [
44                   { "in": "body", "name": "body", "schema": { "type": "object" } }
45                 ],
46                 "responses": {
47                   "200": {"description": "Echo response", "schema": { "type": "object" }},
48                   "401": {"description": "Sorry mate", "schema": { "type": "array" }}
49                 }
50               }
51             }
52           }
53         }
54
55   Application
56       The specification above can be dispatched to handlers inside your
57       Mojolicious application. The do so, add the "security" key when loading
58       the plugin, and reference the "securityDefinitions" name inside that to
59       a callback.  In this example, we have the "dummy" security handler:
60
61         package Myapp;
62         use Mojo::Base "Mojolicious";
63
64         sub startup {
65           my $app = shift;
66
67           $app->plugin(OpenAPI => {
68             url      => "data:///security.json",
69             security => {
70               dummy => sub {
71                 my ($c, $definition, $scopes, $cb) = @_;
72                 return $c->$cb() if $c->req->headers->authorization;
73                 return $c->$cb('Authorization header not present');
74               }
75             }
76           });
77         }
78
79         1;
80
81       $c is a Mojolicious::Controller object. $definition is the security
82       definition from "/securityDefinitions". $scopes is the Oauth scopes,
83       which in this case is just an empty array ref, but it will contain the
84       value for "security" under the given HTTP method.
85
86       Call $cb with "undef" or no argument at all to indicate pass. Call $cb
87       with a defined value (usually a string) to indicate that the check has
88       failed.  When none of the sets of security restrictions are satisfied,
89       the standard OpenAPI structure is built using the values passed to the
90       callbacks as the messages and rendered to the client with a status of
91       401.
92
93       Note that the callback must be called or the dispatch will hang.
94
95       See also "SYNOPSIS" in Mojolicious::Plugin::OpenAPI for example
96       Mojolicious::Lite application.
97
98   Controller
99       Your controllers and actions are unchanged. The difference in behavior
100       is that the action simply won't be called if you fail to pass the
101       security tests.
102
103   Exempted routes
104       All of the routes created by the plugin are protected by the security
105       definitions with the following exemptions.  The base route that renders
106       the spec/documentation is exempted.  Additionally, when a route does
107       not define its own "OPTIONS" handler a documentation endpoint is
108       generated which is exempt as well.
109

METHODS

111   register
112       Called by Mojolicious::Plugin::OpenAPI.
113

SEE ALSO

115       Mojolicious::Plugin::OpenAPI.
116
117
118
119perl v5.36.0                      2023M-o0j1o-l2i0cious::Plugin::OpenAPI::Security(3)
Impressum