diff options
author | Schanzenbach, Martin <martin.schanzenbach@aisec.fraunhofer.de> | 2018-09-08 09:11:44 +0200 |
---|---|---|
committer | Schanzenbach, Martin <martin.schanzenbach@aisec.fraunhofer.de> | 2018-09-08 09:11:44 +0200 |
commit | 965845e9c3612f40c4761d843f807f613fd635e9 (patch) | |
tree | d242674fe4336329b318a17a8e8f01481a6aa61a /doc | |
parent | 15a3a09d508eed0f6d2612dd42d1b8ea720eb036 (diff) | |
download | gnunet-965845e9c3612f40c4761d843f807f613fd635e9.tar.gz gnunet-965845e9c3612f40c4761d843f807f613fd635e9.zip |
update docs for reclaim
Diffstat (limited to 'doc')
-rw-r--r-- | doc/documentation/chapters/user.texi | 119 |
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) | |||
1972 | If you want to revoke the access of a third party to your attributes you can execute: | 1972 | If 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 | ||
1978 | This will prevent the third party from accessing the attribute in the future. | 1978 | 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. | |||
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 | ||
1986 | TODO: 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 | |||
2005 | NGINX setup: | ||
2006 | @example | ||
2007 | server { | ||
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 | |||
2024 | This will expose the REST API of GNUnet at https://reclaim.id/api. | ||
2025 | |||
2026 | @node For Users | ||
2027 | @subsection For Users | ||
2028 | |||
2029 | To use the OpenID Connect Identity Provider as an end user, you must first intall the User Interface from TODOINSERTURLHERE. | ||
2030 | |||
2031 | Start the user interface using: | ||
2032 | |||
2033 | @example | ||
2034 | $ yarn run build --prod | ||
2035 | @end example | ||
2036 | |||
2037 | Now setup a webserver to serve the compiled website under "dist/". | ||
2038 | |||
2039 | Now we can add the user interfce to our NGINX configuraiton: | ||
2040 | |||
2041 | @example | ||
2042 | server { | ||
2043 | ... | ||
2044 | location / { | ||
2045 | proxy_pass http://<whereever you serve the UI>; | ||
2046 | } | ||
2047 | } | ||
2048 | @end example | ||
2049 | |||
2050 | You 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 | |||
2055 | To setup an OpenID Connect client, it must first be registered. | ||
2056 | In 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 | |||
2064 | You can now use the OpenID Connect REST endpoints exposed by reclaim. | ||
2065 | |||
2066 | To 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 | |||
2071 | You should choose a random number for the nonce parameter. The RP_KEY is the public key corresponding to the <rp_name> identity. | ||
2072 | |||
2073 | The redirect URI is the URI that you expect the user to return to within the OpenID Connect authorization code flow. | ||
2074 | |||
2075 | When the user returns to your redirect URI, you can exchange it for an access token at the OpenID Token endpoint. | ||
2076 | The 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 | |||
2082 | To 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 | |||
2091 | If successful, this will return a JSON object containing an ID Token and Access Token. | ||
2092 | The 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 |