aboutsummaryrefslogtreecommitdiff
path: root/doc/handbook/chapters/user.texi
diff options
context:
space:
mode:
Diffstat (limited to 'doc/handbook/chapters/user.texi')
-rw-r--r--doc/handbook/chapters/user.texi140
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
1991* Managing Attributes:: 1991* Managing Attributes::
1992* Sharing Attributes with Third Parties:: 1992* Sharing Attributes with Third Parties::
1993* Revoking Authorizations of Third Parties:: 1993* Revoking Authorizations of Third Parties::
1994* Using the OpenID-Connect IdP:: 1994* OpenID Connect::
1995@end menu 1995@end menu
1996 1996
1997@node Managing Attributes 1997@node Managing Attributes
@@ -2066,131 +2066,61 @@ Please note that if the third party has previously accessed the attribute, there
2066As such, only access to updated data in the future can be revoked. 2066As such, only access to updated data in the future can be revoked.
2067This behaviour is _exactly the same_ as with other IdPs. 2067This behaviour is _exactly the same_ as with other IdPs.
2068 2068
2069@node Using the OpenID-Connect IdP 2069@node OpenID Connect
2070@subsection Using the OpenID-Connect IdP 2070@subsection OpenID Connect
2071 2071
2072@menu 2072There is an OpenID Connect API for use with reclaimID.
2073* Setting up reclaim.id:: 2073However, its use is quite complicated to setup.
2074* For Users:: 2074As a proof-of-concept, you can look at https://gitlab.com/reclaimid.
2075* For Service Providers::
2076@end menu
2077 2075
2078 2076In the PoC and by convention for reclaimID, the OpenID Connect Endpoints are
2079@node Setting up reclaim.id 2077found at:
2080@subsubsection Setting up reclaim.id
2081 2078
2082@example 2079@example
2083$ gnunet-identity -C id 2080http://api.reclaim/openid/authorize
2084$ openssl genrsa -des3 -passout pass:xxxx -out server.pass.key 2048 2081http://api.reclaim/openid/token
2085$ openssl rsa -passin pass:xxxx -in server.pass.key -out /etc/reclaim/reclaim.id.key 2082http://api.reclaim/openid/userinfo
2086$ rm server.pass.key 2083http://api.reclaim/openid/login
2087$ openssl req -new -key /etc/reclaim/reclaim.id.key -out server.csr \
2088 -subj "/CN=reclaim.id.local"
2089$ openssl x509 -req -days 365 -in server.csr -signkey /etc/reclaim/reclaim.id.key -out /etc/reclaim/reclaim.id.crt
2090$ openssl x509 -in /etc/reclaim/reclaim.id.crt -out /etc/reclaim/reclaim.id.der -outform DER
2091$ HEXCERT=`xxd -p /etc/reclaim/reclaim.id.der | tr -d '\n'`
2092$ BOXVALUE="6 443 52 3 0 0 $HEXCERT"
2093$ gnunet-namestore -z id -a -n reclaim -t A -V "127.0.0.1" -e 1d -p
2094$ gnunet-namestore -z id -a -n reclaim -t LEHO -V "reclaim.id.local" -e 1d -p
2095$ gnunet-namestore -z id -a -n reclaim -t BOX -V "$BOXVALUE" -e 1d -p
2096@end example 2084@end example
2097 2085
2098NGINX setup: 2086The token endpoint is protected using HTTP basic authentication.
2099@example 2087You can authenticate using any username and the password configured under:
2100server @{
2101 listen 443;
2102 server_name reclaim.id.local;
2103 ssl on;
2104 ssl_certificate /etc/reclaim/reclaim.id.crt;
2105 ssl_certificate_key /etc/reclaim/reclaim.id.key;
2106 ssl_session_timeout 30m;
2107 ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
2108 ssl_session_cache shared:SSL:10m;
2109
2110 location /api @{
2111 rewrite /api/(.*) /$1 break;
2112 proxy_pass http://127.0.0.1:7776;
2113 @}
2114@}
2115@end example
2116
2117This will expose the REST API of GNUnet at https://reclaim.id/api.
2118
2119@node For Users
2120@subsubsection For Users
2121
2122To use the OpenID Connect Identity Provider as an end user, you must first intall the User Interface from TODOINSERTURLHERE.
2123
2124Start the user interface using:
2125 2088
2126@example 2089@example
2127$ yarn run build --prod 2090$ gnunet-config -s reclaim-rest-plugin -o PSW
2128@end example 2091@end example
2129 2092
2130Now setup a webserver to serve the compiled website under "dist/". 2093The authorize endpoint is protected using a Cookie which can be obtained through
2131 2094a request against the login endpoint.
2132Now we can add the user interfce to our NGINX configuraiton: 2095This flow is meant to be used in the context of the OpenID Connect authorization
2096flow to collect user consent interactively.
2097Without a Cookie, the authorize endpoint redirects to a URI configured under:
2133 2098
2134@example 2099@example
2135server @{ 2100$ gnunet-config -s reclaim-rest-plugin -o ADDRESS
2136...
2137 location / @{
2138 proxy_pass http://<whereever you serve the UI>;
2139 @}
2140@}
2141@end example 2101@end example
2142 2102
2143You can thest your setup by accessing https://reclaim.id in your browser through the GNS proxy. 2103Our PoC includes a user interface (https://gitlab.com/reclaimid) which
2144 2104integrates this process is an OpenID Connect compatible fashion.
2145@node For Service Providers
2146@subsubsection For Service Providers
2147 2105
2148To setup an OpenID Connect client, it must first be registered. 2106The token endpoint is protected using OAuth2 and expects the grant
2149In reclaim, client registration is done by creating a client identity and adding the redirect URI and client description into its namespace: 2107which is retrieved from the authorization endpoint according to the standard.
2150
2151@example
2152$ gnunet-identity -C <rp_name>
2153$ gnunet-namestore -z <rp_name> -a -n "+" -t RECLAIM_OIDC_REDIRECT -V <redirect_uri> -e 1d -p
2154$ gnunet-namestore -z <rp_name> -a -n "+" -t RECLAIM_OIDC_CLIENT -V "My OIDC Client" -e 1d -p
2155@end example
2156 2108
2157You can now use the OpenID Connect REST endpoints exposed by reclaim. 2109The userinfo endpoint is protected using OAuth2 and expects a bearer access
2158 2110token which is retrieved from a token request.
2159To request authorization from a user, your webapplication should initiate the OpenID Connect Authorization Flow like this:
2160@example
2161$ https://reclaim.id/openid/authorize?redirect_uri=<redirect_uri>&client_id=<RP_PKEY>&response_type=code&nonce=1234&scope=attribute1 attribute2 ...
2162@end example
2163
2164You should choose a random number for the nonce parameter. The RP_KEY is the public key corresponding to the <rp_name> identity.
2165
2166The redirect URI is the URI that you expect the user to return to within the OpenID Connect authorization code flow.
2167
2168When the user returns to your redirect URI, you can exchange it for an access token at the OpenID Token endpoint.
2169The authentication at the token endpoint is performed using the configured password (PSW) in the reclaim configuration (reclaim.conf). To set it execute:
2170
2171@example
2172$ gnunet-config -s reclaim-rest-plugin -o PSW -V <secret>
2173@end example
2174
2175To retrieve the access token, you can access the token endpoint through the proxy like this:
2176
2177@example
2178$ curl --socks5-hostname 127.0.0.1:7777 \
2179 -X POST \
2180 https://reclaim.id/openid/token?grant_type=authorization_code&redirect_uri=<redirect_uri>&code=<code> \
2181 -u <RP_KEY>:<secret>
2182@end example
2183 2111
2184If successful, this will return a JSON object containing an ID Token and Access Token. 2112In order to create and register a client you need to execute the following
2185The Access Token can be used to access the OpenID Connect userinfo endpoint: 2113steps:
2186 2114
2187@example 2115@example
2188$ curl --socks5-hostname 127.0.0.1:7777 \ 2116$ gnunet-identity -C <client_name>
2189 -X POST \ 2117$ gnunet-namestore -z <client_name> -a -n "@@" -t RECLAIM_OIDC_REDIRECT -V <redirect_uri> -e 1d -p
2190 https://reclaim.id/openid/userinfo\ 2118$ gnunet-namestore -z <client_name> -a -n "@@" -t RECLAIM_OIDC_CLIENT -V "My OIDC Client" -e 1d -p
2191 -H 'Authorization: Bearer <access_token>'
2192@end example 2119@end example
2193 2120
2121The client_id will be the public key of the client.
2122As a redirect URI, you may use any globally unique DNS or GNS URI.
2123The client description will be displayed to the user on authorization.
2194 2124
2195 2125
2196@node Using the Virtual Public Network 2126@node Using the Virtual Public Network