Background:
This issue is part of the meta-issue for updating the hook_help texts of the Drupal 8 modules:
#1908570: [meta] Update or create hook_help() texts for D8 core modules

Tasks:
- review / write the hook_help text according to help guidelines http://drupal.org/node/632280
More details are on the meta-issue.

Support from Acquia helps fund testing for Drupal Acquia logo

Comments

clemens.tolboom’s picture

The text used for basic_auth

      $output .= '<p>' . t('The basic auth module implements basic user authentication using the HTTP Basic authentication provider.') . '</p>';

is repeating itself:

  • basic (3x)
  • authentication (2x)

and is not helping me in understanding what to do next. Do I have to configure something? Add a username / password somewhere?

Checking the tests for basic_auth I see what the module does but still no clue what to do to configure the site for basic_auth. In router_test.routing.yml there is a router path using basic_auth.

router_test.11:
  path: '/router_test/test11'
  options:
    _auth: [ 'http_basic' ]
  requirements:
    _user_is_logged_in: 'TRUE'
  defaults:
    _content: '\Drupal\router_test\TestContent::test11'

I'm still lost :)

jhodgdon’s picture

Two suggestions:

a) Go to IRC channel #drupal-contribute and see if anyone there can help you figure this out. Start your query by saying you are working on this issue and hopefully someone will answer. You can also see who the maintainers of this module are in core/MAINTAINERS.txt and specifically ask them in IRC.

b) Put this issue in the basic_auth.module component and let the maintainers answer it in the issue queue.

jhodgdon’s picture

Issue summary: View changes

forgot guidelines link

batigolix’s picture

Component: documentation » other
Issue summary: View changes
Status: Active » Needs review
FileSize
1.17 KB

Here a modest first attempt.

Still to do:
- assign to right component (I do not see basic auth in the list)
- get some maintainer feedback (nothing found in MAINTAINERS.txt)
- go on IRC and ask around
- on line docs on d.o.

jhodgdon’s picture

The help text looks reasonable to me.

I didn't see an issue about making a MAINTAINERS or a compnent and my query in IRC wasn't answered, so I filed #2156161: Add basic_auth module to MAINTAINERS.txt and issue components

klausi’s picture

Component: other » rest.module
Status: Needs review » Needs work

This module does not protect any webpages, so the help text is misleading. The primary use case of the module is to be used as an authentication provider for web service calls with REST module for example. Moving to the REST component for now.

So a client can use the Basic Authentication HTTP header instead of session cookies to perform user account authentication against the users database table. This is useful for non-human clients, such as web service consumers, which do not want to deal with cookies.

Can we distill that to one sentence? :-)

jhodgdon’s picture

It doesn't have to be one sentence. :)

batigolix’s picture

Status: Needs work » Needs review
FileSize
1.43 KB
1.03 KB

New attempt with, hopefully, less misleading wording.

Status: Needs review » Needs work

The last submitted patch, 7: update-hook-help-basic-auth.2103035-7.patch, failed testing.

batigolix’s picture

Status: Needs work » Needs review
jhodgdon’s picture

Component: rest.module » basic_auth.module

This looks pretty good to me, except that maybe we should be more specific? It says the module "provides clients a way to authenticate user accounts", and it probably should say something like "provides an authentication handler that uses HTTP headers instead of cookies to authenticate users, for other modules to use". And maybe we should also say explicitly that it doesn't have a user interface?

I'm also not sure about this sentence: "This is useful for web service consumers that can not deal with cookies." ... web service consumers? What does that mean?

jhodgdon’s picture

Status: Needs review » Needs work
clemens.tolboom’s picture

  • +++ b/core/modules/basic_auth/basic_auth.module
    @@ -13,7 +13,7 @@ function basic_auth_help($path, $arg) {
    +      $output .= '<p>' . t('The <a href="http://en.wikipedia.org/wiki/Basic_access_authentication">HTTP Basic Authentication</a> module provides clients a way to authenticate user accounts without using cookies. This is useful for web service consumers that can not deal with cookies. For more information, see <a href="!hba_do">the online documentation for the HTTP Basic Authentication module</a>.', array('!hba_do' => 'https://drupal.org/documentation/modules/basic_auth')) . '</p>';
    

    The page https://drupal.org/documentation/modules/basic_auth does not exists yet.

  • Having the module enabled + configured (currently impossible afaik) the pages will provide for a dialog upfront asking for a username + password.
  • Ain't it better to have the text in the issue? It makes it way easier to read within the issue. And is saves the test bot some work. Like this

    The HTTP Basic Authentication module provides clients a way to authenticate user accounts without using cookies. This is useful for web service consumers that can not deal with cookies. For more information, see the online documentation for the HTTP Basic Authentication module

clemens.tolboom’s picture

clemens.tolboom’s picture

After @klausi replied in #2165393-3: There are no hints on how to use basic_auth module yet. I finally got it. We authenticate Drupal users by sending their username / password together with the request.

So maybe we could add some reference to REST module? Something in line with:

For this to work you probably register a user on your site that is allowed to do REST request.

jhodgdon’s picture

None of the information in the past few comments makes any sense to me.

So... Can you explain what this module does, what happens when you enable it, and how users are authenticated? Does it completely override the normal way to authenticate users -- that seems to be what you are saying in #12 -- or is it just for some pages? I just don't get it.

clemens.tolboom’s picture

In #14 I denied #12

AFAIK now the basic_auth module helps other module to allow access to configured resources / URLs on a drupal website not by normal login workflow using cookies but by adding username/password on the request itself.

The curl command on https://drupal.org/node/2098511 is probably the best example.

Did this help?

jhodgdon’s picture

RE #16 - that is kind of what I thought this module did. So I think my comments in #10 are probably a good idea still, rather than #14.

clemens.tolboom’s picture

AFAIK both #10 and #14 are true.

Say you wan to expose nodes through json usable for a server. Then you create a particular user only having rights to do json requests.

But for d.o we want #1710850: Deploy RestWS for D7 project issue JSON give access to all users aka their tools like drush or dreditor.

To put some more oil on the fire :-(

On http://drupal.d8/admin/config/development/testing/settings on can set Basic Auth for the test to access the site but that's done / service by apache.

I personally find the same/similar terms confusing.

jhodgdon’s picture

OK, let's step back here.

All that this module really does, in technical terms, is to provide a Drupal Service whose machine name is authentication.basic_auth, which uses the Drupal\basic_auth\Authentication\Provider\BasicAuth class. What that service/class does, again in technical terms, is to grab the user name and password from the HTTP header's standard "Basic" authentication, and authenticate as a Drupal user account name and password. This service can be used by the REST module and similar modules providing web services to authenticate the web services calls via HTTP Basic Authentication instead of making the user of the web services go to /user and log in to the site (which would set cookies).

So. The question is, how to put this into some text appropriate for hook_help().

The hook_help text currently says:

The basic auth module implements basic user authentication using the HTTP Basic authentication provider.

Problems with this:
- It doesn't follow our standard hook_help template (which includes a link to the drupal.org docs page for this module -- which may not exist yet but if it doesn't, we'll create it, because our standards say there should be one).
- The name of the module in the text doesn't match the actual human-readable name of the module, which is 'HTTP Basic Authentication'
- It doesn't give us much information about what the module does or how to use it.

The latest patch addresses the first two items admirably, and so we need to figure out better text... here is my proposal for the text:

The HTTP Basic Authentication module supplies an HTTP Basic authentication provider for web service requests. This authentication provider authenticates requests using the HTTP Basic Authentication user name and password, as an alternative to using Drupal's standard cookie-based authentication system, and is only useful if your site provides web services configured to use this type of authentication. For more information ...(standard help template link to d.o here).

I do not think we should say anything else here about how to configure user accounts and set permissions, because that would depend on the web service and not this module (which has no permissions of its own).

The only other thing that might be useful here would be to link to actual core or contrib modules that provide this type of web services that can use this module. I am assuming the XMLRPC module would be the one Core module that does this... but I'm not sure. If so, we should link to its help page.

Thoughts? Maybe klausi or juampy can weigh in (maintainers of this module)?

klausi’s picture

That proposal looks good to me. I would link to REST module, since it uses and recommends basic_auth in its documentation. I have not tried to use it with XMLRPC.

clemens.tolboom’s picture

I would link to REST module, since it uses and recommends basic_auth in its documentation. I have not tried to use it with XMLRPC.

Let's add these like

The HTTP Basic Authentication module supplies an HTTP Basic authentication provider for web service requests. This authentication provider authenticates requests using the HTTP Basic Authentication user name and password, as an alternative to using Drupal's standard cookie-based authentication system, and is only useful if your site provides web services

such as the core REST and XML-RPC modules

configured to use this type of authentication. For more information ...(standard help template link to d.o here).

jhodgdon’s picture

That wording doesn't really quite work, I think...

How about:

The HTTP Basic Authentication module supplies an HTTP Basic authentication provider for web service requests. This authentication provider authenticates requests using the HTTP Basic Authentication user name and password, as an alternative to using Drupal's standard cookie-based authentication system, and is only useful if your site provides web services configured to use this type of authentication (for instance, the (link)RESTful Web Services module(end of link)). For more information ...(standard help template link to d.o here).

(Note: I don't think we should link to the xmlrpc module unless we are certain it can use Basic Auth.)

Time for a patch?

clemens.tolboom’s picture

@jhodgdon nice! Lets roll a patch out of it.

clemens.tolboom’s picture

I tried to create the Basic Auth page but question is where?

I was tempted to place is under https://drupal.org/documentation/modules/rest but Basic Auth is about Authentication.

Should we start a child page for https://drupal.org/node/1241116 called Authentication. Then add page 'Basic Auth' underneath?

jhodgdon’s picture

I am not sure... Maybe what we need is a section under
https://drupal.org/node/1241116
called "Web services". The REST module page could go under that, as well as the new authentication section?

Actually, there is already "Connecting to other sites..."
https://drupal.org/node/627270

Probably we should move the REST page there, and start a new section there called "Authentication" and put the Basic Auth under that.

Thoughts?

clemens.tolboom’s picture

Connecting to other sites...

seems to be about fetch data from other sites.

It would be great to restructure that with a new parent page "Exchange information with other systems and tools" or something better and then add child "Deliver data to the world" or better phrased

  • Exchange information with others systems and tools
    • Connecting to other sites...
    • Deliver data to the world
      • Rest WS
      • Authentication
        • Basic Auth
jhodgdon’s picture

Feel free to reorganize. I've done a bit...

batigolix’s picture

This patch has the text proposed in #22

I split the following phrase in 2 parts to make it easier readable.

This authentication provider authenticates requests using the HTTP Basic Authentication user name and password, as an alternative to using Drupal's standard cookie-based authentication system, and is only useful if your site provides web services configured to use this type of authentication (for instance, the (link)RESTful Web Services module(end of link)).

I left the wikipedia link on HTTP Basic Authentication because it doesnt hurt to have it.

batigolix’s picture

Status: Needs work » Needs review
juampynr’s picture

I have added a module documentation page for Basic Auth at https://drupal.org/node/2171633.

I tried to link it at Core Modules (even though it does not have the proper alias yet) but when I hit Save I get a 500 (perhaps a bug in Drupal.org?).

clemens.tolboom’s picture

I've updated https://drupal.org/documentation/modules/rest with link to https://drupal.org/node/2171633

@juampy nice page ... even I understand it :p

That page https://drupal.org/node/1283408 has a warning:

Editors note: This page is generated from a script. For more information, see the bottom of the page.

Not sure whether that's the cause.

batigolix’s picture

added an alias for the page

the title could be a bit longer and the placement in Site building guide > Core modules seems strange

jhodgdon’s picture

Yeah, see comment #25 about the placement of this page, or at least my thoughts about the placement. Putting it into "core modules" is not really very useful -- the philosophy for other core modules has been to put them into sections related to who would use them and why/when.

Anyway, that aside, the patch in #25 looks good to me. Any final comments from the module maintainers? And can someone please install the patch and test it manually to make sure the links work and go to the right places?

juampynr’s picture

Status: Needs review » Reviewed & tested by the community

Patch applies and links in it work as expected.

juampynr’s picture

@jhodgdon, I linked Basic Auth here as part of the REST documentation https://drupal.org/node/2076725.

jhodgdon’s picture

Thanks for reviewing the patch! We're now in a "only major and criticals" commit window, but I'll get it committed in a week when that's over.

Meanwhile, on the page on d.o... can't we just move the page to that spot in the outline instead of leaving it where it is?

webchick’s picture

Status: Reviewed & tested by the community » Fixed

Yoink! :) Looking for a couple of easy commits to get the RTBC queue under a page.

Committed and pushed to 8.x. Thanks!

jhodgdon’s picture

Thanks!

So... The other task we've been discussing here is the placement of
https://drupal.org/documentation/modules/basic_auth

I moved it so that it is now a sub-page of
https://drupal.org/node/2076725 (Using Other Authentication) -- it had already been added as a link on that page and the other page linked there is a child page, so it seemed logical. There's some caching on drupal.org so it might not show up there immediately, but it should eventually.

The place where that page was in the Documentation outline wasn't useful at all.

clemens.tolboom’s picture

Thanks for https://drupal.org/documentation/modules/basic_auth ... I need some time to get back to this.

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.