{"id":16102391,"url":"https://github.com/sshaw/mojolicious-plugin-digestauth","last_synced_at":"2025-04-12T23:12:22.029Z","repository":{"id":1580144,"uuid":"2060655","full_name":"sshaw/Mojolicious-Plugin-DigestAuth","owner":"sshaw","description":"HTTP Digest Authentication for Mojolicious","archived":false,"fork":false,"pushed_at":"2021-03-30T00:45:42.000Z","size":51,"stargazers_count":1,"open_issues_count":1,"forks_count":5,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-12T23:12:05.763Z","etag":null,"topics":["authentication","digest","http-requests","mojolicious","perl","security-protocol"],"latest_commit_sha":null,"homepage":"","language":"Perl","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sshaw.png","metadata":{"files":{"readme":"README.pod","changelog":"Changes","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2011-07-17T05:22:03.000Z","updated_at":"2021-03-30T00:45:45.000Z","dependencies_parsed_at":"2022-08-28T13:10:20.824Z","dependency_job_id":null,"html_url":"https://github.com/sshaw/Mojolicious-Plugin-DigestAuth","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sshaw%2FMojolicious-Plugin-DigestAuth","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sshaw%2FMojolicious-Plugin-DigestAuth/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sshaw%2FMojolicious-Plugin-DigestAuth/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sshaw%2FMojolicious-Plugin-DigestAuth/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sshaw","download_url":"https://codeload.github.com/sshaw/Mojolicious-Plugin-DigestAuth/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248643004,"owners_count":21138355,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["authentication","digest","http-requests","mojolicious","perl","security-protocol"],"created_at":"2024-10-09T18:53:43.063Z","updated_at":"2025-04-12T23:12:22.001Z","avatar_url":"https://github.com/sshaw.png","language":"Perl","funding_links":[],"categories":[],"sub_categories":[],"readme":"=pod\n\n=encoding UTF-8\n\n=head1 NAME\n\nMojolicious::Plugin::DigestAuth - HTTP Digest Authentication for Mojolicious\n\n=head1 SYNOPSIS\n\n   $self-\u003eplugin('digest_auth');\n\n   # In your action\n   return unless $self-\u003edigest_auth(allow =\u003e { sshaw =\u003e 'password' });\n\n   # Or, in startup()\n   my $r = $self-\u003edigest_auth('/admin', allow =\u003e { sshaw =\u003e 'password' });\n   $r-\u003eroute('/new')-\u003eto('users#new');\n\n=head1 CONFIGURATION\n\n=head2 SETUP\n\nConfiguration can be done globally when loading the plugin\n\n    $self-\u003eplugin('digest_auth', %options)\n\nor locally when calling L\u003c\u003c C\u003cdigest_auth\u003e|/digest_auth \u003e\u003e\n\n    $self-\u003edigest_auth(%options);\n\nLocal options override their global counterparts. For example, the following\nwill apply to all authentication requests\n\n   # setup()\n   $self-\u003eplugin('digest_auth', realm   =\u003e 'Thangz',\n                                expires =\u003e 120,\n                                allow   =\u003e '/path/to/htdigest_file');\n\n\n   # controller\n   sub show\n   {\n       my $self = shift;\n       return unless $self-\u003edigest_auth;\n\n       # ...\n   }\n\nBut can be overridden within an action\n\n   sub edit\n   {\n       my $self = shift;\n       return unless $self-\u003edigest_auth(realm   =\u003e 'RealmX',\n                                        expires =\u003e 24*3600,\n                                        allow   =\u003e { sshaw =\u003e 'Ay3Br4h_!' });\n       # ...\n   }\n\nFor a full list of options see L\u003c/digest_auth\u003e.\n\n=head2 AUTHENTICATION\n\nBy default MD5/auth authentication is performed. This is configurable, see L\u003c/digest_auth\u003e.\n\n=head3 DB\n\nAuthentication information is given via the C\u003callow\u003e option and can be retrieved\nfrom a variety of sources:\n\n=over 4\n\n=item * A hash reference without a realm\n\n    $self-\u003eplugin('digest_auth', allow =\u003e { sshaw =\u003e 'my_pAzw3rD',\n                                            admin =\u003e '-\u003efofinha!' });\n\nIn this case users will either be placed into the realm given by the C\u003crealm\u003e option or\nthe default realm, C\u003cWWW\u003e.\n\nPasswords must be given in plain text.\n\n=item * A hash reference with realm(s)\n\n    $self-\u003eplugin('digest_auth', allow =\u003e { 'Admin Realm' =\u003e { sshaw =\u003e 'my_pAzw3rD' },\n                                            'WWW Users'   =\u003e { tony  =\u003e 'vrooooooom' });\n\nPasswords must be given in plain text.\n\n=item * An htdigest style file\n\n    $self-\u003eplugin('digest_auth', allow =\u003e '/home/sshaw/www_users');\n\n=item * An object with a C\u003cget()\u003e method that returns B\u003chashed\u003e passwords\n\n    $self-\u003eplugin('digest_auth', allow =\u003e $db);\n\nArguments are passed to C\u003cget()\u003e in the following order: C\u003crealm, username\u003e.\n\n=back\n\n=head3 PERFORMING AUTHENTICATION\n\nAuthentication can be performed by calling the C\u003cdigest_auth\u003e method\nfrom within the action you'd like to protect:\n\n   sub some_action\n   {\n       my $self = shift;\n       return unless $self-\u003edigest_auth;\n\n       # Authenticated users get here\n   }\n\nIf authentication is successful C\u003cdigest_auth\u003e returns true, otherwise C\u003cundef\u003e is returned\nand a HTTP 401 status code and the message: C\u003cHTTP 401: Unauthorized\u003e are sent\nto the client. Currently this message cannot be changed.\n\nAuthentication can also be performed for a set of routes by calling\nC\u003cdigest_auth\u003e from within your application's startup function. This form performs authentication automatically\nfor all of the routes defined under the given URL:\n\n   package YourWebApp;\n\n   use Mojo::Base 'Mojolicious';\n\n   sub startup\n   {\n     my $self = shift;\n     $self-\u003eplugin('digest_auth', %options);\n\n     # ...\n\n     my $admin = $self-\u003edigest_auth('/admin');\n     $admin-\u003eroute('/new')-\u003eto('users#new');\n     $admin-\u003eroute('/edit/:id')-\u003eto('users#edit');\n   }\n\nIn this case authentication is performed via a L\u003cbridge|Mojolicious::Guides::Routing/Bridges\u003e with a callback.\n\n=head3 WEB SERVERS\n\nAuthentication will fail if your application is sitting behind a web server does not pass the Authorization header\nto your application. In Apache this can be achieved with C\u003cmod_rewrite\u003e:\n\n   RewriteEngine On\n   RewriteRule ^ - [E=X-HTTP_AUTHORIZATION:%{HTTP:Authorization}]\n\n=head1 METHODS\n\n=head2 plugin\n\n     $self-\u003eplugin('digest_auth', %options)\n\nLoads the plugin and sets up the defaults given by C\u003c%options\u003e.\n\n=head3 Arguments\n\nC\u003c%options\u003e\n\nSee L\u003c/digest_auth\u003e.\n\n=head3 Errors\n\nThis method will C\u003ccroak\u003e if if any of the options are invalid or if there is an error loading the password database.\n\n=head2 digest_auth\n\n     $self-\u003edigest_auth(%options)\n     $routes = $self-\u003edigest_auth($url, %options)\n\n=head3 Arguments\n\nC\u003c$url\u003e\n\nOptional. If provided authentication will be performed for all routes defined under C\u003c$url\u003e.\nSee L\u003c/PERFORMING AUTHENTICATION\u003e.\n\nC\u003c%options\u003e\n\n=over 4\n\n=item * C\u003c\u003c allow =\u003e { user =\u003e password } \u003e\u003e\n\n=item * C\u003c\u003c allow =\u003e { realm =\u003e { user =\u003e password }} \u003e\u003e\n\n=item * C\u003c\u003c allow =\u003e 'htdigest_file' \u003e\u003e\n\n=item * C\u003c\u003c allow =\u003e $obj \u003e\u003e\n\nSee L\u003c/DB\u003e.\n\n=item * C\u003c\u003c algorithm =\u003e 'MD5' | 'MD5-sess' \u003e\u003e\n\nDigest algorithm, either C\u003c'MD5'\u003e or C\u003c'MD5-sess'\u003e. Defaults to C\u003c'MD5'\u003e, C\u003c'MD5-sess'\u003e requires a C\u003cqop\u003e.\n\n=item * C\u003c\u003c domain =\u003e '/path' | 'your.domain.com' \u003e\u003e\n\nAuthentication domain. Defaults to C\u003c'/'\u003e.\n\n=item * C\u003c\u003c expires =\u003e seconds \u003e\u003e\n\nNonce lifetime. Defaults to C\u003c300\u003e seconds (5 minutes).\n\n=item * C\u003c\u003c qop =\u003e 'auth' | '' \u003e\u003e\n\nQuality of protection. Defaults to C\u003c'auth'\u003e.  C\u003cauth-int\u003e is not supported.\n\n=item * C\u003c\u003c realm =\u003e 'Your Realm' \u003e\u003e\n\nAuthentication realm. Defaults to C\u003c'WWW'\u003e.\n\n=item * C\u003c\u003c secret =\u003e 'a salt value' \u003e\u003e\n\nUsed to create the nonce. Defaults to L\u003cyour application's secret|Mojolicious/secrets\u003e, which means\nyou must set your application's secret before loading this plugin. If you're using an array the B\u003cfirst value\u003e\nin the array will be used.\n\nB\u003cIMPORTANT\u003e: Changing this value will cause an HTTP 400 response to be returned to any clients with cached authentication\ncredentials.\n\n=item * C\u003c\u003c support_broken_browsers =\u003e 1 | 0 \u003e\u003e\n\nWhen processing requests from certain browsers skip steps that would otherwise result in a HTTP 400 response. Defaults to C\u003c1\u003e.\n\nCurrently only applies to IE 5 and 6. These two browsers fail to append the query string to the URI included in the\nAuthorization header and, after authenticating, fail to include the opaque value.\n\n=back\n\n=head3 Returns\n\nWithout a URL prefix:\n\nTrue if authentication was successful, C\u003cundef\u003e otherwise. If unsuccessful a HTTP 401 status code and message are sent to the client.\n\nWith a URL prefix:\n\nAn instance of L\u003cMojolicious::Routes\u003e. See L\u003c/PERFORMING AUTHENTICATION\u003e.\n\n=head3 Errors\n\nWill C\u003ccroak\u003e if any of the options are invalid.\n\n=head1 SEE ALSO\n\nL\u003cMojolicious\u003e, L\u003cMojolicious::Plugin::BasicAuth\u003e, http://en.wikipedia.org/wiki/Digest_access_authentication\n\n=head1 AUTHOR\n\nSkye Shaw (skye.shaw AT gmail.com)\n\n=head1 LICENSE\n\nCopyright (c) 2011 Skye Shaw.\nThis library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsshaw%2Fmojolicious-plugin-digestauth","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsshaw%2Fmojolicious-plugin-digestauth","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsshaw%2Fmojolicious-plugin-digestauth/lists"}