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:
- 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, use one of our backend SDKs (PHP or .NET SDKs) 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.
- 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:
- 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.
- 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.
- 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:
- 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
- It will never change for a GoodID user who uses the same verified email.
- It is a pairwise identifier for each GoodID user and RP. See also OpenID Connect, 8. Pairwise Identifier.
- 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.
- 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.
- 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.
- 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.
- 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. - 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.
- 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.
- 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.
- 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!
- 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⌵
- 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. }
- New user from GoodID
In case of new GoodID user:
- Create new user and store data
- Optionally show Welcome new GoodID user message to the user
- Redirect the user to the same page where your Legacy users arrive after login
- 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:
- Store data of GoodID user. Note: storing sub creates the link with Legacy user
- Optionally show Welcome upgraded GoodID user message to the user
- Redirect the user to the same page where your Legacy users arrive after login
- 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.
- Update data of GoodID user
- 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.
- New user from GoodID
- Messages
These are the recommended user messages mentioned above.
- Welcome new GoodID user message
- Welcome upgraded GoodID user message
- Update user data question
- Welcome new GoodID user message
If you have any question or feedback about this manual please let us know.
We wish you a successful integration!
Your GoodID Team