diff --git a/docs/configuration/authentication/digid.rst b/docs/configuration/authentication/digid.rst index 3790d390b0..04bc1f1621 100644 --- a/docs/configuration/authentication/digid.rst +++ b/docs/configuration/authentication/digid.rst @@ -4,11 +4,6 @@ DigiD authentication ==================== -.. warning:: - - This plugin cannot be configured via the admin interface and requires an - update of the Open Forms installation. - Some forms can require authentication. Open Forms supports authentication using `DigiD`_. Access to DigiD can typically be obtained via `Logius`_. @@ -16,10 +11,52 @@ Using DigiD for authentication will provide the BSN (social security number) of the authenticated person to the form context. Using the BSN, certain fields can be :ref:`prefilled ` with relevant personal data. -.. note:: +Steps to request access to a DigiD environment +============================================== + +The high-level overview of steps you need to perform are described here. The following +sections provide more details. + +1. Read the requirements for getting access to DigiD on the `Logius`_ website. + There are several steps that need to be taken on your end that are not + covered here. + +2. Request a `PKIoverheid Private Services Server G1`_ certificate at your + `PKIO SSL certificate supplier`_. This is required for backchannel + communication with Logius (if you already have one for Open Forms, it can be + re-used). + + You can :ref:`prepare the certificates ` + from the admin interface. + +3. Send the following information to your Open Forms supplier in a secure way: + + * Public and private certificate (obtained in step 2, private certificate is already + present if you generated the CSR via the admin) + * Desired service name (for example: "Digitaal Loket") shown in DigiD + * Privacy policy URL of your main website + + Your Open Forms supplier will install the certificates in Open Forms, + generate some XML metadata files and sends these back to you. + +4. Request access to the pre-production environment on the `Logius`_ website + and follow the steps there. To request access, you will need the following + information: + + * **Zekerheidsniveau**: ``Midden`` + * **DigiD eenmalig inloggen**: ``Nee`` + * **URL aansluiting**: *The Open Forms domain, for example: https://forms.organization.com* + * **Webdienstnaam**: *The same desired service name as given in step 3* + * **Metadata**: *The XML-file provided to you by your Open Forms supplier (see previous section)* + * **Publieke deel PKIO-certificaat**: *The public certificate obtained in step 2* - Open Forms currently only supports security level (betrouwbaarheidsniveau) - "Midden". + As technical contact, you should provide your Open Forms supplier contact + details. + +.. tip:: + + You can specify a different security level (betrouwbaarheidsniveau) on a per-form + basis. ============= ================================================================= DigiD SAML2 AuthnContextClassRef element @@ -32,85 +69,102 @@ be :ref:`prefilled ` with relevant personal data. Source: `Logius `__ -Obtaining the Service Provider metadata -======================================= -Once access to a DigiD (pre-)production environment has been obtained, Open-Forms has to be configured. -This can be done by navigating to **Configuration** > **DigiD configuration**. +.. _configuration_authentication_digid_prepare_certificates: -#. **Key pair**: Upload the `PKIoverheid Private Services Server G1`_ and the private key (see point 2 of the next section). - The certificate will be used in the metadata that will be generated, and the private key will be used to sign the metadata. +Preparing the certificates +========================== -#. **Metadata file(XML) URL**: This is the URL where the metadata (XML) for the Identity Provider can be obtained. - The entity ID (of the identity provider) will automatically be extracted from the XML. +To request a *PKIoverheid certificate*, you need a private key and a certificate signing +request. You can generate these using ``openssl`` or other utilities, or use the built-in +signing requests in the admin interface. -#. **Entity ID**: This is the entity ID of Open-Forms. For DigiD, this can be the URL where Open-Forms is deployed, for - example ``https://openforms.test.nl``. +.. tip:: Creating the signing requests from the admin ensures the private key never + leaves the server, lessening the chances that it is accidentally leaked. -#. **Base URL**: This is the URL where Open-Forms is deployed. +**Using the admin interface** -#. **Resolve artifact binding content type**: This is the the value of the ``Content-Type`` header for the resolve artifact binding request. - Modern brokers typically expect ``text/xml`` while ``application/soap+xml`` is considered legacy. +#. Navigate to the **Admin**. +#. In the menu, navigate to **Configuration** > **Signing requests**. +#. In the top right of the page, click the **Add signing request** button. +#. Enter the desired fields - the information will be included in the signing request. + Consult with your certificate supplier which data is required and what values are + expected. +#. Click **Save** to persist the changes. The page is reloaded. +#. Under the section *Signing request (CSR)*, click the **Download CSR** link. -#. **Want assertions signed**: This should be **checked**. +Now, send the downloaded CSR to your certificate supplier and wait for them to verify +it and provide you with the matching certificate. This can take some time (hours to +days), as verification is often a manual process. -#. **Signature algorithm**: Select ``RSA_SHA1``. +Once you have received the certificate, navigate back to the admin and locate your +signing request. -#. **Digest algorithm**: Select ``SHA1``. +#. Edit the original signing request record in the admin. +#. Navigate to the *Upload signed certificate* section. +#. Upload the certificate provided by the certificate supplier. +#. Save the changes. -#. **Service name**: This is the name of the service for which authentication is needed. +If everything is valid, the private key + public cerificate pair is now available and +almost ready for use. You can verify it in the admin via **Configuration** > +**Certificates**. -#. **Service description**: A description of the service for which authentication is needed. +You can now proceed to :ref:`configuration_authentication_digid_metadata`. -#. **Requested attributes**: What attributes are expected to be returned by DigiD after authentication. This should be ``["bsn"]``. +.. _configuration_authentication_digid_metadata: -#. **Organisation details**: Telephone/e-mail contacts of the organisation responsible for the service requiring DigiD authentication. +Generating the Service Provider metadata +======================================== -Click then on **Save and continue editing** to persist the configuration changes. +In the admin environment we can configure the DigiD identity provider and select our +required certificate pair(s). Once this is done, we can generate our service provider +metadata. -On the top right corner of the configuration page, there is a button **View SAML metadata**. Click on this button and save this metadata. -The metadata needs to be sent to the broker to obtain access to a (pre-)production environment. +#. Navigate to the **Admin**. +#. In the menu, navigate to **Configuration** > **DigiD configuration**. +#. Under the *X.509 Certificate* section, click the **Manage (number)** link. +#. Click the **Add Digid/eHerkenning certificate** button in the top right of the page. +#. For **Config type**, select "DigiD". +#. For **Certificate**, click the search icon and select the certificate pair that was + created earlier (in the :ref:`configuration_authentication_digid_prepare_certificates` + section). +#. **Save** the configuration and close the window/tab. +#. Continue on the *DigiD configuration* page. +#. In the section *Identity provider*, enter the identity provider **metadata file (XML) URL**. + E.g. for pre-production: ``https://was-preprod1.digid.nl/saml/idp/metadata``. The + metadata will be retrieved and processed. +#. Next, in the section *SAML configuration*, enter the fields: -.. note:: + * **Entity ID**: This is the entity ID of Open-Forms. For DigiD, this can be the URL + where Open-Forms is deployed, for example ``https://openforms.test.nl``. + * **Base URL**: Enter the URL where Open-Forms is deployed (and publicly accessible). + * **Resolve artifact binding content type**: select ``text/xml`` unless you're using + old/legacy brokers or are instructed to pick ``application/soap+xml``. + * **Want assertions signed**: This should be **checked**. + * **Signature algorithm**: Select ``RSA_SHA1``. + * **Digest algorithm**: Select ``SHA1``. - Any changes to the configuration in the Admin page cause a change in the metadata. The updated metadata must be then - sent to the broker again for the changes to be effective. +#. Continue to the section *Service details* and fill out the fields: + * **Service name**: This is the name of the service for which authentication is needed. + * **Service description**: A description of the service for which authentication is needed. + * **Requested attributes**: What attributes are expected to be returned by DigiD + after authentication. This should be ``["bsn"]``. + * Leave **Single logout** unchecked, as we currently don't support this. -Steps to request access to a DigiD environment -============================================== - -1. Read the requirements for getting access to DigiD on the `Logius`_ website. - There are several steps that need to be taken on your end that are not - covered here. +#. Finally, you should provide some *organization details* - provide the telephone/e-mail + contacts of the organisation responsible for the service requiring DigiD authentication. -2. Request a `PKIoverheid Private Services Server G1`_ certificate at your - `PKIO SSL certificate supplier`_. This is required for backchannel - communication with Logius (if you already have one for Open Forms, it can be - re-used). +Click on **Save and continue editing** to persist the configuration changes. -3. Send the following information to your Open Forms supplier in a secure way: +On the top right corner of the configuration page, there is a button +**View SAML metadata (XML)**. Click this button to download the metadata. The metadata +needs to be sent to the broker to obtain access to a (pre-)production environment. - * Public and private certificate (obtained in step 2) - * Desired service name (for example: "Digitaal Loket") shown in DigiD - * Privacy policy URL of your main website - - Your Open Forms supplier will install the certificates in Open Forms, - generate some XML metadata files and sends these back to you. - -4. Request access to the pre-production environment on the `Logius`_ website - and follow the steps there. To request access, you will need the following - information: - - * **Zekerheidsniveau**: ``Midden`` - * **DigiD eenmalig inloggen**: ``Nee`` - * **URL aansluiting**: *The Open Forms domain, for example: https://forms.organization.com* - * **Webdienstnaam**: *The same desired service name as given in step 3* - * **Metadata**: *The XML-file provided to you by your Open Forms supplier (see previous section)* - * **Publieke deel PKIO-certificaat**: *The public certificate obtained in step 2* +.. note:: - As technical contact, you should provide your Open Forms supplier contact - details. + Any changes to the configuration in the Admin page cause a change in the metadata. + The updated metadata must be then sent to the broker again for the changes to be effective. .. _`PKIoverheid Private Services Server G1`: https://cert.pkioverheid.nl/ .. _`PKIO SSL certificate supplier`: https://www.logius.nl/domeinen/toegang/pkioverheidcertificaat-aanvragen diff --git a/docs/configuration/authentication/eherkenning_eidas.rst b/docs/configuration/authentication/eherkenning_eidas.rst index fdca0a0903..1391830501 100644 --- a/docs/configuration/authentication/eherkenning_eidas.rst +++ b/docs/configuration/authentication/eherkenning_eidas.rst @@ -4,11 +4,6 @@ eHerkenning and eIDAS authentication ==================================== -.. warning:: - - This plugin cannot be configured via the admin interface and requires an - update of the Open Forms installation. - Some forms can require authentication. Open Forms supports authentication using `eHerkenning`_ and `eIDAS`_. To use eHerkenning and/or eIDAS, you must have a contract with an `approved eHerkenning supplier`_.