Developer integration guide

En Hu

Feel free to play around with the options below to find a button layout that fits your needs the most.

Put this HTML code where you want to place the login button configured above

  • data-endpoint: replace with the relative URL of your GoodID login initiation endpoint.
  • data-size: default size of the button, including the GoodID Logo.
    Values currently supported: small, "" (default), large
  • data-lang: locale ID that you want the button to appear in.
    Currently supported: en_US, hu_HU
  • data-width: Width of the button. Default unit is pixel. Minimum width values are:
    • In size of small : 160px
    • In size of default : 200px
    • In size of large : 265px
  • data-font-size: Font size of the button label. Default unit is pixel.
values marked as such are mandatory

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

Custom integration

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.

    If you would like to integrate fast and easy, we provide PHP and .NET SDKs for backend and JavaScript SDK for frontend integrations: see GoodID integration – 1st phase (SDK) below.

    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

    In this phase, you should follow a checklist where we recommend some rules about the handling of data received from GoodID. You might say that it is only your business to handle your customers’ data. You are right, since GoodID is a zero-knowledge service we do not know user data.

    The reason we have created this checklist is to provide a common user experience for GoodID users (who are your customers as well).

    Essential GoodID user experience is the following: the user should be able to log in a fast, easy and secure way to online services, without passwords and registrations. For this purpose, GoodID users maintain their online identity related data in one place only, in their profile because they can re-use it at different Relying Parties providing GoodID login.

    RP will notice any change of user data due to the following reasons:

    1. Some user data (e.g. address, phone number, e-mail, etc.) is permanently changed. In this case, they will change data in the profile itself.
    2. User data is changed for the actual session only. In this case, they do not modify the profile, but create another profile that can be used for the same user account at the RP*. E.g. End-User would like to order products to a different delivery address. In this case, they will use a different profile, where everything but the delivery address will be the same and choose this profile in the app at login. However, RP will receive the same sub after login with either profile.


    *GoodID app will use the same sub for a sign-up to an RP, if a GoodID user registration already exists to the same RP with the same Verified e-mail.

    To achieve this, the basic requirement is that every Relying Party must prefer, at every GoodID login, all the received data from GoodID.

    We kindly ask you to take our integration suggestions into account during your integration process, 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. Legacy user identifier

    The primary user identifier (UID) used to uniquely identify your legacy users. E.g. e-mail, phone-number, user-name, user-id, etc.

  3. GoodID user

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

  4. 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 is a pairwise identifier for each GoodID user and RP. See also OpenID Connect, 8. Pairwise Identifier.
  5. User upgrade

    We call it user upgrade if a Legacy user is linked with 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. Manual upgrade - works for all kinds of Legacy user identification methods: The RP requests UID (email, phone_number or uname claim) from GoodID. Then, after the user is logged in with GoodID a Legacy login is also requested from the user within the same session, based on the UID received from GoodID (e.g. asking the password associated to the legacy account). The link is performed if the login is successful.
    2. Auto upgrade - works for e-mail and phone-number based Legacy user identification method: The RP requests a verified UID, that is, verified email (email and email_verified claims) or Verified phone number (phone_number and phone_number_verified claims) from GoodID. Then, 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 UID.
  6. 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 common identifier requested from GoodID earlier. E.g. a verified claim (e.g. email_verified phone_number_verified to implement SMS based OTP or password reminder.

  7. Verified e-mail

    An e-mail address is verified if it is proven that the user could read the content of an e-mail, which has been sent to this specific e-mail address. In other words, the user owns this e-mail address. Relying Party can request verified e-mail from GoodID, using the "email_verified":{"value":true} claim.

  8. Verified phone-number

    A phone-number is verified if it is proven that the user could read the content of an SMS, which has been sent to this specific phone number. In other words, the user owns this phone number. Relying Party can request verified phone number from GoodID, using the "phone_number_verified":{"value":true} claim.
    Note: it is under development.

  9. Fallback authentication

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

  10. Frontend database

    Customer database behind the online service which directly or indirectly can be accessed from the internet.

  11. Backend database

    Customer database behind the online service which cannot be accessed from the internet. It is recommended to apply pseudonymization on your Backend database.

  12. GDPR Ready integration

    Since GoodID transfers all Claims during each login process - that is in turn the most actual End-User data as well - the RP may decide not to store these data in the Frontend database except the sub and optionally an anonymized Legacy user identifier. E.g. data required to provide the service can be dropped after the service has been performed and data used for other purposes (i.e. CRM, marketing, PR, user statistics, etc.) can be moved to a Backend database, that can be protected much easier against attacks coming from the internet – e.g. by firewall and pseudonymization. GoodID also supports the de-registration of GoodID users from the RP using the following scope value: "gid_deauthn". If the RP follows these methods, we call the GoodID integration GDPR Ready.

    1. Anonymized data

      The concept of personally identifying information lies at the core of the GDPR. Any “personal data,” which is defined as “information relating to an identified or identifiable natural person ‘data subject’,” falls within the scope of the Regulation. The Regulation does not apply, however, to data that “does not relate to an identified or identifiable natural person or to data rendered anonymous in such a way that the data subject is no longer identifiable.”. Hash functions like SHA-256 are perfect way to anonymizing data.

    2. Pseudonymized data

      The GDPR defines pseudonymization as “the processing of personal data in such a way that the data can no longer be attributed to a specific data subject without the use of additional information.”. Although Recital 28 recognizes that pseudonymization “can reduce risks to the data subjects,” it is not alone a sufficient technique to exempt data from the scope of the Regulation. Cryptographic algorithms like AES-GCM with careful key management are perfect way to pseudonymizing data.

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. In fact, with GoodID, you get all up to date information about the End-User every time they log in.

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 deny the request in case of a fraud).

The PHP SDK must be downloaded and hosted by you, preferably as a composer module. This way you can easily update the PHP SDK with composer if it is needed. We have separate SDK's for PHP ≥ 5.5.9 and PHP ≥ 5.6. Click the appropriate button to visit the corresponding GitHub page.


We recommend the PHP ≥ 5.6 version, if it is suitable for you.

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

The .NET SDK must be hosted by you. 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

User Identification

Relying Parties SHOULD identify GoodID users with their sub (subject). Relying Parties use various type of UIDs to identify their Legacy users. In GoodID two methods are differentiated for linking GoodID users with Legacy users. (see also User upgrade, OpenID Connect 5.1. Standard Claims ):

  1. E-mail

    This is the most common user identifier, it is unique by its nature. Furthermore, it can be used for Fallback authentication as well. Request Verified e-mail from GoodID to associate a new GoodID user with an existing Legacy user.

  2. Phone number

    This is also applicable to identify End-User due it’s unique nature and it is also good for Fallback authentication. Request Verified phone number from GoodID to associate a new GoodID user with an existing Legacy user.

  3. User name, user id, etc.

    A unique string chosen by the user and / or by the RP. E.g. johndoe1443, 1444534565, jd_55536. Request uname claim from GoodID to associate a new GoodID user with and existing Legacy user.

Creating request

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

  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. Special case: GoodID supports the so-called „custom claims”, so you can also request special data that is not included in the standard GoodID claimset. In this case please contact us and we help in this!
    3. 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 with this!

    1. You can request mandatory claims with the "essential": true claim parameter.
    2. You can request optional claims with the "essential": false claim parameter, or by simply omitting the essential parameter. Optional claims should be defined so that the login should be successful even if the user did not provide any optional claims.
    3. Delayed claims:

      In order to minimize registration process, some RPs request mandatory user data later when it is necessary, depending on their own business logic (e.g. address data when the user is placing the order). We call these claims - what are non-mandatory but can be mandatory later - as delayed claims. As GoodID gives all data during the login process, the following two ways are suggested to request delayed claims:

      To provide all necessary data and facilitate your own business process you may request delayed claims as mandatory claims, so you will get all data you need during the login at once. In GoodID, most probably it is not a problem for the End-User since they have already filled that data in their profile (e.g. billing address, which was already asked by another RP).

      If you prefer to give more flexibility to the End-User, request it as delayed claim using the "req_later": true proprietary parameter. As a result, GoodID app will call the attention of the user to the fact that these claims might be requested later in the process. So, the End-User can decide to provide these at login or later. E.g.: "address": { "req_later": true }.

Handling response

Data received from GoodID should be processed in different ways by each RP, depending on the following properties.

Please fill this form to automatically customize the flow for your needs.

  1. Pseudo code of handling data received from GoodID

    Based on the received sub and email 6 phone number 6 user name 4 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)
    User user_by_email = FindUserByEmail(receivedEmail)
    
    if (user_by_sub == null) {
        if (user_by_email == null) {
            // 1 - New user from GoodID.
        }
        else if (user_by_email.sub == null) {
            // 2 - New user from GoodID, corresponding Legacy user.
        }
        else {
            // 3 - New GoodID user conflicting with existing GoodID user.
        }
    }
    else if (user_by_sub == user_by_email) {
        // 4 - Existing GoodID user.
    }
    else if (user_by_email == null) {
        // 5 - Existing GoodID user, e-mail does not exist.
    }
    else {
        // 6 - Existing GoodID user, e-mail conflict
    }
    // receivedSub :: sub claim is always returned by GoodID
    // receivedPhoneNumber :: verified phone_number claim
    
    User user_by_sub = FindUserBySub(receivedSub)
    User user_by_phone_number = FindUserByPhoneNumber(receivedPhoneNumber)
    
    if (user_by_sub == null) {
        if (user_by_phone_number == null) {
            // 1 - New user from GoodID.
        }
        else if (user_by_phone_number.sub == null) {
            // 2 - New user from GoodID, corresponding Legacy user.
        }
        else {
            // 3 - New GoodID user conflicting with existing GoodID user.
        }
    }
    else if (user_by_sub == user_by_phone_number) {
        // 4 - Existing GoodID user.
    }
    else if (user_by_phone_number == null) {
        // 5 - Existing GoodID user, phone-number does not exist.
    }
    else {
        // 6 - Existing GoodID user, phone_number conflict.
    }
    // receivedSub :: sub claim is always returned by GoodID
    // receivedUserName :: uname claim, will be received during sign-up only 
    
    User user_by_sub = FindUserBySub(receivedSub)
    
    if (user_by_sub == null) {
        User user_by_uname = FindUserByUserName(receivedUserName)
        if (user_by_uname == null) { 
            // 1 - New user from GoodID.
        }
        else if (user_by_uname.sub == null) {
            // 2 - New user from GoodID, corresponding Legacy user.
        }
        else {
            // 3 - New GoodID user conflicting with existing GoodID user.
        }
    }
    else {
        // 4 - 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. Force a login of the Legacy user creating a session in which Legacy user and GoodID user are also authenticated
      2. Store data of GoodID user. Note: storing the sub creates the link with the Legacy user
      3. Optionally show Welcome upgraded GoodID user message to the user
      4. Redirect the user to the same page where your Legacy users arrive after login
      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. New user from GoodID, another GoodID user conflict

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

      1. Perform a Fallback authentication creating a session in which Legacy users and GoodID user are also authenticated
      2. Store data of GoodID user. Note: storing sub creates the link with Legacy users
      3. Optionally show Welcome upgraded GoodID user message to the user
      4. Redirect the user to the same page where your Legacy users arrive after login.

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

    5. Existing GoodID user, e-mail does not exist Existing GoodID user, phone number does not exist Not applicable

      E-mail Phone number has been changed either by Legacy user or GoodID user and there is no other user having the same e-mail phone number that is received from GoodID. Since data might have changed in the GoodID user’s profile, it is essential using up-to-date data received from GoodID.

      E-mail Phone number has been changed by GoodID user and there is no other user having the same e-mail phone number that is received from GoodID. Since data might have changed in the GoodID user’s profile, it is essential using up-to-date data received from GoodID.

    6. Existing GoodID user, e-mail conflict Existing GoodID user, phone number conflict Not applicable

      E-mail Phone number has been changed either by Legacy user or GoodID user and there is another user having the same e-mail phone number that is received from GoodID. Please apply either of the following three alternatives:


      Alternative A – Keep GoodID user linked to the user account referenced by sub

      1. Update data of GoodID user except e-mail phone number
      2. Redirect the user to the same page where your Legacy users arrive after login


      Alternative B – Relink GoodID user to the user account referenced by e-mail phone number

      1. Perform a Fallback authentication of the Legacy user referenced by the e-mail phone number creating a session in which Legacy user and GoodID user are also authenticated
      2. Delete sub stored at the GoodID user referenced by sub
      3. Update data of the authenticated Legacy user with data received from GoodID. Note: storing sub creates a new link with the new user
      4. Redirect the user to the same page where your Legacy users arrive after login.


      Alternative C – Ask user whether to perform alternative A or B

      E-mail Phone number has been changed by GoodID user and there is another user having the same e-mail phone number that is received from GoodID. Please apply either of the following three alternatives:


      Alternative A – Keep GoodID user linked to the user account referenced by sub

      1. Update data of GoodID user except e-mail phone number
      2. Redirect the user to the same page where your Legacy users arrive after login.


      Alternative B – Relink GoodID user to the user account referenced by e-mail phone number

      1. Perform a Fallback authentication of the Legacy user referenced by the e-mail phone number creating a session in which Legacy user and GoodID user are also authenticated
      2. Delete sub stored at the GoodID user referenced by sub
      3. Update data of the authenticated Legacy user with data received from GoodID. Note: storing sub creates a new link with the new user
      4. Redirect the user to the same page where your Legacy users arrive after login.


      Alternative C – Ask user whether to perform alternative A or B

  2. How to store GoodID data

    GDPR Ready mode: no user data is stored in the Frontend database

    We recommend storing GoodID data according to the following:

    For GoodID users, store only Anonymized data (e.g. hashed e-mailphone number) in your Frontend database and all other data in session and / or temporary database. If necessary - move special data required for CRM, marketing (e.g. name, e-mail) into Backend database

    For upgraded Legacy users, - if necessary - backup legacy data into Backend database.

    Normal mode – user data is stored in the Frontend database

    Apply either of the following:

    1. GoodID user’s data is stored separately from Legacy data but for the same user account

      Since there is no conflict with Legacy data, all data can be overwritten on each login without a question.

    2. GoodID user’s data is stored at the same place as Legacy user’s data

    3. Mix of the previous two options. E.g. the RP handles list of some data (e.g. addresses or phone numbers), only these data are managed separately:

      For example: Let's assume that the Service Provider handles more than one delivery address or billing address (GoodID manages only one delivery and one billing address per profile).

      1. Mark the received data as goodid-delivery-address and the other as goodid-billing-address!
      2. Update the marked goodid-delivery-address and goodid-billing-address at every GoodID login!
      3. Do not modify the unmarked addresses (so those not coming from GoodID) or do not merge them with the GoodID addresses!
      4. Avoid showing duplicated addresses: we suggest marking the addresses coming from GoodID with a GoodID logo or GoodID text at your user interface as well!

  3. Messages

    These are the recommended user messages mentioned abowe.

    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