Skip to content

[Platform Auth] Document DPoP parameters #1381

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Linping Zhang (coder-linping) wants to merge 1 commit into
base: main
Choose a base branch
from
Open

[Platform Auth] Document DPoP parameters #1381

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 10 additions & 2 deletions PlatformAuthentication/explainer.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -88,8 +88,10 @@ dictionary GetTokenParameters {
DOMString redirectUri,
DOMString correlationId,
boolean isSecurityTokenService,
boolean preferBinding,
DOMString? state,
record<DOMString, DOMString>? extraParameters
record<DOMString, DOMString>? extraParameters,
record<DOMString, DOMString>? extraParametersNoCache
}
```
`brokerId`: Required parameter that identifies which platform broker to use. For Microsoft Entra brokers, this should be set to "MicrosoftEntra". Browsers can define additional per-platform requirements for how new brokers can be registered and verified by the browser.
Expand All @@ -108,10 +110,14 @@ dictionary GetTokenParameters {

`isSecurityTokenService`:` When this flag is true, the broker is expected to validate that the request is coming from the Identity provider URL it expects. To do that, as part of the API contract between the browser and the broker, the browser will send an additional "sender" parameter (which is the URL of the website that is initiating the request). If it is valid, this call comes from a security token service (STS). The "sender" is not part of the API described in this document as it is not sent by the JS application, but by the browser itself.

`preferBinding`: When `true`, requests that the broker bind the access token to a broker-owned, attested key when the broker and identity provider support it. The broker may return an unbound token when binding is unavailable, so the caller must inspect the response properties to determine whether binding was applied.

`state`: OAuth protocol "state" param. It will be returned without changes in the response.

`extraParameters`: A string map of additional parameters to send to token and authorize endpoints.

`extraParametersNoCache`: A string map of request-specific parameters that the broker passes to the token request but does not use when looking up or storing a token in its cache. For DPoP requests, this map can contain `pop_method`, `pop_uri`, and `pop_nonce`. These values describe the individual resource request and its proof, rather than the access token itself.

There are additionally known optional parameters that can be passed in via the `extraParameters` map. This is to make the API easier to call from JS as most of the optional parameters will not be present. These optional parameters are:

`prompt`: Indicates the type of user interaction. The value should be `login`, `none`, `consent`, or `select_account`.
Expand All @@ -126,6 +132,8 @@ There are additionally known optional parameters that can be passed in via the `

`ProofOfPossessionParams`: The parameters used for Access Token (AT) proof-of-possession as described in [draft-ietf-oauth-signed-http-request-03](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-signed-http-request-03). For example, `bindingKeyInfo`, `keyId`, `tokenType`, `bindingClaims`, `bindingNonce`, `resourceRequestMethod`, `resourceRequestUri`, and `signPopToken`.

`tokenType`: The requested access-token type. DPoP flows use `dpop` when requesting a DPoP-bound access token, or `dpop+proof` when the broker should also create the proof for the resource request. Request-specific proof inputs belong in `extraParametersNoCache` so they do not affect token-cache lookup.

#### GetToken Response
The GetTokenResult is a dictionary that contain either an error or the response data (e.g. `access_token`, `id_token`, `account`, etc.).

Expand Down Expand Up @@ -223,7 +231,7 @@ dictionary GetTokenResult {

`extendedLifetimeToken`: `true` if the response was an extended lifetime token.

`properties`: Additional response data that also may include platform-specific telemetry data.
`properties`: Additional response data that also may include platform-specific telemetry data. For DPoP responses, this map can include `token_type`, `binding_attested`, and `dpop_proof`. `token_type` identifies the returned token type, `binding_attested` indicates whether the broker used an attested broker-owned key, and `dpop_proof` contains the proof generated by the broker when requested with the `dpop+proof` token type.

#### SignOut Request
The `SignOutParameters` request parameter is a dictionary containing all parameters needed to sign out a user from the from the broker:
Expand Down