path: root/doc/handbook
diff options
authorSchanzenbach, Martin <>2019-02-23 19:36:33 +0100
committerSchanzenbach, Martin <>2019-02-23 19:36:33 +0100
commitb57459d70dc56b7f0e5c50f86e33a1c40600f073 (patch)
treeec3d9eadd1b415ba56391f187d35a6c8108d53c6 /doc/handbook
parentad2d3029a06795dd72b32e5613e58dd1d3e0404f (diff)
update reclaimID docs a bit
Diffstat (limited to 'doc/handbook')
1 files changed, 35 insertions, 105 deletions
diff --git a/doc/handbook/chapters/user.texi b/doc/handbook/chapters/user.texi
index 3f99be7a8..f6fb2424e 100644
--- a/doc/handbook/chapters/user.texi
+++ b/doc/handbook/chapters/user.texi
@@ -1991,7 +1991,7 @@ Like other IdPs, reclaimID features an (optional) OpenID-Connect 1.0-compliant p
* Managing Attributes::
* Sharing Attributes with Third Parties::
* Revoking Authorizations of Third Parties::
-* Using the OpenID-Connect IdP::
+* OpenID Connect::
@end menu
@node Managing Attributes
@@ -2066,131 +2066,61 @@ Please note that if the third party has previously accessed the attribute, there
As such, only access to updated data in the future can be revoked.
This behaviour is _exactly the same_ as with other IdPs.
-@node Using the OpenID-Connect IdP
-@subsection Using the OpenID-Connect IdP
+@node OpenID Connect
+@subsection OpenID Connect
-* Setting up
-* For Users::
-* For Service Providers::
-@end menu
+There is an OpenID Connect API for use with reclaimID.
+However, its use is quite complicated to setup.
+As a proof-of-concept, you can look at
-@node Setting up
-@subsubsection Setting up
+In the PoC and by convention for reclaimID, the OpenID Connect Endpoints are
+found at:
-$ gnunet-identity -C id
-$ openssl genrsa -des3 -passout pass:xxxx -out server.pass.key 2048
-$ openssl rsa -passin pass:xxxx -in server.pass.key -out /etc/reclaim/
-$ rm server.pass.key
-$ openssl req -new -key /etc/reclaim/ -out server.csr \
- -subj "/"
-$ openssl x509 -req -days 365 -in server.csr -signkey /etc/reclaim/ -out /etc/reclaim/
-$ openssl x509 -in /etc/reclaim/ -out /etc/reclaim/ -outform DER
-$ HEXCERT=`xxd -p /etc/reclaim/ | tr -d '\n'`
-$ BOXVALUE="6 443 52 3 0 0 $HEXCERT"
-$ gnunet-namestore -z id -a -n reclaim -t A -V "" -e 1d -p
-$ gnunet-namestore -z id -a -n reclaim -t LEHO -V "" -e 1d -p
-$ gnunet-namestore -z id -a -n reclaim -t BOX -V "$BOXVALUE" -e 1d -p
@end example
-NGINX setup:
-server @{
- listen 443;
- server_name;
- ssl on;
- ssl_certificate /etc/reclaim/;
- ssl_certificate_key /etc/reclaim/;
- ssl_session_timeout 30m;
- ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
- ssl_session_cache shared:SSL:10m;
- location /api @{
- rewrite /api/(.*) /$1 break;
- proxy_pass;
- @}
-@end example
-This will expose the REST API of GNUnet at
-@node For Users
-@subsubsection For Users
-To use the OpenID Connect Identity Provider as an end user, you must first intall the User Interface from TODOINSERTURLHERE.
-Start the user interface using:
+The token endpoint is protected using HTTP basic authentication.
+You can authenticate using any username and the password configured under:
-$ yarn run build --prod
+$ gnunet-config -s reclaim-rest-plugin -o PSW
@end example
-Now setup a webserver to serve the compiled website under "dist/".
-Now we can add the user interfce to our NGINX configuraiton:
+The authorize endpoint is protected using a Cookie which can be obtained through
+a request against the login endpoint.
+This flow is meant to be used in the context of the OpenID Connect authorization
+flow to collect user consent interactively.
+Without a Cookie, the authorize endpoint redirects to a URI configured under:
-server @{
- location / @{
- proxy_pass http://<whereever you serve the UI>;
- @}
+$ gnunet-config -s reclaim-rest-plugin -o ADDRESS
@end example
-You can thest your setup by accessing in your browser through the GNS proxy.
-@node For Service Providers
-@subsubsection For Service Providers
+Our PoC includes a user interface ( which
+integrates this process is an OpenID Connect compatible fashion.
-To setup an OpenID Connect client, it must first be registered.
-In reclaim, client registration is done by creating a client identity and adding the redirect URI and client description into its namespace:
-$ gnunet-identity -C <rp_name>
-$ gnunet-namestore -z <rp_name> -a -n "+" -t RECLAIM_OIDC_REDIRECT -V <redirect_uri> -e 1d -p
-$ gnunet-namestore -z <rp_name> -a -n "+" -t RECLAIM_OIDC_CLIENT -V "My OIDC Client" -e 1d -p
-@end example
+The token endpoint is protected using OAuth2 and expects the grant
+which is retrieved from the authorization endpoint according to the standard.
-You can now use the OpenID Connect REST endpoints exposed by reclaim.
-To request authorization from a user, your webapplication should initiate the OpenID Connect Authorization Flow like this:
-$<redirect_uri>&client_id=<RP_PKEY>&response_type=code&nonce=1234&scope=attribute1 attribute2 ...
-@end example
-You should choose a random number for the nonce parameter. The RP_KEY is the public key corresponding to the <rp_name> identity.
-The redirect URI is the URI that you expect the user to return to within the OpenID Connect authorization code flow.
-When the user returns to your redirect URI, you can exchange it for an access token at the OpenID Token endpoint.
-The authentication at the token endpoint is performed using the configured password (PSW) in the reclaim configuration (reclaim.conf). To set it execute:
-$ gnunet-config -s reclaim-rest-plugin -o PSW -V <secret>
-@end example
-To retrieve the access token, you can access the token endpoint through the proxy like this:
-$ curl --socks5-hostname \
- -X POST \
-<redirect_uri>&code=<code> \
- -u <RP_KEY>:<secret>
-@end example
+The userinfo endpoint is protected using OAuth2 and expects a bearer access
+token which is retrieved from a token request.
-If successful, this will return a JSON object containing an ID Token and Access Token.
-The Access Token can be used to access the OpenID Connect userinfo endpoint:
+In order to create and register a client you need to execute the following
-$ curl --socks5-hostname \
- -X POST \
- -H 'Authorization: Bearer <access_token>'
+$ gnunet-identity -C <client_name>
+$ gnunet-namestore -z <client_name> -a -n "@@" -t RECLAIM_OIDC_REDIRECT -V <redirect_uri> -e 1d -p
+$ gnunet-namestore -z <client_name> -a -n "@@" -t RECLAIM_OIDC_CLIENT -V "My OIDC Client" -e 1d -p
@end example
+The client_id will be the public key of the client.
+As a redirect URI, you may use any globally unique DNS or GNS URI.
+The client description will be displayed to the user on authorization.
@node Using the Virtual Public Network