Documentation updates for 1.50.0

.github/knownwords.txt

@@ -1120,7 +1120,6 @@ clientAuthenticationMethod
 clientAuthenticationPolicy
 clientId
 clientSecret
-cloient
 cloudfront
 cnf
 cockroachdb
@@ -1865,6 +1864,7 @@ relicensing
 relyingPartyApplicationId
 relyingPartyURL
 rememberDevice
+rememberOAuthScopeConsentChoiceTimeToLiveInSeconds
 rememberPreviousPasswords
 renderErrors
 replicable

.github/vale/styles/config/vocabularies/FusionAuth/accept.txt

@@ -6,6 +6,7 @@ authorizer
 Bachman
 Basecamp
 [Bb]crypt
+Boolean
 boolean
 CAPTCHA
 [Cc]yber

DocsDevREADME.md

@@ -19,6 +19,7 @@ Here are some guidelines to follow when writing documentation (everything under
 - Use `admin UI` instead of `Admin UI` when writing about the admin user interface.
 - Use `logged in` instead of `logged-in`
 - `log in` is the verb, `login` is the noun
+- Use `UserInfo` instead of `Userinfo`
 - Don't abbreviate FusionAuth, use the full name.
 - References to `http://127.0.0.1` should be updated to `http://localhost`. Remove hyperlinks to `localhost`.
 - Always provide an alt text for images. It should always be a full sentence describing the content of the image.
@@ -40,13 +41,14 @@ Here are some guidelines to follow when writing documentation (everything under
 - Don't use complex breadcrumbs styling in docs. Use `->`. Use the [Breadcrumb](astro/src/components/Breadcrumb.astro) component. Breadcrumbs should look like this `<Breadcrumb>foo -> bar -> baz</Breadcrumb>`.
 - If you are referencing a field in a form or JSON API doc, use the [InlineField](astro/src/components/InlineField.astro) component: `<InlineField>Issuer</InlineField>`.
 - If you are referencing a UI element or button, use the [InlineUIElement](astro/src/components/InlineUIElement.astro) component: `Click the <UIelement>Ok</UIelement> button`.
+- If you are referencing a tab in the UI, use the [Breadcrumb](astro/src/components/Breadcrumb.astro) component: `On the <Breadcrumb>OAuth</Breadcrumb> tab`.
 - When you have a list of values, use this phrase to prefix it: "The possible values are:"
 - When using images that are cropped, add `top-cropped` and/or `bottom-cropped` roles as appropriate. Use `box-shadow` only when an image isn't captured in the manner documented below. It's used only when we have screenshots of things that do not have a box shadow and are all white and blend in too much with our white background. No other image classes are needed when creating documentation.
 - Include fragments that are shared between different sections of the doc should be stored in the [shared](astro/src/content/docs/_shared) directory.
 - All links elements should be fully-qualified and never include a slash at the end (i.e. `[users](/docs/apis/users)` not `[users](./users)`)
 - If something is new in a version, mark it with something like this:
 
-  <Aside type="since">
+  <Aside type="version">
     Available Since Version 1.5.0
   </Aside>
 

astro/src/components/icon/Icon.astro

@@ -18,6 +18,8 @@ const { name, title, size } = Astro.props;
         <i class="fa-id-badge fas text-blue-700" {title} />, //todo new icon
       'bell':
         <BellIcon/>,
+      'code':
+        <span class="bg-blue-900 py-1 px-2 rounded"><i class="fas fa-code text-white" {title}/></span>,
       'cogs':
         <i class="fa-cogs fas" {title}/>, //todo new icon
       'copy':

astro/src/content/blog/single-sign-on-with-drupal.mdx

@@ -51,7 +51,7 @@ Click "Continue". It will take some time to fetch and add the module. Once the i
 
 ![Enabling the OIDC module.](/img/blogs/single-sign-on-drupal/enabling-modules.png)
 
-Scroll down to the "Security" section, check the checkbox next to "OpenID COnnect". 
+Scroll down to the "Security" section, check the checkbox next to "OpenID Connect".
 
 ![The OIDC module in the list.](/img/blogs/single-sign-on-drupal/oidc-module-in-list.png)
 

astro/src/content/docs/_shared/_access-token-claims.mdx

@@ -1,6 +1,8 @@
 import APIBlock from 'src/components/api/APIBlock.astro';
 import APIField from 'src/components/api/APIField.astro';
 import AuthenticationTypeClaimValues from 'src/content/docs/_shared/_authentication_type_claim_values.mdx';
+import InlineField from 'src/components/InlineField.astro';
+import RemovedSince from 'src/components/api/RemovedSince.astro';
 
 <APIBlock>
   <APIField name="applicationId" type="UUID">
@@ -25,9 +27,15 @@ import AuthenticationTypeClaimValues from 'src/content/docs/_shared/_authenticat
   </APIField>
   <APIField name="email" type="String">
     The email address of the User whose claims are represented by this JWT.
+
+    <RemovedSince since="1.50.0" />
+    In version `1.50.0` and later this claim is not returned when the <InlineField>oauthConfiguration.scopeHandlingPolicy</InlineField> value of the Application is `Strict`.
   </APIField>
   <APIField name="email_verified" type="Boolean">
     The OpenId Connect claim indicating if the User's email has been verified.
+
+    <RemovedSince since="1.50.0" />
+    In version `1.50.0` and later this claim is not returned when the <InlineField>oauthConfiguration.scopeHandlingPolicy</InlineField> value of the Application is `Strict`.
   </APIField>
   <APIField name="exp" type="Long">
     The expiration instant of the JWT, expressed as UNIX time which is the number of seconds since Epoch. This registered claim is defined by
@@ -47,10 +55,19 @@ import AuthenticationTypeClaimValues from 'src/content/docs/_shared/_authenticat
   </APIField>
   <APIField name="preferred_username" type="String" since="1.5.0">
     The username of the User whose claims are represented by this JWT.
+
+    <RemovedSince since="1.50.0" />
+    In version `1.50.0` and later this claim is not returned when the <InlineField>oauthConfiguration.scopeHandlingPolicy</InlineField> value of the Application is `Strict`.
   </APIField>
   <APIField name="roles" type="Array<String>">
     The roles assigned to the User in the authenticated Application. This claim is only present if the User has a registration to the Application.
   </APIField>
+  <APIField name="scope" type="String" since="1.50.0">
+    The scope of the Access token. This meaning of this field is specified by
+    [RFC 6749 Section 3.3](https://datatracker.ietf.org/doc/html/rfc6749#section-3.3).
+
+    Contains the validated and consented OAuth scopes from the initial authentication request. See [Scopes](/docs/lifecycle/authenticate-users/oauth/scopes) for more detail on scope consent.
+  </APIField>
   <APIField name="sid" type="String" since="1.37.0">
     The unique Id of the refresh token returned along with this access token when the `offline_access` scope was requested. This unique Id is the persistent identifier for this refresh token, and will not change even when using one-time use refresh tokens. This value may optionally be used to revoke the token using the [Refresh Token API](/docs/apis/jwt#revoke-refresh-tokens).
   </APIField>

astro/src/content/docs/_shared/_application-oauth-settings.mdx

@@ -0,0 +1,104 @@
+import APIBlock from 'src/components/api/APIBlock.astro';
+import APIField from 'src/components/api/APIField.astro';
+import InlineField from 'src/components/InlineField.astro';
+import OAuthWildcardUsage from 'src/content/docs/_shared/_oauth-wildcard-usage.mdx';
+
+<APIBlock>
+  <APIField name="Client Id" readonly>
+    The unique client identifier as defined by [RFC 6749 Section 2.2](https://tools.ietf.org/html/rfc6749#section-2.2). This value is read only and is equal to the unique Id of the Application.
+  </APIField>
+  <APIField name="Client secret" readonly>
+    The client secret as defined by [RFC 6749 Section 2.3.1](https://tools.ietf.org/html/rfc6749#section-2.3.1). When <InlineField>Client Authentication</InlineField> is `Required`, this client secret will be required to obtain an access token from the Token endpoint.
+
+    This value may be regenerated if you think it has been compromised by clicking the regenerate button. If this Application is configured to require client authentication, regenerating the client secret will cause all clients to fail, and they will not be able to complete the OAuth login process. If this Application is not configured to require client authentication, regenerating this secret will not have any effect.
+  </APIField>
+  <APIField name="Client Authentication" optional since="1.28.0">
+    This selector allows you to set a rule for accessing the [Token endpoint](/docs/lifecycle/authenticate-users/oauth/endpoints#token).
+
+    The possible values are:
+    * `Required` - The `client_secret` parameter must be used. This is the default setting. In most cases you will not want to change this setting.
+    * `Not required` - Use of the `client_secret` parameter is optional.
+    * `Not required when using PKCE` - Requires the use of the `client_secret` parameter unless a valid PKCE [code_verifier](https://datatracker.ietf.org/doc/html/rfc7636#section-4.1) parameter is used. This is useful for scenarios where you have a requirement to make a request to the Token endpoint where you cannot safely secure a client secret such as native mobile applications and single page applications (SPAs) running in a browser. In these scenarios it is recommended you use PKCE.
+
+    See the [Token endpoint](/docs/lifecycle/authenticate-users/oauth/endpoints#token) for more information.
+  </APIField>
+  <APIField name="PKCE" optional since="1.28.0">
+    This selector allows you to set a rule for [Proof Key for Code Exchange](https://datatracker.ietf.org/doc/html/rfc7636) (or PKCE) requirements when using the authorization code grant.
+
+    The possible values are:
+    * `Required` - The `code_verifier` parameter must be used. If you want to require PKCE for this application, set <InlineField>PKCE</InlineField> to this value.
+    * `Not required` - Use of the `code_verifier` parameter is optional. This is the default setting.
+    * `Not required when using client authentication` - Requires the use of the `code_verifier` parameter unless a valid `client_secret` parameter is used.
+  </APIField>
+  <APIField name="Generate refresh tokens" since="1.3.0">
+    When enabled, FusionAuth will return a refresh token when the `offline_access` scope has been requested. When this setting is disabled refresh tokens will not be generated even if the `offline_access` scope is requested.
+
+    In order to use the Refresh Token with the Refresh Grant to refresh a token, you must ensure that the `Refresh Token` grant is enabled. See the <InlineField>Enabled grants</InlineField> field.
+  </APIField>
+  <APIField name="Debug enabled" optional since="1.25.0">
+    Enable debug to create an event log to assist you in debugging integration errors.
+  </APIField>
+  <APIField name="URL validation" optional since="1.43.0">
+    Controls the validation policy for <InlineField>Authorized redirect URLs</InlineField> and <InlineField>Authorized request origin URLs</InlineField>.
+
+    The possible values are:
+    * `Exact match` - Only the configured values that do not contain wildcards are considered for validation. Values during OAuth 2.0 workflows must match a configured value exactly.
+    * `Allow wildcards` - Configured values with and without wildcards are considered for validation. Values during OAuth 2.0 workflows can be matched against wildcard patterns or exactly match a configured value.
+  </APIField>
+  <APIField name="Authorized redirect URLs" optional>
+    When OAuth grants, such as the authorization code grant, require a browser redirect to a URL found in the `redirect_uri` parameter, the destination URLs must be added to this list. URLs that are not authorized may not be utilized in the `redirect_uri` parameter or the `post_logout_redirect_uri` parameter.
+
+    You can add as many URLs as you'd like to this list. Prior to version `1.43.0` only exact string matches with the provided `redirect_uri` will be allowed. No partial or wildcard matches will be accepted.
+
+    <OAuthWildcardUsage fieldName="Authorized redirect URLs" wildcard="Allow wildcards" />
+  </APIField>
+  <APIField name="Authorized request origin URLs" optional>
+    This optional configuration allows you to restrict the origin of an OAuth2 / OpenID Connect grant request. If no origins are registered for this Application, all origins are allowed.
+
+    By default FusionAuth will add the `X-Frame-Options: DENY` HTTP response header to the login pages to keep these pages from being rendered in an iframe. If the request comes from an authorized origin, however, FusionAuth will not add this header to the response. To load FusionAuth hosted login pages in an iframe, you will need to add the request origin to this configuration.
+
+   <OAuthWildcardUsage fieldName="Authorized request origin URLs" wildcard="Allow wildcards" />
+  </APIField>
+  <APIField name="Logout URL" optional>
+    The optional logout URL for this Application. When provided this logout URL should handle the logout of a user in your application.
+
+    If you need to end an HTTP session or delete cookies to logout a user from your application, these operations should be handled by this URL. When the `/oauth2/logout` endpoint is utilized, each Logout URL registered for Applications in this tenant will be called within an iframe to complete the SSO logout.
+
+    If the OAuth2 logout endpoint is used with this Client Id, this configured Logout URL will be also utilized as the redirect URL. This behavior only occurs when the `post_logout_redirect_uri` parameter is not provided.
+
+    If this Application has not defined a Logout URL, the value configured at the Tenant level will be used. If no Logout URL has been configured, a redirect to `/` will occur. A specific redirect URL may also be provided by using the `post_logout_redirect_uri` request parameter.
+
+    See the [Logout endpoint](/docs/lifecycle/authenticate-users/oauth/endpoints#logout) for more information.
+  </APIField>
+  <APIField name="Logout behavior" optional since="1.11.0">
+    This selector allows you to modify the behavior when using the [Logout endpoint](/docs/lifecycle/authenticate-users/oauth/endpoints#logout) with this Client Id.
+
+    The possible values are:
+      * `All applications` - This is the default behavior. Upon Logout of the FusionAuth SSO, call each registered Logout URLs for the entire tenant and then redirect to the Logout URL registered for this application.
+      * `Redirect only` - Do not call each registered Logout URL in the tenant, instead logout out of the FusionAuth SSO and then only redirect to the Logout URL registered for this application.
+
+    See the [Logout endpoint](/docs/lifecycle/authenticate-users/oauth/endpoints#logout) for more information.
+  </APIField>
+  <APIField name="Enabled grants" optional since="1.5.0">
+    The enabled OAuth2 grants. If a grant is not enabled and a client requests this grant during authentication an error will be returned to the caller indicating the grant is not enabled.
+
+      * Authorization Code
+      * Device
+      * Implicit
+      * Password
+      * Refresh Token
+
+    When creating a new Application, the `Authorization Code` and `Refresh Token` grants will be enabled by default. See The [OAuth 2.0 & OpenID Connect Overview](/docs/lifecycle/authenticate-users/oauth/) for additional information on each of these grants.
+  </APIField>
+  <APIField name="Device Verification URL" optional since="1.11.0">
+    The URL to be returned during the Device Authorization request to be displayed to the end user. This URL will be where the end user navigates in order to complete the device authentication workflow.
+
+    This field is required if `Device` is enabled in the OAuth <InlineField>Enabled grants</InlineField> for this Application and hidden when not.
+  </APIField>
+  <APIField name="Require registration" optional since="1.28.0">
+    When enabled the user will be required to be registered, or complete registration before redirecting to the configured callback in the authorization code grant or the implicit grant. This configuration does not affect any other grant, and does not affect the API usage.
+  </APIField>
+  <APIField name="UserInfo populate lambda" optional since="1.50.0">
+    The lambda to be invoked during the generation of the UserInfo response when provided a token associated with this Application. See [UserInfo populate lambda](/docs/extend/code/lambdas/userinfo-populate).
+  </APIField>
+</APIBlock>

astro/src/content/docs/_shared/_application-scopes-settings.mdx

@@ -0,0 +1,46 @@
+import AdvancedEditionBlurbApi from 'src/content/docs/_shared/_advanced-edition-blurb-api.astro';
+import APIBlock from 'src/components/api/APIBlock.astro';
+import APIField from 'src/components/api/APIField.astro';
+import InlineField from 'src/components/InlineField.astro';
+
+<APIBlock>
+  <APIField name="Relationship">
+    The application's relationship to the authorization server, otherwise known as the OAuth server.
+
+    The possible values are:
+
+    * `First-party` - The application has the same owner as the authorization server. Consent to requested OAuth scopes is granted implicitly. This was the default behavior for all versions of FusionAuth before version 1.50.0.
+    * `Third-party` - The application is external to the authorization server. Users will be prompted to consent to requested OAuth scopes based on <InlineField>Consent mode</InlineField>.
+
+    <AdvancedEditionBlurbApi feature="third-party applications"/>
+  </APIField>
+  <APIField name="Consent mode">
+    Controls the policy for prompting a user to consent to requested OAuth scopes. This field is only visible when the application's <InlineField>Relationship</InlineField> is `Third-party`.
+
+    The possible values are:
+
+    * `Always prompt` - Always prompt the user for consent.
+    * `Remember decision` - Remember previous consents; only prompt if the choice expires or if the requested or required scopes have changed. The duration of this persisted choice is controlled by the tenant's <InlineField>Remember OAuth scope consent choice</InlineField> configuration.
+    * `Never prompt` - The user will be never be prompted to consent to requested OAuth scopes. Permission will be granted implicitly as if this were a `First-party` application. This configuration is meant for testing purposes only and should not be used in production.
+  </APIField>
+  <APIField name="Unknown scope policy">
+    Controls the policy for handling unknown scopes on an OAuth request.
+
+    The possible values are:
+
+    * `Allow` - Unknown scopes will be allowed on the request, passed through the OAuth workflow, and written to the resulting tokens without consent. This is the behavior for all versions of FusionAuth before version 1.50.0.
+    * `Remove` - Unknown scopes will be removed from the OAuth workflow, but the workflow will proceed without them.
+    * `Reject` - Unknown scopes will be rejected and cause the OAuth workflow to fail with an error. This is the default behavior for new applications.
+  </APIField>
+  <APIField name="Scope handling policy">
+    Controls the policy for handling of OAuth scopes when populating JWTs and the UserInfo response.
+
+    The possible values are:
+
+    * `Compatibility` - OAuth workflows will populate JWT and UserInfo claims in a manner compatible with versions of FusionAuth before version 1.50.0.
+    * `Strict` - OAuth workflows will populate token and UserInfo claims according to the OpenID Connect 1.0 specification based on requested and consented scopes.
+  </APIField>
+  <APIField name="Provided scopes">
+    Configuration for standard scopes provided by FusionAuth. Each provided scope is reserved by FusionAuth and can be individually <InlineField>Enabled</InlineField> and <InlineField>Required.</InlineField> A disabled scope will be treated as unknown by FusionAuth and handled in accordance with the <InlineField>Unknown scope policy.</InlineField> A user must consent to all <InlineField>Required</InlineField> scopes present in an OAuth workflow, but may choose whether or not to consent to <InlineField>Enabled</InlineField> fields that are not <InlineField>Required.</InlineField>
+  </APIField>
+</APIBlock>

astro/src/content/docs/_shared/_list-hosted-login-pages-use-cases.mdx

@@ -16,6 +16,7 @@ import InlineUIElement from 'src/components/InlineUIElement.astro';
 * Breach password detection
 * Federated login with IdPs such as Google and Microsoft Active Directory
 * Advanced self service registration forms
+* Prompting for consent to requested OAuth scopes
 * Linking between IdP accounts and FusionAuth accounts
 * Multi application logout (OAuth front channel logout)