Skip to content
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

Jump to bottom

Parsing headers from Identity Provider pages to create TOCs #2917

Merged
merged 2 commits into from
Mar 6, 2024
Merged

Parsing headers from Identity Provider pages to create TOCs #2917

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4815509
:children_crossing: Parsing headers from Identity Providers pages to …
vcampitelli Mar 1, 2024
9aaf2dc
:memo: refs #2917 Restoring "Overview" header and changing prop name
vcampitelli Mar 5, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
1 change: 1 addition & 0 deletions astro/src/content/config.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,7 @@ const docsCollection = defineCollection({
nestedHeadings: z.boolean().optional(),
disableTOC: z.boolean().default(false),
topOfNav: z.boolean().default(false),
idpDisplayName: z.string().optional(),
}),
});

Expand Down
52 changes: 26 additions & 26 deletions astro/src/content/docs/apis/identity-providers/_oauth-idp-operations.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,17 +14,17 @@
import IdentityProviderLoginRequestBody from 'src/content/docs/apis/identity-providers/_identity-provider-login-request-body.astro';
import IdentityProviderLoginResponseBody from 'src/content/docs/apis/identity-providers/_identity-provider-login-response-body.mdx';

## Create the {props.idp_display_name} Identity Provider
## Create the {props.manual_idp_display_name} Identity Provider

### Request

<API method="POST" uri="/api/identity-provider" authentication={["api-key"]} title={`Create the ${props.idp_display_name} Identity Provider`}/>
<API method="POST" uri="/api/identity-provider" authentication={["api-key"]} title={`Create the ${props.manual_idp_display_name} Identity Provider`}/>

The <InlineField>type</InlineField> in the request JSON is used to determine that you are managing the {props.idp_display_name} identity provider.
The <InlineField>type</InlineField> in the request JSON is used to determine that you are managing the {props.manual_idp_display_name} identity provider.

<OauthIdpRequestBody idp_lowercase={props.idp_lowercase}
idp_type={props.idp_type}
idp_display_name={props.idp_display_name}
idp_display_name={props.manual_idp_display_name}
idp_linking_strategy={props.idp_linking_strategy}
idp_login_method={props.idp_login_method}
idp_since={props.idp_since}
Expand All @@ -36,78 +36,78 @@

<OauthIdpResponseBody idp_lowercase={props.idp_lowercase}
idp_type={props.idp_type}
idp_display_name={props.idp_display_name}
idp_display_name={props.manual_idp_display_name}
idp_linking_strategy={props.idp_linking_strategy}
idp_login_method={props.idp_login_method}
idp_since={props.idp_since}
idp_id={props.idp_id}
optional_tag={props.optional_tag} />


## Retrieve the {props.idp_display_name} Identity Provider
## Retrieve the {props.manual_idp_display_name} Identity Provider

There is only one {props.idp_display_name} Identity Provider, so this Identity Provider may be retrieved by type or Id.
There is only one {props.manual_idp_display_name} Identity Provider, so this Identity Provider may be retrieved by type or Id.

### Request

<API method="GET" uri={`/api/identity-provider?type=${props.idp_type}`} authentication={["api-key"]} title={`Retrieve the ${props.idp_display_name} Identity Provider by type`}/>
<API method="GET" uri={`/api/identity-provider?type=${props.idp_type}`} authentication={["api-key"]} title={`Retrieve the ${props.manual_idp_display_name} Identity Provider by type`}/>

Check failure on line 53 in astro/src/content/docs/apis/identity-providers/_oauth-idp-operations.mdx

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Vale.Terms] Use 'API' instead of 'api'.

Raw Output:
{"message": "[Vale.Terms] Use 'API' instead of 'api'.", "location": {"path": "astro/src/content/docs/apis/identity-providers/_oauth-idp-operations.mdx", "range": {"start": {"line": 53, "column": 26}}}, "severity": "ERROR"}

<API method="GET" uri={`/api/identity-provider/${props.idp_id}`} authentication={["api-key"]} title={`Retrieve the ${props.idp_display_name} Identity Provider by Id`}/>
<API method="GET" uri={`/api/identity-provider/${props.idp_id}`} authentication={["api-key"]} title={`Retrieve the ${props.manual_idp_display_name} Identity Provider by Id`}/>

Check failure on line 55 in astro/src/content/docs/apis/identity-providers/_oauth-idp-operations.mdx

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Vale.Terms] Use 'API' instead of 'api'.

Raw Output:
{"message": "[Vale.Terms] Use 'API' instead of 'api'.", "location": {"path": "astro/src/content/docs/apis/identity-providers/_oauth-idp-operations.mdx", "range": {"start": {"line": 55, "column": 26}}}, "severity": "ERROR"}

### Response

<StandardGetResponseCodes never_search_error />

<OauthIdpResponseBody idp_lowercase={props.idp_lowercase}
idp_type={props.idp_type}
idp_display_name={props.idp_display_name}
idp_display_name={props.manual_idp_display_name}
idp_linking_strategy={props.idp_linking_strategy}
idp_login_method={props.idp_login_method}
idp_since={props.idp_since}
idp_id={props.idp_id}
optional_tag={props.optional_tag} />


## Update the {props.idp_display_name} Identity Provider
## Update the {props.manual_idp_display_name} Identity Provider

<GenericUpdateExplanationFragment extra_id_verbiage={`There is only one ${props.idp_display_name} Identity Provider, so this Identity Provider may be updated by type or Id.`} capitalized_object_name={`${props.idp_display_name} Identity Provider`} />
<GenericUpdateExplanationFragment extra_id_verbiage={`There is only one ${props.manual_idp_display_name} Identity Provider, so this Identity Provider may be updated by type or Id.`} capitalized_object_name={`${props.manual_idp_display_name} Identity Provider`} />

### Request

<API method="PUT" uri={`/api/identity-provider?type=${props.idp_type}`} authentication={["api-key"]} showPatch={true} title={`Update the ${props.idp_display_name} Identity Provider by type`}/>
<API method="PUT" uri={`/api/identity-provider?type=${props.idp_type}`} authentication={["api-key"]} showPatch={true} title={`Update the ${props.manual_idp_display_name} Identity Provider by type`}/>

Check failure on line 77 in astro/src/content/docs/apis/identity-providers/_oauth-idp-operations.mdx

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Vale.Terms] Use 'API' instead of 'api'.

Raw Output:
{"message": "[Vale.Terms] Use 'API' instead of 'api'.", "location": {"path": "astro/src/content/docs/apis/identity-providers/_oauth-idp-operations.mdx", "range": {"start": {"line": 77, "column": 26}}}, "severity": "ERROR"}

<API method="PUT" uri={`/api/identity-provider/${props.idp_id}`} authentication={["api-key"]} showPatch={true} title={`Update the ${props.idp_display_name} Identity Provider by Id`}/>
<API method="PUT" uri={`/api/identity-provider/${props.idp_id}`} authentication={["api-key"]} showPatch={true} title={`Update the ${props.manual_idp_display_name} Identity Provider by Id`}/>

Check failure on line 79 in astro/src/content/docs/apis/identity-providers/_oauth-idp-operations.mdx

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Vale.Terms] Use 'API' instead of 'api'.

Raw Output:
{"message": "[Vale.Terms] Use 'API' instead of 'api'.", "location": {"path": "astro/src/content/docs/apis/identity-providers/_oauth-idp-operations.mdx", "range": {"start": {"line": 79, "column": 26}}}, "severity": "ERROR"}

<OauthIdpRequestBody idp_lowercase={props.idp_lowercase}
idp_type={props.idp_type}
idp_display_name={props.idp_display_name}
idp_display_name={props.manual_idp_display_name}
idp_linking_strategy={props.idp_linking_strategy}
idp_since={props.idp_since}
optional_tag={props.optional_tag} />
### Response

The response for this API contains the {props.idp_display_name} Identity Provider.
The response for this API contains the {props.manual_idp_display_name} Identity Provider.

<StandardPutResponseCodes never_search_error />

<OauthIdpResponseBody idp_lowercase={props.idp_lowercase}
idp_type={props.idp_type}
idp_display_name={props.idp_display_name}
idp_display_name={props.manual_idp_display_name}
idp_linking_strategy={props.idp_linking_strategy}
idp_since={props.idp_since}
idp_id={props.idp_id}
optional_tag={props.optional_tag} />


## Delete the {props.idp_display_name} Identity Provider
## Delete the {props.manual_idp_display_name} Identity Provider

There is only one {props.idp_display_name} Identity Provider, so this Identity Provider may be deleted by type or Id.
There is only one {props.manual_idp_display_name} Identity Provider, so this Identity Provider may be deleted by type or Id.

### Request

<API method="DELETE" uri={`/api/identity-provider?type=${props.idp_type}`} authentication={["api-key"]} title={`Delete the ${props.idp_display_name} Identity Provider by type`}/>
<API method="DELETE" uri={`/api/identity-provider?type=${props.idp_type}`} authentication={["api-key"]} title={`Delete the ${props.manual_idp_display_name} Identity Provider by type`}/>

Check failure on line 108 in astro/src/content/docs/apis/identity-providers/_oauth-idp-operations.mdx

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Vale.Terms] Use 'API' instead of 'api'.

Raw Output:
{"message": "[Vale.Terms] Use 'API' instead of 'api'.", "location": {"path": "astro/src/content/docs/apis/identity-providers/_oauth-idp-operations.mdx", "range": {"start": {"line": 108, "column": 29}}}, "severity": "ERROR"}

<API method="DELETE" uri={`/api/identity-provider/${props.idp_id}`} authentication={["api-key"]} title={`Delete the ${props.idp_display_name} Identity Provider by Id`}/>
<API method="DELETE" uri={`/api/identity-provider/${props.idp_id}`} authentication={["api-key"]} title={`Delete the ${props.manual_idp_display_name} Identity Provider by Id`}/>

Check failure on line 110 in astro/src/content/docs/apis/identity-providers/_oauth-idp-operations.mdx

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Vale.Terms] Use 'API' instead of 'api'.

Raw Output:
{"message": "[Vale.Terms] Use 'API' instead of 'api'.", "location": {"path": "astro/src/content/docs/apis/identity-providers/_oauth-idp-operations.mdx", "range": {"start": {"line": 110, "column": 29}}}, "severity": "ERROR"}

### Response

Expand All @@ -116,13 +116,13 @@
<StandardDeleteResponseCodes never_search_error />


## Complete the {props.idp_display_name} Login
## Complete the {props.manual_idp_display_name} Login

<CompleteLoginText idp_display_name={props.idp_display_name} token_text_with_article={"a " + props.idp_token_or_code} token_text={props.idp_token_or_code} />
<CompleteLoginText idp_display_name={props.manual_idp_display_name} token_text_with_article={"a " + props.idp_token_or_code} token_text={props.idp_token_or_code} />

### Request

<API method="POST" uri="/api/identity-provider/login" authentication={["none"]} title={`Complete ${props.idp_display_name} Login`}/>
<API method="POST" uri="/api/identity-provider/login" authentication={["none"]} title={`Complete ${props.manual_idp_display_name} Login`}/>

#### Request Headers

Expand All @@ -133,12 +133,12 @@
</APIBlock>

<IdentityProviderLoginRequestBody idp_token_or_code={props.idp_token_or_code}
idp_display_name={props.idp_display_name}
idp_display_name={props.manual_idp_display_name}
idp_lowercase={props.idp_lowercase}
idp_since={props.idp_since} />

### Response

The response for this API contains the User object.

<IdentityProviderLoginResponseBody idp_display_name={props.idp_display_name} />
<IdentityProviderLoginResponseBody idp_display_name={props.manual_idp_display_name} />
5 changes: 3 additions & 2 deletions astro/src/content/docs/apis/identity-providers/epicgames.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ title: Epic Games
description: Learn about the APIs for creating, retrieving, updating and disabling the Epic Games identity provider.
section: apis
subcategory: identity providers
idpDisplayName: Epic Games
---
import PremiumEditionBlurb from 'src/content/docs/_shared/_premium-edition-blurb.astro';
import Aside from 'src/components/Aside.astro';
Expand All @@ -21,6 +22,6 @@ The Epic Games identity provider type will use the Epic Games OAuth login API. I

This identity provider will call Epic Games' API to load the Epic Games user's `displayName` and use that as `username` to lookup or create a user in FusionAuth depending on the linking strategy configured for this identity provider. However, Epic Games does not allow access to user emails, so neither email linking strategy can be used and user’s will not be able to login or be created.

<TokenStorageNote idp_long_lived_token_type="refresh" idp_refresh_additional_info_url="https://dev.epicgames.com/docs/web-api-ref/authentication" idp_display_name="Epic Games" token_name="refresh_token" return_text="the Epic Games login " hide_token_map_deprecation="true" />
<TokenStorageNote idp_long_lived_token_type="refresh" idp_refresh_additional_info_url="https://dev.epicgames.com/docs/web-api-ref/authentication" manual_idp_display_name={frontmatter.idpDisplayName} token_name="refresh_token" return_text="the Epic Games login " hide_token_map_deprecation="true" />

<OAuthIdpOperations idp_long_lived_token_type="refresh" idp_refresh_additional_info_url="https://dev.epicgames.com/docs/web-api-ref/authentication" idp_display_name="Epic Games" idp_id="1b932b19-61a8-47c7-9e81-27dbf9011dad" idp_linking_strategy="CreatePendingLink" idp_lowercase="epicgames" idp_since={12800} idp_token_or_code="token or code" idp_type="EpicGames" />
<OAuthIdpOperations idp_long_lived_token_type="refresh" idp_refresh_additional_info_url="https://dev.epicgames.com/docs/web-api-ref/authentication" manual_idp_display_name={frontmatter.idpDisplayName} idp_id="1b932b19-61a8-47c7-9e81-27dbf9011dad" idp_linking_strategy="CreatePendingLink" idp_lowercase="epicgames" idp_since={12800} idp_token_or_code="token or code" idp_type="EpicGames" />
7 changes: 3 additions & 4 deletions astro/src/content/docs/apis/identity-providers/google.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,13 +3,12 @@ title: Google
description: Learn about the APIs for creating, retrieving, updating and disabling the Google identity provider.
section: apis
subcategory: identity providers
idpDisplayName: Google
---
import Aside from 'src/components/Aside.astro';
import TokenStorageNote from 'src/content/docs/apis/identity-providers/_token-storage-note.mdx';
import OauthIdpOperations from 'src/content/docs/apis/identity-providers/_oauth-idp-operations.mdx';

export const idp_display_name = 'Google';

## Overview

<Aside type="version">
Expand All @@ -20,8 +19,8 @@ The Google identity provider type will use the Google OAuth v2.0 login API. It w

This identity provider will call Google’s API to load the user's `email` and `preferred_username` and use those as `email` and `username` to lookup or create a user in FusionAuth depending on the linking strategy configured for this identity provider. Additional claims returned by Google can be used to reconcile the user to FusionAuth by using a Google Reconcile Lambda.

<TokenStorageNote idp_long_lived_token_type="id_token" idp_display_name="Google" idp_linking_strategy="LinkByEmail" token_name="id_token" return_text="Google API" />
<TokenStorageNote idp_long_lived_token_type="id_token" manual_idp_display_name={frontmatter.idpDisplayName} idp_linking_strategy="LinkByEmail" token_name="id_token" return_text="Google API" />

Please note if an `idp_hint` is appended to the OAuth Authorize endpoint, then the login method interaction will be `redirect`, even if popup interaction is explicitly configured.

<OauthIdpOperations idp_id="82339786-3dff-42a6-aac6-1f1ceecb6c46" idp_display_name={idp_display_name} idp_login_method idp_lowercase="google" idp_since="10100" idp_token_or_code="token or code" idp_type="Google" />
<OauthIdpOperations idp_id="82339786-3dff-42a6-aac6-1f1ceecb6c46" manual_idp_display_name={frontmatter.idpDisplayName} idp_login_method idp_lowercase="google" idp_since="10100" idp_token_or_code="token or code" idp_type="Google" />
6 changes: 4 additions & 2 deletions astro/src/content/docs/apis/identity-providers/nintendo.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ title: Nintendo
description: Learn about the APIs for creating, retrieving, updating and deleting the Nintendo identity provider.
section: apis
subcategory: identity providers
idpDisplayName: Nintendo
---
import PremiumEditionBlurb from 'src/content/docs/_shared/_premium-edition-blurb.astro';
import Aside from 'src/components/Aside.astro';
Expand All @@ -21,10 +22,11 @@ The Nintendo identity provider type will use the Nintendo OAuth login API. It wi

If the linking strategy depends on a username or email address, FusionAuth will leverage the `/users/me` API that is part of the Nintendo specification. The email address and username returned in the response will be used to create or lookup the existing User. Additional claims from the response can be used to reconcile the User in FusionAuth by using an Nintendo Reconcile Lambda. Unless you assign a reconcile lambda to this provider or configure the IdP options to use different claims, the `email` and `preferred_username` will be used from the available claims returned by the Nintendo identity provider.

<TokenStorageNote idp_long_lived_token_type="access_token" idp_display_name="Nintendo" token_name="access_token" return_text="Nintendo API" hide_token_map_deprecation="true" />
<TokenStorageNote idp_long_lived_token_type="access_token" manual_idp_display_name={frontmatter.idpDisplayName} token_name="access_token" return_text="Nintendo API" hide_token_map_deprecation="true" />

<OauthIdpOperations idp_long_lived_token_type="access_token"
idp_display_name="Nintendo" idp_id="b0ac2e16-d4af-483e-98c8-7f6693610665"
manual_idp_display_name={frontmatter.idpDisplayName}
idp_id="b0ac2e16-d4af-483e-98c8-7f6693610665"
idp_linking_strategy="CreatePendingLink"
idp_lowercase="nintendo"
idp_since="13600"
Expand Down
5 changes: 3 additions & 2 deletions astro/src/content/docs/apis/identity-providers/sonypsn.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ title: Sony PlayStation Network
description: Learn about the APIs for creating, retrieving, updating and disabling the Sony PlayStation Network identity provider.
section: apis
subcategory: identity providers
idpDisplayName: Sony PlayStation Network
---
import PremiumEditionBlurb from 'src/content/docs/_shared/_premium-edition-blurb.astro';
import Aside from 'src/components/Aside.astro';
Expand All @@ -22,13 +23,13 @@ The Sony PlayStation Network identity provider type will use the Sony OAuth v2.0
This identity provider will call Sony’s API to load the user's `email` and `online_id` and use those as `email` and `username` to lookup or create a user in FusionAuth depending on the linking strategy configured for this identity provider. Additional claims returned by Sony PlayStation Network can be used to reconcile the user to FusionAuth by using a Sony PlayStation Network Reconcile Lambda.

<TokenStorageNote idp_long_lived_token_type="access_token"
idp_display_name="Sony PlayStation Network "
manual_idp_display_name={frontmatter.idpDisplayName}
token_name="access_token"
return_text="Sony PlayStation Network API"
hide_token_map_deprecation="true" />

<OauthIdpOperations idp_long_lived_token_type="access_token"
idp_display_name="Sony PlayStation Network "
manual_idp_display_name={frontmatter.idpDisplayName}
idp_id="7764b5c7-165b-4e7e-94aa-02ebe2a0a5fb"
idp_linking_strategy="CreatePendingLink"
idp_lowercase="sonypsn"
Expand Down
5 changes: 3 additions & 2 deletions astro/src/content/docs/apis/identity-providers/steam.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ title: Steam
description: Learn about the APIs for creating, retrieving, updating and disabling the Steam identity provider.
section: apis
subcategory: identity providers
idpDisplayName: Steam
---
import PremiumEditionBlurb from 'src/content/docs/_shared/_premium-edition-blurb.astro';
import Aside from 'src/components/Aside.astro';
Expand All @@ -22,13 +23,13 @@ The Steam identity provider type will use the Steam OAuth login API. It will als
This identity provider will call Steam's API to load the Steam user's `personaname` and use that as `username` to lookup or create a user in FusionAuth depending on the linking strategy configured for this identity provider. However, Steam does not allow access to user emails, so neither email linking strategy can be used and user’s will not be able to login or be created.

<TokenStorageNote idp_long_lived_token_type="token"
idp_display_name="Steam"
manual_idp_display_name={frontmatter.idpDisplayName}
token_name="token"
return_text="Steam login"
hide_token_map_deprecation="true" />

<OauthIdpOperations idp_long_lived_token_type="token"
idp_display_name="Steam"
manual_idp_display_name={frontmatter.idpDisplayName}
idp_id="e4f39345-7833-4b1d-b331-ca03bdc2c4be"
idp_linking_strategy="CreatePendingLink"
idp_lowercase="steam"
Expand Down
5 changes: 3 additions & 2 deletions astro/src/content/docs/apis/identity-providers/twitch.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ title: Twitch
description: Learn about the APIs for creating, retrieving, updating and disabling the Twitch identity provider.
section: apis
subcategory: identity providers
idpDisplayName: Twitch
---
import PremiumEditionBlurb from 'src/content/docs/_shared/_premium-edition-blurb.astro';
import Aside from 'src/components/Aside.astro';
Expand All @@ -25,9 +26,9 @@ FusionAuth will also store the Twitch `refresh_token` returned from the Twitch A

<TokenStorageNote idp_long_lived_token_type="refresh"
idp_refresh_additional_info_url="https://dev.twitch.tv/docs/authentication/refresh-tokens/"
idp_display_name="Twitch"
manual_idp_display_name={frontmatter.idpDisplayName}
token_name="refresh_token"
return_text="Twitch API"
hide_token_map_deprecation="true" />

<OauthIdpOperations idp_long_lived_token_type="refresh" idp_refresh_additional_info_url="https://dev.twitch.tv/docs/authentication/refresh-tokens/" idp_display_name="Twitch" idp_id="bf4cf83f-e824-42d7-b4a3-5b10847a66b2" idp_linking_strategy="CreatePendingLink" idp_lowercase="twitch" idp_since="12800" idp_token_or_code="token or code" idp_type="Twitch" />
<OauthIdpOperations idp_long_lived_token_type="refresh" idp_refresh_additional_info_url="https://dev.twitch.tv/docs/authentication/refresh-tokens/" manual_idp_display_name={frontmatter.idpDisplayName} idp_id="bf4cf83f-e824-42d7-b4a3-5b10847a66b2" idp_linking_strategy="CreatePendingLink" idp_lowercase="twitch" idp_since="12800" idp_token_or_code="token or code" idp_type="Twitch" />