Developer integration guide

En Hu
Our minimum requirements about the button are the followings:
  • Colors: The GoodID Blue color is #084edd. You must use it as either the foreground or background color of the button.
  • Logo: The use of our logo is not mandatory on the GoodID Login button, however you must not use another logo or modify ours
    in any way.
  • Text: You are free to choose the text for the button, but it must contain the word »GoodID«.
  • Font, shape, etc.: You can customise them as much as you like.
  • Use the following HTML code:

Include this JavaScript code into your page to load the GoodID JavaScript library

The JavaScript library is a helper used to set up the GoodID Login button, as well as to open the GoodID login page.
We only support loading the JavaScript library from our servers.

Back to overview

Hot topics: Trying GoodID / Creating a login button, Downloading the PHP SDK, Getting the .NET SDK, Handling response
Actions: Expand all, Collapse all

Introduction

Integration phases

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 – 1st 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 – 2nd phase below.

Terminology

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.

GoodID integration 1st phase – Creating Login button (using SDK)

Login button

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

Backend integration / PHP

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).

Backend integration / .NET

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 integration 2nd phase – Data handling

Creating request

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!

Handling response

  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
    4. 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

    2. Welcome upgraded GoodID user message

    3. Update user data question

If you have any question or feedback about this manual please let us know.

We wish you a successful integration!

Your GoodID Team