fei/connect-package

Connect client package integration for Objective PHP applications


README

This package provide Connect Client integration for Objective PHP v2 applications.

With the Connect Package, your Objective PHP application integrate the SAML standard protocol and can act as a Service Provider.

Installation

Connect Package needs PHP 7.0 or up, with the extension openssl plugged to run correctly.

You will have to integrate it to your Objective PHP project with composer require fei/connect-package

Integration

In order to work properly, Connect-Package must be register in your Application.

<?php

namespace Fei\Service\Project;

use ObjectivePHP\Application\AbstractHttpApplication;
use Fei\Service\Connect\Package\ConnectPackage;

/**
 * Class Application
 *
 * @package Showcase
 */
class Application extends AbstractHttpApplication
{
    public function init()
    {        
        $this->registerPackage(new ConnectPackage());
        
        // Register other stuff
    }
}

By registering Connect-Package, your application will gain:

  • Connect-Client, Connect-Config and Connect-User services with their associated injectors
  • If your application is a HTTP Application (extending ObjectivePHP\Application\AbstractHttpApplication), Connect-Package middlewares

Connect Services

Connect-Package exposes 3 services (see configuration section for service name purpose):

  • connect.config: this is the configuration instance injected into Connect-Client constructor
  • connect.client: the Connect-Client instance used to get Connect-User instance
  • connect.user : the Connect-User instance representing the current identity of your application user

Injectors

Injectors is an great feature of Objective-PHP services factory. With injectors, your services will be injected in the right dependency by the services factory. Here below an example:

<?php

namespace Fei\Service\Project\Services;

use Fei\Service\Connect\Package\UserAwareInterface;
use Fei\Service\Connect\Package\UserAwareTrait;

/**
 * Class Application
 *
 * @package Showcase
 */
class MyService implements UserAwareInterface
{
    use UserAwareTrait;
    
    public function myBusinessMethod()
    {
        // Doing my business  
        
        $this->getUser(); // Returns Connect-User service instance
        
        // Doing other business stuff
    }
}

By implementing Fei\Service\Connect\Package\UserAwareInterface, services factory will inject into your service the current instance of Connect-User service thanks to injectors.

Connect-Package register 2 injectors:

  • Fei\Service\Connect\Package\Injector\UserAwareInjector: will inject Connect-User service into your services that implement Fei\Service\Connect\Package\UserAwareInterface interface.
  • Fei\Service\Connect\Package\Injector\ConnectAwareInjector: will inject Connect-Client service into your services that implement Fei\Service\Connect\Package\ConnectAwareInterface interface.

Mostly, you will prefer to inject Connect-User service. In this way, you will decrease the coupling of your service layer with Connect-Client.

Disable Connect behaviours and Mocked User

You can disable the Connect middlewares and so disable Connect behaviour. It's commonly used in development environment (Connect-IDP is not installed for example).

If you disable Connect middleware, Connect-Package will replace Connect-User instance by a mocked Connect-User instance you could configure.

In this way, your application will work as if it's wired to Connect-IDP.

Configuration

Connect-Package look like below:

{
    "connect": {
        "enable": true,
        "name": "SP name",
        "entity_id": "http://sp.com",
        "idp_entity_id": "http://idp.com",
        "client_service_id": "connect.client",
        "config_service_id": "connect.config",
        "user_service_id": "connect.user",
        "mock_user" : {
            "username": "Gauthier",
            "current_role": "SUPER_ADMIN"
        },
        "default_target_path": "/",
        "logout_target_path": "/",
        "profile_association_path": "/connect/profile",
        "profile_association_service_id": "connect.profile-association",
        "saml_metadata_basedir": "app/config/Saml/metadata",
        "sp_metadata_file": "sp.xml",
        "idp_metadata_file": "idp.xml",
        "idp_metadata_file_target": "/idp.xml",
        "private_key_file_path": "/some/path/key/key.pem",
        "admin_path_info": "/connect/admin",
        "allowed_roles": ["USER", "ADMIN"],
        "filters": ["service.filter.first", "service.filter.second"]
    }
}

Final word on filters

Yes, yes, after this point your will be ready to use Connect-Package and enjoy with Objective-PHP.

So filters...

Filters is a way to activate or not Connect middlewares. There are the same effect that enable option but with the execution context (like disable Connect for API call for example).

A filter is a class that implement ObjectivePHP\Filter\FilterInterface and when it's run by the package, it's decide if the Connect middlewares must be register or not.

Before use filters you must register into services factory the your filters descriptions.