ps
/
docs
4
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Внесены правки по тексту, расширен последний раздел

master
Ашотян 2021-11-12 11:28:58 +03:00
parent 2192eaf7d0
commit e8e3583715
1 changed files with 113 additions and 54 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

167
OpenID_Connect_new.md
View File

@ -12,15 +12,17 @@
**[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)**
**[JWT generation, delivery & validation](JWT-generation,-delivery-&-validation)**
## Introduction
@ -34,13 +36,13 @@ The system developed by us is such a solution that solves the problem of localiz
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.
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 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.
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 JWTs (https://staging.ps.radium-it.ru/.well-known/jwks.json).
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](https://openid.net/specs/openid-connect-core-1_0.html#RFC6749).
Futher, a more detailed mechanism of the system operation on the OpenID Connect protocol, examples of requests, data flows, etc will be presented.
@ -66,6 +68,7 @@ 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
@ -80,7 +83,7 @@ flowchart LR
```
*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.
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:
@ -88,12 +91,16 @@ 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 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 Сlient ID, Redirect Uri, Response Type and one or more Scopes (permissions), that it needs.
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.
An example of HTTP 302 redirect response:
**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
@ -122,16 +129,44 @@ I-->B[/redirect_uri/]
J--> K[/Web consent/]--> B[/redirect_uri/]
E-->RF[Registration form]
```
*Figure 3. End-User authentication on oidc authorization server*
*Figure 3. End-User authentication on oidc Authorization Server*
If the user has already been in contact with the authorization server, browser sends the existing cookies to the authorization server along with the request.
The oidc authorization server receives cookies along with the request from the website, and based on this data decides whether the End-User is authenticated or not.
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.
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.
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:
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.
```
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
```
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.
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](https://openid.net/specs/openid-connect-core-1_0-final.html#Authenticates)
### Authorization
@ -151,9 +186,9 @@ CP--> RU[/redirect_uri/]
AZ--> RF[Registration form]
```
*Figure 4.*
*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 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
>
@ -163,7 +198,7 @@ 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 `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).
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:
@ -172,12 +207,22 @@ HTTP/1.1 302 Redirect
Location: {redirect_uri}
```
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.
**ПРИМЕР ответа из спецификации: Какой оставить?**
```
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
Visiting Consent page & entering primary data
```mermaid
flowchart LR
AZ[Authorization]--> CF[Consent form]
@ -193,10 +238,10 @@ N--> EA[Email]
```
*Figure 5.*
*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 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.
>
@ -208,20 +253,20 @@ On the page the End-User sees a form to fill out the data and the following text
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)**:
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)**:
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 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`.
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
@ -236,47 +281,61 @@ N--> EA[Email]
EA--> WF[Website Form]
```
*Figure 6.*
*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 try to request the known information about this End-User from third-party databases, for this the oidc authorization server sends a GET request on [*email*].
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).
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
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 Consent to Personal Data Processing 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).
```mermaid
flowchart LR
WC[Website consent]-->UI[(User Info)]
U[User]-->|PD input| WF[Website form]
WF-.->UI[(User Info)]
WF-->RU[/redirect_uri/]
```
*Figure 7. Data flow diagram for user data collection*
### JWT generation & delivery
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).
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):
**NOTE:** Registration form and Website form are the same pages but with the different content depending on the situation.
### JWT generation, delivery & validation
```mermaid
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` (see Figure 8).
Signature contains the private key with which the oidc authorization server signs a particular JWT.
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`.
```mermaid
flowchart LR
OD[oidc]-->|JWT|A[User]-->|JWT|B(Website)
```
*Figure 8. JWT delivery*
More information on `id_token` data structure can be found [here](https://openid.net/specs/openid-connect-core-1_0-final.html#IDToken).
The website must verify the signed JWT 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.
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 goal has been achieved.
The website can now use the id_token (JWT) to get the necessary information about the End-User.
The website must [validate](https://openid.net/specs/openid-connect-core-1_0-final.html#IDTokenValidation) 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:**
@ -284,4 +343,4 @@ The website can now use the id_token (JWT) to get the necessary information abou
Using multiple devices will prevent successful authorization.
2. 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*.
3. Cookies are currently stored on the oidc authorization server for 30 days, but this period may be extended if necessary.
3. Cookies are currently stored on the oidc Authorization Server for 30 days, but this period may be extended if necessary.