Tutorials

Okey, we get it. The whole wallet, blockchain claims etc can be rather daunting and to be frank quite complicated. Thats exactly why we chose to implement OAuth as our main ID-Provider, because that makes it extremely easy. Still you might be wondering how to implement OAuth in you application and use it to get a users data. That's why we made a couple of tutorials to help you along.


Setting up your application

Before you can begin implementing ID-Vault you need to register your applications to ID-Vault, for legal reasons applications always belong to organizations. So let's set up an organization first, you can do that from your personal dashboard.

But first you need to activate developer mode, you can do that from the settings page with the developers view slider.

You should then see a developers menu appear at the bottom left of your dashboard menu, go to organizations and press “add”, fill in the form and save your organization.

Next you can setup your application, and save it. Now scroll to the bottom of the organization page to the application settings and press ‘add’, fill in the form and presto! You have yourself an application including a client secret for production and one for testing purposes.


Setting up a login

The main identity provider for the ID-Vault platform is OAuth2 or more specific OpenID, the main reasons for this are simplicity, compliance to standards (most providers use oauth) and control of data (OAuth allows a user to choose which data to unlock for applications).

So how does that work? Well rather easily actually first you need to set up your application (see tutorial here) and then you just redirect the user to the authorize url https://id-vault.com/oauth/authorize

When redirecting the user to the authorize url you include the following query parameters

Parameter Required Description
response_type yes this tells the authorization server that the application is initiating the authorization code flow. This value should be ‘code’
clientId yes The public identifier for the application obtained when the developer first registered the application
scopes yes One or more separated strings indicating which permissions the application is requesting. The strings are separated by a + sign e.g. &scope=create+delete
redirect_uri no Tells the authorization server where to send the user back to after they approve the request. This need to be either a whitelisted response url for your application or ‘localhost’ (if you are usung your test secret)
state no A random string used by your application to identify a unique session

Putting that all together we get something like this https://id-vault.com/oauth/authorize?response_type=code&clientId=759a959a-85bf-42c6-bc43-1a7d00ad14c0&scope=create+delete. So that's the beauty and simplicity of the OAuth set up, you simply forward the user to somewhere else and wait until the user returns authenticated.

At the forward url the user will then be presented with an authorization screen by ID-Vault (or login screen if the user isn’t currently logged in). After autorization the user is then forwarded to the authorization url (provided at application registration) with the code and state parameters, or localhost if a test secret is used and the redirect_uri property is set to localhost (both http and https supported)

You will then need to “handle” the login request at your application, that goes in two stages.

First an applications needs to exchange the authorization code for an access token (be aware that an authorization code is only valid for 10 minutes). This is done by Making a POST request to the https://id-vault.com/oauth/access_tokens endpoint. The request MUST be POST and MUST contain a JSON encoded body with the following parameters.

Property Required Description
grantType yes always ‘authorization_code’
clientId yes The applications id
clientSecret yes The applications secret
code yes The code send by ID-Vault when returning a user
state no A random string used by your application to identify a unique session

so for example:

{
    "grantType":"b8133d82-8dc3-40fb-8626-e251c797416e",
    "clientId":"759a959a-85bf-42c6-bc43-1a7d00ad14c0",
    "clientSecret":"c9c19e37-0802-4d77-85fd-62ca86dc83c4",
    "code":"d7f33b1b-be8d-4cda-9617-7eaa04678f14",
    "state":"97a564b2-33cb-4dfd-b6a7-d59a6664731e"
}
    

You will then get an response containing you your Access token, for example

{
    "token_type":"bearer",
    "expires_in":3600,
    "scope":"public_repo,user",
    "access_token":"....",
    "state":"97a564b2-33cb-4dfd-b6a7-d59a6664731e"
}
    

The properties should be interpreted as followed

Property Description
token_type always ‘authorization_code’
expires_in
scope The scopes granted by the user, note that these might difer from the requested scopes
access_token A jwt token
state The state provided in the request, passed in order for your application to be able to check the validity of the login

Okay so let's take a look at this JWT token, this can be stored as a text in which case you can simply use it to login the ID-Vault API but we can also parse it(see tutorial) which will give us something like:


 {
    "azp":"272196069173.apps.googleusercontent.com",
    "aud":"272196069173.apps.googleusercontent.com",
    "sub":"110248495921238986420",
    "hd": "id-vault.com",
    "name": Ruben van der Linde",
    "given_name": "Ruben",
    "family_name": "van der Linde",
    "picture": "[[url]",
    "email":"[email protected]",
    "email_verified": true,
    "locale":"en",
    "at_hash":"0bzSP5g7IfV3HXoLwYS3Lg",
    "exp":1524601669,
    "iss":"https://www.id-vault.com/dashboard",
    "iat":1524598069,
    "alg":"RS256",
    "kid":"affc62907a446182adc1fa4e81fdba6310dce63f"
}
    

Wich we can then interpret as followed

Property Description
azp always ‘authorization_code’
aud The full URL of the resource you're using the JWT to authenticate to
sub The sub (subject) property contains the unique user identifier of the user who signed in
name The username of the user (in most cases an email addres)
given_name
family_name
picture
email
email_verified
locale The preferred language of a user
exp expire duration
iss client_id
iat date token was created

So that’s nice, the access token itself already gives you some basic information to fire up your UI and present a user with his/her/their with an familiar enviroment.


Using the ID Token to Retrieve User

Info ID-Vault provides an additional API endpoint, called the tokeninfo endpoint, which you can use to look up the ID token details instead of parsing it yourself. This is not recommended for production applications, as it requires an additional HTTP round trip, but can be useful for testing and troubleshooting.

ID-Vaults tokeninfo endpoint is at https://id-vault.com/oauth/tokeninfo/[[uuid]], as found in their OpenID Connect discovery document at https://www..id-vault.com/dashboard/.well-known/openid-configuration. To look up the info for the ID token we received, make a GET request to the tokeninfo endpoint with the ID token in the query string.

https://www.id-vault.com/oauth2/v3/tokeninfo?id_token=eyJ... The response will be a JSON object with a similar list of properties that were included in the JWT itself.

    
{
    "azp":"272196069173.apps.googleusercontent.com",
    "aud":"272196069173.apps.googleusercontent.com",
    "sub":"110248495921238986420",
    "hd": "id-vault.com",
    "email":"[email protected]",
    "email_verified": true,
    "at_hash":"0bzSP5g7IfV3HXoLwYS3Lg",
    "exp":1524601669,
    "iss":"https://www.id-vault.com/dashboard",
    "iat":1524598069,
    "alg":"RS256",
    "kid":"affc62907a446182adc1fa4e81fdba6310dce63f"
}

Using the Access Token to Retrieve User Info

As mentioned before, many OAuth 2.0 services also provide an endpoint to retrieve the user info of the user who logged in. This is part of the OpenID Connect standard, and the endpoint will be part of the service’s OpenID Connect Discovery Document.

ID-Vault’s userinfo endpoint is https://www.id-vault.com/oauth2/v3/userinfo. In this case, you use the access token rather than the ID token to look up the user info. Make a GET request to that endpoint and pass the access token in the HTTP Authorization header like you normally would when making an OAuth 2.0 API request.

GET /oauth2/v3/userinfo Host: www.id-vault.com Authorization: Bearer ya29.Gl-oBRPLiI9IrSRA70…

The response will be a JSON object with several properties about the user. The response will always include the sub key, which is the unique identifier for the user. ID-Vault also returns the user’s profile information such as name (first and last), profile photo URL, gender, locale, profile URL, and email


{
    "sub": "110248495921238986420",
    "name": Ruben van der Linde",
    "given_name": "Ruben",
    "family_name": "van der Linde",
    "picture": "[[url]",
    "email": "[email protected]",
    "email_verified": true,
    "locale":"en",
    "hd":"id-vault.com"
}

That means that you will always have acces to a users primary email, name and locale as part of an authorization request. EVEN IF YOU DO NOT REQUIRE ANY SCOPES


Working with scopes

Scopes form the base for both the OAuth2 and OpenId Connect protocol, they define both what an application can do on its users behalve and to which data it has access. Both the OAuth2 and OpenId Connect protocol give a great amount of liberty to how you can define scopes, there is however some conformity to be found between wallet solutions and that is dot notation.

We differentiate between 3 base structures: schema, application and special

The first two of these are about data storage and sharing, it is basically how users fill up their wallet. The first (and preferred way) is using schema.org object structure, this provides a communal point for data mapping e.g. more than one application can provide an authenticated telephone nr. The second way (and deterred way) is by application this is an way of storing data that simply won’t fit in the shema.org system, this is stored in an application specific way onder the application reference as a key. The obvious problem with the second concept being that you don’t share data between applications.

Requesting a schema scope automatically give’s you both the read and the write right’s to that specific datapoint. But keep in mind that a user will always be alerted and promoted when you add data to their wallet and has a final say. E.g. you may suggest a user to add something to his or her wallet but they choose to do so.

You do not need to request application scopes for scopes that are part of your application nor is a user required to accept changes. You MAY request scopes for other applications and when in the possession of suchs a scope you MAY write to such a scope but the original application AND the user will need to accept such a write as per schema scope change.

This means that your application data may be altered by the user outside of your application, but only if everybody agrees. This reflects the fact that the data is owned by the user and not the application.

Root Property Scope Description
schema person.birthPlace schema.person.birthPlace The place where the person was born
schema person.birthDate schema.person.birthday Date of birth
schema person.address schema.person.address Physical address of the person
schema person.telephone schema.person.telephone The telephone number
schema person.email schema.person.email Email address
schema person.givenName schema.person.given_name Given name. In the U.S., the first name of a Person
schema person.familyName schema.person.family_name Family name. In the U.S., the last name of a Person
schema person.image schema.person.image An image of the person. This can be a URL or a fully described ImageObject
schema person.taxID schema.person.taxID The tax identifier for a person (also know as social security number) e.g. the TIN in the US, the CIF/NIF in Spain or BSN in The Netherlands.
schema person.educationalCredential schema.person.educationalCredential An educational or occupational credential. A diploma, academic degree, certification, qualification, badge, etc., that may be awarded to a person that meets the requirements defined by the credentialer. For example a nursing diploma or EHBO certificate
schema organization.vatID schema.organization.vatID The Value-added Tax ID of the organization or person. e.g. BTW Number in The Netherlands
special n.v.t force Allows an application to force authentication
special n.v.t factor Allows an application to force two or three factor authentication
special n.v.t mailing_list Allows an application to add a user to mailings lists and/or send emails
special n.v.t phone_list Allows an application to add a user to phone lists and/or send text messages
special n.v.t dossier This scope allows you to create dossiers to your contracts
special n.v.t contract Allows an applications to provide contracts to a user
special n.v.t assent Allows an application to provide assentsto a user
special n.v.t notification Allows an application to recieve updates when a user changes there data
special n.v.t single_sign_on Allows an application to single sign on functionality assentsto a user

Obtaining information from a user’s wallet

As mentioned before ID-Vault provides an endpoint to retrieve the user info of the user who logged in. This is part of the OpenID Connect standard. This endpoint (https://www.id-vault.com/oauth/userinfo) is configured to give back a minimal set of data by default but can also provide access to those claims in a users wallet that the application was granted a scope to.

In this case, you again use the access token rather than the ID token to look up the user info. Make a GET request to that endpoint and pass the access token in the HTTP Authorization header like you normally would when making an OAuth 2.0 API request.

But as an additional option you provide scopes in a query parameter divided by commas (,) and a goal parameter, the later one states the goal for which you want to use the data.

GET /oauth/userinfo?scopes=schema.person.birthDate,schema.person.telephone&goal=birthdaycall Host: www.id-vault.com Authorization: Bearer ya29.Gl-oBRPLiI9IrSRA70…

The relevant claim data will then either be added to the schema or application part of the response, in this case:

{
    "sub": "110248495921238986420",
    "name": Ruben van der Linde",
    "given_name": "Ruben",
    "family_name": "van der Linde",
    "picture": "[[url]",
    "email": "[email protected]",
    "email_verified": true,
    "locale":"en",
    "hd":"id-vault.com",
    "claims":{
        "schema":{
           "person": {
                "telephone":"+316-12345678",
                "birthDate":"1985-07-27"
            }
        }
    }
}

Interestingly enough that means that you can actually get the wallet information as part of your normal OAuth login flow, you just need to make an call to the https://www.id-vault.com/oauth/userinfo endpoint after obtaining the authorization token in the last fase of your login handling


Storing information to a user’s wallet

This is where it gets a bit more tricky, as an application you can not simply “write” something to someone’s wallet. A wallet is a personal concept, unique to a specific user. So you can't just “write” to a scope. You need proof :)

The concept of “proof” within a chain of trust is that is sharable and controllable, you can read a bit more about that here. But for now that means that in order to varify proof a verifier needs an endpoint against whichs to check that proof. That leaves you with two options, first is that you set up your own verification endpoint (recommended but hard) or secondly you use ID-Vaults proofing endpoint (less save but easier).

Let's focus on the second one first, and then move on to the preferable more complex one. You just post the claims that you want to proof to the claim endpoint and the claim API handles the rest. So a post would look like.

{
    "claims":{
        "schema":{
           "person": {
                "telephone":"+316-12345678",
                "birthDate":"1985-07-27"
            }
        }
    }
}

Downright easy right? The problem here is that ID-Vault will create a signing certificate for this data (and reference your organization in it). That means that our endpoint will be used to verify the claim, which means that you will need to keep our database in sync with ours to prevent a “false” positive on the provided data. That also means that the data can not be used on a trustlevel of 3 or higher, significantly reducing its value.


Two (or three) Factor Authentication

For some user actions you might need an additional layer of proof that a user is who he’s says he or she is. A common practice is the implementation of two factor authentication, this means that a user will be required to take an additional action to identify themselves. Normally this takes the form of an additional security code, either provided by a randomizer, text or mail message.

ID-Vault has a build in two factor authentication which you can trigger by setting up a normal OAuth request and adding the factor parameter to your authentication url and setting it to the factor that you require e.g. &factor=2 (default is 1). ID-Vault will then check if the user has done a multiple factor authentication on there current session in the last 10 minuten, and if not require the user to use a secondary (or third) authentication method of their choice.


Forcing Authentication

On a normal OAuth request ID-Vault will use its own session with a user to determine whether or not a user is logged in, you can however force a user to re-authenticate themselves on an OAuth request by adding the &force=true parameter. This will force a user to present their password credential to ID-Vault (akin to the linux sudo command). This might come in handy when you need a bit of additional proof but don’t know if the user has set op two (or three) factor authentication.

This form of authentication is commonly used when users check their personal data or perform destructive action’s (like deleting objects or cancelling orders)


Requiring proof

&proof=true


Adjusting the level of trust

&levelOfTrust=4