From a0b0206588ec94c9359f1cad0247de1bf3cf79b3 Mon Sep 17 00:00:00 2001 From: Kip Parker Date: Tue, 16 Jul 2024 11:00:19 +0100 Subject: [PATCH 1/5] Add information about the client demo --- README.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 91fa41f..8dc2ba7 100644 --- a/README.md +++ b/README.md @@ -39,7 +39,7 @@ You will need to create a "certs" directory in the root of the project, and move ### Using client certificates -Most of the endpoints require a client certificate to be presented. As the directory service is not yet available, the contents of the certificate will not be checked with an external, so any valid certificate will be acceptable. The certificate **is** used to confirm identity, so the same one must be presented in all requests. +Most of the endpoints require a client certificate to be presented. As the directory service is not yet available, the contents of the certificate will not be checked with an external CA, so any valid certificate will be acceptable. The certificate **is** used to confirm identity, so the same one must be presented in all requests. ## Creating signing certificates @@ -107,6 +107,11 @@ Granting consent will redirect to our demo client application, with the authoris ![Redirect](docs/exchange.png) +### Client demo app + +As an alternative to the command line client, the authorisation flow can be completed in a browser at https://perseus-demo-accounting.ib1.org/start. Technical information such as the code verifier, token, and the contents of the introspected token are displayed +at each step. + ### Introspection To show the response of the introspection endpoint, run: From 680ac69906b72b7e050f27e2fb02e07a30e279da Mon Sep 17 00:00:00 2001 From: Kip Parker Date: Wed, 17 Jul 2024 17:41:57 +0100 Subject: [PATCH 2/5] Add details to readme regarding external user authentication and consent services --- README.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/README.md b/README.md index 8dc2ba7..c853017 100644 --- a/README.md +++ b/README.md @@ -155,6 +155,28 @@ Please contact IB1 for the Client ID and secret if you would like to test agains ![Scopes and redirecs](docs/scope-redirects.png) +### Authentication and consent + +For this demo, we have used Ory hydra user management platform to provide authentication and consent as part of the authorisation code flow. In production, data providers will be using existing user management systems. Whilst some user management platforms may provide Oauth2 endpoints as Ory Hydra does, in other cases the implementation may need to integrate separate Oauth and user management and consent services. Whilst it is outside of the scope this demo to anticipate all possible configurations, the following steps explain how a separate user management and consent service could be integrated, using Ory Oauth2 as an example. + +#### Flow steps for Ory Hydra with external user management and consent services + +1. The OAuth 2.0 Client initiates an Authorize Code flow, and the user is redirected to Ory OAuth2 + +2. Ory OAuth2, if unable to authenticate the user (no session cookie exists), redirects the user's user agent to the Login Provider's login page. The URL the user is redirected to looks like https://data-provider.com/oauth2-screens/login?login_challenge=1234.... + +3. The Login Provider, once the user has logged in, tells Ory OAuth2 some information about who the user is (for example the user's ID) and also that the login attempt was successful. This is done using a REST request which returns another redirect URL like https://{project-slug}.projects.oryapis.com/oauth2/auth?client_id=...&...&login_verifier=4321. + +4. The user's user agent follows the redirect and lands back at Ory OAuth2. Next, Ory OAuth2 redirects the user's user agent to the Consent Provider, hosted at - for example - https://example.org/oauth2-screens/consent?consent_challenge=4567... + +5. The Consent Provider shows a user interface which asks the user if they would like to grant the OAuth 2.0 Client the requested permissions ("OAuth 2.0 Scope"). + +6. The Consent Provider makes another REST request to Ory OAuth2 to let it know which permissions the user authorized, and if the user declined consent. In the response to that REST request, a redirect URL is included like https://{project-slug}.projects.oryapis.com/oauth2/auth?client_id=...&...&consent_verifier=7654.... + +7. The user's user agent follows that redirect. + +8. Now, the user has authenticated and authorized the application. Ory OAuth2 will run checks and if all is well issue access, refresh, and ID tokens. + ## FAPI Flow ![FAPI Flow diagram](docs/fapi-authlete-flow.png) From 1fa1653025d836f0c488a5ac4b112b1fb09440de Mon Sep 17 00:00:00 2001 From: Kip Parker Date: Wed, 17 Jul 2024 17:44:52 +0100 Subject: [PATCH 3/5] readme edit --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index c853017..b2d107a 100644 --- a/README.md +++ b/README.md @@ -157,7 +157,7 @@ Please contact IB1 for the Client ID and secret if you would like to test agains ### Authentication and consent -For this demo, we have used Ory hydra user management platform to provide authentication and consent as part of the authorisation code flow. In production, data providers will be using existing user management systems. Whilst some user management platforms may provide Oauth2 endpoints as Ory Hydra does, in other cases the implementation may need to integrate separate Oauth and user management and consent services. Whilst it is outside of the scope this demo to anticipate all possible configurations, the following steps explain how a separate user management and consent service could be integrated, using Ory Oauth2 as an example. +For this demo, we have used Ory hydra user management platform to provide authentication and consent as part of the authorisation code flow. In production, data providers will be using existing user management systems. Whilst some user management platforms may provide Oauth2 endpoints as Ory Hydra does, in other cases the implementation may need to integrate separate Oauth and user management and consent services. Whilst it is outside of the scope this demo to anticipate all possible configurations, the following steps explain how a separate user management and consent service might be integrated, using Ory Oauth2 as an example. #### Flow steps for Ory Hydra with external user management and consent services From f8fd22b0c7ec72d5b8c252f9e0afa407e50b6111 Mon Sep 17 00:00:00 2001 From: Kip Parker Date: Wed, 17 Jul 2024 17:46:11 +0100 Subject: [PATCH 4/5] Standardise on american zeds --- README.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index b2d107a..4bb258f 100644 --- a/README.md +++ b/README.md @@ -68,7 +68,7 @@ In this simple implementation, the request is stored in a redis instance, using ## Testing the API with client.py -client.py can be used to test authorisation code flow, introspection, id_token decoding and retrieving data from the resource URL. +client.py can be used to test authorization code flow, introspection, id_token decoding and retrieving data from the resource URL. Four commands are available, and are run using: @@ -80,7 +80,7 @@ nb. The optional `-W ignore` switch suppresses multiple warnings about the self- ### Auth -Running `client.py auth` will perform the initial steps in the authorisation code flow, outputting a URL that will open the UI to log in and confirm consent. The PKCE code verifier will also be in the output, which will be needed after the redirect +Running `client.py auth` will perform the initial steps in the authorization code flow, outputting a URL that will open the UI to log in and confirm consent. The PKCE code verifier will also be in the output, which will be needed after the redirect ```bash python -W ignore client.py auth @@ -103,13 +103,13 @@ Opening the redirect url will present you with the default Ory Hydra log in/ sig ![Consent screen](docs/consent.png) -Granting consent will redirect to our demo client application, with the authorisation code appended to the url. The authorisation code can be exchanged for an access token by adding the code_verifier value to the form and submitting: +Granting consent will redirect to our demo client application, with the authorization code appended to the url. The authorization code can be exchanged for an access token by adding the code_verifier value to the form and submitting: ![Redirect](docs/exchange.png) ### Client demo app -As an alternative to the command line client, the authorisation flow can be completed in a browser at https://perseus-demo-accounting.ib1.org/start. Technical information such as the code verifier, token, and the contents of the introspected token are displayed +As an alternative to the command line client, the authorization flow can be completed in a browser at https://perseus-demo-accounting.ib1.org/start. Technical information such as the code verifier, token, and the contents of the introspected token are displayed at each step. ### Introspection @@ -120,7 +120,7 @@ To show the response of the introspection endpoint, run: python -W ignore client.py introspect --token ``` -with token being the `token` value obtained from authorisation code flow +with token being the `token` value obtained from authorization code flow ### Client side id_token decoding @@ -130,7 +130,7 @@ To show the response of client side id_token decoding, run: python -W ignore client.py id-token --token ``` -with token being the `id_token` value obtained from authorisation code flow +with token being the `id_token` value obtained from authorization code flow ### Retrieve data from protected endpoint @@ -143,7 +143,7 @@ python -W ignore client.py resource --token Please contact IB1 for the Client ID and secret if you would like to test against our demo Ory account. Alternatively you can set up a free developer account and create an Oauth2 client with your own details. The client should have: - Authentication method set to None -- Grant types Authorisation Code and Refresh Token +- Grant types authorization Code and Refresh Token - Response types Code and ID Token - Access Token Type jwt - Scopes profile and offline_access @@ -157,7 +157,7 @@ Please contact IB1 for the Client ID and secret if you would like to test agains ### Authentication and consent -For this demo, we have used Ory hydra user management platform to provide authentication and consent as part of the authorisation code flow. In production, data providers will be using existing user management systems. Whilst some user management platforms may provide Oauth2 endpoints as Ory Hydra does, in other cases the implementation may need to integrate separate Oauth and user management and consent services. Whilst it is outside of the scope this demo to anticipate all possible configurations, the following steps explain how a separate user management and consent service might be integrated, using Ory Oauth2 as an example. +For this demo, we have used Ory hydra user management platform to provide authentication and consent as part of the authorization code flow. In production, data providers will be using existing user management systems. Whilst some user management platforms may provide Oauth2 endpoints as Ory Hydra does, in other cases the implementation may need to integrate separate Oauth and user management and consent services. Whilst it is outside of the scope this demo to anticipate all possible configurations, the following steps explain how a separate user management and consent service might be integrated, using Ory Oauth2 as an example. #### Flow steps for Ory Hydra with external user management and consent services From ce7a9f325780526a0e1d55ad522287bf84cd6477 Mon Sep 17 00:00:00 2001 From: Kip Parker Date: Tue, 23 Jul 2024 13:20:44 +0100 Subject: [PATCH 5/5] Chris' corrections --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 4bb258f..35da6d8 100644 --- a/README.md +++ b/README.md @@ -80,7 +80,7 @@ nb. The optional `-W ignore` switch suppresses multiple warnings about the self- ### Auth -Running `client.py auth` will perform the initial steps in the authorization code flow, outputting a URL that will open the UI to log in and confirm consent. The PKCE code verifier will also be in the output, which will be needed after the redirect +Running `client.py auth` will perform the initial steps in the authorization code flow, outputting the URL of a UI to log in and confirm consent. The PKCE code verifier will also be in the output, which will be needed after the redirect ```bash python -W ignore client.py auth @@ -140,7 +140,7 @@ python -W ignore client.py resource --token ## Ory Hydra -Please contact IB1 for the Client ID and secret if you would like to test against our demo Ory account. Alternatively you can set up a free developer account and create an Oauth2 client with your own details. The client should have: +Please contact [tf-ops@icebreakerone.org](mailto:tf-ops@icebreakerone.org) for the Client ID and secret if you would like to test against our demo Ory account. Alternatively you can set up a free developer account and create an OAuth2 client with your own details. The client should have: - Authentication method set to None - Grant types authorization Code and Refresh Token @@ -157,7 +157,7 @@ Please contact IB1 for the Client ID and secret if you would like to test agains ### Authentication and consent -For this demo, we have used Ory hydra user management platform to provide authentication and consent as part of the authorization code flow. In production, data providers will be using existing user management systems. Whilst some user management platforms may provide Oauth2 endpoints as Ory Hydra does, in other cases the implementation may need to integrate separate Oauth and user management and consent services. Whilst it is outside of the scope this demo to anticipate all possible configurations, the following steps explain how a separate user management and consent service might be integrated, using Ory Oauth2 as an example. +For this demo, we have used Ory hydra user management platform to provide authentication and consent as part of the authorization code flow. In production, data providers will be using existing user management systems. Whilst some user management platforms may provide OAuth2 endpoints as Ory Hydra does, in other cases the implementation may need to integrate separate OAuth and user management and consent services. Whilst it is outside of the scope this demo to anticipate all possible configurations, the following steps explain how a separate user management and consent service might be integrated, using Ory OAuth2 as an example. #### Flow steps for Ory Hydra with external user management and consent services