From 61d3e5659ece58b3d422add8cbc1f000ae04da39 Mon Sep 17 00:00:00 2001 From: Bobby Rullo Date: Thu, 16 Jun 2016 10:07:13 -0700 Subject: [PATCH] Documentation * Start Documentation --- Documentation/clients.md | 58 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 Documentation/clients.md diff --git a/Documentation/clients.md b/Documentation/clients.md new file mode 100644 index 00000000..c034c540 --- /dev/null +++ b/Documentation/clients.md @@ -0,0 +1,58 @@ +# Clients (\*aka Relying Parties) + +## Configuration + +Clients can be created in two different ways: + +1. Through the [bootstrap API.](https://github.com/coreos/dex/tree/master/schema/adminschema) +1. Through the [Dynamic Registration API.](https://openid.net/specs/openid-connect-registration-1_0.html) That endpoint is hosted at `/registration` + + +## Dex Features + +Dex contains some client features that are not in any OIDC spec, but can be very useful. + +## Cross Client Authorization + +Inspired by Google's [Cross-Client Identity](https://developers.google.com/identity/protocols/CrossClientAuth), dex also has a way of having one client mint tokens for other ones, called Cross-client authorization. + +A client can only mint JWTs for another client if it is a *trusted peer* of that other client. Currently the only way to set trusted peers is the [bootstrap API](https://github.com/coreos/dex/tree/master/schema/adminschema). + +To initiate cross-client authentication, add one more scopes of the following form to the initial auth request: + +``` +audience:server:client_id:$OTHER_CLIENT_ID +``` + +OTHER\_CLIENT\_ID is the ID of the client for whom you want a token. You can have multiple such scopes in your request, one for each client whom you want the token to be valid for. + +After proceeding as normal with the rest of the auth flow, the resulting ID token will have an `aud` field of only the client ID(s) specified by the scope(s). Note that this means this JWT will not have the initiating client's ID in the `aud`; if you want the client's own ID in the `aud`, you must explicitly request it. A client is always implicitly a trusted client of itself. + +## Public Clients + +There are times when the confidentiality of the client secret cannot be guaranteed; native mobile clients and command-line tools are common examples. + +For these cases, *Public Clients* exist, which have certain restrictions: + +1. `http://localhost:$PORT` and `urn:ietf:wg:oauth:2.0:oob` are the only valid redirect URIs. + +1. A native client cannot obtain *client credentials* from the `/token` endpoint. + +These restrictions are aimed at mitigating certain attacks that can arise as the result of having a non-confidenital client secert. + +### Creating a public client. + +The only way to create a public client is through the [bootstrap API.](https://github.com/coreos/dex/tree/master/schema/adminschema) There are also special requirements for creating a public client: + +* A public client must have a client name specified. This is because client name is used in the creation of the client ID for public clients - in confidential clients, the name is dervied from a redirect URI, which public clients do not have. + +* Redirect URIs must not be specified; they are implicit. + +## Out-Of-Band Auth Flow + +For situations in which an app does not have access to a browser, the out-of-band (oob) flow exists. If you specify "urn:ietf:wg:oauth:2.0:oob" as a redirect URI, after authentication, instead of being redirected to the client site, the user is presented with the auth code in a text field, which they must copy and paste ("out of band" as it were) into their app. + + +\* In OpenID Connect a client is called a "Relying Party", but "client" seems to +be the more common ter, has been around longer and is present in paramter names +like "client_id" so we prefer it over "Relying Party" usually.