docs: Auth Server Guide / id_token (#3465)

Initial checkin for Auth Server / Tokens / id_token. Small fixes to sessions page.
JanssenProject · Dec 30, 2022 · f0e98e8 · f0e98e8
1 parent 1001dd0
commit f0e98e8
Show file tree

Hide file tree

Showing 2 changed files with 68 additions and 4 deletions.
diff --git a/docs/admin/auth-server/session-management/multiple-sessions-one-browser.md b/docs/admin/auth-server/session-management/multiple-sessions-one-browser.md
@@ -20,16 +20,15 @@ session_id: de510ab6-b06c-4393-86d8-12a7c501aafe
 current_sessions: ["de510ab6-b06c-4393-86d8-12a7c501aafe", "c691e83d-eb1b-41f0-b453-fab905681b5b"]
 ```
 
-An RP trigger Auth Server's built in Account Chooser feature by sending an
+An RP can trigger Auth Server's built in Account Chooser feature by sending an
 [OpenID Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest) with the parameter `prompt=select_account`. In
 this case, Auth Server renders the default page:
 `/opt/jans/jetty/jans-auth/custom/pages/selectAccount.xhtml`
 
 This page iterates `current_sessions` and enables the person
 to login as a different account, for example:
 
-![Sample Select Account login page screenshot](../../assets/auth_server_sessions_selectAccount.png)
+![Sample Select Account login page screenshot](../../../../assets/auth_server_sessions_selectAccount.png)
 
 You can override this page if you place a `selectAccount.xhtml` in
 `custom/pages`.
-
diff --git a/docs/admin/auth-server/tokens/openid-id-token.md b/docs/admin/auth-server/tokens/openid-id-token.md
@@ -5,4 +5,69 @@ tags:
   - token
 ---
 
-## OpenID Connect `id_token`
+## OpenID Connect ID Token
+
+Defined in [Section 2](https://openid.net/specs/openid-connect-core-1_0.html#IDToken)
+of `OpenID Connect Core 1.0`:
+
+> The primary extension that OpenID Connect makes to OAuth 2.0 to enable End-Users to be Authenticated is the ID Token data structure. The ID Token is a security token that contains Claims about the Authentication of an End-User by an Authorization Server when using a Client, and potentially other requested Claims. The ID Token is represented as a JSON Web Token (JWT) [JWT].
+
+The ID Token is similar to a
+[SAML 2.0](http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html)
+Assertion, which must contain an Authentication statement, and may optionally
+contain an Attribute statement, defined in the spec as:
+
+> - Authentication statements: These are created by the party that successfully authenticated a user. At a minimum, they describe the particular means used to authenticate the user and the specific time at which the authentication took place.
+
+> - Attribute statements: These contain specific identifying attributes about the subject (for example, that user “John Doe” has “Gold” card status).
+
+The ID Token is a standard JWT, and can use signing and encryption depending on
+the configuration preferences of the client. A sample payload for a Jans Auth
+Server `id_token` is below:
+
+```
+{
+  "iss": "https://idp.example.tld",                 <-- OP hostname
+  "aud": "bd0469f7-f80a-4595-bd52-df9826f0a2f4",    <-- client_id  
+  "sub": "0a9ca356-6130-4032-91c6-a2dfe4e19804",    <-- in this case, a pairwise identifer
+  "iat": 1672373703,                                <-- issued at
+  "auth_time": 1672373700,                          <-- when user authenticated
+  "acr": "basic",                                   <-- how user authenticated
+  "amr": ["10"],                                    <-- Extra authn details
+  "nonce": "1u0y3ii",                               <-- client should verify
+  "sid": "5f01565c-f2dc-4b4b-af8a-ab1578a5dbe3",    <-- session id handle
+  "jansOpenIDConnectVersion": "openidconnect-1.0"   <-- OpenID version
+}
+```
+
+A great tool if you want to decode a JWT is Auth0's [https://jwt.io/](https://jwt.io/).
+
+Notice that a basic ID Token, like the one above, contains details about the
+authentication event, not user claims. You can configure the client to "include
+claims in id_token", or you can set a Auth Server configuration property,
+`legacyIdTokenClaims` to `True` to set the behavior for all clients.
+
+## Obtaining an ID Token
+
+The client may obtain an ID Token in the authorization response, from the
+token endpoint, or both. Note, if you intend to use the Code Flow, and you
+don't intend to validate the `c_hash` or `s_hash` values in the ID Token
+returned from the authorization endpoint, don't check `id_token` in the
+response_type for the authorization endpoint, as it will waste compute and
+storage generating a token you don't need.
+
+## Validating an ID Token
+
+At a minimum, client developers should always validate the following:
+- Signature of the ID token
+- `iss` make sure the ID Token was issued by the OP you trust
+- `aud` make sure the ID Token was issued to your `client_id`
+- `exp` make sure the token is not expired
+- `nonce` make sure the id_token correlates to your original authn request
+
+## Using the ID Token as an access token for API's
+
+Don't do this. The ID Token is an identity assertion, not an access token. It
+may be passed in the payload to an API, but it should not be used in lieu of
+an OAuth access token! Fundamentally, the `id_token` details how a person
+was authenticated, not which API's a client is authorized to call.