README

Auth0 enables you to rapidly integrate authentication and authorization for your applications, so you can focus on your core business. (Learn more)

Our PHP SDK provides a straight-forward and rigorously tested interface for accessing Auth0's Authentication and Management API endpoints through modern releases of PHP.

This is one of many libraries we offer supporting numerous platforms.

Requirements
Installation
Getting Started
- Authentication API
- Management API
Examples
- Organizations
Documentation
Contributing
Support + Feedback
Vulnerability Reporting
What is Auth0?
License

Requirements

PHP 7.3+ / 8.0+
Composer

Installation

The recommended way to install the SDK is through Composer:

$ composer require auth0/auth0-php

Guidance on setting up Composer and alternative installation methods can be found in our documentation.

Getting Started

To get started, you'll need to create a free Auth0 account and register an Application.

Authentication API

Begin by instantiating the SDK and passing the relevant details from your Application's settings page:

use Auth0\SDK\Auth0;

$auth0 = new Auth0([
  // The values below are found on the Application settings tab.
  'domain'        => '{YOUR_TENANT}.auth0.com',
  'client_id'     => '{YOUR_APPLICATION_CLIENT_ID}',
  'client_secret' => '{YOUR_APPLICATION_CLIENT_SECRET}',

  // This is your application URL that will be used to process the login.
  // Save this URL in the "Allowed Callback URLs" field on the Application settings tab
  'redirect_uri' => 'https://{YOUR_APPLICATION_CALLBACK_URL}',
]);

Note: In a production application you should never hardcode these values. Consider using environment variables to store and pass these values to your application, as suggested in our documentation.

Using the SDK, making requests to Auth0's endpoints couldn't be simpler. For example, signing users in using Auth0's Universal Login and retrieving user details can be done in a few lines of code:

// Do we have an authenticated session available?
if ($user = $auth0->getUser()) {
  // Output the authenticated user
  print_r($user);
  exit;
}

// No session was available, so redirect to Universal Login page
$auth0->login();

Further examples of how you can use the Authentication API Client can be found on our documentation site.

Management API

This SDK also offers an interface for Auth0's Management API which, in order to access, requires an Access Token that is issued specifically for your tenant's Management API by specifying the corresponding Audience.

The process for retrieving such an Access Token is described in our documentation.

use Auth0\SDK\API\Management;

$mgmt_api = new Management('{YOUR_ACCESS_TOKEN}', 'https://{YOUR_TENANT}.auth0.com');

The SDK provides convenient interfaces to the Management API's endpoints. For example, to search for users:

$results = $mgmt_api->users()->getAll([
  'q' => 'josh'
]);

if (! empty($results)) {
  echo '<h2>User Search</h2>';

  foreach ($results as $datum) {
    printf(
      '<p><strong>%s</strong> &lt;%s&gt; - %s</p>',
      !empty($datum['nickname']) ? $datum['nickname'] : 'No nickname',
      !empty($datum['email']) ? $datum['email'] : 'No email',
      $datum['user_id']
    );
  }
}

At the moment the best way to see what endpoints are covered is to read through the \Auth0\SDK\API\Management class, available here.

Examples

Organizations

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

Configure the Authentication API client with your Organization ID:

use Auth0\SDK\Auth0;

$auth0 = new Auth0([
  // Found in your Auth0 dashboard, under Organization settings:
  'organization' => '{YOUR_ORGANIZATION_ID}',

  // Found in your Auth0 dashboard, under Application settings:
  'domain'       => '{YOUR_TENANT}.auth0.com',
  'client_id'    => '{YOUR_APPLICATION_CLIENT_ID}',
  'redirect_uri' => 'https://{YOUR_APPLICATION_CALLBACK_URL}',
]);

Redirect to the Universal Login page using the configured organization:

$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:

// Expects the Auth0 SDK to be configured first, as demonstrated above.
$auth0->handleInvitation();

If you prefer to have more control over this process, a separate helper function is provided for extracting the query parameters, getInvitationParameters(), which you can use to initiate the Universal Login redirect yourself:

// Expects the Auth0 SDK to be configured first, as demonstrated above.

// Returns an object containing the invitation query parameters, or null if they aren't present
if ($invite = $auth0->getInvitationParameters()) {
  // Does the invite organization match your intended organization?
  if ($invite->organization !== '{YOUR_ORGANIZATION_ID}') {
    throw new Exception("This invitation isn't intended for this service. Please have your administrator check the service configuration and request a new invitation.");
  }

  // Redirect to Universal Login using the emailed invitation
  $auth0->login(null, null, [
    'invitation'   => $invite->invitation,
    'organization' => $invite->organization
  ]);
}

After successful authentication via the Universal Login Page, the user will arrive back at your application using your configured redirect_uri, their token will be automatically validated, and the user will have an authenticated session. Use getUser() to retrieve details about the authenticated user.

Validation guidance

In the examples above, our application is operating with a single, configured Organization. By initializing the SDK with the organization option, we are telling the internal ID Token verifier (IdTokenVerifier) to validate an org_id claim's presence, and that it matches what we provided.

Your application might not know the Organization ID ahead of time, or potentially need to support multiple organizations.

Your application should validate an org_id claim itself to ensure the value received is expected and known by your application.

This could be achieved by reading the value of "org_id" returned by the getUser() method. An example might look like this:

use Auth0\SDK\Auth0;

// Example: a list of organizations our app supports
$allowedOrganizations = ['org_123', 'org_456'];
$defaultOrganization = $allowedOrganizations[0];

// For this scenario, do not pass any `organization` during SDK initialization. You'll handle the organization validation yourself.
$auth0 = new Auth0([
  // Found in your Auth0 dashboard, under Application settings:
  'domain'       => '{YOUR_TENANT}.auth0.com',
  'client_id'    => '{YOUR_APPLICATION_CLIENT_ID}',
  'redirect_uri' => 'https://{YOUR_APPLICATION_CALLBACK_URL}',
]);

// Are they authenticated?
if ($user = $auth0->getUser()) {
  // Do they have an organization claim?
  if (! isset($user['org_id'])) {
    // They do not; stop processing their request.
    throw new Exception('Please sign in using an organization.');
  }

  // Does the claim match an expected organization?
  if (! in_array($user['org_id'], $allowedOrganizations)) {
    // It does not; stop processing their request.
    throw new Exception('Access denied.');
  }
}

// Do we have an incoming invitation?
if ($invite = $auth0->getInvitationParameters()) {
  // Is the invite for an expected organization?
  if (! in_array($invite->organization, $allowedOrganizations)) {
    throw new Exception("This invitation isn't intended for this service. Please have your administrator check the service configuration and request a new invitation.");
  }

  // Redirect to Universal Login using the invitation
  $auth0->login(null, null, [
    'invitation'   => $invite->invitation,
    'organization' => $invite->organization
  ]);
}

// Redirect to Universal Login using our default organization
$auth0->login(null, null, [
  'organization' => $defaultOrganization
]);

If the claim can't be validated, your application should reject the token as invalid. See https://auth0.com/docs/organizations/using-tokens for more information.

Documentation

Documentation
Quickstarts
- Basic authentication example (GitHub repo)
- Authenticated backend API example (GitHub repo)

Contributing

We appreciate your feedback and contributions to the project! Before you get started, please review the following:

Support + Feedback

The Auth0 Community is a valuable resource for asking questions and finding answers, staffed by the Auth0 team and a community of enthusiastic developers
For code-level support (such as feature requests and bug reports) we encourage you to open issues here on our repo
For customers on paid plans, our support center is available for opening tickets with our knowledgeable support specialists

Further details about our support solutions are available on our website.

Vulnerability Reporting

Please do not report security vulnerabilities on the public GitHub issue tracker. The Responsible Disclosure Program details the procedure for disclosing security issues.

What is Auth0?

Auth0 helps you to:

Add authentication with multiple authentication sources, either social like Google, Facebook, Microsoft, LinkedIn, GitHub, Twitter, Box, Salesforce (amongst others), or enterprise identity systems like Windows Azure AD, Google Apps, Active Directory, ADFS or any SAML Identity Provider.
Add authentication through more traditional username/password databases.
Add support for passwordless and multi-factor authentication.
Add support for linking different user accounts with the same user.
Analytics of how, when and where users are logging in.
Pull data from other sources and add it to the user profile, through JavaScript rules.

Why Auth0?

License

The Auth0 PHP SDK is open source software licensed under the MIT license. See the LICENSE file for more info.

icanid / icanid-sdk-php

Maintainers

Details