From 965845e9c3612f40c4761d843f807f613fd635e9 Mon Sep 17 00:00:00 2001 From: "Schanzenbach, Martin" Date: Sat, 8 Sep 2018 09:11:44 +0200 Subject: update docs for reclaim --- doc/documentation/chapters/user.texi | 119 ++++++++++++++++++++++++++++++++++- 1 file changed, 117 insertions(+), 2 deletions(-) (limited to 'doc/documentation') diff --git a/doc/documentation/chapters/user.texi b/doc/documentation/chapters/user.texi index 50b795197..9a5c41d34 100644 --- a/doc/documentation/chapters/user.texi +++ b/doc/documentation/chapters/user.texi @@ -1972,7 +1972,7 @@ $ gnunet-reclaim -e "friend" -T (TODO there is only a REST API for this ATM) If you want to revoke the access of a third party to your attributes you can execute: @example -$ gnunet-idp -e "username" -R "ticket" +$ gnunet-reclaim -e "username" -R "ticket" @end example This will prevent the third party from accessing the attribute in the future. @@ -1983,7 +1983,122 @@ This behaviour is _exactly the same_ as with other IdPs. @node Using the OpenID-Connect IdP @subsection Using the OpenID-Connect IdP -TODO: Document setup and REST endpoints +@node Preliminaries +@subsection Preliminaries + +@example +$ 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/reclaim.id.key +$ rm server.pass.key +$ openssl req -new -key /etc/reclaim/reclaim.id.key -out server.csr \ + -subj "/CN=reclaim.id.local" +$ openssl x509 -req -days 365 -in server.csr -signkey /etc/reclaim/reclaim.id.key -out /etc/reclaim/reclaim.id.crt +$ openssl x509 -in /etc/reclaim/reclaim.id.crt -out /etc/reclaim/reclaim.id.der -outform DER +$ HEXCERT=`xxd -p /etc/reclaim/reclaim.id.der | tr -d '\n'` +$ BOXVALUE="6 443 52 3 0 0 $HEXCERT" +$ gnunet-namestore -z id -a -n reclaim -t A -V "127.0.0.1" -e 1d -p +$ gnunet-namestore -z id -a -n reclaim -t LEHO -V "reclaim.id.local" -e 1d -p +$ gnunet-namestore -z id -a -n reclaim -t BOX -V "$BOXVALUE" -e 1d -p +@end example + +NGINX setup: +@example +server { + listen 443; + server_name reclaim.id.local; + ssl on; + ssl_certificate /etc/reclaim/reclaim.id.crt; + ssl_certificate_key /etc/reclaim/reclaim.id.key; + 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 http://127.0.0.1:7776; + } +} +@end example + +This will expose the REST API of GNUnet at https://reclaim.id/api. + +@node For Users +@subsection 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: + +@example +$ yarn run build --prod +@end example + +Now setup a webserver to serve the compiled website under "dist/". + +Now we can add the user interfce to our NGINX configuraiton: + +@example +server { +... + location / { + proxy_pass http://; + } +} +@end example + +You can thest your setup by accessing https://reclaim.id in your browser through the GNS proxy. + +@node For Service Providers +@subsection For Service Providers + +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: + +@example +$ gnunet-identity -C +$ gnunet-namestore -z -a -n "+" -t RECLAIM_OIDC_REDIRECT -V -e 1d -p +$ gnunet-namestore -z -a -n "+" -t RECLAIM_OIDC_CLIENT -V "My OIDC Client" -e 1d -p +@end example + +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: +@example +$ https://reclaim.id/openid/authorize?redirect_uri=&client_id=&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 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: + +@example +$ gnunet-config -s reclaim-rest-plugin -o PSW -V +@end example + +To retrieve the access token, you can access the token endpoint through the proxy like this: + +@example +$ curl --socks5-hostname 127.0.0.1:7777 \ + -X POST \ + https://reclaim.id/openid/token?grant_type=authorization_code&redirect_uri=&code= \ + -u : +@end example + +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: + +@example +$ curl --socks5-hostname 127.0.0.1:7777 \ + -X POST \ + https://reclaim.id/openid/userinfo\ + -H 'Authorization: Bearer ' +@end example + + @node Using the Virtual Public Network @section Using the Virtual Public Network -- cgit v1.2.3