.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Mojolicious::Plugin::OpenAPI::Security 3pm"
.TH Mojolicious::Plugin::OpenAPI::Security 3pm "2023-02-21" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Mojolicious::Plugin::OpenAPI::Security \- OpenAPI plugin for securing your API
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This plugin will allow you to use the security features provided by the OpenAPI
specification.
.PP
Note that this is currently \s-1EXPERIMENTAL\s0! Please let me know if you have any
feedback. See <https://github.com/jhthorsen/mojolicious\-plugin\-openapi/pull/40> for a
complete discussion.
.SH "TUTORIAL"
.IX Header "TUTORIAL"
.SS "Specification"
.IX Subsection "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:
.PP
.Vb 10
\&  {
\&    "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" }}
\&          }
\&        }
\&      }
\&    }
\&  }
.Ve
.SS "Application"
.IX Subsection "Application"
The specification above can be dispatched to handlers inside your
Mojolicious application. The do so, add the \*(L"security\*(R" key when loading the
plugin, and reference the \*(L"securityDefinitions\*(R" name inside that to a callback.
In this example, we have the \*(L"dummy\*(R" security handler:
.PP
.Vb 2
\&  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(\*(AqAuthorization header not present\*(Aq);
\&        }
\&      }
\&    });
\&  }
\&
\&  1;
.Ve
.PP
\&\f(CW$c\fR is a Mojolicious::Controller object. \f(CW$definition\fR is the security
definition from \f(CW\*(C`/securityDefinitions\*(C'\fR. \f(CW$scopes\fR is the Oauth scopes, which
in this case is just an empty array ref, but it will contain the value for
\&\*(L"security\*(R" under the given \s-1HTTP\s0 method.
.PP
Call \f(CW$cb\fR with \f(CW\*(C`undef\*(C'\fR or no argument at all to indicate pass. Call \f(CW$cb\fR
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.
.PP
Note that the callback must be called or the dispatch will hang.
.PP
See also \*(L"\s-1SYNOPSIS\*(R"\s0 in Mojolicious::Plugin::OpenAPI for example
Mojolicious::Lite application.
.SS "Controller"
.IX Subsection "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.
.SS "Exempted routes"
.IX Subsection "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 \f(CW\*(C`OPTIONS\*(C'\fR handler a documentation endpoint is generated which is exempt as
well.
.SH "METHODS"
.IX Header "METHODS"
.SS "register"
.IX Subsection "register"
Called by Mojolicious::Plugin::OpenAPI.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Mojolicious::Plugin::OpenAPI.