Download the PHP package users-au/users-au-laravel-client without Composer

Users.au OAuth Laravel Client

Table of Contents

• Introduction
• Features
• Requirements
• Installation
• Configuration
• Usage
• API Reference
• Migration Guide
• Troubleshooting
• Contributing
• Changelog
• License

Introduction

This package provides a seamless Laravel integration for Users.au OAuth authentication. It simplifies the process of implementing Users.au single sign-on (SSO) in your Laravel applications, handling authentication, user management, and session control.

Features

• 🔐 OAuth 2.0 Authentication - Secure authentication via Users.au
• 👤 Automatic User Management - Creates and updates user records automatically
• 🔄 Token Management - Handles access and refresh tokens
• 🎨 Profile Photo Support - Optional profile photo synchronization
• 🛡️ Middleware Protection - Configurable middleware for route protection
• 📱 Account Management - Direct integration with Users.au account pages
• 🚪 Single Sign-Out - Coordinated logout across systems

Requirements

• PHP >= 8.0
• Composer >= 2.0
• Laravel 5.0+ (supports versions 5.x through 10.x)
• Users.au OAuth application credentials

Installation

Install the package via Composer:

Publish the package assets:

Run the migrations to add required columns to your users table:

Configuration

1. Update Your User Model

Add the following fields to your User model's fillable and hidden arrays:

2. Service Configuration

Add Users.au configuration to your config/services.php:

3. Environment Variables

Set the following environment variables in your .env file:

4. Package Configuration

The package publishes a configuration file at config/usersau.php. You can customize:

5. Manual Service Provider Registration (Optional)

If auto-discovery is disabled, manually register the service provider in config/app.php:

Usage

Authentication Routes

The package automatically registers the following routes:

Basic Usage Examples

Login Link

Logout Link

Registration Link

Account Management Link

Middleware Protection

Protect your routes using Laravel's built-in auth middleware:

Custom User Handling

You can listen for authentication events to perform custom actions:

API Reference

AuthController Methods

The AuthController provides the following public methods:

redirect()

Initiates the OAuth flow by redirecting to Users.au.

callback()

Handles the OAuth callback, creates/updates user records, and logs in the user.

Process:

1. Retrieves user data from Users.au
2. Creates or updates local user record
3. Syncs profile photo (if configured)
4. Logs in the user
5. Redirects to configured URL

logout()

Logs out the user locally and redirects to Users.au logout.

account()

Redirects authenticated users to their Users.au account page.

register()

Redirects to Users.au registration page.

Configuration Options

Migration Guide

From Version 1.x to 2.x

If you're upgrading from an older version:

1. Update your composer requirements
2. Run php artisan vendor:publish --provider="Usersau\UsersauLaravelClient\UsersauLaravelClientServiceProvider" --force
3. Run php artisan migrate
4. Update your environment variables if needed

Troubleshooting

Common Issues

"Invalid State Exception"

This usually occurs when the OAuth state parameter doesn't match. Common causes:

• Session configuration issues
• Multiple redirect attempts
• Browser security settings

Solution: Ensure your session driver is properly configured and cookies are enabled.

"Client Exception during OAuth"

This indicates communication issues with Users.au servers.

Solutions:

• Verify your USERSAU_CLIENT_ID and USERSAU_CLIENT_SECRET
• Check your USERSAU_REDIRECT_URI matches exactly what's configured in Users.au
• Ensure USERSAU_HOST is correct

"User Model Not Found"

The configured user model doesn't exist.

Solution: Verify the user_model in config/usersau.php points to your correct User model.

Migration Errors

Issues running the package migrations.

Solutions:

• Ensure your users table exists before running migrations
• Check for conflicting column names
• Verify database connection

Debug Mode

Enable debug mode in your .env for detailed error messages:

Support

For additional support:

• Check the GitHub Issues
• Review the Users.au Documentation
• Contact support at [email protected]

Contributing

We welcome contributions! Please see CONTRIBUTING.md for details.

Development Setup

1. Clone the repository
2. Install dependencies: composer install
3. Run tests: composer test
4. Follow PSR-12 coding standards

Testing

Run the test suite:

For coverage reports:

Changelog

Please see CHANGELOG.md for more information on what has changed recently.

License

The MIT License (MIT). Please see LICENSE.md for more information.