Skip to content

Commit

Permalink
add new emailVerifiedClaim to ExternalJWT and OpenID Connect.
Browse files Browse the repository at this point in the history
  • Loading branch information
robotdan committed Nov 3, 2023
1 parent 2e9eecf commit e073b2f
Show file tree
Hide file tree
Showing 3 changed files with 44 additions and 13 deletions.
16 changes: 9 additions & 7 deletions astro/src/content/docs/_shared/_hosted-backend-warning.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,12 @@
When developing against a FusionAuth Cloud instance with a `.fusionauth.io` address, unless your application also lives at a `.fusionauth.io` address, you'll receive a `403` response code. The hosted backend does not work across origins. This occurs whenever FusionAuth is hosted on a different domain from the application accessing the hosted backend.
When developing against a FusionAuth Cloud instance using an apex domain of `fusionauth.io` address, unless your application shares the same domain of `fusionauth.io` attempts to use these endpoints will fail with a `403` status code.

To work around this, you can:
These endpoints will not work correctly for cross origin requests. Cross origin requests occur when the application making the request to FusionAuth is using a separate domain. For example, if your application URL is `app.acme.com` and the FusionAuth URL is `acme.fusionauth.io` requests from your application to FusionAuth will be considered cross origin.

* develop using a local FusionAuth instance, so both your webapp and FusionAuth are running on `localhost`.
* set up a lightweight proxy to ensure both servers are the same domain.
* stand up a barebones backend with a more liberal cookie policy: [here's an example](https://github.com/FusionAuth/fusionauth-example-react-sdk/tree/main/server).
* set up a [custom domain name for the FusionAuth Cloud instance](/docs/get-started/run-in-the-cloud/cloud#updating-with-existing-custom-domains) (limited to certain plans).
If at all possible you should plan to access FusionAuth and your application in the same domain. If this is not possible, you may use one of these alternative methods:

Modifying FusionAuth CORS configuration options will not fix this issue.
* Develop using a local FusionAuth instance, so both your webapp and FusionAuth are running on `localhost`.
* Use a proxy to rewrite the requests to utilize the same domain.
* Do not use the the FusionAuth hosted backend, and instead write your own backend with a cross origin cookie policy: [here's an example](https://github.com/FusionAuth/fusionauth-example-react-sdk/tree/main/server).
* Configure a [custom domain name for the FusionAuth Cloud instance](/docs/get-started/run-in-the-cloud/cloud#updating-with-existing-custom-domains) (limited to certain plans).

Modifying FusionAuth CORS configuration options will not fix this issue because the cookies that FusionAuth writes will not be accessible cross domain.
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
import APIBlock from 'src/components/api/APIBlock.astro';
import APIField from 'src/components/api/APIField.astro';
import InlineField from 'src/components/InlineField.astro';
import JSON from 'src/components/JSON.astro';
import ClaimMappings from 'src/content/docs/apis/identity-providers/_claim_mappings.mdx';
import IdentityProviderDebugRequestParameter from 'src/content/docs/apis/identity-providers/_identity-provider-debug-request-parameter.mdx';
Expand Down Expand Up @@ -30,6 +31,14 @@ import IdentityProviderLinkingStrategyRequestParameter from 'src/content/docs/ap
<APIField name="identityProvider.enabled" type="Boolean" optional defaults="false">
Determines if this provider is enabled. If it is false then it will be disabled globally.
</APIField>
<APIField name="identityProvider.oauth2.emailClaim" type="String" optional defaults="email">
The name of the claim that contains the user's email address. This will only be used when the <InlineField>identityProvider.linkingStrategy</InlineField> is equal to `LinkByEmail` or `LinkByEmailForExistingUser`.
</APIField>
<APIField name="identityProvider.oauth2.emailVerifiedClaim" type="String" optional defaults="email_verified" since="1.48.0">
The name of the claim that identities if the user's email address has been verified.

When the <InlineField>identityProvider.linkingStrategy</InlineField> is equal to `LinkByEmail` or `LinkByEmailForExistingUser` and this claim is present and the value is `false` a link will not be established and an error will be returned indicating a link cannot be established using an unverified email address.
</APIField>
<APIField name="identityProvider.headerKeyParameter" type="String" required>
The name header claim that identifies the public key used to verify the signature. In most cases this be `kid` or `x5t`.
</APIField>
Expand Down Expand Up @@ -63,15 +72,22 @@ import IdentityProviderLinkingStrategyRequestParameter from 'src/content/docs/ap
The token endpoint for this Identity Provider. This value is not utilized by FusionAuth is only provided to be returned by the
Lookup Identity Provider API response. During integration you may then utilize this value to complete the OAuth2 grant workflow.
</APIField>
<APIField name="identityProvider.oauth2.uniqueIdClaim" type="String" optional defaults="sub">
The name of the claim that contains the user's unique user Id.
</APIField>
<APIField name="identityProvider.oauth2.usernameClaim" type="String" optional defaults="preferred_username">
The name of the claim that contains the user's username. This will only be used when the <InlineField>identityProvider.linkingStrategy</InlineField> is equal to `LinkByUsername` or `LinkByUsernameForExistingUser`.
</APIField>

<IdentityProviderTenantConfiguration />

<APIField name="identityProvider.type" type="String" required>
This field must be set to `ExternalJWT`.
</APIField>
<APIField name="identityProvider.uniqueIdentityClaim" type="String" required>
The name of the claim that represents the unique identify of the User. This will generally be `email` or the name of the claim that provides
the email address.
<APIField name="identityProvider.uniqueIdentityClaim" type="String" optional deprecated>
The name of the claim that represents the unique identify of the User. This will generally be `email` or the name of the claim that provides the email address.

This parameter has been deprecated, prefer the use of <InlineField>uniqueIdClaim</InlineField>.
</APIField>
</APIBlock>

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -80,7 +80,16 @@ import IdentityProviderTenantConfiguration from 'src/content/docs/apis/identity-
* `none`
</APIField>
<APIField name="identityProvider.oauth2.emailClaim" type="String" optional defaults="email" since="1.17.3">
An optional configuration to modify the expected name of the claim returned by the IdP that contains the email address. The UserInfo response found using the Access Token is inspected for this claim first. If it is not present and an Id Token is available, the Id Token is examined as well.
An optional configuration to modify the expected name of the claim returned by the IdP that contains the email address.

This claim will be resolved using the following precedence where the first occurrence will be used. The UserInfo response, followed by the `id_token` when present assuming the signature can be verified.
</APIField>
<APIField name="identityProvider.oauth2.emailVerifiedClaim" type="String" optional defaults="email_verified" since="1.48.0">
An optional configuration to modify the expected name of the claim returned by the IdP that indicates if the email is verified.

This claim will be resolved using the following precedence where the first occurrence will be used. The UserInfo response, followed by the `id_token` when present assuming the signature can be verified.

When the <InlineField>identityProvider.linkingStrategy</InlineField> is equal to `LinkByEmail` or `LinkByEmailForExistingUser` and this claim is present and the value is `false` a link will not be established and an error will be returned indicating a link cannot be established using an unverified email address.
</APIField>
<APIField name="identityProvider.oauth2.issuer" type="String" optional>
The top-level issuer URI for the OpenID Connect identity provider. If this is provided, the authorization endpoint, token endpoint and userinfo endpoint will all be resolved using the `issuer` URI plus `/.well-known/openid-configuration`.
Expand All @@ -92,13 +101,17 @@ import IdentityProviderTenantConfiguration from 'src/content/docs/apis/identity-
The top-level token endpoint for the OpenID Connect identity provider. You can leave this blank if you provide the `issuer` field, which will be used to make a request to the OpenID Connect `.well-known` endpoint in order to dynamically resolve the token endpoint. If you provide an `issuer` then this field will be ignored.
</APIField>
<APIField name="identityProvider.oauth2.uniqueIdClaim" type="String" optional defaults="sub">
An optional configuration to modify the expected name of the claim returned by the IdP that contains the user Id. The UserInfo response found using the Access Token is inspected for this claim first. If it is not present and an Id Token is available, the Id Token is examined as well.
An optional configuration to modify the expected name of the claim returned by the IdP that contains the user Id.

This claim will be resolved using the following precedence where the first occurrence will be used. The UserInfo response, followed by the `id_token` when present assuming the signature can be verified.
</APIField>
<APIField name="identityProvider.oauth2.userinfo_endpoint" type="String" optional>
The top-level userinfo endpoint for the OpenID Connect identity provider. You can leave this blank if you provide the `issuer` field, which will be used to make a request to the OpenID Connect `.well-known` endpoint in order to dynamically resolve the userinfo endpoint. If you provide an `issuer` then this field will be ignored.
</APIField>
<APIField name="identityProvider.oauth2.usernameClaim" type="String" optional defaults="preferred_username">
An optional configuration to modify the expected name of the claim returned by the IdP that contains the username. The UserInfo response found using the Access Token is inspected for this claim first. If it is not present and an Id Token is available, the Id Token is examined as well.
An optional configuration to modify the expected name of the claim returned by the IdP that contains the username.

This claim will be resolved using the following precedence where the first occurrence will be used. The UserInfo response, followed by the `id_token` when present assuming the signature can be verified.
</APIField>
<APIField name="identityProvider.postRequest" type="Boolean" optional defaults="false" since="1.20.0">
Set this value equal to `true` if you wish to use POST bindings with this OpenID Connect identity provider. The default value of `false` means that a redirect binding which uses a `GET` request will be used.
Expand Down

0 comments on commit e073b2f

Please sign in to comment.