Download the PHP package slashid/laravel without Composer

Laravel SlashID integration

Installation

1. Install the Laravel SlashID packaged with composer:

2. Edit your environment file, .env, adding the following variables to the end of the file:

   • SLASHID_ENVIRONMENT, either sandbox or production
   • SLASHID_ORGANIZATION_ID, your organization's ID. You'll find it in your SlashID console (https://console.slashid.dev/ for production, https://console.sandbox.slashid.dev/ for sandbox), in the "Settings" tab, on the top of the page.
   • SLASHID_API_KEY, your organization's API Key. You'll also find it in your SlashID console, in the "Settings" tab, at the very bottom of the page.
3. Run the following artisan command to publish the resources:

You're ready! Now access /login in your website and enjoy your new login with SlashID :)

Configuration

There are several configurations in this package, that you can edit on config/slashid.php. The configurations that are more likely for you to override are web_redirect_after_login and web_redirect_after_logout.

Login form configuration

The login form is a bundled version of SlashID's React SDK. As such all options in the components are usable here, just note that you have to convert camelCase to kebab-case (see examples below).

In config/slashid.php, the option login_form_configuration, has the following default value:

Authentication methods

For instance, if you want to add password login, first add the password option in the SlashID Console > Settings, then change the configuration to as such:

For more information, check the documentation at: https://developer.slashid.dev/docs/access/sdk/interfaces/Types.Factor

Login form theme

You can choose between a light and a dark theme by overriding the theme-props option in the login_form_configuration. For instance, this will make the theme dark:

You can also override any of the CSS variables provided by the React SDK. For instance, to make the login button red, you can do the following:

Groups

Group-based access check-in routes

You can use the slashid_group middleware to restrict certain routes to people of a given group. For instance, if you want to create a route /content-management that only people within the "Editor" group can access, and a route /admin that only people within the "Admin" group can access, you can do it like this:

If the user is not logged in, they will be redirected to the login page. If the user is logged in, they will receive an Access Denied exception.

:warning: Note: group names are case-sensitive, please make sure you are using the correct group names.

You can also combine different groups in your route checking! For instance, if you want the /dashboard page to be accessible for anyone in ANY of the groups "Admin", "Editor" or "Reviewer", you can use | to combine different group names in an OR conjunction:

You can also use & to combine groups in an AND conjunction:

:warning: Note: you cannot combine | and & in a same route, e.g. ->middleware('slashid_group:Admin&Editor|Reviewer') is an invalid declaration and will raise an exception.

Group-checking in custom code

If you want to check the groups of a user in your custom code, you can use any of the group-related methods of the \SlashId\Laravel\SlashIdUser class, e.g.:

Group-checking in Blade

You can also use the hasGroup / hasAnyGroup / hasAllGroups methods to build templates in Blade that display different things depending on the groups the user belongs to.

Webhooks

See SlashID documentation on Webhooks.

Artisan webhook commands

To use webhooks, you need first to register your URL with SlashID. Webhooks are managed via API, but this package provides three Artisan commands to help you manage them.

How to register webhooks

To register a new webhook for the current website use the following command. You are required to define a unique name for it, in this example, we're using my_laravel_webhook.

By default, the webhook is registered with the triggers: PersonDeleted_v1, PersonLoggedOut_v1, and PasswordChanged_v1. You can specify which triggers to register, listing the triggers separated by space:

You can run slashid:webhook:register as many times as you want, if there is already a webhook registered to that URL, it will be updated and the list of triggers will be overridden.

How to test webhooks locally

You can test webhooks in your local development environment with a tool such as ngrok, then use the option --base-url to register a webhook with the proxy.

For instance, if you are running Laravel on port 8080, you can proxy your local environment with ngrok with:

The ngrok command-line will then display data about your proxy, such as:

Then, you can register a web service to the proxy URL, with the following command:

How to register webhooks for other applications

You can use the artisan command to register webhooks with any arbitrary URL:

How to see existing webhooks

You can see all webhooks registered to your SlashID organization with the command:

How to delete a webhook

You can delete a webhook by its ID.

To learn a webhook ID, use the slashid:webhook:list command.

Listening to events

Any received webhook will be made available to the developer as a Laravel event.

To listen to webhook events in your Laravel application, create a class in the app/Listeners folder of your application. In the example below, we are naming it WebhookListener, but you can name it as you like.

After creating the listener class, you need to let Laravel know it exists by editing the file app/Providers/EventServiceProvider.php. On the $listen property, add your class, such as:

The listener will receive the event of class \SlashId\Laravel\Events\WebhookEvent. It has three methods you can use to extract information about the webhook call:

• $event->getEventName() will return the trigger name, such as AuthenticationFailed_v1, that is, ->trigger_content->event_metadata->event_name in the JSON sent to the webhook.
• $event->getEventId() will return the event ID, such as 68a850ca-b2ee-46ce-8592-410813037739, that is, ->trigger_content->event_metadata->event_id in the JSON sent to the webhook.
• $event->getTriggerContent() will return the full content of the webhook call, that is, ->trigger_content in the JSON sent to the webhook.

User Migration

If you are installing SlashID in an existing Laravel website, you will probably already have a user base that you'll want to migrate to SlashID's database. This is made easy with two migration commands.

First, you have to run the artisan command php artisan slashid:import:create-script. It will ask you the User class in your installation, usually \App\Models\User.

A script will be created in database/slashid/user-migration.php. It will look like this:

You must adapt the user-migration.php to model the data to be migrated as you want. The script must return an array of \SlashId\Laravel\SlashIdUser with all the users you want to bulk import into SlashID.

After adapting the script to your needs, run php artisan slashid:import:run, e.g.:

Any errors that occured in a migration will be output as a CSV. Check the CSV to fix the errors and run again.

Overriding the login form

Blade template and how to insert the form in a layout

The login form is rendered in two Blade templates: slashid/login.blade.php and slashid/login-form.blade.php. The actual code lies in the template login-form, login being just a wrapper to add a <html> around the form.

Therefore, if you want to wrap the login form in /login inside the layout of the page, you can override the login template. So:

First, copy vendor/slashid/laravel/resources/views/login.blade.php to resources/views/vendor/slashid/login.blade.php, then edit the file according to your needs. For instance, if you have a <x-app-layout> component, your template can be:

In most cases, you will not need to override login-form.blade.php.

Using custom JavaScript

The Laravel package comes with a bundle of the SlashID React SDK and a small JavaScript glue piece of code in vendor/slashid/laravel/public/slashid.laravel-web-login.js.

You may want to override the Bundled React SDK to compile your implementation of the React login form. If that's the case, change the option login_form_override_bundled_javascript to true in config/slashid.php to prevent the Bundled React SDK from being loaded.

Alternatively, you may want to override the glue code, to include custom actions after the login. If that's the case, change the option login_form_override_javascript_glue to true in config/slashid.php to prevent the glue code from being loaded.

In both cases, you are responsible for loading your custom code yourself.