asminog/yii2-saml

Connect Yii 2 application to a Saml Identity Provider for Single Sign On

2.1.1 2021-07-07 10:01 UTC

Requires

• onelogin/php-saml: ^3.0.0
• yiisoft/yii2: ^2.0.15

MIT

• Arba Sasmoyo
• Muhammad Safri Juliardi

• extension
• single sign on
• yii2
• saml

README

Connect Yii 2 application to a Saml Identity Provider for Single Sign On

Installation

The preferred way to install this extension is through composer.

Either run

php composer.phar require --prefer-dist asminog/yii2-saml "*"

or add

"asminog/yii2-saml": "*"

to the require section of your composer.json file.

Configuration

Register asminog\yii2saml\Saml to your components in config/web.php.

'components' => [
    'saml' => [
        'class' => 'asminog\yii2saml\Saml',
        'configFileName' => '@app/config/saml.php', // OneLogin_Saml config file (Optional)
    ]
]

This component requires a OneLogin_Saml configuration stored in a php file. The default value for configFileName is @app/config/saml.php so make sure to create this file before. This file must returns the OneLogin_Saml configuration. See this link for example configuration.

<?php

$urlManager = Yii::$app->urlManager;
$spBaseUrl = $urlManager->getHostInfo() . $urlManager->getBaseUrl();

return [
    'sp' => [
        'entityId' => $spBaseUrl.'/saml/metadata',
        'assertionConsumerService' => [
            'url' => $spBaseUrl.'/saml/acs',
        ],
        'singleLogoutService' => [
            'url' => $spBaseUrl.'/saml/sls',
        ],
        'NameIDFormat' => 'urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified',
    ],
    'idp' => [
        'entityId' => 'identity-provider',
        'singleSignOnService' => [
            'url' => 'https://idp.com/sso',
        ],
        'singleLogoutService' => [
            'url' => 'https://idp.com/sls',
        ],
        'x509cert' => '<x509cert string>',
    ],
];

NOTE : As of version 1.6.0 you can directly put your configuration into your component. For example:

<?php

$urlManager = Yii::$app->urlManager;
$spBaseUrl = $urlManager->getHostInfo() . $urlManager->getBaseUrl();

$config = [
    // some other configuration here

    'components' => [
        'saml' => [
            'class' => 'asasmoyo\yii2saml\Saml',
            'config' => [
                'sp' => [
                    'entityId' => $spBaseUrl.'/saml/metadata',
                    'assertionConsumerService' => [
                        'url' => $spBaseUrl.'/saml/acs',
                    ],
                    'singleLogoutService' => [
                        'url' => $spBaseUrl.'/saml/sls',
                    ],
                    'NameIDFormat' => 'urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified',
                ],
                'idp' => [
                    'entityId' => 'identity-provider',
                    'singleSignOnService' => [
                        'url' => 'https://idp.com/sso',
                    ],
                    'singleLogoutService' => [
                        'url' => 'https://idp.com/sls',
                    ],
                    'x509cert' => '<x509cert string>',
                ],
            ];
        ]
    ],

    // some other configuration here
];

return $config;

Usage

This extension provides 4 actions:

1. LoginAction

   This actions will initiate login process to Identity Provider specified in config file. To use this action, just register this action to your actions in your controller.

   <?php
   
   namespace app\controllers;
   
   use Yii;
   use yii\web\Controller;
   use yii\helpers\Url;
   
   
   class SamlController extends Controller {
   
       // Remove CSRF protection
       public $enableCsrfValidation = false;
   
       public function actions() {
           return [
               'login' => [
                   'class' => 'asminog\yii2saml\actions\LoginAction'
               ]
           ];
       }
   
   }

   Now you can login to your Identity Provider by visiting saml/login.

2. AcsAction

   This action will process saml response sent by Identity Provider after succesfull login. You can register a callback to do some operation like read the attributes sent by Identity Provider and create a new user from that attributes. To use this action just register this action to you controllers's actions.

   <?php
   
   namespace app\controllers;
   
   use Yii;
   use yii\web\Controller;
   use yii\helpers\Url;
   
   
   class SamlController extends Controller {
   
       // Remove CSRF protection
       public $enableCsrfValidation = false;
   
       public function actions() {
           return [
               ...
               'acs' => [
                   'class' => 'asminog\yii2saml\actions\AcsAction',
                   'successCallback' => [$this, 'callback'],
                   'successUrl' => Url::to('site/welcome'),
               ]
           ];
       }
   
       /**
        * @param array $attributes attributes sent by Identity Provider.
        * @param string $nameId nameId sent by Identity Provider after v2.1.1.
        */
       public function callback($attributes, $nameId = null) {
           // do something
       }
   }

   NOTE: Make sure to register the acs action's url to AssertionConsumerService and the sls actions's url to SingleLogoutService (if supported) in the Identity Provider.

3. MetadataAction

   This action will show metadata of you application in xml. To use this action, just register the action to your controller's action.

   <?php
   
       public function actions() {
           return [
               ...
               'metadata' => [
                   'class' => 'asminog\yii2saml\actions\MetadataAction'
               ]
           ];
       }

4. LogoutAction

   This action will initiate SingleLogout process to Identity Provider. To use this action, just register this action to your controller's actions.

   <?php
   
       public function actions() {
           return [
               ...
               'logout' => [
                   'class' => 'asminog\yii2saml\actions\LogoutAction',
                   'returnTo' => Url::to('site/bye'),
               ]
           ];
       }

5. SlsAction

   This action will process saml logout request/response sent by Identity Provider. To use this action just register this action to you controllers's actions.

   <?php
   
       public function actions() {
           ...
   
           return [
               ...
               'sls' => [
                   'class' => 'asminog\yii2saml\actions\SlsAction',
                   'successUrl' => Url::to('site/bye'),
               ]
           ]
       }

Usage

If the SAMLResponse is rejected, add to the SAML settings the parameter

'debug' => true,

and the reason will be prompted.

LICENCE

MIT Licence