oauth-login-page

A rather simple login-page written in PHP, intended to serve as an authentication portal. The login-page communicates to a OAuth 2.0 server for authentication of users, using custom grant type. The login-page aims to be compliant to section 4.2 of RFC6749 (Implicit Grant type).

Suitable when you want to run your own OAuth 2.0 server, and need a centralized login-page.

Standalone PHP, no frameworks required, customizable.

Features

• Provides OAuth 2.0 authentication interface to calling sites. Redirects browsers back to calling site after authentication
• Communicates with OAuth 2.0 server to authenticate, using customized grant (Extension Grants type)
• Grabs tokens from OAuth 2.0 server and gives to the authenticated user's browser
• Only recognized sites will be able to have users authenticate and redirected back
• Uses sophisticated nonce strings to counteract attempts to steal authentication tokens
• Possible to run the site on multiple hosts simultainously, as shared data is stored in database
• Standalone, no frameworks required
• Filtering functionality, making core code extendable
• Comprensive test-suite

Security features

• Implements OAuth 2.0 interface for sites wanting to authenticate against it
• Verification of redirection URIs done by OAuth 2.0 server
• Strict input checking
• Nonce tokens are used to counteract attempts to let users use other forms to submit against oauth-login-page
• Nonce tokens are created, using a static secret key (configurable), a session secret (attached to user's session, autogenerated), a salt and an expiry timestamp. These are then hashed. The nonce string will contain the salt, timestamp and the resulting hash
• Sessions are initialized with many of PHP's default settings altered. These settings will decrease the odds of sessions being hijacked
• Sessions are created with user-agent string saved as a part of the server-side session-data. If later requests, using same session, are not made with the same user-agent, the session is destroyed and the request halted. This is one way to minimize likelyhood of session theft

TODO

• Implement simple rate-limiting functionality

Installing

• To install, simply copy all the files, and place in a web-root suitable.

Requirements

• PHP 5.4 or later
• PHP with OpenSSL and cURL support
• Webserver running on Linux or other UNIX-like system
• MySQL database with InnoDB support (recommended)

Configure PHP

• It is recommended to set up XCache or APC to increase speed
• It is recommended to use database connection pooling, as the code does a lot of fast-run queries, and each request takes a short while
• To run the unit-tests, install the PHP pecl-runkit add-on
• Optionally set the following variables in /etc/php.ini for increased security:

max_execution_time = 45
max_input_time = 20
max_input_vars = 75
memory_limit = 50M
post_max_size = 250K

Configuration file

• Configuration is stored in 'config.php', which you have to create. Create it by simply copying config_example.php to config.php, and then make changes to config.php. Follow the instructions found in the example file.

Creating DB-table

• You will have to create a database for the login-page
• Then create a table in that database using the following SQL:

CREATE TABLE `lp_sessions` (
  `session_id` varchar(256) CHARACTER SET latin1 NOT NULL DEFAULT '',
  `session_expires` int(10) unsigned NOT NULL DEFAULT '0',
  `session_data` text,
  PRIMARY KEY (`session_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8

Running tests

Note that the test-suite uses a special database. You should configure what that database is, in the config-file. You will not need to create any tables in that database.

To run the tests, do something like the following:

$ cd /var/www/oauth-login-page
$ phpunit tests/
 ...

Templates

The default templates can be found in tpl/ -- all of these have the '-default.tpl.php' suffix. These should not be altered, but rather should new files be created, which do not have the '-default' string in their name, and these will be used instead of the default, automatically. Hence, 'header-default.tpl.php' would be 'header.tpl.php'. In these new files, various alterations can be performed safely.

Customizations

Customizations can be added. These work via filters that can be added dynamically by putting PHP files (file-names ending with '.php') in 'customizations/'. So far, only customizations for cURL calls can be performed, but support can be added for various other functionality. See filters.php and misc.php for more information.

OAuth 2.0 servers

You should only use servers that are compliant with RFC6749.

You will have to implement a Extension Grant on the OAuth 2.0 server for this package to work. In simple terms this means that the server has to be capable of accepting the following in a HTTP POST request:

• username
• password
• client_id
• client_secret
• scope
• redirect_uri

Note that these are the names of the fields sent. client_secret should always be empty.

It is extremely important that the OAuth server actually checks that the redirect URIs are associated with the client_id sent. Unrecognized sites should never be able to have authorized users redirected to them.

Note that the test suite will not test the responses of your OAuth 2.0 server - you will have to do that. You can add tests, if you want.

You also have to define available scopes.

Configuring calling site (clients)

Configuring calling sites involves creating records with OAuth 2.0 server. Then to actually perform authentication, one must have users submitting forms such as this one:

        <form action="https://Z.Z.Z.Z/authorize" method="GET"> <!-- Z.Z.Z.Z is path to where this package is deployed -->
        <input type="hidden" name="response_type" value="token"> <!-- type of response; always "token" -->
        <input type="hidden" name="redirect_uri" value="<?php echo urlencode("https://Y.Y.Y.Y/redirect.php"); ?>"> <!-- redirect URI - i.e. URI to the site requesting access -->
        <input type="hidden" name="scope" value="mysite-api"> <!-- requested scope -->
        <input type="hidden" name="client_id" value="testclient"> <!-- client_id -->
        <input type="hidden" name="state" value="39260fcb02ff666f1174ec364950e3c769ea4cc9339526bfd255791f533b1b92"> <!-- unique hash -->

        <input type="submit" value="Log in">
        </form>

Calling sites must take care to use unique hash values for the state parameter, and bind them to browser sessions. See RFC6749, section 10.12 and section 4.2. The state parameter must never be static accross requests.