Download the PHP package slashid/symfony without Composer

Symfony SlashID Integration Bundle

Installation

1. Install the Symfony 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 Symfony command to publish the bundle assets:

4. Edit config/routes.yaml and add this to the end of it:

5. Edit config/packages/security.yaml to add the following references to SlashID:

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

Stateless Login

If your Symfony installation acts as an API backend (for a React application, for instance), you will probably want to configure stateless login. To do that, just add stateless: true to the firewall configuration, for instance:

In the example above, any requests to /api/**** will be logged in by sending the SlashID token in a Authorization: Bearer <<TOKEN>> header. All other routes will be logged in with a cookie.

:warning: Attention! If you do not add stateless: true, requests with a Authorization: Bearer <<TOKEN>> header WILL create a cookie login.

Configuration

If you want to customize the SlashID integration by creating a config/packages/slashid.yaml file inside your Symfony installation, for instance:

These are the configuration options:

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).

For instance, to use the dark theme, do this:

If you want to enable password login and disable email link login, do this:

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

Groups

Group-based access in routes

The groups in SlashID are exposed as Symfony roles. So, for instance, if you have a group named "Editor", the user will have the role ROLE_EDITOR.

You can protected routes by SlashID groups editing security.yaml like this:

:warning: Attention! All group names will be capitalized, so groups named "Editor", "editor" and "EDITOR" will all be transcribed as ROLE_EDITOR.

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\Symfony\SlashIdUser class, e.g.:

Group-checking in Twig

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

Webhooks

See SlashID documentation on Webhooks.

CLI webhook commands

To use webhooks, you need first to register your URL with SlashID. Webhooks are managed via API, but this package provides three CLI 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_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 Symfony 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 CLI 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 Symfony event.

To listen to webhook events in your Symfony application, create a class in the src/EventListener folder of your application. In the example below, we are naming it WebhookEventListener, but you can name it as you like.

The listener will receive the event of class \SlashId\Symfony\Event\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.

Overriding routes

By default, the Symfony bundle exposes three routes:

• /login - the login form
• /login/callback - a route called in the background to complete the login process
• /slashid/webhook - the webhook listener

In some cases, you might not want to expose either the webhook or the login form, or even to change the URLs for those routes. To accomplish that, first remove the _slashid_symfony_bundle: line from config/routes.yaml, then add the routes manually:

:warning: Note: you must keep the names of the routes: slashid.login, slashid.login.callback and slashid.webhook.

User Migration

If you are installing SlashID in an existing Symfony 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 command php bin/console slashid:import:create-script. It will ask you the User class in your installation, usually \App\Models\User.

A script will be created in migrations/slashid/user-migration.php (you can customize the folder destination by changing the migration_script_folder option). It will look like this:

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

After adapting the script to your needs, run php bin/console 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

Twig template and how to insert the form in a layout

The login form is rendered in the Twig template templates/login/login.html.twig, that extends base.html.twig, so that the login form is wrapped by the site's default layout.

If you want to change the template, copy the file vendor/slashid/symfony/templates/login/login.html.twig to templates/bundles/slashid/login/login.html.twig and change it as you please.

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/symfony/public/slashid.symfony-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 slashid.login_form.override_bundled_javascript to true in config/packages/slashid.yaml 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 slashid.login_form.override_javascript_glue to true to prevent the glue code from being loaded.

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