Download the PHP package chris911/slim-api-auth without Composer

Slim Auth

Slim Auth is an authorization and authentication library for the Slim Framework. Authentication is accomplished by using the Zend Framework Authentication component, and authorization by using the Zend Framework Acl component.

DOCUMENTATION INCOMPLETE

This lib is usable, but is beta software, and this documentation is incomplete. If you're extremely familiar with Zend Auth and Zend ACL, you can probably work it out just fine. Otherwise, you might want to wait for the docs to be completed.

Caveat emptor and all that.

Installation

Install composer in your project:

Create a composer.json file in your project root:

(Please check Packagist for the most recent version of Slim Auth)

Install via composer:

Add this line to your application’s index.php file:

Preparing Your App For Slim Auth

Configuring Password Validator

Database

Your database should have a user table, and that table must have a role column. The contents of the role column should be a string and correspond to the roles in your ACL. The user table name and all other column names are up to you.

Here's an example schema for a user table. If you don't already have a user table, feel free to use this one:

ACL

An Access Control List, or ACL, defines the set of rules that determines which group of users have access to which routes within your Slim application. Below is an example ACL suitable for an extremely simple app. Please pay special attention to the comments.

Please refer to the Zend ACL documentation for complete details on using their ACL component.

The Guest Role

Please note the guest role. You must use the name guest as the role assigned to an unauthenticated user. The other role names are yours to choose.

Acl "Privileges"

IMPORTANT: The third argument to Acl::allow(), 'privileges', is either a string or an array, and should be an HTTP verb or HTTP verbs respectively. By adding the third argument, you are restricting route access by HTTP method. If you do not provide an HTTP verb or verbs, you are allowing access to the specified route via all HTTP methods. Be extremely vigilant here. You wouldn't want to accidentally allow a 'guest' role access to an admin DELETE route simply because it references a public resource.

Configuring Slim Auth: Defaults

Now that you have a user database table with a role column and an ACL, you're ready to configure Slim Auth and add it to your application.

First, add use statements for the PDO adapter and the Slim Auth Bootstrap.

Next, create your Slim application with cookies.encrypt and cookies.secret_key as a minimum configuration.

Default Slim Auth identity storage is session storage. You MUST set the following cookie encryption settings if you use the SessionCookie middleware, which this example does. Details on configuring different storage are available later in the documentation.

Authentication Adapter

From the Zend Authentication documentation:

Zend\Authentication adapters are used to authenticate against a particular type of authentication service, such as LDAP, RDBMS, or file-based storage.

Slim Auth provides an RDBMS authentication adapter for PDO. The constructor accepts four required arguments:

• A \PDO instance
• The name of the user table
• The name of the identity, or username, column
• The name of the credential, or password, column

Credential Validation Callback

There is an optional fifth parameter: $credentialValidationCallback. If you do not provide a callback (and it's recommended that you don't), Slim Auth uses PHP's new password hash functionality by default. If you're not able to use PHP 5.5's new password hashing functions and your version of PHP doesn't support the userland implementation password_compat, then you'll need to provide your own credential validation functionality via a callback.

Putting it all Together

Now it's time to instantiate your ACL and bootstrap Slim Auth.

Finally, and this is crucial, you must add Slim's SessionCookie Middleware, and you must add it after the Slim Auth Boostrap::bootstrap() method has been called.

NOTE: This is only a requirement if you're using the default Session Storage and you opt to use the SessionCookie middleware. It is possible to configure Slim Auth to use storage other than Slim's SessionCookie.

Login Route

You'll need a login route, of course, and it's important that you name your route login using Slim's Route Names feature.

This allows you to use whatever route pattern you like for your login route. Slim Auth will redirect users to the correct route using Slim's urlFor() Route Helper.

Here's a sample login route:

Logout Route

As authentication stores the authenticated user's identity, logging out consists of nothing more than clearing that identity. Clearing the identity is handled by Authenticator::logout.