Changes in schemas
parent
6a8b2d253e
commit
9dd69adf40
GPG Key ID:
CC3C1E3EA2534D0C
210
oidc.md
210
oidc.md
|
|
@ -6,28 +6,23 @@
|
|||
* [Scheme of the OpenID Connect Core 1.0 protocol work](#Scheme-of-the-OpenID-Connect-Core-1.0-protocol-work)
|
||||
* Steps:
|
||||
|
||||
* [Visiting a foreign website](#Visiting-a-foreign-website)
|
||||
* [Authentication](#Authentication)
|
||||
* [Authorization](#Authorization)
|
||||
* [Consent form](#Consent-form)
|
||||
* [Registration form](#Registration-form)
|
||||
* [Search for available user data](#Search-for-available-user-data)
|
||||
* [Filling out the Website form](#Filling-out-the-Website-form)
|
||||
* [Visiting target website](#Visiting-target-website)
|
||||
* [Authentication](#Authentication-Authorization)
|
||||
* [JWT generation, delivery & validation](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.
|
||||
According to Russian legislation on personal data foreign websites cannot process personal data of Russian citizens without first collecting and processing it in Russian 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 proposed bellow system 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](https://openid.net/specs/openid-connect-core-1_0-final.html) stadard.
|
||||
Follow the link to the specification to explore the core functionality of OpenID Connect: authentication built on top of [OAuth 2.0](https://oauth.net/2/), and the use of Claims to communicate information about the End-User.
|
||||
The system provides OpenID Connect provider services in accordance with [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0-final.html) standard.
|
||||
Follow the link to the specification to explore the core functionality of OpenID Connect: authentication built on top of [OAuth 2.0](https://oauth.net/2/), and the use of Claims to communicate information about the User.
|
||||
|
||||
Also, within the framework of the system, a [Staging](https://staging.ps.radium-it.ru/.well-known/openid-configuration) environment configuration is deployed, within which it is possible to test the operation of the OpenID Connect Authorization Server.
|
||||
Also, within the framework of the system, a [Staging](https://staging.ps.radium-it.ru/.well-known/openid-configuration) environment configuration is deployed, within which it is possible to test the services 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.
|
||||
|
|
@ -39,123 +34,98 @@ All the necessary information regarding the configuration is available [here](ht
|
|||
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
|
||||
|
||||
```mermaid
|
||||
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
|
||||
|
||||
```mermaid
|
||||
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.client.com/
|
||||
```
|
||||
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](https://openid.net/specs/openid-connect-core-1_0-final.html#FragmentNotes).
|
||||
|
||||
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.
|
||||
## Work flow
|
||||
|
||||
```mermaid
|
||||
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"
|
||||
autonumber
|
||||
actor Visitor
|
||||
participant Website
|
||||
participant OIDC
|
||||
Visitor->>Website: Sign me inkk
|
||||
Website->>Visitor: Obtain token from OIDC
|
||||
Visitor->>OIDC: Authorize website
|
||||
OIDC->>Visitor: Token for Website
|
||||
Visitor->>Website: Sign me in with token
|
||||
Website-->>OIDC: Userinfo?
|
||||
OIDC-->>Website: {email: 'user@site.tld'}
|
||||
Website-)Visitor: Signed in
|
||||
```
|
||||
*Figure 2. Browser - Website communication*
|
||||
|
||||
### Authentication
|
||||
|
||||
#### NOTE: The system only supports [Implicit Flow](https://openid.net/specs/openid-connect-core-1_0-final.html#ImplicitFlowAuth)
|
||||
### Visiting a website
|
||||
|
||||
```mermaid
|
||||
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]
|
||||
U[User]-->W(Website)
|
||||
W--> A{Authenticated?}
|
||||
A-->|Yes| AC[Grant access]
|
||||
A-->|No| R[/redirect/]
|
||||
R-->O[OpenID Connect Provider]
|
||||
```
|
||||
|
||||
When an User visits a Website, the Website determines whether the User is known for the Website or is visiting the site for the first time.
|
||||
This check can be done by analyzing a request from the user for the presence of cookies.
|
||||
|
||||
If no data about the User is found, the Website needs to identify the User.
|
||||
To do this, the Website redirects the User to the OpenID Provider and includes in the request `client_id`, `redirect_uri`, `response_type` and one or more `scope` (permissions), that it needs.
|
||||
|
||||
**NOTE:**
|
||||
|
||||
`redirect_uri` is the address of the Website's page that can process the response from the provider.
|
||||
`redirect_uri` and `client_id` shall be pre-registered at the provider.
|
||||
|
||||
Example of 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"
|
||||
```
|
||||
|
||||
### Authentication & athorization
|
||||
|
||||
NOTE: The system currently only supports [Implicit Flow](https://openid.net/specs/openid-connect-core-1_0-final.html#ImplicitFlowAuth)
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
A{Process cookies.<br>Login required?} -->|No| C{Request database.<br>Consent required?}
|
||||
C -->|Yes| CF[Consent form]
|
||||
CF --> D
|
||||
C -->|No| W[Redirect to website<br>with token]
|
||||
A -->|Yes| CL[Consent & login form]
|
||||
CL --> M[/Magic-link/]
|
||||
M --> U{Request database.<br>Registered?}
|
||||
U -->|Yes| CC[/Write auth cookie/] --> D
|
||||
U -->|No| RF[Registration form] --> CC
|
||||
D[(Store)] -->|redirect| W
|
||||
```
|
||||
*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:
|
||||
The following is a non-normative example request using the Implicit Flow that would be sent by the Browser to the OIDC Authorization Server:
|
||||
|
||||
```
|
||||
GET /authorize?
|
||||
response_type=id_token%20token
|
||||
GET /oidc/authorize?
|
||||
response_type=id_token
|
||||
&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
|
||||
Host: staging.ps.radium-it.ru
|
||||
```
|
||||
|
||||
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 User has already been authenticated, Authorization Endpoint asks the database if the User's consent has been obtained for that Website.
|
||||
|
||||
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 the client (Website) has already been given by the User, the OIDC Authorization Server redirects the User to the address that was specified in the `redirect_uri` with some extra data according to the specification.
|
||||
|
||||
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.
|
||||
If User is not authenticated or consent for the client has not yet been given by 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 Authorization Server will attempt to authenticate the 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.
|
||||
- The User is not already authenticated.
|
||||
- The authentication request contains the `prompt` parameter with the value `login`.
|
||||
|
||||
More information can be found [here](https://openid.net/specs/openid-connect-core-1_0-final.html#Authenticates)
|
||||
|
||||
|
|
@ -175,9 +145,8 @@ CF-->|Click on 'submit' button| CP[Consent to PD processing]-.-> DB[(sub+client_
|
|||
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):
|
||||
On the page with the Consent form the 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
|
||||
>
|
||||
|
|
@ -187,21 +156,18 @@ On the page with the Consent form the End-User sees a form with the following te
|
|||
>
|
||||
> [Submit]
|
||||
|
||||
As soon as the End-User clicks [Submit], Consent is written to the database and the End-user is immediately redirected from the oidc Authorization Server back to the Website he wanted to visit (see Figure 4).
|
||||
As soon as the User clicks [Submit], Consent is written to the 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 Found
|
||||
Location: {redirect_uri}#
|
||||
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.
|
||||
If the Authorization Server decides that the User has never been authorized, then the oidc Authorization Server asks the end user to authorize via Registration form.
|
||||
|
||||
#### Registration form
|
||||
|
||||
|
|
@ -223,9 +189,9 @@ 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):
|
||||
On the page the 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.
|
||||
> 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]
|
||||
>
|
||||
|
|
@ -233,20 +199,20 @@ On the page the End-User sees a form to fill out the data and the following text
|
|||
>
|
||||
> | 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.
|
||||
In addition to filling out the field for entering email, the 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):
|
||||
After the 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):
|
||||
When the User clicks [Submit], a request is sent to the oidc Authorization Server to send a *magic link* to the 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 the 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 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`.
|
||||
|
||||
|
|
@ -263,12 +229,12 @@ N--> EA[Email]
|
|||
EA--> WF[Website Form]
|
||||
```
|
||||
|
||||
*Figure 6. Search for available End-User data*
|
||||
*Figure 6. Search for available 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.
|
||||
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 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).
|
||||
If a list of necessary User information is returned to the oidc Authorization Server from any database, then this data is saved in the User Info table and the User is redirected to the Website address specified earlier in `redirect_uri` (see Figure 7).
|
||||
|
||||
#### Filling out the Website form
|
||||
|
||||
|
|
@ -281,7 +247,7 @@ 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.
|
||||
If the oidc Authorization Server has not received any response from databases, after clicking on the *magic link* in the email, the 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.
|
||||
|
|
@ -298,7 +264,7 @@ 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):
|
||||
After all the necessary data about the User has been collected, the oidc Authorization Server sends the following response to the User, containing a link to the website and the `id_token` (JWT - JSON Web Token):
|
||||
|
||||
```
|
||||
HTTP/1.1 302 Redirect
|
||||
|
|
@ -317,7 +283,7 @@ To do this, it accesses the `jwks_endpoint`, from which it can obtain public key
|
|||
|
||||
The goal achieved.
|
||||
|
||||
The website can now use the JWT to get the necessary information about the End-User.
|
||||
The website can now use the JWT to get the necessary information about the User.
|
||||
|
||||
**ATTENTION:**
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue