Download the PHP package goodid/goodid-php55-sdk without Composer

[DEPRECATED]

Note: This version supports >= PHP 5.5.9. If you have PHP 5.6 or greater we suggest you to use https://github.com/idandtrust/goodid-php-sdk instead.

GoodID SDK for PHP 5.5

This repository contains our open source PHP SDK that allows you to collect, decrypt and verify the data that you receive from the user.

Installation

The GoodID PHP SDK can be installed with Composer. Add the GoodID PHP SDK package to your composer.json file.

Prerequisites

To provide GoodID login to your users, you need to first register at GoodID. You will receive GoodID mobile app beta access, GoodID mobile app download link, client id, client secret, default keypairs and suggested claim-set. At this point you also had the chance to generate your own keypairs and send the public key to GoodID.

The GoodID login flow

This is a short introduction to the GoodID login flow, to let you know what is the purpose of the endpoints that you will implement in the "Endpoints to be implemented" section.

Brief overview of the GoodID login flow:

1. When the user clicks on the "Login with GoodID" button, the GoodID Javascript SDK gets a new "OpenID Authentication Request" from your GoodID Login Initiation Endpoint over AJAX.
2. The GoodID Javascript SDK opens the GoodID login page with the received "Authorization Request", where the user logs in using their phone.
3. The user is redirected to your Redirect URI (Landing page), with "code" and "state" parameters that are used by the GoodID PHP SDK to collect, decrypt and verify the information provided by the user.
4. Congratulations! You have all requested data about the user. You can perform the login or registration process (if it is the first time they log in with the given subject identifier).

Endpoints to be implemented

GoodID Login Initiation Endpoint

The so-called GoodID Login Initiation endpoint is a designated endpoint for GoodID. It is analogous to the OpenID Connect Login Initiation endpoint. Currently it is responsible for the following things: It generates the OpenID authentication request and makes possible the GoodID App-Initiated Login Flow (Login from providers screen, etc.). The endpoint should be a separate PHP file (e.g. goodid-endpoint.php) with content similar to the below code snippet. You don't have to handle GET/POST parameters, or write a response, this is all done automatically by the GoodID Endpoint that is instantiated in the code snippet.

Redirect URI (Landing page)

You also have to handle the login requests of the user. When a user logs in with GoodID, they will be redirected to your so-called Redirect URI with a "code" and a "state" parameter. You can use something similar to the below code snippet. Doing a redirect after the login (attempt) is highly recommended as it removes the query parameters from the HTTP request URL, providing a cleaner experience for the user. It also keeps their browser history free of long expired authorization codes.

Sending custom validation errors to GoodID

When a certain data is judged valid by the GoodID app, but your custom validation thinks that it is invalid, you might want to notify us. With the information, we can make the validation better, or help you tune your claimset for better results. You can send error logs to us in the following way:

Miscellaneous

These steps may be useful at certain steps of the integration.

Generating your own keypairs

If you wish to generate your own keypairs, it is possible as follows, with openssl Installing openssl for Ubuntu:

Generating keypairs:

After that please send us the following:

• The new public keypairs (.pub files) and please label them so we know exactly to which environment they are for
• The request object created with the new public key for digital signature (based on the next paragraph)

Generating a Request Object

As the last step of the integration you are required to send GoodID a signed default request object. GoodID will publish this to the "request URI" hosted by GoodID, but created uniquely for you. When a sign in process starts from the GoodID app we will get the request signed by you from there. It can be generated as follows:

Generating the content of your JWKs URI

Your JWKs URI is an endpoint, which contains a JWKSet, which is a set of JSON Web Keys in JSON format. You have to store your signing and encryption public keys on the JWKs URI, to make it easily available in the app-initiated login flow (e.g. Providers Screen).

If you don't have a JWKs URI yet, you can generate its content like this:

If you have an existing JWKs URI, and you would like to add more keys to it, you can do it as described below. $jwksUriContent will contain the old keys from your existing JWKs URI and the new keys passed in the parameters too.

Using a picture returned in the picture_data claim

This is only interesting to you if you requested a picture from the user. You don't have to write the image to a file, it is just an example.