Easy way to add ID-card and mobile-ID identification on you website.

Current homepage is made using WordPress and Smart-ID plugin for WordPress. Other platforms can use internet standard Oauth 2.0 protocol to add ID-card and Mobile-ID logins.

Smart-ID using OAuth 2.0 protocol like Google and Facebook. For details about using OAuth 2.0 for authentication, see OpenID Connect

OAuth 2.0 works so that website end user is sent to Smart-ID authentication page where user authenticates himself and is Smart-ID redirects him back to the website with authentication code which can be used to get user data from the Smart-ID. Application must first be registered before starting to use the login service.

There is open source sample application for php and node.js that is the easiest way to get started. You will get this answer.

However if you want to have more details of how to integrate then read on.

STEP 1 – Register website to get the API keys.

  1. Open registration page at id.smartid.ee/admin
  2. Authenticate yourself
  3. Enter Website home page address and redirect_uri value where user will be redirected after authentication.
  4. Save the created client_id and secret values to a safe place. Do not tell the secret value to anyone for added security

STEP 2 – Integrate the login into your website.

  1. Redirect user to Smart-ID authorize endpoint https://id.smartid.ee/oauth/authorize with client_id, redirect_uri and response_type url parameters. Full url will look like https://id.smartid.ee/oauth/authorize?client_id=pM…m5&redirect_uri=https://example.com/login&response_type=code. There are also a few specialized endpoints.  https://id.smartid.ee/oauth/authorize/idcard?client_id?client_id=.. directs to Estonian ID-card identification immediately.  Adding &method=mobile-id brings on the Estonian Mobile-ID identification page.
    Explanation of the url parameters:

    1. client_id – client_id value that you got when registering the website
    2. redirect_uri – redirect_uri value that you entered when registering the website
    3. response_type=code – this is always like that on authorize page
  2. After user has been autenticated then he is redirected to the redirect_uri page with url parameter code. Code is authentication token that can be exchanged with access_token to get user data as described in next point.
  3. Exchange authorization code with access token with http POST query to https://id.smartid.ee/oauth/access_token with post body parameters code, grant_type, client_id, client_secret and redirect_uri. Full url will look like https://id.smartid.ee/oauth/access_token and post body needs to contain values in following format
    code=fy…36&grant_type=authorization_code&client_id=r1…oo&client_secret=Iu…ch&redirect_uri=https://example.com/login.  Query returns JSON like {“access_token”:”yF…zc”,”token_type”:”Bearer”,”expires_in”:3600} . Use the access_token value from this json to get the user data as a next step.
    Make sure that “Content-Type: application/x-www-form-urlencoded” and redirect_uri value is urlencoded.
    Explanation of the URL parameters:

    1. client_id – client_id value that you got when registering the website
    2. client_secret – secret value that you gotwhen registering the website
    3. redirect_uri – redirect_uri value that you enteredwhen registering the website
    4. code – code value that was set when redirecting user back from authorization endpoint
    5. grant_type=authorization_code – this is always like that when getting the access token
  4. Get the user data from url https://id.smartid.ee/api/v2/user_data . This call has only one url parameter access_token. Full url will look like https://id.smartid.dev/api/v2/user_data?access_token=2D…Co .
    Result will be JSON where new fields could be added. Example user_data response in JSON format is {“status”:”OK”,”idcode”:”46912302711″,”lastname”:”Kersti”,”firstname”:”Kaljulaid”,”email”:”president@eesti.ee”,”email_verified”:”true”,”last_login_method”:”est-idc”,”current_login_method”:”Facebook”}”
    Explanation of the URL parameters:

    1. access_token – access_token value that was received when sending post call to https://id.smartid.ee/oauth/access_token

 

If oauth2 client library is used then all of the integration flow is very easy. One example of such library is https://github.com/thephpleague/oauth2-client

Q&A

They are stored in Smart-ID database. These are used only by Smart-ID to authenticate its customers and deciding if and which info to return. If these get lost then it could be possible that 3rd party gets paid service on behalf of the other customer.

SmartID APi is running over https with valid certificate. Client can check for the certificate validity to make sure it gets ID user info from valid server. Several browsers don’t allow non encrypted traffic with OAuth2 protocol.