diff options
Diffstat (limited to 'doc/handbook/chapters/user.texi')
-rw-r--r-- | doc/handbook/chapters/user.texi | 140 |
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 | |||
2066 | As such, only access to updated data in the future can be revoked. | 2066 | As such, only access to updated data in the future can be revoked. |
2067 | This behaviour is _exactly the same_ as with other IdPs. | 2067 | This 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 | 2072 | There is an OpenID Connect API for use with reclaimID. |
2073 | * Setting up reclaim.id:: | 2073 | However, its use is quite complicated to setup. |
2074 | * For Users:: | 2074 | As a proof-of-concept, you can look at https://gitlab.com/reclaimid. |
2075 | * For Service Providers:: | ||
2076 | @end menu | ||
2077 | 2075 | ||
2078 | 2076 | In the PoC and by convention for reclaimID, the OpenID Connect Endpoints are | |
2079 | @node Setting up reclaim.id | 2077 | found at: |
2080 | @subsubsection Setting up reclaim.id | ||
2081 | 2078 | ||
2082 | @example | 2079 | @example |
2083 | $ gnunet-identity -C id | 2080 | http://api.reclaim/openid/authorize |
2084 | $ openssl genrsa -des3 -passout pass:xxxx -out server.pass.key 2048 | 2081 | http://api.reclaim/openid/token |
2085 | $ openssl rsa -passin pass:xxxx -in server.pass.key -out /etc/reclaim/reclaim.id.key | 2082 | http://api.reclaim/openid/userinfo |
2086 | $ rm server.pass.key | 2083 | http://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 | ||
2098 | NGINX setup: | 2086 | The token endpoint is protected using HTTP basic authentication. |
2099 | @example | 2087 | You can authenticate using any username and the password configured under: |
2100 | server @{ | ||
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 | |||
2117 | This will expose the REST API of GNUnet at https://reclaim.id/api. | ||
2118 | |||
2119 | @node For Users | ||
2120 | @subsubsection For Users | ||
2121 | |||
2122 | To use the OpenID Connect Identity Provider as an end user, you must first intall the User Interface from TODOINSERTURLHERE. | ||
2123 | |||
2124 | Start 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 | ||
2130 | Now setup a webserver to serve the compiled website under "dist/". | 2093 | The authorize endpoint is protected using a Cookie which can be obtained through |
2131 | 2094 | a request against the login endpoint. | |
2132 | Now we can add the user interfce to our NGINX configuraiton: | 2095 | This flow is meant to be used in the context of the OpenID Connect authorization |
2096 | flow to collect user consent interactively. | ||
2097 | Without a Cookie, the authorize endpoint redirects to a URI configured under: | ||
2133 | 2098 | ||
2134 | @example | 2099 | @example |
2135 | server @{ | 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 | ||
2143 | You can thest your setup by accessing https://reclaim.id in your browser through the GNS proxy. | 2103 | Our PoC includes a user interface (https://gitlab.com/reclaimid) which |
2144 | 2104 | integrates this process is an OpenID Connect compatible fashion. | |
2145 | @node For Service Providers | ||
2146 | @subsubsection For Service Providers | ||
2147 | 2105 | ||
2148 | To setup an OpenID Connect client, it must first be registered. | 2106 | The token endpoint is protected using OAuth2 and expects the grant |
2149 | In reclaim, client registration is done by creating a client identity and adding the redirect URI and client description into its namespace: | 2107 | which 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 | ||
2157 | You can now use the OpenID Connect REST endpoints exposed by reclaim. | 2109 | The userinfo endpoint is protected using OAuth2 and expects a bearer access |
2158 | 2110 | token which is retrieved from a token request. | |
2159 | To 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 | |||
2164 | You should choose a random number for the nonce parameter. The RP_KEY is the public key corresponding to the <rp_name> identity. | ||
2165 | |||
2166 | The redirect URI is the URI that you expect the user to return to within the OpenID Connect authorization code flow. | ||
2167 | |||
2168 | When the user returns to your redirect URI, you can exchange it for an access token at the OpenID Token endpoint. | ||
2169 | The 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 | |||
2175 | To 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 | ||
2184 | If successful, this will return a JSON object containing an ID Token and Access Token. | 2112 | In order to create and register a client you need to execute the following |
2185 | The Access Token can be used to access the OpenID Connect userinfo endpoint: | 2113 | steps: |
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 | ||
2121 | The client_id will be the public key of the client. | ||
2122 | As a redirect URI, you may use any globally unique DNS or GNS URI. | ||
2123 | The 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 |