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.

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

oauth sso bootstrap documentation #3539

Open
wants to merge 2 commits into
base: main
Choose a base branch
from

Conversation

lyleschemmerling
Copy link
Contributor

doc for the sso bootstrap

@Copilot Copilot bot review requested due to automatic review settings February 27, 2025 17:49
@lyleschemmerling lyleschemmerling requested review from a team as code owners February 27, 2025 17:49

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot reviewed 9 out of 9 changed files in this pull request and generated no comments.


In order to use this feature you must enable the setting on the tenant either via the <InlineField>Allow access token bootstrap</InlineField> setting in the [Admin UI](/docs/get-started/core-concepts/tenants#oauth) or by setting the `tenant.ssoConfiguration.allowAccessTokenBootstrap` field to `true` in the [Tenant API](/docs/apis/tenants).

Because browsers do not provide a way to set the `Authorization` header in a redirect, you must use a server-side proxy to make the request to FusionAuth. The proxy will need to set the `Authorization` header in the redirect of the browser to the `/oauth2/authorize` endpoint.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we provide an example of Bearer token usage?


In certain scenarios you may have authenticated a user outside of the typical OAuth flow. In such cases you can still acquire an SSO session from FusionAuth as long as you have a valid access token for the user. The way to do this is to redirect the browser to the `/oauth2/authorize` endpoint and provide the access token JWT as a Bearer token in the `Authorization` header. If the token is valid, FusionAuth will create an SSO session and redirect the browser back to the `redirect_uri` you provided.

In order to use this feature you must enable the setting on the tenant either via the <InlineField>Allow access token bootstrap</InlineField> setting in the [Admin UI](/docs/get-started/core-concepts/tenants#oauth) or by setting the `tenant.ssoConfiguration.allowAccessTokenBootstrap` field to `true` in the [Tenant API](/docs/apis/tenants).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see other places we use InlineField for API fields.

Suggested change
In order to use this feature you must enable the setting on the tenant either via the <InlineField>Allow access token bootstrap</InlineField> setting in the [Admin UI](/docs/get-started/core-concepts/tenants#oauth) or by setting the `tenant.ssoConfiguration.allowAccessTokenBootstrap` field to `true` in the [Tenant API](/docs/apis/tenants).
In order to use this feature you must enable the setting on the tenant either via the <InlineField>Allow access token bootstrap</InlineField> setting in the [Admin UI](/docs/get-started/core-concepts/tenants#oauth) or by setting the <InlineField>tenant.ssoConfiguration.allowAccessTokenBootstrap</InlineField> field to `true` in the [Tenant API](/docs/apis/tenants).

### Bootstrapping SSO via Proxy
<Aside type="version">Available in FusionAuth 1.56.0</Aside>

In certain scenarios you may have authenticated a user outside of the typical OAuth flow. In such cases you can still acquire an SSO session from FusionAuth as long as you have a valid access token for the user. The way to do this is to redirect the browser to the `/oauth2/authorize` endpoint and provide the access token JWT as a Bearer token in the `Authorization` header. If the token is valid, FusionAuth will create an SSO session and redirect the browser back to the `redirect_uri` you provided.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Redirecting "back" implies that they are returning to the page they came from, but that may not be the case. The "of" is a personal preference, but I've seen style guides suggest it's redundant in cases like this.

Suggested change
In certain scenarios you may have authenticated a user outside of the typical OAuth flow. In such cases you can still acquire an SSO session from FusionAuth as long as you have a valid access token for the user. The way to do this is to redirect the browser to the `/oauth2/authorize` endpoint and provide the access token JWT as a Bearer token in the `Authorization` header. If the token is valid, FusionAuth will create an SSO session and redirect the browser back to the `redirect_uri` you provided.
In certain scenarios you may have authenticated a user outside the typical OAuth flow. In such cases you can still acquire an SSO session from FusionAuth as long as you have a valid access token for the user. The way to do this is to redirect the browser to the `/oauth2/authorize` endpoint and provide the access token JWT as a Bearer token in the `Authorization` header. If the token is valid, FusionAuth will create an SSO session and redirect the browser to the `redirect_uri` you provided.

### Bootstrapping SSO via Proxy
<Aside type="version">Available in FusionAuth 1.56.0</Aside>

In certain scenarios you may have authenticated a user outside of the typical OAuth flow. In such cases you can still acquire an SSO session from FusionAuth as long as you have a valid access token for the user. The way to do this is to redirect the browser to the `/oauth2/authorize` endpoint and provide the access token JWT as a Bearer token in the `Authorization` header. If the token is valid, FusionAuth will create an SSO session and redirect the browser back to the `redirect_uri` you provided.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Removed redirect because we actually don't know if this is a redirect vs. someone just clicking a link. And some suggested rewording.

Suggested change
In certain scenarios you may have authenticated a user outside of the typical OAuth flow. In such cases you can still acquire an SSO session from FusionAuth as long as you have a valid access token for the user. The way to do this is to redirect the browser to the `/oauth2/authorize` endpoint and provide the access token JWT as a Bearer token in the `Authorization` header. If the token is valid, FusionAuth will create an SSO session and redirect the browser back to the `redirect_uri` you provided.
In certain scenarios you may have authenticated a user outside of the typical OAuth flow. In such cases you can still acquire an SSO session from FusionAuth as long as you have a valid access token for the user. To do this, take the user's browser to the `/oauth2/authorize` endpoint and provide the access token JWT as a Bearer token in the `Authorization` header. If the token is valid, FusionAuth will create an SSO session and redirect the browser to the `redirect_uri` you provided. The `redirect_uri` must be an authorized URI, registered with the given application. See the [OAuth Authorize](/docs/lifecycle/authenticate-users/oauth/endpoints#authorize) documentation for details.


In order to use this feature you must enable the setting on the tenant either via the <InlineField>Allow access token bootstrap</InlineField> setting in the [Admin UI](/docs/get-started/core-concepts/tenants#oauth) or by setting the `tenant.ssoConfiguration.allowAccessTokenBootstrap` field to `true` in the [Tenant API](/docs/apis/tenants).

Because browsers do not provide a way to set the `Authorization` header in a redirect, you must use a server-side proxy to make the request to FusionAuth. The proxy will need to set the `Authorization` header in the redirect of the browser to the `/oauth2/authorize` endpoint.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Because browsers do not provide a way to set the `Authorization` header in a redirect, you must use a server-side proxy to make the request to FusionAuth. The proxy will need to set the `Authorization` header in the redirect of the browser to the `/oauth2/authorize` endpoint.
Note that because browsers do not provide a way to set the `Authorization` header when browsing to a location, you will need to add that header using a reverse proxy or some other method.
The header will need to be in the following form:
<code-replaceme>
Authorization: Bearer <access token>
</code-replaceme>

@@ -355,6 +355,17 @@ If you are looking to integrate with a commercial off the shelf or open source s

Please see the [SAML IdP](/docs/lifecycle/authenticate-users/saml/) and [OIDC documentation](/docs/lifecycle/authenticate-users/oauth/) or the single sign-on documentation for the application you're looking to integrate with for more.

### Bootstrapping SSO via Proxy
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
### Bootstrapping SSO via Proxy
### Bootstrapping SSO Session After Login

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants