README

A PHP implementation of the 5.0.0 version of the Oz web authorization protocol.

NOTICE: Although the original JavaScript version of Oz will not be maintained anymore, this library will continue to be maintained. The original JavaScript version of Oz was complete and only had periodic documentation and library dependency updates.

What is Oz?
- Oz and OAuth 2.0
Getting Started
- Prerequisites
- Installation
Usage Examples
- Server Usage Examples
- Client Usage Examples
Documentation
- API References
Security Considerations
Related Projects
Contributing/Development
Versioning
License

What is Oz?

According to the Oz README

Oz is a web authorization protocol based on industry best practices. Oz combines the Hawk authentication protocol with the Iron encryption protocol to provide a simple to use and secure solution for granting and authenticating third-party access to an API on behalf of a user or an application.

Oz and OAuth 2.0

Oz is an alternative to OAuth 1.0a and OAuth 2.0 three-legged authorization. One of the goals of Oz is to be simple to use for the most common use cases without needing to be a web security expert while being flexible enough for less common use cases that may need more advanced web security knowledge. Oz does this by providing default options that are secure for the most common use cases, in other words Oz aims to be secure by default.

All of the official three-legged OAuth 2.0 workflows have an equivalent Oz workflow. Below is table showing the Oz workflow equivalents for the OAuth 2.0 workflows.

OAuth 2.0 Workflow	Oz Workflow
Authorization Code	RSVP (The only offical workflow)
Implicit/PKCE	Implicit (Not an offical workflow)
Resource Owner Password Credentials	User Credentials (Not an offical workflow)
Client Credentials	Hawk

Getting Started

Prerequisites

Git 2.9+
PHP 7.2.0+
OpenSSL PHP Extension
JSON PHP Extension
cURL PHP Extension (Only if using the Oz client)
Composer
Node 6.9.0+ (Only for development)

Installation

Download and install using Composer:

composer require shawm11/oz-auth-php

Workflows

This package includes two workflows that are not part of the official Oz web authorization protocol. These two new workflows are the User Credentials Workflow and the Implicit Workflow. The standard Oz workflow that is specifed by the official protocal is referred to as the "RSVP workflow".

Usage Examples

Server Usage Examples

Client Usage Examples

Documentation

RSVP Workflow (Without Delegation) — General overview of the RSVP (standard) workflow when delegation is not being used
User Credentials Workflow — General overview of the User Credentials workflow
Implicit Workflow — General overview of the Implicit workflow

API References

Server API — API reference for the classes in the Shawm11\Oz\Server namespace
Client API — API reference for the classes in the Shawm11\Oz\Client namespace
Shared Arrays — Details about collections of data used in other parts of the API

Security Considerations

See the Security Considerations section of Oz's README.

Related Projects

Hawk PHP Implementation — Hawk is an HTTP authentication scheme that is an alternative to OAuth 1.0a and OAuth 2.0 two-legged authentication.
Iron PHP Implementation — iron (spelled with all lowercase), a cryptographic utility for sealing a JSON object into an encapulated token. iron can be considered as an alternative to JSON Web Tokens (JWT).

Contributing/Development

Please read CONTRIBUTING.md for details on coding style, Git commit message guidelines, and other development information.

Versioning

This project using SemVer for versioning. For the versions available, see the tags on this repository.

License

This project is open-sourced software licensed under the MIT license.

shawm11 / oz-auth

Maintainers

Details