4 – User management application
libraries for SAML2 or OpenID Connect would be a relevant step in the direction of integrating Tarallo with the SSO process.
Additionally, since Nextcloud had already been connected with SAML2, a decision was made to use OpenID Connect, to test the configuration of that protocol both from SSO and from an application side.
Moreover, since Tarallo is built without a framework but a set of different libraries, another decision was made to use no framework for this project, to exclude any OpenID Connect library that depends on a specific framework.
For this reason, a deliberate attempt as been made at keeping the project as simple as possible.
4 – User management application
To give a coherent structure to the project, the pds/skeleton specification 1.0.02 has been followed. It specifies, among other things, which directory may be used for files that can be served by the web server, and which ones should be used for other types of files. By restricting the web server to serve a single directory in the project clients cannot access configuration files, templates and classes directly. Accessing these files usually has no effect in any case, but this completely eliminates the risk of a misconfiguration that may accidentally print out the contents of a configuration file, for example.
Despite no frameworks being used, some libraries are still used: Plates3, a PHP library for templating, and Bootstrap4, an HTML, CSS and JS library for the user interface. To manage these libraries and their dependencies, the Composer dependecy manager has been chosen.5
For LDAP, the LDAP library that is part of the PHP core distribution was used.
It offers some PHP functions that are wrappers around the C functions provided by the OpenLDAP client library.
For OpenID Connect, a library had to be chosen since it would simplify the devel-opment compared to implementing the client part from scratch. In particular, the client part involves validating the cryptographic signature of different tokens and their content[6], which is a task best left to an already existing, open source and well-tested library, to avoid introducing security vulnerabilities.
The OpenID Connect web site lists some of the compatible libraries6. For PHP, there are four open source libraries listed at the time of writing, June 2019:
• phpOIDC7
• OpenID-Connect-PHP8
• oauth2-server-php9
• Drupal OpenID Connect Plugin10
2https://github.com/php-pds/skeleton/tree/1.0.0
3http://platesphp.com/
4https://getbootstrap.com/
5https://getcomposer.org/
6https://openid.net/developers/libraries/
7https://bitbucket.org/PEOFIAMP/phpoidc/src/default/
8https://github.com/jumbojett/OpenID-Connect-PHP
9https://bshaffer.github.io/oauth2-server-php-docs/
10https://www.drupal.org/project/openid_connect
4 – User management application
The Drupal connector was ruled out since it is a plugin for the Drupal CMS.
oauth2-server-php only implements the identity provider (SSO server) part of the specification, not the relying party (a client application) so it is not suitable for Crauto.
phpOIDCis the only certified library among these, but the readme file points out that
“the focus was on the interoperability, less focus was given to the security issues”, negating one of the potential advantages of using an existing library. Moreover, it seems to require a database even for the relying party implementation, which would make Crauto more complicated to deploy and manage.
OpenID-Connect-PHP instead is much simpler and requires no database, so that was the chosen library.
Implementing the authentication code flow was done as follows: the “Crauto” service provider was created in WSO2 IS, the client key and secret were randomly gener-ated by WSO2 IS, and a few lines of code were written to call OpenID-Connect-PHP library functions, provide them the key, secret, server URI and a few other parame-ters. The library then proceeds to perform the authentication code flow, with some specific steps to make it work in PHP:
1. Generate “nonce” and a “state” parameters[6] and store them in a PHP session 2. Prepare a request with these and any other needed parameters
3. Redirect the user to the OpenID Connect authorization endpoint on WSO2 IS 4. User performs authentication and consents to send claims to the Crauto
ap-plication
5. WSO2 IS redirects to the same page that the user came from, because the library has been configured to supply that URI to WSO2 IS
6. The user is sent back to the page, with a query parameter that contains the authorization token appended to the URI
7. The same code path is executed, until the point where the library checks if an authorization token is present among the query parameters: before it was not present so it went on to generate nonce and state and redirect the user, now they are present, so instead it makes a request to the token endpoint to exchange the access token for an ID token. The request is done through a
“back channel”: that is, the request is prepared and sent from PHP without involving the user agent
8. Check that the stored “state” parameter matches the one present in query pa-rameters along with the authorization token: this prevents some attacks where a malicious user injects a valid authentication token from another request in
4 – User management application
the redirect, or unsolicited responses with forged tokens
9. Decode and parse the JWT ID token (values are stored in a PHP array) and validate its signature and contents according to the specification. The nonce parameter, which provides protection against replay attacks[6], is also checked, which is a good thing despite its use being optional in the OpenID Connect specification
10. The validated token is stored in the object where the authenticate function has been called
From the point of view of the programmer, if the code before the authenticate function doesn’t have any side effects, it can be thought as executing it once and no ID token exists before authenticate is called while one is available later, although due to redirects the code before authenticate function is actually executed twice.
This approach proved to be very simple to integrate in an application. After the authentication step is completed, Crauto reads the parsed ID token and stores some of its attributes in a PHP session for later use: the user ID, full name and groups – which are all claims coming from the LDAP server through the SSO server – the expiration time, the refresh token and a copy of the ID token itself since it is required for sign-out.
The sign-out part does work in a similar manner, so it is not interesting to describe here. It should also be noted that, while sign-out works, single sign-out does not work yet: see section 3.4.1 for more details.
The refresh token part is more interesting and will be described in section 4.3.