Developer integration guide

The integration can be carried out in the following two phases:

1. 1st phase – Creating Login button

   In this phase, you create a working Sign in with GoodID button on your site. From technical point of view this is the main part of the integration. If you have done it right – either using our SDK or API – you can receive all the intended claims from GoodID.

   1. If you would like to integrate fast and easy, use one of our backend SDKs (PHP or .NET SDKs) and JavaScript SDK for frontend integrations: see GoodID integration – 1^st phase (SDK) below.
   2. If you prefer developing on lower level, you can integrate using our OpenID Connect compliant API: The API documentation will be published soon.

2. 2nd phase – Data handling

   For the purpose of providing the same user experience for GoodID users (who are your customers as well) during the process of signing into any Relying Parties, we defined a checklist that contains recommendations to follow about how to handle the user data received from GoodID.

   We kindly ask you to take our suggestions, hereby providing standardized and smooth user experience for our common End-Users, while using GoodID login option on your site: see GoodID integration – 2^nd phase below.

Since GoodID is an OpenID Connect compliant IdP (Identity Provider) service we follow OpenID Connect terminology.

This guidance also defines the following terms:

1. Legacy user

   The user, who has a user account in your database and can log in to your service the legacy way, e.g. username / password.

2. GoodID user

   The End-User who has a sub (subject) in your database, that is received in every response from GoodID and never changes for the same user. A GoodID user can also be a Legacy user at the same time, but this is not necessary.

3. GoodID user identifier (sub)

   GoodID creates a unique identifier for each GoodID user, called sub (subject), that GoodID sends to the RP at every user’s login. Regarding sub, the following properties are relevant:

   1. It is guaranteed to be unique in the context of GoodID. If you integrate other OpenID Connect compliant IdP services, keep in mind that sub (subject) is unique together with iss (issuer). See also OpenID Connect 5.7. Claim Stability and Uniqueness
   2. It will never change for a GoodID user who uses the same verified email.
   3. It is a pairwise identifier for each GoodID user and RP. See also OpenID Connect, 8. Pairwise Identifier.
4. User upgrade

   We call it user upgrade if a Legacy user is linked with a GoodID user, and can log in to your site using GoodID too. Link is implemented simply by storing the sub within the Legacy user’s account. User upgrade can be manual or automatic.

   1. Auto upgrade: The RP requests a Verified email (email and email_verified claims) from GoodID. After the user is logged in with GoodID the link can be automatically performed if a Legacy user is found in your database based on the received Verified email.
   2. Manual upgrade: After the user is logged in with GoodID a Legacy login can also be requested from the user within the same session, based on the email received from GoodID (e.g. asking the password associated to the legacy account). The link is performed if the login is successful.
5. User downgrade

   We call it user downgrade if a GoodID user becomes Legacy user as well, and can log in to your site the legacy way. We recommend offering your Fallback authentication mechanism to your customers based on a verified claim (e.g. email_verified, phone_number_verified) requested from GoodID earlier.

6. Verified e-mail

   An e-mail address is verified if it is proven that the user owns this e-mail address. Relying Party can request verified e-mail from GoodID, using the "email_verified":{"value":true} claim.

7. Fallback authentication

   Legacy authentication mechanism implemented by the Relying Party which enables a Legacy user to reset their login credentials.

With GoodID you don't need a separate login and registration button, because the login and registration flow is practically the same.

It is strongly recommended to place the GoodID login button to all the following places:

• Your site's Log In page or form
• Your site's Sign Up / registration page or form
  With proper integration, GoodID can provide user data in sync with your registration form.
• Your site's Reset Password / Forgotten Password page or form, if any
  If using the same e-mail address, your users can just switch to GoodID and forget their passwords from now on!
• Your Shopping Basket page to Log In
  If the current user has items in the Shopping Basket, and would like to initiate the payment.
• Your site's Payout without registration page or form, if any

The GoodID PHP SDK builds the authentication request, collects the response data, checks the authenticity of the End-User and verifies some attributes (currently: e-mail), before you save data in your database and log in the End-User (or denies the request in case of a fraud).

PHP SDK on GitHub

The GoodID .NET SDK builds the authentication request, collects the response data, checks the authenticity of the End-User and verifies some attributes (currently: e-mail), before you save data in your database and log in the End-User (or deny the request in case of a fraud).

At this time it is only available upon request. Soon it will be uploaded as a Nu-get package.

GoodID can provide various kind of user data based on the individual claims included in the Authentication Request. Create the request in sync with registration data of your Legacy users by requesting the same claims.

1. Bring all user data from GoodID

   It is an essential function of GoodID that End-Users provide their data only once in their profile, then they can reuse the profile at different RPs, who will receive up-to-date user data at each login.

   1. We kindly ask you to request all available user data from GoodID. If you have any questions regarding data requesting, formatting, validating, etc. please do not hesitate to contact us, we are more than happy to help you in this matter! You can find the available claims here: Available claims.
   2. Exception: If GoodID cannot provide the necessary data to you. E.g. it needs special validation method on your side, please redirect the user to your registration page after their first GoodID login to finish the special part of the registration process!
2. Optional, Mandatory and Conditional claims

   GoodID allows RPs to request Optional, Conditional and Mandatory claims based on their preferences, so the data they receive from GoodID will be consistent with their registration form. We kindly ask you to create the claimset to be in sync with your registration form. We are happy to help you to generate your claimset, contact us!

1. Pseudo code of handling data received from GoodID

   Based on the received sub and verified email 3 cases can be differentiated, as illustrated by the following pseudo code:

   
   // receivedSub :: sub claim is always returned by GoodID
   // receivedEmail :: verified email claim
   
   User user_by_sub = FindUserBySub(receivedSub)
   
   if (user_by_sub == null) {
       User user_by_email = FindUserByEmail(receivedEmail)
       
       if (user_by_email == null) {
           // 1 - New user from GoodID.
       }
       else {
           // 2 - New user from GoodID, corresponding Legacy user.
       }
   }
   else {
       // 3 - Existing GoodID user.
   }
   

   1. New user from GoodID

      In case of new GoodID user:

      1. Create new user and store data
      2. Optionally show Welcome new GoodID user message to the user
      3. Redirect the user to the same page where your Legacy users arrive after login

   2. New user from GoodID, corresponding Legacy user

      If the new GoodID user is already a Legacy user in your database perform User upgrade, according to the following:

      1. Store data of GoodID user. Note: storing sub creates the link with Legacy user
      2. Optionally show Welcome upgraded GoodID user message to the user
      3. Redirect the user to the same page where your Legacy users arrive after login

   3. Existing GoodID user

      Since data might have changed in the GoodID user’s profile, it is essential using up-to-date data received from GoodID.

      1. Update data of GoodID user
      2. Redirect the user to the same page where your Legacy users arrive after login

   For those RPs who let their users change their email addresses: we ask to unlink associated sub at the same time as changing the email.

2. Messages

   These are the recommended user messages mentioned above.

   1. Welcome new GoodID user message

      Dear Customer!

      Congratulations, you have successfully signed up using GoodID!

      We have created the user account for your GoodID profile.

      Hereafter you can log in to our site quickly and easily using GoodID.

      We wish you a happy shopping experience!

      The Service Provider

   2. Welcome upgraded GoodID user message

      Dear User!

      Congratulations, you have successfully signed up using GoodID!

      We have linked your existing user account with your GoodID profile.

      Hereafter you can log in to our site the traditional way or quickly and easily using GoodID.

      Would you like to update your old data based on your GoodID profile?

      [Update from GoodID] [Keep old data]

      We wish you a happy shopping experience!

      The Service Provider

   3. Update user data question

      Dear User!

      Data we have received from your GoodID profile is different from your existing data.

      Would you like to update your existing data based on your GoodID profile?

      [Update from GoodID] [Keep existing data]

      We wish you a happy shopping experience!

      The Service Provider