Merge pull request #184 from italia/dev

Refresh token, tools and access history and several small bug fixes

README.md

@@ -37,7 +37,7 @@ each of these can be installed separately within a django project. These are the
 ------------------------------------------------
 
 ![RP Auth demo](docs/images/rp_auth_demo_3.gif)
-_An onboarded Relying Party with a succesful authentication._
+_An onboarded Relying Party with a succesfull authentication._
 
 ## Setup
 

docs/CREATE_A_FEDERATION.md

@@ -158,6 +158,7 @@ An example of metadata[here](https://github.com/italia/spid-cie-oidc-django/blob
 
 ![RP federation entity](images/rp_federation_entity.png)
 
+## Register an entity as descendant
 
 Now that you configured your Provider Entity you have to register it in the federation.
 Access to the Federation Authority admin backend and configure your RP as descendant and assign to it a profile.

docs/FEDERATION_ENTITY_API.md

@@ -39,7 +39,6 @@ To evaluate a TrustChain we need at least of three things:
 - __subject identifier__ of the entity to which we want to establish the trust, the leaf.
 - __trust_anchor__, subject identifier of the Federation authority that represent the Federation,
 the root of the trust and the point of arrival, the final destination, of the path of trust.
-- __metadata_type__, which kind of metadata we want to export from the trust chain, if openid provider or relying party.
 The final metadata will be combined with the metadata policy of the superiors statements.
 - __required_trust_marks__, which trust marks are required to start a metadata discovery on the subject of the trust chain.
 At least one MUST be present as valid in the entity configuration of the subject. The validation of the trust mark JWS must be done

docs/technical_specifications/AUTHORITY.md

@@ -38,11 +38,51 @@ Lists all the descendant entities.
  - `http://127.0.0.1:8000/list/?type=openid_provider`
 
 
+#### Advanced entity listing endpoint
+
+The advanced entity listing endpoint extends Listings endpoint.
+
+The request MUST be an HTTP request using the GET method, an entity needs to know only the endpoint url.
+
+Example of Advanced listing request: `http://127.0.0.1:8000/advanced_entity_listing/`
+
+
+The response is a json object (content type: "application/json") in which for each entity the only REQUIRED claim is iat.
+The entity's result set must have a descendant ordering with higher iat on top.
+
+A response example: 
+````
+{
+    "iss": "https://registry.spid.gov.it/",
+    "iat": 1620050972,
+    "entities": [
+        {
+            "https://rp.example.it/spid/": {
+            "iat": 1588455866,
+            },
+            {
+            "https://rp.another.it/spid/": {
+            "iat": 1588455856,
+            },
+            {
+            "https://rp.it/spid/": {
+            "iat": 1588355866,
+            },
+        ... # many other entries
+    ],
+    "page": 1,
+    "total_pages": 2,
+    "total_entries": 189,
+    "next_page_path": "/federation_adv_list/?page=2",
+    "prev_page_path": ""
+}
+```` 
+
 #### Resolve entity statement
 
 An entity MAY use the resolve endpoint to fetch resolved metadata and trust marks for an entity as seen/trusted by the resolver. 
 
-- `http://127.0.0.1:8000/resolve/?sub=http://127.0.0.1:8000/oidc/op/&anchor=http://127.0.0.1:8000/&format=json`
+- `http://127.0.0.1:8000/resolve/?sub=http://127.0.0.1:8000/oidc/rp/&anchor=http://127.0.0.1:8000/&type=openid_relying_party&format=json`
 - `http://127.0.0.1:8000/resolve/?sub=http://127.0.0.1:8000/oidc/op/&anchor=http://127.0.0.1:8000/`
 
 

docs/technical_specifications/ONBOARDING.md

@@ -2,82 +2,65 @@
 
 > ⚠️ This application is only intended for demostration purpose and not for production use.
 
-
 ## General OnBoarding registration flow
 
 The actions to accredit an entity within the demo federation are described below.
 
 ### Entity Registration
 
-1. the legal representative of an entity/org accesses via SPID or CIE
-   - __demo__ web resource `/onboarding/landing/`
-   - __warning__ this onboarding demo comes with an unprotected registration page.
-   The SPID and CIE authentication won't be involved in this demo.
-
-2. becomes recognizable as an org affiliate and is given privileges to operate on
-behalf of that org for the registration of an entity, if not already present within the federation.
-
-
-3. The user accesses the submission form of a federation entity, fill in the following REQUIRED fields:
-    1. Organization Name (String)
-    2. unique identifier of the entity (url) of the instance in production/stage (URL)
-        1. validators:
-            - download of the Entity Configuration, a self-signed statement
-            - JWS signature validation
-            - structure analysis of the JSON (json-schema)
-            - presence and validation of the claim  __authority_hints__ that MUST matches to the onboarding system entity (trust anchor)
-    3. IPA code or VAT number, that determines whether the participant is public or private (String)
-        1. validators:
-            - TODO: fetch and verify the IPA code from the national registry of public services
-    4. public jwks (List[JSON])
-        1. validators:
-            - check if the jwks is public and not private (for sake!)
-            - check of the presence of kid claim
-            - check that the certificate is not expired
-            - check that the kid is unique and of the lenght of a minimum JWK thumbprint length
-    5. at least one administrative email contact (String)
-        1. validators:
-            - Email Field
-    6. at least one administrative email contact (String)
-        1. validators:
-            - Email Field
-    7. URL where the RP page shows the SPID and CIE authentication button
-        1. validators:
-            - Null, just for demo purpose
-    8. SPID/CIE authentication request trigger url at the onboarding system testing OP
-        1. validators:
-            - Null, just for demo purpose
-
-### SPID/CIE QaD tests
-
-Once the submission passes the initial checks the request is saved and a batch will start the
-Automatic checks on the latter new registered entity. These check covers
-
-- entity configuration:
-    - reachability
-    - signature validation
-    - best practices checks following AgID and IPZS OIDC Fed guidelines.
-
-- RP authz check following AgID and IPZS OIDC Fed guidelines.
-- trust marks forgery (if present for recurrent sample checks)
-
-The tests produces a json report.
-this report would be also available in HTML format.
-
-### Entity OnBoarding
-
-- all the required information are moved (copied) from the OnBoardin registration storage to the FederationDescendant storage
-- trust marks is automatically generated for the available profile, public or private
-- the onboarding staff in any time can add more profiles and trust marks  through the FederationDescendant back office panel
-- an entity configuration with trust marks and metadata policy applied, signed by the Trust Anchor of the onboarding system, is automatically created and published to its __Resolve Entity Statement__ endpoint.
-- an email is sent to the user to inform on the succesfull state of the onboarding and the final entity configuration
-
-
-### Considerations
-
-1. it would be necessary to "regulate" how the entities must expose a trigger url of the authn request.
-This would allow us to batch automate testing and obtain asynchronous reports and request states.
-Automatically a warning email would be sent to users.
-
-2. It would be useful to standardize a "quota" to avoid that "the usual primers"
-can make too many stupid requests all at once, that is, max N batch testing can be performed per day for a single applicant.
+To accredit a new entity point your browser to /onboarding/landing and click on the button `Register your entity`.
+![Onboarding landing](../images/onboarding_landing.png)
+
+The user accesses the submission form of a federation entity, fill in the following REQUIRED fields:
+
+1. Organization Name (String)
+2. unique identifier of the entity (url) of the instance in production/stage (URL)
+    1. validators:
+        - download of the Entity Configuration, a self-signed statement
+        - JWS signature validation
+        - structure analysis of the JSON (json-schema)
+        - presence and validation of the claim  __authority_hints__ that MUST matches to the onboarding system entity (trust anchor)
+3. TODO: IPA code or VAT number, that determines whether the participant is public or private (String)
+    1. validators:
+        - TODO: fetch and verify the IPA code from the national registry of public services
+4. public jwks (List[JSON])
+    1. validators:
+        - check if the jwks is public and not private (for sake!)
+        - check of the presence of kid claim
+        - check that the certificate is not expired
+        - check that the kid is unique and of the lenght of a minimum JWK thumbprint length
+5. TODO: at least one email contact (String)
+    1. validators:
+        - Email Field
+6. URL where the RP page shows the SPID and CIE authentication button
+    1. validators:
+        - Null, just for demo purpose
+7. TODO: SPID/CIE authentication request trigger url at the onboarding system testing OP
+    1. validators:
+        - Null, just for demo purpose
+
+![Registration entity](../images/fillregistration.png)
+
+After a successful submission the user is redirected to the list of registered entities.
+
+![entity list](../images/listentity.png)
+
+## The Federation Operator enables the entity as descendant
+
+- from the admin panel a staff user can enable the entity as a FederationDescendant
+- all the required information are moved (copied) from the OnBoarding registration 
+- the staff user assigns a Descendant Profile (trust mark) to the onboarded entity
+ (See the example in the documentation [CREATE_A_FEDERATION.md](../CREATE_A_FEDERATION.md#register-an-entity-as-descendant) )
+ see "Register an entity as descendant".
+- the staff user in any time can add more profiles and trust marks through the FederationDescendant back office panel
+- an entity configuration with trust marks and metadata policy applied, signed by the Trust Anchor of the onboarding system,
+ is now available to its __Resolve Entity Statement__ endpoint.
+
+To enable the onboarded entity, the Federation Operator points its web browser to the admin panel:
+
+- Click OnBoarding Registrations
+- Select the entity you want to enable 
+- Select action "enable descendant"
+- Submit
+
+![admin enable descendant](../images/enable_descendant.png)

docs/technical_specifications/PROVIDER.md

@@ -120,8 +120,8 @@ OIDCFED_PROVIDER_AUTH_CODE_MAX_AGE = getattr(
 Example
 ````
 OIDCFED_PROVIDER_PROFILES_DEFAULT_ACR = dict(
-    spid = AcrValuesSpid.l2.value,
-    cie = AcrValuesCie.l2.value
+    spid = AcrValues.l2.value,
+    cie = AcrValues.l2.value
 )
 ````
 
@@ -190,7 +190,7 @@ The UserInfo Endpoint returns an encrypthed jwt of the user claims.
 
 ### Login history page
 
-![OIDC Provider login history](docs/images/provider_login_history.png)
+![OIDC Provider login history](../images/provider_login_history.png)
 _The user can consult the history of his accesses and also can revoke the access tokens for selected RPs._
 
 ## SPID/CIE QAD and compliances tests

docs/technical_specifications/RELYING_PARTY.md

@@ -71,13 +71,13 @@ RP_PROVIDER_PROFILES = getattr(
     "RP_PROVIDER_PROFILES",
     {
         "spid": {
-            "authorization_request": {"acr_values": AcrValuesSpid.l2.value},
+            "authorization_request": {"acr_values": AcrValues.l2.value},
             "rp_metadata": RPMetadataSpid,
             "authn_response": AuthenticationResponse,
             "token_response": TokenResponse
         },
         "cie": {
-            "authorization_request": {"acr_values": AcrValuesCie.l2.value},
+            "authorization_request": {"acr_values": AcrValues.l2.value},
             "rp_metadata": RPMetadataCie,
             "authn_response": AuthenticationResponseCie,
             "token_response": TokenResponse
@@ -136,10 +136,7 @@ LOGIN_REDIRECT_URL = "/oidc/rp/echo_attributes"
 `OIDCFED_ACR_PROFILES`, acr value required to OP Authentication Endpoint
 Example
 ````
-    dict(
-        spid = AcrValuesSpid.l2.value,
-        cie = AcrValuesCie.l2.value
-     )
+`OIDCFED_ACR_PROFILES` = AcrValues.l2.value
 ````
 
 `RP_DEFAULT_PROVIDER_PROFILES`, default profile for OP
@@ -173,9 +170,9 @@ As inherited from [__spid_cie_oidc.entity__](docs/tecnhical_specifications/ENTIT
 
 This endpoint is the starting point for OIDC SPID/CIE authentication.
 
-the webpath is customizable in the `urls.py` file and by default it's
+The webpath is customizable in the `urls.py` file and by default it's
 configured [here](https://github.com/peppelinux/spid-cie-oidc-django/blob/main/spid_cie_oidc/relying_party/urls.py#L13) 
-and correspond to `spid_cie_oidc.relying_party.views.SpidCieOidcRpBeginView`.
+and correspond to `spid_cie_oidc.relying_party.views.rp_begin.SpidCieOidcRpBeginView`.
 
 The request is of type GET and supports the following parameters:
 
@@ -189,11 +186,42 @@ The request is of type GET and supports the following parameters:
 
 ### auth code redirect
 
-WiP
+This endpoint corresponds to the redirect uri where the auth code lands.
+
+The webpath is customizable in the `urls.py` file and by default it's
+configured [here](https://github.com/italia/spid-cie-oidc-django/blob/main/spid_cie_oidc/relying_party/urls.py#L19) 
+and correspond to `spid_cie_oidc.relying_party.views.rp_callback.SpidCieOidcRpCallbackView`.
+
+This endpoint accepts a request with this parameters:
+
+- __code__, REQUIRED. Authorization code
+- __state__, REQUIRED. State value enclosed in the authentication request
+- __iss__, REQUIRED only for cie. Issuer identifier of the OP
+
+This endpoint first call OP's token endpoint and, after getting the access token, it calls the OP's userinfo endpont.
+
+The request to token endpoint is of type POST and supports the following parameters:
+
+- __client_id__, REQUIRED. RP's client id
+- __client_assertion__, REQUIRED. JWT signed by using the private key of the RP
+- __client_assertion_type__, REQUIRED.
+- __code__, REQUIRED. Authorization code recived from authorization endpoint
+- __code_verifier__, REQUIRED
+- __grant_type__, REQUIRED. Specified the way RP gets the OIDC-Core tokens. It may be "authorization_code" or "refresh_token"
+- __refresh_token__, REQUIRED only if grant_type is refresh_token
+
+The request to userinfo endpoint is of type GET and access token is sent using the authorization header field.
+
 
 ### logout
 
-WiP
+This endpoint calls the token revocation endpoint of the op.
+
+The webpath is customizable in the `urls.py` file and by default it's
+configured [here](https://github.com/italia/spid-cie-oidc-django/blob/main/spid_cie_oidc/relying_party/urls.py#L36) 
+and correspond to `spid_cie_oidc.relying_party.views.rp_initiated_logout.oidc_rpinitiated_logout`.
+
+The request contains user to logout
 
 ## SPID/CIE QAD and compliances tests
 

examples/federation_authority/dumps/example.json

@@ -928,7 +928,6 @@
     "modified": "2022-03-01T17:49:22.983Z",
     "sub": "http://127.0.0.1:8000/oidc/op/",
     "trust_anchor": 107,
-    "type": "openid_provider",
     "exp": "2022-03-18T17:05:57Z",
     "iat": "2022-02-25T20:24:45.840Z",
     "chain": [
@@ -1261,6 +1260,8 @@
       ]
     ],
     "metadata": {
+        "openid_provider":
+    {
       "authorization_endpoint": "http://127.0.0.1:8000/oidc/op/authorization",
       "revocation_endpoint": "http://127.0.0.1:8000/oidc/op/revocation/",
       "id_token_encryption_alg_values_supported": [
@@ -1409,7 +1410,7 @@
         "ES384",
         "ES512"
       ]
-    },
+    }},
     "trust_marks": [],
     "parties_involved": [
       "http://127.0.0.1:8000/oidc/op/",
@@ -1429,7 +1430,6 @@
     "modified": "2022-02-26T19:53:36.683Z",
     "sub": "http://127.0.0.1:8000/oidc/rp/",
     "trust_anchor": 107,
-    "type": "openid_relying_party",
     "exp": "2022-03-18T17:05:57Z",
     "iat": "2022-02-26T19:53:36.683Z",
     "chain": [
@@ -1586,6 +1586,7 @@
       ]
     ],
     "metadata": {
+        "openid_relying_party": {
       "application_type": "web",
       "client_id": "http://127.0.0.1:8000/oidc/rp/",
       "client_registration_types": [
@@ -1617,7 +1618,7 @@
         "code"
       ],
       "subject_type": "pairwise"
-    },
+    }},
     "trust_marks": [],
     "parties_involved": [
       "http://127.0.0.1:8000/oidc/rp/",