summaryrefslogtreecommitdiff
path: root/doc/documentation
diff options
context:
space:
mode:
authorSchanzenbach, Martin <martin.schanzenbach@aisec.fraunhofer.de>2018-09-08 09:11:44 +0200
committerSchanzenbach, Martin <martin.schanzenbach@aisec.fraunhofer.de>2018-09-08 09:11:44 +0200
commit965845e9c3612f40c4761d843f807f613fd635e9 (patch)
treed242674fe4336329b318a17a8e8f01481a6aa61a /doc/documentation
parent15a3a09d508eed0f6d2612dd42d1b8ea720eb036 (diff)
update docs for reclaim
Diffstat (limited to 'doc/documentation')
-rw-r--r--doc/documentation/chapters/user.texi119
1 files changed, 117 insertions, 2 deletions
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://<whereever you serve the UI>;
+ }
+}
+@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 <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
+
+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=<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:
+
+@example
+$ 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:
+
+@example
+$ curl --socks5-hostname 127.0.0.1:7777 \
+ -X POST \
+ https://reclaim.id/openid/token?grant_type=authorization_code&redirect_uri=<redirect_uri>&code=<code> \
+ -u <RP_KEY>:<secret>
+@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 <access_token>'
+@end example
+
+
@node Using the Virtual Public Network
@section Using the Virtual Public Network