15 KiB

Raw Blame History

OpenID Connect

Introduction

Scheme of the OpenID Connect Core 1.0 protocol work

Steps:

Visiting a foreign website

Authentication

Authorization

- Consent form

- Registration form

- Search for available user data

- Filling out the Website form

JWT generation, delivery & validation

Introduction

At the moment, the use of global websites is a serious problem for international companies when doing business in the Russian Federation. In accordance with local legislation, foreign websites cannot process personal data of citizens of the Russian Federation without first collecting and processing it in local databases.

The solution to this problem is to use a server located on the territory of the Russian Federation, which will collect the necessary data, update, store, and also allow end users to change the entered data, revoke consent, etc.

The system developed by us is such a solution that solves the problem of localizing personal data.

The system provides for OpenID Connect protocol in accordance with OpenID Connect Core 1.0 stadard. Follow the link to the specification to explore the core functionality of OpenID Connect: authentication built on top of OAuth 2.0, and the use of Claims to communicate information about the End-User.

Also, within the framework of the system, a Staging environment configuration is deployed, within which it is possible to test the operation of the OpenID Connect Authorization Server.

It is important to note that the address of the Production server will be different from the Staging environment. By default, production server is located under https://client.ps.radium-it.ru. To customize a web address of the oidc Authorization Server, for example, https://privacy.client.ru or you need to add a CNAME Record to your DNS server.

In addition, the system assumes a jwks_endpoint, provided by the oidc Authorization Server, from which public keys can be obtained to verify the signature of signed JWT (https://staging.ps.radium-it.ru/.well-known/jwks.json). All the necessary information regarding the configuration is available here.

Futher, a more detailed mechanism of the system operation on the OpenID Connect protocol, examples of requests, data flows, etc will be presented. We provide an opportunity to study our system and try out the work in the configuration of the described algorithm.

Scheme of the OpenID Connect Core 1.0 protocol work

flowchart TD 
VW[Visiting a foreign website]--> GA(Grant Access) & SA[Authentication]
SA--> AT{User authenticated?}
AT--> Y(Yes) & N(No)
Y--> CO{Consent obtained?}
CO--> Y2(Yes) & N2(No)
Y2--> RU[/redirect_uri/]
N--> AZ[Authorization]
N2--> AZ[Authorization]
AZ--> CF[Consent form] & RF[Registration form]
CF--> RU[/redirect_uri/]
RF--> CD[Check for available data]
CD--> AD{Any data?}
AD--> Y3[Yes] & N3[No]
Y3--> RU[/redirect_uri/]
N3-->|magic link| WF[Website form]
WF--> RU[/redirect_uri/]
RU---W[Website]

Visiting a foreign website

flowchart LR
    A[User]-->B(Website)
    B--> C{User is authenticated?}
    C--> D[Yes] & E[No]
    D--> F[Grant access]
    E-->|redirect|G[oidc]

Figure 1. End-User visits website

When an End-User visits a Website, the Website determines whether the End-User is familiar with the Website or is visiting the site for the first time. The check is carried out by analyzing a request from the user for the presence of cookies.

An example of GET-request from the user:

GET https://www.foreign_website//

If a cookie determines that the End-User has already visited the Website, access is granted.

If no data about the End-User is found, the Website needs to identify the End-User. To do this, the Website redirects the End-User to the oidc Authorization Server and includes in the request client_id, redirect_uri, response type and one or more scopes (permissions), that it needs.

NOTE:

redirect_uri is JavaScript file that a Website might host at its redirect_uri. It must be previously configured and sent to the Authorization Server according to the configuration.

The following is a non-normative example of HTTP 302 redirect response:

HTTP/1.1 302 Found
Location: https://{OIDC server}/oidc/authorize?scope=openid&redirect_uri={Redirect URI}&client_id={Client ID}&response_type=id_token"

An example of Browser - Website communication is presented in figure 2.

sequenceDiagram
BROWSER ->> WEBSITE: GET https://www.foreign_website//
WEBSITE ->> BROWSER: HTTP/1.1 302 Found <br/> Location: https://{OIDC server}/oidc/authorize?<br/>?scope=openid&redirect_uri={Redirect URI}&client_id={Client ID}&response_type=id_token"

Figure 2. Browser - Website communication

Authentication

NOTE: The system only supports Implicit Flow

flowchart LR
G[oidc]--> C{User authenticated?}
C--> D[Yes] & E[No]
D--> H{Consent<br>obtained?}
H--> I[Yes] & J[No]
I-->B[/redirect_uri/]
J--> K[/Web consent/]--> B[/redirect_uri/]
E-->RF[Registration form]

Figure 3. End-User authentication on oidc Authorization Server

If the user has already been in contact with the oidc Authorization Server, browser sends the existing cookies to the oidc Authorization Server along with the request.

The following is a non-normative example request using the Implicit Flow that would be sent by the Browser to the oidc Authorization Server in response to a corresponding HTTP 302 redirect response by the Website:

GET /authorize?
response_type=id_token%20token
&client_id=s6BhdRkqt3
&redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb
&scope=openid%20profile
&state=af0ifjsldkj
&nonce=n-0S6_WzA2Mj HTTP/1.1
Host: server.example.com

The oidc Authorization Server receives cookies along with the request, and based on this data decides whether the End-User is authenticated or not.

If the End-User has already been authenticated, Authorization Endpoint asks the database if the End-User's consent has been obtained for that Website.

If consent for this site has already been given by the End-User, the oidc Authorization Server redirects the End-User to the address that was specified in the redirect_uri.

If consent for this site has not yet been given by the End-User, the oidc Authorization Server displays a Consent form with a list of all Scopes requested by the Website, as well as a checkbox to confirm consent to the processing of personal data.

NOTE:

The Authorization Server must attempt to authenticate the End-User in the following cases:

The End-User is not already authenticated.
The authentication request contains the prompt parameter with the value login. In this case, the Authorization Server must reauthenticate the End-User even if the End-User is already authenticated.

The Authorization Server must not interact with the End-User in the following case:

The authentication request contains the prompt parameter with the value none. In this case, the Authorization Server must return an error if an End-User is not already authenticated or could not be silently authenticated.

More information can be found here

Authorization

flowchart LR
AT{User authenticated?}--> Y(Yes) & N(No)
Y--> CO{Consent obtained?}
CO--> Y2(Yes) & N2(No)
Y2--> RU[/redirect_uri/]
N2--> AZ[Authorization]
N--> AZ[Authorization]
AZ--> CF[Consent form]
CF-->|Click on 'submit' button| CP[Consent to PD processing]-.-> DB[(sub+client_id+<br/>+date+scope)]
CP--> RU[/redirect_uri/]
AZ--> RF[Registration form]

Figure 4. General authorization scheme

On the page with the Consent form the End-User sees a form with the following text (An example demo will be presented later):

The example.client.ru requests access to your data: ID, email

Allow data access?

[X] Consent

[Submit]

As soon as the End-User clicks [Submit], Consent is written to the sub+client_id+date+scope database and the End-user is immediately redirected from the oidc Authorization Server back to the Website he wanted to visit (see Figure 4).

An example of HTTP 302 redirect response:

HTTP/1.1 302 Redirect
Location: {redirect_uri}

ПРИМЕР ответа из спецификации: Какой оставить?

HTTP/1.1 302 Found
Location: https://client.example.org/cb#
access_token=SlAV32hkKG
&token_type=bearer
&id_token=eyJ0 ... NiJ9.eyJ1c ... I6IjIifX0.DeWt4Qu ... ZXso
&expires_in=3600
&state=af0ifjsldkj

If the Authorization Server decides that the End-User has never been authorized, then the oidc Authorization Server asks the end user to authorize via Registration form.

Registration form

flowchart LR
AZ[Authorization]--> CF[Consent form]
AZ-->|Enter email| RF[Registration form]--> CB[User clicks on checkbox & 'submit' button]
CB-->AS[oidc]
AS-->|magic link| EA[Email]
EA--> WF[Website Form]
AS-.-> CAD[Check for available data]
CAD-->AD{Any data?}
AD--> Y[Yes] & N[No]
Y--> RU[/redirect_uri/]
N--> EA[Email]

Figure 5. Start of authorization via registration form

The oidc Authorization Server displays a Registration form listing all the Scopes requested by the Website. On the page the End-User sees a form to fill out the data and the following text (An example demo will be presented later):

The example.client.ru requests access to your data: ID, email.

If you allow access to the data, enter the data in the marked fields and click [Submit]

[] Consent

| Enter your email |

In addition to filling out the field for entering email, the End-User also ticks the checkbox, thereby confirming his consent to the processing of personal data.

After the End-User has entered the email into the form, put a tick in the checkbox and clicked [Submit], he sees a page with the following text (An example demo will be presented later):

Thank you for your submission, please check your email.

When the End-User clicks [Submit], a request is sent to the oidc Authorization Server to send a magic link to the End-User, whereupon the oidc Authorization Server sends an email containing a magic link and the following text to the specified email (An example demo will be presented later):

If you want to access the website, follow the link below:

magic link

When the End-User follows the magic link, he is actually sending GET request on [magic link] to the oidc Authorization Server. Thus, the oidc Authorization Server sees that the End-User has confirmed that he authorizes the Website to access his personal data.

When receiving GET request on [magic link], the oidc Authorization Server creates a unique and never reassignable identifier in the database based on the data it just received sub+client_id+scope+consent_data.

Search for available user data

flowchart LR
CAD[Check for available data]
CAD-->AD{Any data?}
AD<-.-> DB[(DB)]
AD--> Y[Yes] & N[No]
Y--> RU[/redirect_uri/]
N--> EA[Email]
EA--> WF[Website Form]

Figure 6. Search for available End-User data

Since one email is not enough to work correctly with the Website, the oidc Authorization Server will attempt to request the known information about the End-User with this email from the local or, if necessary, third-party databases. For this the oidc Authorization Server sends a GET request on [email].

If a list of necessary End-User information is returned to the oidc Authorization Server from any database, then this data is saved in the User Info table and the End-User is redirected to the Website address specified earlier in redirect_uri (see Figure 7).

Filling out the Website form

flowchart LR
U[User]-->|PD input| WF[Website form]
WF-.->UI[(User Info)]
WF-->RU[/redirect_uri/]

Figure 7. Data flow diagram for user data collection

If the oidc Authorization Server has not received any response from databases, after clicking on the magic link in the email, the End-User sees a Website form, which in addition to the pre-filled field with the previously entered email, also contains additional fields, for example: [first name], [last name], [place of employment], etc. All data collected using this form is also saved to the User Info table (see Figure 7).

NOTE: Registration form and Website form are the same pages but with the different content depending on the situation.

JWT generation, delivery & validation

flowchart LR

OD[oidc]-->|JWT|A[User]-->|JWT|B[/redirect_uri/]
B-->|Decoding JWT|JW[/jwks_endpoint/]
JW-.->CH[Check public & private keys]-->S(Successful)
S-->GA(Goal achieved)

Figure 8. JWT generation, delivery & validation

After all the necessary data about the End-User has been collected, the oidc Authorization Server sends the following response to the End-User, containing a link to the website and the id_token (JWT - JSON Web Token):

HTTP/1.1 302 Redirect
Location: {redirect_uri}?id_token

The id_token (JWT) is a JSON file that contains the information needed for authentication and validation, and the website can extract various information from the JWT, such as ID, user name, time of login to the account, expiration date of the ID Token, the presence of tampering attempts in the JWT, for example, sub+email+collected_data+signature.

More information on id_token data structure can be found here.

Signature contains the private key with which the oidc Authorization Server signs a particular JWT. The private key used to sign the JWT content must be associated with a public key used for signature verification published by the sender in its jwks_endpoint (JWK Set document).

The website must validate the JWT in the Token Response to proceed with the data. To do this, it accesses the jwks_endpoint, from which it can obtain public keys to verify the JWT signature.

The goal achieved.

The website can now use the JWT to get the necessary information about the End-User.

ATTENTION:

The user must perform all actions in one browser = from one device. Using multiple devices will prevent successful authorization.
In Stage 2, the user can be asked to enter not an email, but, for example, a phone number or both. Then, at the next stages, it will be possible to choose the most convenient communication method when sending magic link.
Cookies are currently stored on the oidc Authorization Server for 30 days, but this period may be extended if necessary.

15 KiB Raw Blame History