Skip to content

Commit

Permalink
Merge pull request #33 from icebreakerone/preprod
Browse files Browse the repository at this point in the history
Changes to README - adds details about integrating with third part authentication platforms
  • Loading branch information
kipparker authored Jul 23, 2024
2 parents 10e218a + ce7a9f3 commit 41edcfb
Showing 1 changed file with 35 additions and 8 deletions.
43 changes: 35 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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:

Expand All @@ -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 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
Expand All @@ -103,10 +103,15 @@ 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 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

To show the response of the introspection endpoint, run:
Expand All @@ -115,7 +120,7 @@ To show the response of the introspection endpoint, run:
python -W ignore client.py introspect --token <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

Expand All @@ -125,7 +130,7 @@ To show the response of client side id_token decoding, run:
python -W ignore client.py id-token --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

Expand All @@ -135,10 +140,10 @@ python -W ignore client.py resource --token <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 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
Expand All @@ -150,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 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

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)

0 comments on commit 41edcfb

Please sign in to comment.