aboutsummaryrefslogtreecommitdiff
path: root/doc
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
parent15a3a09d508eed0f6d2612dd42d1b8ea720eb036 (diff)
downloadgnunet-965845e9c3612f40c4761d843f807f613fd635e9.tar.gz
gnunet-965845e9c3612f40c4761d843f807f613fd635e9.zip
update docs for reclaim
Diffstat (limited to 'doc')
-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)
1972If you want to revoke the access of a third party to your attributes you can execute: 1972If you want to revoke the access of a third party to your attributes you can execute:
1973 1973
1974@example 1974@example
1975$ gnunet-idp -e "username" -R "ticket" 1975$ gnunet-reclaim -e "username" -R "ticket"
1976@end example 1976@end example
1977 1977
1978This will prevent the third party from accessing the attribute in the future. 1978This 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.
1983@node Using the OpenID-Connect IdP 1983@node Using the OpenID-Connect IdP
1984@subsection Using the OpenID-Connect IdP 1984@subsection Using the OpenID-Connect IdP
1985 1985
1986TODO: Document setup and REST endpoints 1986@node Preliminaries
1987@subsection Preliminaries
1988
1989@example
1990$ gnunet-identity -C id
1991$ openssl genrsa -des3 -passout pass:xxxx -out server.pass.key 2048
1992$ openssl rsa -passin pass:xxxx -in server.pass.key -out /etc/reclaim/reclaim.id.key
1993$ rm server.pass.key
1994$ openssl req -new -key /etc/reclaim/reclaim.id.key -out server.csr \
1995 -subj "/CN=reclaim.id.local"
1996$ openssl x509 -req -days 365 -in server.csr -signkey /etc/reclaim/reclaim.id.key -out /etc/reclaim/reclaim.id.crt
1997$ openssl x509 -in /etc/reclaim/reclaim.id.crt -out /etc/reclaim/reclaim.id.der -outform DER
1998$ HEXCERT=`xxd -p /etc/reclaim/reclaim.id.der | tr -d '\n'`
1999$ BOXVALUE="6 443 52 3 0 0 $HEXCERT"
2000$ gnunet-namestore -z id -a -n reclaim -t A -V "127.0.0.1" -e 1d -p
2001$ gnunet-namestore -z id -a -n reclaim -t LEHO -V "reclaim.id.local" -e 1d -p
2002$ gnunet-namestore -z id -a -n reclaim -t BOX -V "$BOXVALUE" -e 1d -p
2003@end example
2004
2005NGINX setup:
2006@example
2007server {
2008 listen 443;
2009 server_name reclaim.id.local;
2010 ssl on;
2011 ssl_certificate /etc/reclaim/reclaim.id.crt;
2012 ssl_certificate_key /etc/reclaim/reclaim.id.key;
2013 ssl_session_timeout 30m;
2014 ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
2015 ssl_session_cache shared:SSL:10m;
2016
2017 location /api {
2018 rewrite /api/(.*) /$1 break;
2019 proxy_pass http://127.0.0.1:7776;
2020 }
2021}
2022@end example
2023
2024This will expose the REST API of GNUnet at https://reclaim.id/api.
2025
2026@node For Users
2027@subsection For Users
2028
2029To use the OpenID Connect Identity Provider as an end user, you must first intall the User Interface from TODOINSERTURLHERE.
2030
2031Start the user interface using:
2032
2033@example
2034$ yarn run build --prod
2035@end example
2036
2037Now setup a webserver to serve the compiled website under "dist/".
2038
2039Now we can add the user interfce to our NGINX configuraiton:
2040
2041@example
2042server {
2043...
2044 location / {
2045 proxy_pass http://<whereever you serve the UI>;
2046 }
2047}
2048@end example
2049
2050You can thest your setup by accessing https://reclaim.id in your browser through the GNS proxy.
2051
2052@node For Service Providers
2053@subsection For Service Providers
2054
2055To setup an OpenID Connect client, it must first be registered.
2056In reclaim, client registration is done by creating a client identity and adding the redirect URI and client description into its namespace:
2057
2058@example
2059$ gnunet-identity -C <rp_name>
2060$ gnunet-namestore -z <rp_name> -a -n "+" -t RECLAIM_OIDC_REDIRECT -V <redirect_uri> -e 1d -p
2061$ gnunet-namestore -z <rp_name> -a -n "+" -t RECLAIM_OIDC_CLIENT -V "My OIDC Client" -e 1d -p
2062@end example
2063
2064You can now use the OpenID Connect REST endpoints exposed by reclaim.
2065
2066To request authorization from a user, your webapplication should initiate the OpenID Connect Authorization Flow like this:
2067@example
2068$ https://reclaim.id/openid/authorize?redirect_uri=<redirect_uri>&client_id=<RP_PKEY>&response_type=code&nonce=1234&scope=attribute1 attribute2 ...
2069@end example
2070
2071You should choose a random number for the nonce parameter. The RP_KEY is the public key corresponding to the <rp_name> identity.
2072
2073The redirect URI is the URI that you expect the user to return to within the OpenID Connect authorization code flow.
2074
2075When the user returns to your redirect URI, you can exchange it for an access token at the OpenID Token endpoint.
2076The authentication at the token endpoint is performed using the configured password (PSW) in the reclaim configuration (reclaim.conf). To set it execute:
2077
2078@example
2079$ gnunet-config -s reclaim-rest-plugin -o PSW -V <secret>
2080@end example
2081
2082To retrieve the access token, you can access the token endpoint through the proxy like this:
2083
2084@example
2085$ curl --socks5-hostname 127.0.0.1:7777 \
2086 -X POST \
2087 https://reclaim.id/openid/token?grant_type=authorization_code&redirect_uri=<redirect_uri>&code=<code> \
2088 -u <RP_KEY>:<secret>
2089@end example
2090
2091If successful, this will return a JSON object containing an ID Token and Access Token.
2092The Access Token can be used to access the OpenID Connect userinfo endpoint:
2093
2094@example
2095$ curl --socks5-hostname 127.0.0.1:7777 \
2096 -X POST \
2097 https://reclaim.id/openid/userinfo\
2098 -H 'Authorization: Bearer <access_token>'
2099@end example
2100
2101
1987 2102
1988@node Using the Virtual Public Network 2103@node Using the Virtual Public Network
1989@section Using the Virtual Public Network 2104@section Using the Virtual Public Network