diff --git a/README.md b/README.md index 6585669e..f39872ea 100644 --- a/README.md +++ b/README.md @@ -80,6 +80,86 @@ auth('auth0')->check(); Route::group(['middleware' => 'auth:auth0'], function () {}); ``` +## Examples + +### Organizations (Closed Beta) + +Organizations is a set of features that provide better support for developers who build and maintain SaaS and Business-to-Business (B2B) applications. + +Using Organizations, you can: + +- Represent teams, business customers, partner companies, or any logical grouping of users that should have different ways of accessing your applications, as organizations. +- Manage their membership in a variety of ways, including user invitation. +- Configure branded, federated login flows for each organization. +- Implement role-based access control, such that users can have different roles when authenticating in the context of different organizations. +- Build administration capabilities into your products, using Organizations APIs, so that those businesses can manage their own organizations. + +Note that Organizations is currently only available to customers on our Enterprise and Startup subscription plans. + +#### Logging in with an Organization + +Open your Auth0 Laravel plugin configuration file (usually `config/laravel-auth0.php`) uncomment the `organization` optiion and specify the Id for your Organization (found in your Organization settings on the Auth0 Dashboard.) + +```php +// config/laravel-auth0.php +// ... + +/* +|-------------------------------------------------------------------------- +| Auth0 Organizations +|-------------------------------------------------------------------------- +| organization (string) Optional. Id of an Organization, if being used. Used when generating log in urls and validating token claims. +*/ + +'organization' => 'org_E6WbrPMQU2UJn6Rz', +``` + +From there, the Organization will automatically be used throughout your Laravel application's authentication login, including redirecting to the Universal Login page. + +```php +// Expects the Laravel plugin to be configured first, as demonstrated above. + +App::make('auth0')->login(); +``` + +#### Accepting user invitations + +Auth0 Organizations allow users to be invited using emailed links, which will direct a user back to your application. The URL the user will arrive at is based on your configured `Application Login URI`, which you can change from your Application's settings inside the Auth0 dashboard. + +When the user arrives at your application using an invite link, you can expect three query parameters to be provided: `invitation`, `organization`, and `organization_name`. These will always be delivered using a GET request. + +A helper function is provided to handle extracting these query parameters and automatically redirecting to the Universal Login page. Invoke this from your application's logic, such as a controller for an authentication route, to handle this process automatically. + +```php +// routes/example.php + +Route::get('/invite', [ExampleIndexController::class, 'invite'])->name('invite'); +``` + +```php +// Http/Controllers/Example/ExampleIndexController.php + +handleInvitation(); + } + +``` + ## Installation Install this plugin into a new or existing project using [Composer](https://getcomposer.org/doc/00-intro.md): diff --git a/composer.json b/composer.json index 5e2d1109..328629f5 100644 --- a/composer.json +++ b/composer.json @@ -6,7 +6,7 @@ "php": "^7.3 | ^8.0", "ext-json": "*", "ext-openssl": "*", - "auth0/auth0-php": "^7.6", + "auth0/auth0-php": "^7.7", "illuminate/support": " ^6.0 | ^7.0 | ^8.0", "illuminate/contracts": "^6.0 | ^7.0 | ^8.0" }, diff --git a/src/Auth0/Login/Auth0Service.php b/src/Auth0/Login/Auth0Service.php index 40b17c60..f0f50a69 100644 --- a/src/Auth0/Login/Auth0Service.php +++ b/src/Auth0/Login/Auth0Service.php @@ -106,6 +106,22 @@ public function login($connection = null, $state = null, $additional_params = [' return new RedirectResponse($auth_url); } + /** + * If invitation parameters are present in the request, handle extraction and automatically redirect to Universal Login. + */ + public function handleInvitation() + { + $this->getSDK()->handleInvitation(); + } + + /** + * Extract invitation details from any incoming GET request. + */ + public function getInvitationParameters() + { + return $this->getSDK()->getInvitationParameters(); + } + /** * If the user is logged in, returns the user information. * diff --git a/src/config/config.php b/src/config/config.php index 567baca8..b3facc05 100644 --- a/src/config/config.php +++ b/src/config/config.php @@ -62,6 +62,15 @@ */ // 'api_identifier' => '', + + /* + |-------------------------------------------------------------------------- + | Auth0 Organizations + |-------------------------------------------------------------------------- + | organization (string) Optional. Id of an Organization, if being used. Used when generating log in urls and validating token claims. + */ + // 'organization' => '', + /* |-------------------------------------------------------------------------- | The secret format