Yoursafe ID is the identity service of Yoursafe. It's targeted to companies that have difficulties obtaining full identification from their customers and to platforms that have an interest not to know the full identity, while still being required to identify their suppliers.
Yoursafe ID is using the OpenID Connect standard and technology to allow all Yoursafe Business Account holders to identify their customers. Yoursafe ID is free of charge.
This page explains how you would integrate Yoursafe ID with your online platform.
To get started, let's make sure that we agree on the meaning of 'entity' and 'identity'. An entity refers to a thing that exists as an individual unit while identity is a set of attributes that you can use to distinguish this entity within a context.
Quick example. Take any person - Newton, for example. Newton, by the most fundamental definition, was an entity. In this case, he was an entity that was capable of thinking, speaking, walking, teaching, and so on. However, the people around the scientist did not perceive him as an entity directly. Those people perceived Newton indirectly through his various attributes, like his name, gender, height, and home address.
The different subsets of attributes that people used to perceive Newton formed the identities that he had.
For some people, he was a mathematician with a name and an author (among other things). For a bank, he was a customer with a signature and an account number.
Different observers perceive one entity through different identities. That is, each observer uses a different set of attributes (identities) to understand the same entity.
At Yoursafe we protect the set of attributes of our customers (their identities), while they are engaging in global payments.
Yoursafe has defined one set of attributes: the mundane identity. The mundane identity proves the existence of this person in the offline world. It is mostly registered at birth by one of the parents. It contains the first name(s), last name(s), date of birth, place of birth, gender, nationality and tax ID.
Financial institutions worldwide require to know and verify the mundane identity to fight money-laundering and terrorist financing. At the same time the entity itself has the right of privacy: an individual's right to seclusion, or right to be free from public interference.
Yoursafe allows its YOU customers to use any other identity than their mundane identity in payments.
By using another identity than their mundane identity Yoursafe customers get full privacy between them and the counterparty, while the counterparty financial institution is still able to know and verify the mundane identity.
OpenID Connect, popularly abbreviated as OIDC, is a protocol used by Yoursafe enabling different types of applications to support authentication and identity management in a secure, centralized, and standardized way. Apps based on the OpenID Connect protocol rely on identity providers, like Yoursafe, to handle authentication processes for them securely and to verify the identities (i.e., personal attributes) of their users.
Yoursafe operates as an identity provider, as it has verified the mundane identities of its customers. The OIDC protocol uses the word Authorization Server to refer to the entity in charge of authenticating end-users. Yoursafe operates the Authorization Server as identity provider.
There are two ways how to look at the OpenID Connect protocol works: the end-user perspective and the software perspective.
Enduser point-of-view
From the end-user point of view, the steps involved in an OIDC flow are fairly simple. For starters, users will open the application in question to start the authentication process. When they start this process, the application will redirect them to Yoursafe where they will authenticate themselves. After they authenticate, Yoursafe will redirect them back to the application where they will be logged in.
In case of a traditional web application (those that do a full reload on the browser for each page requested) the steps involved in authenticating users are:
One important artifact that your application will get at the end of an authentication process is an ID Token. This token will contain a set of personal attributes about a user and, as such, your application can use it to identify the user (hence the name, ID Token).
Software perspective
When you dive deeper into the protocol, you will see that the steps above are oversimplified. However, in broad terms, they show how authentication processes flow and what steps you, as an application developer, can expect to see.
One thing that was briefly mentioned is that OpenID Connect is based on a framework called OAuth 2.0, which handles delegated authorization. If you know how this framework works, you probably realized that the steps above are extremely similar to what happens in an OAuth 2.0 authorization flow. The similarities between the processes are not a coincidence; they are a reflection of that fact that one extends the other.
Using the official terminology, OAuth 2.0 is an authorization framework that enables clients to use resource servers on behalf of resources owners. Clients, resource servers, and resource owners are probably not terms you are used to, so this might not help explain what the framework does.
In that case, let's take into consideration the following example. Imagine a Yoursafe YOU account holder would like to use your application, where he or she is providing certain content creation services. In this scenario, the platform application that manages the content creation and displays the content would be what OAuth 2.0 calls a Client, the Yoursafe YOU account holder would be the Resource Owner, and the Yoursafe API would be the Resource Server.
If you replace the terms that the framework uses with the terms you know, the definition of OAuth 2.0 would read like: OAuth 2.0 is an authorization framework that enables applications to use APIs on behalf of users.
Apart from the elements mentioned above, another essential term that the OAuth 2.0 framework defines is Authorization Server. Earlier on this page it was mentioned that OpenID Connect uses authorization server to refer to the entity in charge of authenticating users. We were able to say that because OIDC reuses (or extends) the term authorization server to include its role as the place where end users sign in. However, in a pure OAuth 2.0 sense, this entity plays a slightly different role. Authorizations servers in an OAuth 2.0 flow provide a means for resource owners to decide whether they want to grant the client the power to do something on their behalf or not.
Revisiting the scenario where a Yoursafe YOU account holder would grant a platform application permission to manage its content creation account, the authorization server would be Yoursafe. In this case, the first time the Yoursafe YOU account holder asked the platform application to get to know his or her alias, the app would send the Yoursafe YOU account holder to Yoursafe where the service would ask the Yoursafe YOU account holder if he or she would like to give the app this consent.
If he or she agrees, Yoursafe would provide the application with an artifact representing this grant. Then, at the time the platform application needs to further take action with this Yoursafe YOU account holder, the platform app would send a request to the Yoursafe API and would present this artifact to let the resource server know that you gave the app permission to perform this action.
Key Term glossary: The OAuth 2.0 framework uses the term Access Token to define the artifact that grants third-party applications (Clients) delegated authorization to act on behalf of users (Resource Owners). The name is quite descriptive. With this token, an API (Resource Server) will let an application access some part of it to perform some action.
You already now know some key key terms that are defined both by OpenID Connect and OAuth 2.0. The most important are:
Authorization Server - the place where, in a pure OAuth 2.0 authorization flow, Yoursafe YOU account holders authorize third-party applications to act on their behalf; or, in an OpenID Connect flow, where Yoursafe YOU account holders authenticate.
ID Token - an artifact that carries personal information about Yoursafe YOU account holders that authenticate on an OpenID Connect flow.
Resource owner - Yoursafe YOU account holder.
Resource server - Yoursafe API
Client - third party application (for example, your platform web application).
Access Tokens - the artifact that grants, to a client, the authorization to act on behalf of a resource owner.
Let's start coding! You will use a set of technologies that are arguably the most popular available nowadays: Node.js and NPM. That is, you will use JavaScript to implement OpenID Connect in different types of applications. Also, to avoid making you spending time on mundane tasks like scaffolding new apps, you will use GitHub to fetch some pre-existing code.
Node.js and NPM are essential to the tasks that follow. Therefore, you will have to install them in your environment if you want to get your hands dirty. If you are not sure whether these tools are available or not, you can open a terminal and issue the following commands:
node -v
npm -v
In case you get a message back saying “command not found” or similar, head to the Node.js and NPM documentation and follow the steps to install these tools.
Besides that, to fetch the pre-existing code from GitHub, you will have two options: either use the Git command-line interface as the sections will show, or use GitHub's website. Both alternatives are valid and will get the job done. However, you will probably find that using Git (which requires it to be available in your environment) is easier and more straightforward than using a webpage.
When you are ready for integration you first need to register your application as Client.
You can create a Client Configuration in business.yoursafe.com. All Business Accounts are eligable to use Yoursafe ID at no charge. You will find Yoursafe ID in the top right menu.
Please refer to the various scopes available of Yoursafe ID - depending on the services you use at Yoursafe.
After creating a client configuration in business.yoursafe.com you may review the Client ID and Client Secret. You need this information when connecting to the Yoursafe ID platform.
Connecting to the Yoursafe ID platform requires certain endpoints. These endpoints are described in this OpenID Connect discovery document:
https://accounts.yoursafe.com/.well-known/openid-configuration
An Access Token or Authorization Code is a temporary code received after a Yoursafe YOU account holder (the Resource owner) uses his/her credentials to authorize. It is used by your Client to obtain an ID Token.
You may connect your application to the following URL to obtain the Access Token / Authorization Code:
https://accounts.yoursafe.com/oauth2/authorize?response_type=code&client_id=<CLIENTID>&scope=<SCOPE>&state=<STATE>&redirect_uri=<REDIRECT URI>
The <CLIENTID> is the Client ID you received when registering your Client.
The <SCOPE> could be either "openid default", "openid platform" or "openid profile". Please note that "openid default" is available for all Yoursafe Business Accounts.
The Platform Scope and Profile Scope are available upon approval. You may request access to these scopes through your account manager.
The <REDIRECT_URI> is the full path of a returning URL on your web server, like https://www.yourserver.com/yourpath. This should be the same as the Redirect URL entered when you registered your application. Using a different URL will result in an error.
You may use <STATE> for any variable passing through to your REDIRECT_URI. After a Yoursafe YOU account holder authorizes this user is redirected to:
<REDIRECT URI>?code=<AUTHORIZATION_CODE>&state=<STATE>
To obtain authorization from your users (and a Yoursafe YOU account holder) you would need to use one of the buttons and graphics that are available. These buttons and graphics are well-known to the Yoursafe YOU account holder and he will be invited to press this graphic, which should link to your Access Token / Authorization Code retrieval code.
Please note that the received Access Token / Authorization Code can only be used once.
Now, we need to turn that Access Token or Authorization Code into an ID Token, by having your server make a request to Yoursafe's token endpoint:
https://accounts.yoursafe.com/oauth2/token
Please note that you can only use the HTTPS Request Method Put to this endpoint. You may post the following variables:
grant_type=authorization_code
client_id=<CLIENTID>
client_secret=<CLIENTSECRET>
scope=<SCOPE>
code=<AUTHORIZATION_CODE>
redirect_uri=<REDIRECT_URI>
Where CLIENTID, SCOPE and REDIRECT_URI are the variables that you have used before.
The <CLIENTSECRET> can be obtained after you registered your Client in business.yoursafe.com.
The <AUTHORIZATION_CODE> is the code you obtained during the process of obtaining the Access Token / Authorization Code.
The ID Token received is a JSON Web Token. You may want to use a library to get the payload from this ID Token. The payload contains the Claims of the chosen scope (Default, Platform, Profile).
You have now received all information needed to ensure that the natural person that authorized this process is identified and screened by Yoursafe. Screening includes screening against PEP lists and various sanction lists.
This natural person is now known to you with an AliasToken. An AliasToken is a fully qualified domain name: <6CHAR-NAME>.yoursafe.id.
With this AliasToken you are able to verify - without the need of an API - if the Yoursafe YOU account holder is still in good standing and if he/she has been checked recently on PEP and sanction lists. Please refer to the AliasToken Verification documentation.
To summarize: your user may identify him/herself by pressing a Yoursafe ID button or graphic on your website. This button or graphic launches an authorization request. After authorization by the user (and some consent approval request shown to him/her) your server will receive an Access Token (also known as Authorization Code). Your server converts this Authorization Code into an ID Token by posting the relevant data to Yoursafe. The contents of this ID Token (a JSON Web Token) contains the default, platform or profile scope of the user. The user has an AliasToken. You can use the AliasToken to receive status updates of the applicable user by visiting the fully qualified domain name (and retrieve JSON values) or use DNS TXT requests. That's it! Easy huh. It seems a lot of info, but luckily there is a lot of information available online to solve any issues you may have.
Yoursafe opened up a good old message board to answer any questions from users. It can be found at https://yoursafeidmb.yoursafe.com.