openconextapps / ssp-voot-groups

simpleSAMLphp module to add VOOT group memberhips to the SAML attributes

Introduction

This is a module for simpleSAMLphp to fetch group memberships from an API service protected with OAuth 2.0 using the VOOT protocol (versions 1 and 2 are supported) and add them to the list of attributes received from the identity provider.

Why?

Because it is cumbersome to implement your own OAuth 2.0 and REST API client to fetch group memberships while they could also be made part of the received attributes when you are already a SAML service provider.

Who?

If you are a service provider that connects to an identity federation that supports VOOT to publish group membership information for users logging into your service. If you are currently already using simpleSAMLphp as SAML SP software you can just install the module. If you are using other software you can also install a simpleSAMLphp SAML proxy and install the module.

Installation

This module can be installed in two ways:

1. By unpacking a release tarball under the modules/ directory; or
2. with the simpleSAMLphp module installer.

For the first option, download ssp-voot-groups.x.y.z.tar.gz and unpack it under your modules/ directory of simpleSAMLphp. For the second option, you need to have Composer. Then it should suffice to run:

composer.phar require openconextapps/simplesamlphp-module-vootgroups

Configuration

Below is an example configuration for VOOT 1.0. You can place this in metadata/saml20-idp-remote.php for the IdP you want to attach the group fetching to.

'authproc' => array(
    40 => array (
        'class' => 'vootgroups:AttributeAddVootGroups',
        'vootScope' => 'http://openvoot.org/groups',
        'vootEndpoint' => 'https://voot.example.org/groups/@me',
        'userIdAttribute' => 'uid',
        'targetAttribute' => 'isMemberOf',
        'clientConfig' => array (
            'authorize_endpoint' => 'https://auth.example.org/authorize',
            'client_id' => 'my_client_id',
            'client_secret' => 'my_client_secret',
            'token_endpoint' => 'https://auth.example.org/token',
        ),
        'storage' => array (
            'type' => 'SessionStorage',
        ),
    ),
),

For VOOT 2.0, use /me/groups as the vootEndpoint.

If you want to use the PDO backed storage for using an SQL database you can modify the above storage configuration from:

'storage' => array (
    'type' => 'SessionStorage',
),

to this is you are using SQLite:

'storage' => array(
    'type' => 'PdoStorage',
    'dsn' => 'sqlite:/var/simplesamlphp/data/oauth.sqlite',
),

Make sure this oauth.sqlite file is writable by the web server. This may involve setting file permissions, dealing with SELinux and possibly some web server configuration. If you are using MySQL you could use the following:

'storage' => array(
    'type' => 'PdoStorage',
    'dsn' => 'mysql:host=localhost;dbname=oauth',
    'username' => 'foo',
    'password' => 'bar',
), 

See the PDO documentation on how to use your favorite database. The database schema for storing the tokens can be found as part of the OAuth client and can be found in schema/db.sql. It was tested with SQLite and MySQL. Importing this schema and configuring the database are out of scope here.

The schema can be found in vendor/fkooman/php-oauth-client/schema/db.sql after running Composer (see Installation section).

Registration

The OAuth configuration is shown above, but in addition you also need to register a redirect_uri at the OAuth 2.0 service. This depends on where simpleSAMLphp is installed. For example:

https://service.example.org/simplesaml/module.php/vootgroups/callback.php

This assumes that simpleSAMLphp is installed and reachable through http://service.example.org/simplesaml, modify the URL accordingly.

If you need to provide the redirect_uri as part of the authorize request as well you can also add the redirect_uri parameter to the clientConfig section of the configuration.

SURFconext

For SURFconext you can use the following configuration:

SURFconext API v 1 (VOOT 1.0):

40 => array (
    'class' => 'vootgroups:AttributeAddVootGroups',
    'vootEndpoint' => 'https://api.surfconext.nl/v1/social/rest/groups/@me',
    'vootScope' => 'read',
    'targetAttribute' => 'isMemberOf',
    'userIdAttribute' => 'urn:mace:dir:attribute-def:eduPersonPrincipalName',
    'clientConfig' => array (
        'authorize_endpoint' => 'https://api.surfconext.nl/v1/oauth2/authorize',
        'redirect_uri' => 'https://service.example.org/simplesaml/module.php/vootgroups/callback.php',
        'client_id' => 'MY_SURFCONEXT_CLIENT_ID',
        'client_secret' => 'MY_SURFCONEXT_CLIENT_SECRET',
        'credentials_in_request_body' => true,
        'token_endpoint' => 'https://api.surfconext.nl/v1/oauth2/token',
    ),
    'storage' => array (
        'type' => 'SessionStorage',
    ),
),

SURFconext API v 2 (VOOT 2.0):

40 => array (
    'class' => 'vootgroups:AttributeAddVootGroups',
    'vootEndpoint' => 'https://voot.surfconext.nl/me/groups',
    'vootScope' => 'groups',
    'targetAttribute' => 'isMemberOf',
    'userIdAttribute' => 'urn:mace:dir:attribute-def:eduPersonPrincipalName',
    'clientConfig' => array (
        'authorize_endpoint' => 'https://authz.surfconext.nl/oauth/authorize',
        'redirect_uri' => 'https://service.example.org/simplesaml/module.php/vootgroups/callback.php',
        'client_id' => 'MY_SURFCONEXT_CLIENT_ID',
        'client_secret' => 'MY_SURFCONEXT_CLIENT_SECRET',
        'token_endpoint' => 'https://authz.surfconext.nl/oauth/token',
    ),
    'storage' => array (
        'type' => 'SessionStorage',
    ),
),

NOTE: you need to use an attribute for userIdAttribute. In the example we use eduPersonPricipalName. Another candidate is eduPersonTargetedID. You may need to request permission to use this attribute when connecting your service to SURFconext.

If you have a client_id with a colon (:) in it, make sure to also set 'credentials_in_request_body' => true in the clientConfig section.

Of course, you can replace SessionStorage with PdoStorage (see above) for production setups.

License

This module is free software, licensed under the Apache 2.0 license. See the file LICENSE for details.

ssp-voot-groups's Issues

No license information found

I cannot seem to find any license information in this package...

Allow using persistent NameID instead of attribute for userId

Now a (global unique) attribute is required to store the access tokens in the client database. It would be super helpful if that can also be the persistent nameid value.

Revoked tokens gives problems

Whenever a token is revoked the module breaks. It won't retrieve the groups anymore in that session. Only in the next session (close browser, restart browser) the groups will be fetched.

upstream as "official" simpleSAMLphp module

I've created an upstream tracker bug:

http://code.google.com/p/simplesamlphp/issues/detail?id=558

Deal with situation when user does not give consent to retrieve groups

Now SSP gives a nasty error when the user does not give consent to retrieving the groups.

login again breaks with SessionStorage handler

SSP "Test configured authentication sources" fails with the SessionStorage hander when you:

1. login (this works great)
2. logout (works great as well)
3. login again (fails!)

Fatal error: fkooman\OAuth\Client\SessionStorage::getAccessToken(): The script tried to execute a method or access a property of an incomplete object.

This flow works great when using PdoStorage...

Don't create attribute when no groups available

Now that isMemberOf attribute is created, even when there are no groups to put in there. This should not be done.