Skip to content
This repository has been archived by the owner on Apr 13, 2022. It is now read-only.

Various Documentation improvements #27

Merged
merged 17 commits into from
Aug 12, 2019
Merged
Binary file added ApplicationWorkflow.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
34 changes: 31 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,8 @@ as most LDP-based systems. It is based on decentralized OAuth2/OpenID Connect.
- [Issuer Discovery From Link Header](#issuer-discovery-from-link-header)
- [Issuer Discovery From WebID Profile](#issuer-discovery-from-webid-profile)
* [Detailed Sign In Workflow Example](#detailed-sign-in-workflow-example)
* [Detailed Application Workflow Example](#detailed-application-workflow-example)
* [Workflow Example for Tokens Representing the App Itself](#detailed-app-centric-workflow)
* [Workflow Example for Tokens Representing a User via App Itesef](#detailed-user-app-centric-workflow)
* [Decentralized Authentication Glossary](#decentralized-authentication-glossary)

## Introduction
Expand All @@ -43,7 +44,8 @@ See also: [Motivation for WebID-OIDC](motivation.md).
### Benefits and Capabilities

* Fully decentralized cross-domain authentication (any peer node can serve as
an identity provider as well as a relying party to any other node)
an identity provider as well as a relying party to any other node) made possible by
[Proof of Posession (PoP) Tokens](https://tools.ietf.org/html/rfc7800).
* Builds on decades of real-world authentication industry experience
* Incorporates lessons from, and fixes to threat models of: SAML, OpenID and
OpenID 2, OAuth and OAuth 2. See, for example, [RFC 6819 - OAuth 2.0 Threat
Expand Down Expand Up @@ -99,6 +101,8 @@ WebID-OIDC makes the following changes to the base OpenID Connect protocol
* Specifies the [Authorized OIDC Issuer
Discovery](#authorized-oidc-issuer-discovery) process (used as part of
Provider Confirmation, and during Provider Selection steps).
* Utilizes [PoP tokens](https://tools.ietf.org/html/rfc7800) as a means to
access a wide array of resource providers.

It's also worth mentioning that while traditional OpenID Connect use cases are
concerned with retrieving user-related claims from [UserInfo
Expand Down Expand Up @@ -300,17 +304,41 @@ that profile, she would add the following triple to her profile:
<#me> solid:oidcIssuer <https://provider.com> .
```

## Securing tokens for multiple resource servers

#### The Problem

WebID-OIDC must deal with a number of RSs many of which the OP will not know about. OIDC defines the `aud` claim which defines the RSs for which a token can be used.

However, given Solid's use case, a token should be usable for any RS so the user may federate a query across multiple Pods, so the `aud`ience cannot be constrained. Yet, an unconstrained `aud`ience opens up the possibility of token stealing. In this case, a user sends a request to `evilPod.example`. The Pod returns the requested information, but now has the user's token and may pretend to be the user on any other Pod in the world.

#### The Solution

The solution employs [Proof of Possession (PoP) tokens](https://tools.ietf.org/html/rfc7800) changing the way the Bearer token is constructed:

1. A client application generates a short-lived public and private key.
2. The client generates a request `JWT` just as it would under normal OIDC with the addition of a `key` field containing the public key.
3. Authentication proceeds normally and yields a signed `id_token` where the `aud`ience is the client application (represented by the `origin` of the provided `redirect_uri`) and an additional field `cnf` is provided containing the client's public key.
4. Before sending requests to any RSs, the client generates a new signed JWT PoP token containing the RS's uri as the `aud`ience and an `id_token` feild containing the `id_token` provided by the OP.
5. When an RS receives the PoP token, it MUST reject any tokens containing a mismatched audience or a signature that is not associated with the public key in the `cnf` claim.

## Detailed Sign In Workflow Example

To walk through a more detailed example for WebID-OIDC login, refer to the
[Example WebID-OIDC Workflow](example-workflow.md) doc.

## Detailed Application Workflow Example
## Detailed App Centric Workflow

For a detailed example of how an application/agent can access resources in a
pod on behalf of a given user, refer to the
[Example Application OIDC Workflow](application-workflow.md).

## Detailed App User Centric Workflow

For a detailed example of how an application/agent can gain a token representing
the user via the application, refer to the
[Example Application User OIDC Workflow](application-user-workflow.md).

## Decentralized Authentication Glossary

In order to discuss decentralized authentication protocol details, it would be
Expand Down
Loading