Basic Authentication

Overview

cAPI's REST API is protected by the same restrictions which are provided via Joomla's standard web interface. This means that if you do not log in, you are accessing cAPI anonymously. Furthermore, if you log in and do not have permission to access something in Joomla, you will not be able to access it using the cAPI REST API either.

Basic Authentication will be available in cAPI release v1.3.4

In most cases, the first step in using the cAPI REST API is to authenticate a user account with your Joomla site. Any authentication that works against Joomla will work against the REST API. On this page we will show you a simple example of basic authentication.

Simple example

Most client software provides a simple mechanism for supplying a user name and password and will build the required authentication headers automatically. For example you can specify the -u argument with curl as follows:

curl -D- -u Bob:Loblaw -X GET -H "Content-Type: application/json" https://yoursite.com/api/v1/user

Supplying Basic Auth headers

If you need to you may construct and send basic auth headers yourself. To do this you need to perform the following steps:

• Build a string of the form username:password
• Base64 encode the string
• Supply an "Authorization" header with content "Basic " followed by the encoded string. For example, the string "bob:loblaw" encodes to "Ym9iOmxvYmxhdw==" in base64, so you would make the request as follows. curl -D- -X GET -H "Authorization: Basic Ym9iOmxvYmxhdw==" -H "Content-Type: application/json" "https://yoursite.com/api/v1/user"

Forcing Basic HTTP Authentication Prompt

An end user may trigger a Basic Auth challenge window by appending the following URL parameter to any REST method request:

basic_auth=true

This will prompt a modal pop-in (depending on web browser) requesting the authorized username and password. Once submitted, the credentials will be saved for the duration of the session.

Note: Always use HTTPS encrypted connections when connecting to your REST API.

Troubleshooting

PHP Does Not See Authorization Header

( original source )

While implementing a token endpoint you may notice that you are unable to access the value of an HTTP Authorization header - $_SERVER did not include it.

$ curl -H 'Authorization: Basic U1RBUkJVVFRPTlNOT1RUVUJSQVRT' 127.0.0.1/securepage.php |grep -i auth
$

It turns out that you manually have to pass them, e.g. by adding the following line to your .htaccess file:

SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1

$ curl -H 'Authorization: Bearer wolf' 127.0.0.1/dumpserver.php |grep -i auth
  'HTTP_AUTHORIZATION' => string 'Bearer wolf'(length=11)
$

Alternatively you may use mod_rewrite:

RewriteCond %{HTTP:Authorization} ^(.+)$
RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]

FastCGI

When Apache speaks via FastCGI with PHP, then the authorization header is available as REDIRECT_HTTPAUTHORIZATION. There is no way to get rid of the REDIRECT in front; your code has to check both variants.

References

HTTP Authentication

PSR-7 Basic Auth Middleware

HTTP authentication with PHP

How To Check If A String is Valid Base64 in PHP

Authentication and Authorization

JIRA REST API Example - Basic Authentication

@since version 1.3.4