diff --git a/astro/src/components/quickstarts/DockerSpinup.astro b/astro/src/components/quickstarts/DockerSpinup.astro new file mode 100644 index 0000000000..085df87038 --- /dev/null +++ b/astro/src/components/quickstarts/DockerSpinup.astro @@ -0,0 +1,59 @@ +--- +import Aside from 'src/components/Aside.astro'; +import Code from 'astro/components/Code.astro'; +import { RemoteValue } from '@fusionauth/astro-components'; + +export interface Props { + /** + * Full URI to extract values from kickstart.json + * e.g. https://raw.githubusercontent.com/FusionAuth/fusionauth-quickstart-ruby-on-rails-web/main/kickstart/kickstart.json + */ + kickstartUri: string; + + /** + * Flag that indicates whether this in API quickstart or not (default) + */ + api?: boolean; +} + +const { kickstartUri, api = false } = Astro.props as Props; +--- +

You'll find a Docker Compose file (docker-compose.yml) and an environment variables configuration file (.env) in the root directory of the repo.

+ +

Assuming you have Docker installed, you can stand up FusionAuth on your machine with the following.

+ + + +

Here you are using a bootstrapping feature of FusionAuth called Kickstart. When FusionAuth comes up for the first time, it will look at the kickstart/kickstart.json file and configure FusionAuth to your specified state.

+ + + +

FusionAuth will be initially configured with these settings:

+ + + +

You can log in to the FusionAuth admin UI and look around if you want to, but with Docker and Kickstart, everything will already be configured correctly.

+ + + + diff --git a/astro/src/components/quickstarts/Intro.astro b/astro/src/components/quickstarts/Intro.astro new file mode 100644 index 0000000000..668c05472a --- /dev/null +++ b/astro/src/components/quickstarts/Intro.astro @@ -0,0 +1,49 @@ +--- +/** + * Using parenthesis due to @link https://github.com/withastro/compiler/issues/749 + */ +type InnerProps = ({ + /** + * Technology used to build the application. + */ + technology: string; + /** + * Indicate that this intro is for API quickstarts. + * @default false + */ + api?: boolean; +} | { + /** + * If the default "you are going to build an application with text doesn't apply, you can pass the + * entire text here. + */ + fulltext: string; +}); + +export type Props = (InnerProps & { + /** + * URL for the source code location + */ + repositoryUrl: string; +}); + +const { technology, fulltext, repositoryUrl, api = false } = Astro.props as Props; +--- +{(api) ? ( +

+ In this quickstart, you are going to learn how to integrate a {technology} resource server with FusionAuth. + You will protect an API resource from unauthorized usage. + You’ll be building it for ChangeBank, a global leader in converting dollars into coins. + +

+) : ( +

+ In this quickstart, you are going to build {fulltext || `an application with ${technology}`} and integrate it with FusionAuth. + You’ll be building it for ChangeBank, a global leader in converting dollars into coins. + It’ll have areas reserved for users who have logged in as well as public facing sections. + +

+)} +

+ The Docker Compose file and source code for a complete application are available at {repositoryUrl}. +

diff --git a/astro/src/components/quickstarts/LoginArchitectureApi.astro b/astro/src/components/quickstarts/LoginArchitectureApi.astro new file mode 100644 index 0000000000..b1b3d53a38 --- /dev/null +++ b/astro/src/components/quickstarts/LoginArchitectureApi.astro @@ -0,0 +1,8 @@ +--- +import Diagram from 'src/diagrams/quickstarts/resource-server.astro'; +--- +

A client wants access to an API resource at /resource. However, it is denied this resource until it acquires an access token from FusionAuth.

+ + + +

While the access token is acquired via the Login API above, this is for simplicity of illustration. The token can be, and typically is, acquired through one of the OAuth grants.

diff --git a/astro/src/components/quickstarts/LoginArchitectureNative.astro b/astro/src/components/quickstarts/LoginArchitectureNative.astro new file mode 100644 index 0000000000..a504b0162b --- /dev/null +++ b/astro/src/components/quickstarts/LoginArchitectureNative.astro @@ -0,0 +1,15 @@ +--- +import LoginAfterNative from 'src/diagrams/quickstarts/login-after-native.astro'; +import LoginBeforeNative from 'src/diagrams/quickstarts/login-before-native.astro'; +--- +

While this sample application doesn't have login functionality without FusionAuth, a more typical integration will replace an existing login system with FusionAuth.

+ +

In that case, the system might look like this before FusionAuth is introduced.

+ + + +

The login flow will look like this after FusionAuth is introduced.

+ + + +

In general, you are introducing FusionAuth in order to normalize and consolidate user data. This helps make sure it is consistent and up-to-date as well as offloading your login security and functionality to FusionAuth.

diff --git a/astro/src/components/quickstarts/LoginArchitectureSdk.astro b/astro/src/components/quickstarts/LoginArchitectureSdk.astro new file mode 100644 index 0000000000..88b2aae924 --- /dev/null +++ b/astro/src/components/quickstarts/LoginArchitectureSdk.astro @@ -0,0 +1,14 @@ +--- +import LoginAfterSdk from 'src/diagrams/quickstarts/login-after-sdk.astro'; +import LoginBefore from 'src/diagrams/quickstarts/login-before.astro'; +--- +

While this sample application doesn't have login functionality without FusionAuth, a more typical integration will replace an existing login system with FusionAuth.

+

In that case, the system might look like this before FusionAuth is introduced.

+ + + +

The login flow will look like this after FusionAuth is introduced.

+ + + +

In general, you are introducing FusionAuth in order to normalize and consolidate user data. This helps make sure it is consistent and up-to-date as well as offloading your login security and functionality to FusionAuth.

diff --git a/astro/src/components/quickstarts/LoginArchitectureWeb.astro b/astro/src/components/quickstarts/LoginArchitectureWeb.astro new file mode 100644 index 0000000000..903ab54cfb --- /dev/null +++ b/astro/src/components/quickstarts/LoginArchitectureWeb.astro @@ -0,0 +1,29 @@ +--- +import LoginAfter from 'src/diagrams/quickstarts/login-after.astro'; +import LoginBefore from 'src/diagrams/quickstarts/login-before.astro'; + +export interface Props { + /** + * Custom introduction text if the default one doesn't apply + */ + intro?: string; +} + +const { intro } = Astro.props; + +--- +{(intro) + ? (

{intro}

) + : ( +

While this sample application doesn't have login functionality without FusionAuth, a more typical integration will replace an existing login system with FusionAuth.

+

In that case, the system might look like this before FusionAuth is introduced.

+ ) +} + + + +

The login flow will look like this after FusionAuth is introduced.

+ + + +

In general, you are introducing FusionAuth in order to normalize and consolidate user data. This helps make sure it is consistent and up-to-date as well as offloading your login security and functionality to FusionAuth.

diff --git a/astro/src/components/quickstarts/NextSteps.astro b/astro/src/components/quickstarts/NextSteps.astro new file mode 100644 index 0000000000..45ee711ef6 --- /dev/null +++ b/astro/src/components/quickstarts/NextSteps.astro @@ -0,0 +1,27 @@ +

This quickstart is a great way to get a proof of concept up and running quickly, but to run your application in production, there are some things you're going to want to do.

+ +

FusionAuth Customization

+ +

FusionAuth gives you the ability to customize just about everything to do with the user's experience and the integration of your application. This includes:

+ + + +

Security

+ + + +

Tenant and Application Management

+ + diff --git a/astro/src/components/quickstarts/NextStepsApi.astro b/astro/src/components/quickstarts/NextStepsApi.astro new file mode 100644 index 0000000000..96dc46fa94 --- /dev/null +++ b/astro/src/components/quickstarts/NextStepsApi.astro @@ -0,0 +1,16 @@ +

This quickstart is a great way to get a proof of concept up and running quickly, but to run your API in production, there are some things you're going to want to do.

+ +

FusionAuth Integration

+ +
    +
  • Rather than call the Login API, you're probably going to want to use the Authorization Code grant, which keeps all sensitive credentials within the bounds of FusionAuth. You can customize the hosted login pages.
    • +
  • You may want to generate a token using the Client Credentials grant if you are calling the API from another service.
    • +
+ +

Security

+ + diff --git a/astro/src/content/config.js b/astro/src/content/config.js index 44fd8bcb36..cf3e8cdb96 100644 --- a/astro/src/content/config.js +++ b/astro/src/content/config.js @@ -43,6 +43,7 @@ const quickstartsCollection = defineCollection({ featured: z.boolean().default(false), faIcon: z.string().optional(), color: z.string().optional(), + codeRoot: z.string().optional(), }), }); diff --git a/astro/src/content/quickstarts/5-minute-docker.mdx b/astro/src/content/quickstarts/5-minute-docker.mdx index 68ef10df4c..993f4ed61a 100644 --- a/astro/src/content/quickstarts/5-minute-docker.mdx +++ b/astro/src/content/quickstarts/5-minute-docker.mdx @@ -1,6 +1,6 @@ --- title: Docker Install For the 5-Minute Guide -description: Use Docker and docker compose for the 5-minute guide. +description: Use Docker and Docker Compose for the 5-minute guide. section: five-minute icon: /img/icons/5minute-docker.svg faIcon: fa-gem @@ -20,9 +20,9 @@ import FiveMinuteSummingUp from 'src/content/quickstarts/_5-minute-summing-up.md import { YouTube } from '@astro-community/astro-embed-youtube'; -You've chosen to install FusionAuth via docker and docker compose. +You've chosen to install FusionAuth via Docker and Docker Compose. -This is the best option if you have docker installed locally or you plan to run FusionAuth in a Docker compatible environment such as Kubernetes and want to learn more about how FusionAuth runs in Docker. +This is the best option if you have Docker installed locally or you plan to run FusionAuth in a Docker compatible environment such as Kubernetes and want to learn more about how FusionAuth runs in Docker. If you've arrived here directly, start with the [5-Minute Setup Guide Overview](/docs/quickstarts/5-minute-setup-guide). @@ -50,7 +50,7 @@ Here are steps to take to set up FusionAuth and configure it to provide login an ## 1. Install and Start FusionAuth -You are following the Docker 5 minute guide, so you'll use `docker-compose`. +You are following the Docker 5 minute guide, so you'll use `docker compose`. @@ -93,4 +93,4 @@ And that's it! Docker makes standing up a FusionAuth instance a snap. Next, crea ## 9. Summing Up - \ No newline at end of file + diff --git a/astro/src/content/quickstarts/quickstart-android-java-native.mdx b/astro/src/content/quickstarts/quickstart-android-java-native.mdx index f5809a688e..2369fd16ce 100644 --- a/astro/src/content/quickstarts/quickstart-android-java-native.mdx +++ b/astro/src/content/quickstarts/quickstart-android-java-native.mdx @@ -12,17 +12,16 @@ color: indigo cta: EmailListCTA --- import Aside from '../../components/Aside.astro'; -import LoginAfter from '../../diagrams/quickstarts/login-after-native.astro'; -import LoginBefore from '../../diagrams/quickstarts/login-before-native.astro'; +import DockerSpinup from '/src/components/quickstarts/DockerSpinup.astro'; import IconButton from '../../components/IconButton.astro'; +import Intro from '/src/components/quickstarts/Intro.astro'; +import LoginArchitectureWeb from '/src/components/quickstarts/LoginArchitectureWeb.astro'; +import NextSteps from '/src/components/quickstarts/NextSteps.astro'; import {RemoteCode} from '@fusionauth/astro-components'; -In this quickstart you are going to build an Android app with Java and integrate it with FusionAuth. -You'll be building it for [ChangeBank](https://www.youtube.com/watch?v=CXDxNCzUspM), a global leader in converting dollars into coins. -It'll have areas reserved for users who have logged in as well as public facing sections. + -The docker compose file and source code for a complete application are available at -[https://github.com/FusionAuth/fusionauth-quickstart-java-android-native](https://github.com/FusionAuth/fusionauth-quickstart-java-android-native). ## Prerequisites @@ -35,17 +34,7 @@ This app was built on top of [AppAuth](https://github.com/openid/AppAuth-Android ## General Architecture -While this sample application doesn't have login functionality without FusionAuth, a more typical integration will replace an existing login system with FusionAuth. - -In that case, the system might look like this before FusionAuth is introduced. - - - -The login flow will look like this after FusionAuth is introduced. - - - -In general, you are introducing FusionAuth in order to normalize and consolidate user data. This helps make sure it is consistent and up-to-date as well as offloading your login security and functionality to FusionAuth. + ## Getting Started @@ -62,25 +51,7 @@ cd fusionauth-quickstart-java-android-native ### Run FusionAuth via Docker -In the root directory of the repo you'll find a Docker compose file (`docker-compose.yml`) and an environment variables configuration file (`.env`). Assuming you have Docker installed on your machine, you can stand up FusionAuth up on your machine with: - -``` -docker compose up -d -``` - -Here you are using a bootstrapping feature of FusionAuth, called [Kickstart](/docs/get-started/download-and-install/development/kickstart). When FusionAuth comes up for the first time, it will look at the `kickstart/kickstart.json` file and configure FusionAuth to a certain initial state. - - - -FusionAuth will be initially configured with these settings: - -* Your client Id is `e9fdb985-9173-4e01-9d73-ac2d60d1dc8e`. -* Your client secret is `super-secret-secret-that-should-be-regenerated-for-production`. -* Your example username is `richard@example.com` and the password is `password`. -* Your admin username is `admin@example.com` and the password is `password`. -* The base URL of FusionAuth `http://localhost:9011/`. + ### Expose FusionAuth Instance @@ -197,24 +168,12 @@ You can either [connect a hardware device](https://developer.android.com/studio/ ## Next Steps -This quickstart is a great way to get a proof of concept up and running quickly, but to run your application in production, there are some things you're going to want to do. - -### FusionAuth Customization - -FusionAuth gives you the ability to customize just about everything with the user's experience and your application's integration. This includes -* [Hosted pages](/docs/customize/look-and-feel/) such as login, registration, email verification, and many more -* [Email templates](/docs/customize/email-and-messages/email-templates) -* [User data and custom claims in access token JWTs](/articles/tokens/jwt-components-explained) - -### Security -* Implement refresh tokens using [AppAuth](https://github.com/openid/AppAuth-Android) -* You may want to customize the [token expiration times and policies](/docs/lifecycle/authenticate-users/oauth/#configure-application-oauth-settings) in FusionAuth -* Choose [password rules](/docs/get-started/core-concepts/tenants#password) and a [hashing algorithm](/docs/reference/password-hashes) that meet your security needs + + +
  • Implement refresh tokens using [AppAuth](https://github.com/openid/AppAuth-Android).
    • +     +     -### Tenant and Application Management -* Model your application topology using [Applications](/docs/get-started/core-concepts/applications), [Roles](/docs/get-started/core-concepts/roles), [Groups](/docs/get-started/core-concepts/groups), [Entities](/docs/get-started/core-concepts/groups), and more -* Set up [MFA](/docs/lifecycle/authenticate-users/multi-factor-authentication), [Social login](/docs/lifecycle/authenticate-users/identity-providers/), and/or [SAML](/docs/lifecycle/authenticate-users/identity-providers/overview-samlv2) integrations -* Integrate with external systems using [Webhooks](/docs/extend/events-and-webhooks/), [SCIM](/docs/lifecycle/migrate-users/scim/scim), and [Lambdas](/docs/extend/code/lambdas/) ## Troubleshooting diff --git a/astro/src/content/quickstarts/quickstart-dotnet-api.mdx b/astro/src/content/quickstarts/quickstart-dotnet-api.mdx index 7ea00da519..ffe401d1d2 100644 --- a/astro/src/content/quickstarts/quickstart-dotnet-api.mdx +++ b/astro/src/content/quickstarts/quickstart-dotnet-api.mdx @@ -10,16 +10,20 @@ icon: /img/icons/dotnet-c.svg faIcon: fa-gem color: rose cta: EmailListCTA +codeRoot: https://raw.githubusercontent.com/FusionAuth/fusionauth-quickstart-dotnet-api/main --- import Aside from '../../components/Aside.astro'; -import Diagram from '../../diagrams/quickstarts/resource-server.astro'; +import DockerSpinup from '/src/components/quickstarts/DockerSpinup.astro'; import DotNetPreReqs from '../../components/quickstarts/dotnet-prereqs.mdx'; +import Intro from '/src/components/quickstarts/Intro.astro'; +import LoginArchitectureApi from '/src/components/quickstarts/LoginArchitectureApi.astro'; +import NextStepsApi from '/src/components/quickstarts/NextStepsApi.astro'; import {RemoteCode} from '@fusionauth/astro-components'; -In this tutorial, you are going to learn how to integrate a .NET Web API resource server with FusionAuth. You will protect an API resource from unauthorized usage. You'll be building it for [ChangeBank](https://www.youtube.com/watch?v=CXDxNCzUspM), a global leader in converting dollars into coins. - -The docker compose file and source code for a complete application are available at https://github.com/FusionAuth/fusionauth-quickstart-dotnet-api. + ## Prerequisites @@ -27,11 +31,7 @@ The docker compose file and source code for a complete application are available ## General Architecture -A client wants access to an API resource at `/resource`. However, it is denied this resource until it acquires an access token from FusionAuth. - - - -While the access token is acquired via the Login API above, this is for simplicity of illustration. The token can be, and typically is, acquired through one of the [OAuth grants](/docs/lifecycle/authenticate-users/oauth/). + ## Getting Started @@ -49,34 +49,7 @@ cd fusionauth-quickstart-dotnet-api ### Run FusionAuth Via Docker -In the root directory of the repo you’ll find a Docker compose file `docker-compose.yml` and an environment variables configuration file `.env`. Assuming you have Docker installed, you can start FusionAuth on your machine with the following. - -```shell -docker compose up -d -``` - -This will start three containers, one each for FusionAuth, Postgres, and Elasticsearch. - -Here you are using a bootstrapping feature of FusionAuth, called [Kickstart](/docs/get-started/download-and-install/development/kickstart). When FusionAuth starts for the first time, it will look at the `kickstart/kickstart.json` file and configure FusionAuth to your specified state. - - - -FusionAuth will be initially configured with these settings: - -* Your client Id is `e9fdb985-9173-4e01-9d73-ac2d60d1dc8e`. -* Your client secret is `super-secret-secret-that-should-be-regenerated-for-production`. -* Your example teller username is `teller@example.com` and your password is `password`. They will have the role `teller`. -* Your example customer username is `customer@example.com` and your password is `password`. They will have the role `customer`. -* Your admin username is `admin@example.com` and your password is `password`. -* The base URL of FusionAuth is 'http://localhost:9011/'. - -You can log in to the [FusionAuth admin UI](http://localhost:9011/admin) and look around if you want to, but with Docker and Kickstart, everything will already be configured correctly. - - + ## Create Your ASP.NET Web API Resource Server @@ -120,17 +93,17 @@ dotnet add package Microsoft.IdentityModel.Protocols.OpenIdConnect -v 7.0.3 Next, replace your `appsettings.json` file with settings specific to the FusionAuth Issuer and Client Id (Audience). - + Replace the code in the `appsettings.Development.json` file with the following. - + The `appsettings.Development.json` file will be used when you run the application in development mode. It will enable some useful development options, mainly that HTTPS will not be required for the Issuer (FusionAuth) server. In production, you must use HTTPS for the Issuer server. Update the `Program.cs` file to configure ASP.NET authentication to use JWT tokens. Replace the code in the `Program.cs` file with the following code. - The `Program.cs` file configures the authentication services to use JWT bearer tokens to authenticate users through the `.AddJwtBearer()` method. The Issuer and Audience settings used by the JWT verification code are set in the `appsettings.json` file under the `Authentication` section. The `options.Events` section configures the JWT bearer authentication to use the `OnMessageReceived` event to read the JWT from the `app.at` cookie if it is present. By default, the JWT bearer authentication will only read the JWT from the `Authorization` header. With this code, the JWT can be passed in either the `Authorization` header or the `app.at` cookie. @@ -159,7 +132,7 @@ touch Models/PanicResponse.cs Add the following code to it. - Next, you need an object to show the breakdown from making change. This object will hold a double `total` and Integers `nickels` and `pennies`. In the `Models` folder, create a new class `Change.cs`. @@ -170,7 +143,7 @@ touch Models/Change.cs Add the following code to it. - ### Add Controllers @@ -183,7 +156,7 @@ touch Controllers/MakeChangeController.cs Add the following code to it. - In this class, a `total` is an HTTP request query parameter that is converted to a `double`, and the `get` method divides the `total` into `nickels` and `pennies` and returns the response object. @@ -221,7 +194,7 @@ touch Controllers/PanicController.cs Add the following code to it. - This class listens on `/panic` for a POST request and returns a response indicating that the police were called. The attributes are the same as the `MakeChangeController.cs` route, except that this is a `POST` request, so it is named `Post` and has the `[HttpPost]` attribute marking it as such. @@ -409,18 +382,7 @@ Enjoy your secured resource server! ## Next Steps -This quickstart is a great way to get a proof of concept up and running quickly, but to run your API in production, there are some things you're going to want to do. - -### FusionAuth Integration - -* Rather than call the Login API, you're probably going to want to use the [Authorization Code grant](/docs/lifecycle/authenticate-users/oauth/#example-authorization-code-grant), which keeps all sensitive credentials within the bounds of FusionAuth. You can customize the [hosted login pages](/docs/customize/look-and-feel/). -* You may want to generate a token using the [Client Credentials grant](/docs/lifecycle/authenticate-users/oauth/#example-client-credentials-grant) if you are calling the API from another service. - -### Security - -* Customize the [token expiration times and policies](/docs/lifecycle/authenticate-users/oauth/#configure-application-oauth-settings) in FusionAuth -* [Make sure you know how to securely consume a token](/articles/tokens/building-a-secure-jwt#consuming-a-jwt) -* Secure your API [using an API gateway](/docs/extend/examples/api-gateways/) rather than at the framework layer. + ## Troubleshooting diff --git a/astro/src/content/quickstarts/quickstart-dotnet-web.mdx b/astro/src/content/quickstarts/quickstart-dotnet-web.mdx index 28cfcd9f5c..f6284b28e4 100644 --- a/astro/src/content/quickstarts/quickstart-dotnet-web.mdx +++ b/astro/src/content/quickstarts/quickstart-dotnet-web.mdx @@ -10,18 +10,17 @@ icon: /img/icons/dotnet-c.svg faIcon: fa-gem color: rose cta: EmailListCTA -coderoot: https://raw.githubusercontent.com/FusionAuth/fusionauth-quickstart-dotnet-web/main +codeRoot: https://raw.githubusercontent.com/FusionAuth/fusionauth-quickstart-dotnet-web/main --- import Aside from '../../components/Aside.astro'; -import LoginAfter from '../../diagrams/quickstarts/login-after.astro'; -import LoginBefore from '../../diagrams/quickstarts/login-before.astro'; +import DockerSpinup from '/src/components/quickstarts/DockerSpinup.astro'; +import Intro from '/src/components/quickstarts/Intro.astro'; +import LoginArchitectureWeb from '/src/components/quickstarts/LoginArchitectureWeb.astro'; +import NextSteps from '/src/components/quickstarts/NextSteps.astro'; import {RemoteCode} from '@fusionauth/astro-components'; -In this quickstart you are going to build an application with C# and .NET and integrate it with FusionAuth. -You'll be building it for [ChangeBank](https://www.youtube.com/watch?v=CXDxNCzUspM), a global leader in converting dollars into coins. -It'll have areas reserved for users who have logged in as well as public facing sections. - -The docker compose file and source code for a complete application are available on github under [fusionauth-quickstart-dotnet-web](https://github.com/FusionAuth/fusionauth-quickstart-dotnet-web) project. + ## Prerequisites @@ -31,17 +30,7 @@ The docker compose file and source code for a complete application are available ## General Architecture -While this sample application doesn't have login functionality without FusionAuth, a more typical integration will replace an existing login system with FusionAuth. - -In that case, the system might look like this before FusionAuth is introduced. - - - -The login flow will look like this after FusionAuth is introduced. - - - -In general, you are introducing FusionAuth in order to normalize and consolidate user data. This helps make sure it is consistent and up-to-date as well as offloading your login security and functionality to FusionAuth. + ## Getting Started @@ -58,27 +47,7 @@ cd fusionauth-quickstart-dotnet-web ### Run FusionAuth via Docker -In the root directory of the repo you'll find a Docker compose file (docker-compose.yml) and an environment variables configuration file (.env). Assuming you have Docker installed on your machine, you can stand up FusionAuth up on your machine with: - -``` -docker compose up -d -``` - -Here you are using a bootstrapping feature of FusionAuth, called [Kickstart](/docs/get-started/download-and-install/development/kickstart) When FusionAuth comes up for the first time, it will look at the `kickstart/kickstart.json` file and configure FusionAuth to a certain initial state. - - - -FusionAuth will be initially configured with these settings: - -* Your client Id is `e9fdb985-9173-4e01-9d73-ac2d60d1dc8e`. -* Your client secret is `super-secret-secret-that-should-be-regenerated-for-production`. -* Your example username is `richard@example.com` and the password is `password`. -* Your admin username is `admin@example.com` and the password is `password`. -* The base URL of FusionAuth `http://localhost:9011/`. - -You can log into the [FusionAuth admin UI](http://localhost:9011/admin) and look around if you want, but with Docker/Kickstart you don't need to. + ### Create your .NET 7 Application @@ -146,24 +115,24 @@ Create `Account.cshtml` and `Account.cshtml.cs` in the `Pages` directory. To pro Copy the following code into `Account.cshtml.cs`: - Copy the following code into `Account.cshtml`: - Create `MakeChange.cshtml` and `MakeChange.cshtml.cs` in the `Pages` directory. You will use the same [Authorize filter attribute](https://docs.microsoft.com/en-us/aspnet/core/razor-pages/filter?view=aspnetcore-3.1#authorize-filter-attribute) to secure the page. Copy the following code into `MakeChange.cshtml.cs`: - Copy the following code into `MakeChange.cshtml`: - You will need a way to allow the user to logout of the application as well. You'll build the logout functionality in the `Logout` page. This will: @@ -175,14 +144,14 @@ FusionAuth will then destroy its session and redirect the user back to the app's Add the following file to the `Pages` directory and call it `Logout.cshtml.cs`: - `OnGet` is the important method. Here you sign out using a method of the authentication library, delete the JWT cookie, and send the user to the FusionAuth OAuth logout endpoint. Now add `Logout.cshtml` to the `Pages` directory. No content is necessary. Just declare the page and model as shown below. - ### Application Configuration @@ -191,19 +160,19 @@ You will need to do a little plumbing to ensure things like having the correct s #### App Settings Replace the text in the `appsettings.json` file with the text below. The important part here is that we are adding the `FusionAuthSettings` section so that the code above will run with the correct configuration settings. `Authority` is just the location of the user identity server, in this case, FusionAuth. `Urls` ensures the application runs on the specified port, 5000. - #### Program Settings Replace the text in the `Program.cs` file. Since you are using unsecured cookies, you need to allow this in the configuration. Safari and Chrome require different settings and that is reflected in the code below. - #### Startup Settings Add the `Startup.cs` file in the root directory of the application. This sets the correct port and manages unsecured cookies for the browsers. The `CheckSameSite` and `DisallowsSameSiteNone` functions help manage the cookie settings for the different browsers. - - Then add the code to compare the required roles to the user's roles based on the token. - Finally you will add two helper functions. `GetFunctionName` will return the name of the function being called by the endpoint. `SetWriterReturn` will format the response properly. - That is all the code for the sample application. Save the `main.go` file. @@ -389,17 +367,7 @@ Looks like this user does not have access to this function. Enjoy your secured r ## Next Steps -This quickstart is a great way to get a proof of concept up and running quickly, but to run your API in production, there are some things you're going to want to do. - -### FusionAuth Integration - -* Rather than call the Login API, you're probably going to want to use the [Authorization Code grant](/docs/lifecycle/authenticate-users/oauth/#example-authorization-code-grant), which keeps all sensitive credentials within the bounds of FusionAuth. You can customize the [hosted login pages](/docs/apis/themes). -* You may want to generate a token using the [Client Credentials grant](/docs/lifecycle/authenticate-users/oauth/#example-client-credentials-grant) if you are calling the API from another service. - -### Security -* Customize the [token expiration times and policies](/docs/lifecycle/authenticate-users/oauth/#configure-application-oauth-settings) in FusionAuth -* [Make sure you know how to securely consume a token](/articles/tokens/building-a-secure-jwt#consuming-a-jwt) -* Secure your API [using an API gateway](/docs/extend/examples/api-gateways/) rather than at the framework layer. + ## Troubleshooting diff --git a/astro/src/content/quickstarts/quickstart-golang-web.mdx b/astro/src/content/quickstarts/quickstart-golang-web.mdx index 88d882baa5..4a4320f7d3 100644 --- a/astro/src/content/quickstarts/quickstart-golang-web.mdx +++ b/astro/src/content/quickstarts/quickstart-golang-web.mdx @@ -9,21 +9,19 @@ language: Golang icon: /img/icons/golang.svg faIcon: fa-g color: blue -coderoot: https://raw.githubusercontent.com/FusionAuth/fusionauth-quickstart-golang-web/main +codeRoot: https://raw.githubusercontent.com/FusionAuth/fusionauth-quickstart-golang-web/main cta: EmailListCTA --- import Aside from '/src/components/Aside.astro'; -import LoginAfter from '../../diagrams/quickstarts/login-after.astro'; -import LoginBefore from '../../diagrams/quickstarts/login-before.astro'; +import DockerSpinup from '/src/components/quickstarts/DockerSpinup.astro'; +import Intro from '/src/components/quickstarts/Intro.astro'; +import LoginArchitectureWeb from '/src/components/quickstarts/LoginArchitectureWeb.astro'; +import NextSteps from '/src/components/quickstarts/NextSteps.astro'; import {RemoteCode} from '@fusionauth/astro-components'; -In this quickstart you are going to build an application with Go and integrate it with FusionAuth. -You'll be building it for [ChangeBank](https://www.youtube.com/watch?v=CXDxNCzUspM), a global leader in converting dollars into coins. -It'll have areas reserved for users who have logged in as well as public facing sections. - -The docker compose file and source code for a complete application are available at -https://github.com/FusionAuth/fusionauth-quickstart-golang-web + ## Prerequisites * [Go v1.16](https://go.dev/doc/install) @@ -31,17 +29,7 @@ https://github.com/FusionAuth/fusionauth-quickstart-golang-web ## General Architecture -While this sample application doesn't have login functionality without FusionAuth, a more typical integration will replace an existing login system with FusionAuth. - -In that case, the system might look like this before FusionAuth is introduced. - - - -The login flow will look like this after FusionAuth is introduced. - - - -In general, you are introducing FusionAuth in order to normalize and consolidate user data. This helps make sure it is consistent and up-to-date as well as offloading your login security and functionality to FusionAuth. + ## Getting Started In this section, you'll get FusionAuth up and running, and configured with the ChangeBank application. @@ -56,33 +44,7 @@ cd fusionauth-quickstart-golang-web ### Run FusionAuth via Docker -In the root directory of the repo you'll find a Docker compose file (docker-compose.yml) and an environment -variables configuration file (.env). Assuming you have Docker installed on your machine, you can stand up -FusionAuth up on your machine with: - -``` -docker compose up -d -``` - -This will start three containers, once each for FusionAuth, Postgres, and Elastic. - -Here you are using a bootstrapping feature of FusionAuth, called [Kickstart](/docs/get-started/download-and-install/development/kickstart). -When FusionAuth comes up for the first time, it will look at the `kickstart/kickstart.json` file and -configure FusionAuth to a certain initial state. - - - -FusionAuth will be configured with these settings -* Your client Id is `e9fdb985-9173-4e01-9d73-ac2d60d1dc8e`. -* Your client secret is `super-secret-secret-that-should-be-regenerated-for-production`. -* Your example username is `richard@example.com` and the password is `password`. -* Your admin username is `admin@example.com` and the password is `password`. -* The base URL of FusionAuth `http://localhost:9011/`. - -You can log into the [FusionAuth admin UI](http://localhost:9011/admin) and look around if you want, but with Docker/Kickstart you don’t need to. + ### Create a Basic Golang Application In this section, you'll set up a basic Golang application with a single page. @@ -98,7 +60,7 @@ cd changebank Create a go.mod file listing these dependencies: `go.mod` - #### Create the Application @@ -109,7 +71,7 @@ This app sets up a handful of routes that just serve a home page for now. Over t you'll be modifying each of these route handler functions to complete the integration with FusionAuth. `main.go` - @@ -161,7 +123,7 @@ The CoreOS OpenID Connect client needs to be set up so that it knows how to talk First, create some constants that you can use throughout your program. Put these after your `import` block and before `func main()`. - @@ -176,13 +138,13 @@ find the client id and client secret values in the `OAuth configuration` section Next, create variables for the OAuth config and the OIDC provider, and initialize them in an `init()` function. Put this code after the `const` block you just added. - You'll also need to add some additional imports. Modify your `import` block to look like this. - @@ -192,7 +154,7 @@ taken to your `/login` endpoint. Have this redirect them to FusionAuth so that FusionAuth can present them with a login page. Change the `handleLoginRequest` function to do that. - @@ -210,7 +172,7 @@ as well as a valid client ID and client secret. Modify the `handleFusionAuthCallback` function to do this. - @@ -226,7 +188,7 @@ should just be taken to the home page. Edit the `handleAccount()` function to do this. There is also a `getLogoutUrl()` function that you'll need to add. - @@ -238,7 +200,7 @@ At this point, you should be able to successfully log into your application! Next you'll modify the `handleMain()` function to automatically take a logged-in user to their account page. - @@ -250,7 +212,7 @@ application created, clearing the user's session. Update the `handleLogout()` function to do this. - @@ -259,21 +221,5 @@ Click the `Logout` button and watch the browser first go to FusionAuth to log ou ## Next Steps -This quickstart is a great way to get a proof of concept up and running quickly, but to run -your application in production, there are some things you're going to want to do. - -### FusionAuth Customization -FusionAuth gives you the ability to customize just about everything with the user's experience and your application's integration. This includes -* [Hosted pages](/docs/customize/look-and-feel/) such as login, registration, email verification, and many more -* [Email templates](/docs/customize/email-and-messages/email-templates) -* [User data and custom claims in access token JWTs](/articles/tokens/jwt-components-explained) - -### Security -* You may want to customize the [token expiration times and policies](/docs/lifecycle/authenticate-users/oauth/#configure-application-oauth-settings) in FusionAuth -* Choose [password rules](/docs/get-started/core-concepts/tenants#password) and a [hashing algorithm](/docs/reference/password-hashes) that meet your security needs - -### Tenant and Application Management -* Model your application topology using [Applications](/docs/get-started/core-concepts/applications), [Roles](/docs/get-started/core-concepts/roles), [Groups](/docs/get-started/core-concepts/groups), [Entities](/docs/get-started/core-concepts/groups), and more -* Set up [MFA](/docs/lifecycle/authenticate-users/multi-factor-authentication), [Social login](/docs/lifecycle/authenticate-users/identity-providers/), and/or [SAML](/docs/lifecycle/authenticate-users/identity-providers/overview-samlv2) integrations -* Integrate with external systems using [Webhooks](/docs/extend/events-and-webhooks/), [SCIM](/docs/lifecycle/migrate-users/scim/scim), and [Lambdas](/docs/extend/code/lambdas/) + diff --git a/astro/src/content/quickstarts/quickstart-java-springboot-api.mdx b/astro/src/content/quickstarts/quickstart-java-springboot-api.mdx index f16ae0db01..ba37a70a5b 100644 --- a/astro/src/content/quickstarts/quickstart-java-springboot-api.mdx +++ b/astro/src/content/quickstarts/quickstart-java-springboot-api.mdx @@ -10,15 +10,19 @@ icon: /img/icons/spring.svg faIcon: fa-leaf color: green cta: EmailListCTA +codeRoot: https://raw.githubusercontent.com/FusionAuth/fusionauth-quickstart-java-springboot-api/main --- import Aside from '../../components/Aside.astro'; -import Diagram from '../../diagrams/quickstarts/resource-server.astro'; +import DockerSpinup from '/src/components/quickstarts/DockerSpinup.astro'; +import Intro from '/src/components/quickstarts/Intro.astro'; +import LoginArchitectureApi from '/src/components/quickstarts/LoginArchitectureApi.astro'; +import NextStepsApi from '/src/components/quickstarts/NextStepsApi.astro'; import SpringBootPreReqs from '../../components/quickstarts/springboot-prereqs.mdx'; import {RemoteCode} from '@fusionauth/astro-components'; -In this tutorial, you are going to learn how to integrate a Java Spring Boot resource server with FusionAuth. You will protect an API resource from unauthorized usage. You'll be building it for [ChangeBank](https://www.youtube.com/watch?v=CXDxNCzUspM), a global leader in converting dollars into coins. - -The docker compose file and source code for a complete application are available at https://github.com/FusionAuth/fusionauth-quickstart-java-springboot-api. + ## Prerequisites @@ -26,11 +30,7 @@ The docker compose file and source code for a complete application are available ## General Architecture -A client wants access to an API resource at `/resource`. However, it is denied this resource until it acquires an access token from FusionAuth. - - - -While the access token is acquired via the Login API above, this is for simplicity of illustration. The token can be, and typically is, acquired through one of the [OAuth grants](/docs/lifecycle/authenticate-users/oauth/). + ## Getting Started @@ -47,28 +47,7 @@ cd fusionauth-quickstart-java-springboot-api ### Run FusionAuth Via Docker -In the root directory of the repo you’ll find a Docker compose file (docker-compose.yml) and an environment variables configuration file (.env). Assuming you have Docker installed on your machine, you can stand up FusionAuth up on your machine with: - -``` -docker compose up -d -``` - -Here you are using a bootstrapping feature of FusionAuth, called [Kickstart](/docs/get-started/download-and-install/development/kickstart). When FusionAuth comes up for the first time, it will look at the `kickstart/kickstart.json` file and configure FusionAuth to a certain initial state. - - - -FusionAuth will be initially configured with these settings: - -* Your client Id is: `e9fdb985-9173-4e01-9d73-ac2d60d1dc8e` -* Your client secret is: `super-secret-secret-that-should-be-regenerated-for-production` -* Your example teller username is `teller@example.com` and your password is `password`. They will have the role `teller`. -* Your example customer username is `customer@example.com` and your password is `password`. They will have the role `customer`. -* Your admin username is `admin@example.com` and your password is `password`. -* Your fusionAuthBaseUrl is 'http://localhost:9011/' - -You can log into the [FusionAuth admin UI](http://localhost:9011/admin) and look around if you want, but with Docker/Kickstart you don't need to. + ## Create Your Spring Boot Resource Server Application @@ -126,7 +105,7 @@ rmdir springapi Open `src/main/resources/application.properties`. - We need two properties here: @@ -145,19 +124,19 @@ This tutorial puts all these classes in the same package for simplicity, but for We will need response objects for the API to return. One is the `PanicResponse` which returns a message when a successful `POST` call is made to `/panic`. In the base package create a new class `PanicResponse.java`. - Next you need an object to show the breakdown from making change. This object will hold a BigDecimal `total` and Integers `nickels` and `pennies`. In the base package create a new class `Change.java`. - ### Add Controllers Next you need to add controllers to handle API calls. In the base package add a new class `MakeChangeController.java`. - In this class a `total` is a http request query parameter that is converted to a `BigDecimal`, and the `get` method divides the `total` into `nickels` and `pennies` and returns the response object. @@ -169,7 +148,7 @@ There are three annotations that are important for the controller to work: Now, add a controller for tellers to call in an emergency. In the base package add a class `PanicController.java`. - This class listens on `/panic` for a POST request and returns a response indicating that the police were called. The annotations are the same as `MakeChangeController.java` except for `@PostMapping` indicates a POST request handler. @@ -200,7 +179,7 @@ So far you have not done anything with auth, and the controllers are unaware of You need to tell Spring how to parse the `roles` out of the claim in the JWT, and for that you need a `Converter`. In the base package add a class `CustomJwtAuthenticationConverter.java`: - This class implements the `Converter` interface and takes the `roles` claim and maps it to a `Collection` Spring will use to authorize the user. We set these as the `authorities` on the AuthenticationToken. @@ -209,7 +188,7 @@ Because you are using a custom converter you also need to check the audience. Pu Now you can add a security configuration. In the base package create a new class `SecurityConfiguration.java`. - This class does a lot in a few lines of code. Let's break it down: @@ -380,17 +359,7 @@ Enjoy your secured resource server! ## Next Steps -This quickstart is a great way to get a proof of concept up and running quickly, but to run your API in production, there are some things you're going to want to do. - -### FusionAuth Integration - -* Rather than call the Login API, you're probably going to want to use the [Authorization Code grant](/docs/lifecycle/authenticate-users/oauth/#example-authorization-code-grant), which keeps all sensitive credentials within the bounds of FusionAuth. You can customize the [hosted login pages](/docs/customize/look-and-feel/). -* You may want to generate a token using the [Client Credentials grant](/docs/lifecycle/authenticate-users/oauth/#example-client-credentials-grant) if you are calling the API from another service. - -### Security -* Customize the [token expiration times and policies](/docs/lifecycle/authenticate-users/oauth/#configure-application-oauth-settings) in FusionAuth -* [Make sure you know how to securely consume a token](/articles/tokens/building-a-secure-jwt#consuming-a-jwt) -* Secure your API [using an API gateway](/docs/extend/examples/api-gateways/) rather than at the framework layer. + ## Troubleshooting diff --git a/astro/src/content/quickstarts/quickstart-java-springboot-web.mdx b/astro/src/content/quickstarts/quickstart-java-springboot-web.mdx index 809e99fccb..07975d5da5 100644 --- a/astro/src/content/quickstarts/quickstart-java-springboot-web.mdx +++ b/astro/src/content/quickstarts/quickstart-java-springboot-web.mdx @@ -11,16 +11,17 @@ faIcon: fa-leaf color: green --- import Aside from '../../components/Aside.astro'; +import DockerSpinup from '/src/components/quickstarts/DockerSpinup.astro'; import InlineUIElement from '../../components/InlineUIElement.astro'; -import LoginAfter from '../../diagrams/quickstarts/login-after.astro'; -import LoginBefore from '../../diagrams/quickstarts/login-before.astro'; -import {RemoteCode} from '@fusionauth/astro-components'; +import Intro from '/src/components/quickstarts/Intro.astro'; +import LoginArchitectureWeb from '/src/components/quickstarts/LoginArchitectureWeb.astro'; +import NextSteps from '/src/components/quickstarts/NextSteps.astro'; import SpringBootPreReqs from '../../components/quickstarts/springboot-prereqs.mdx'; +import {RemoteCode} from '@fusionauth/astro-components'; -In this quickstart, you will build a Spring Boot web application and integrate it with FusionAuth. The application is for [ChangeBank](https://www.youtube.com/watch?v=pkH-kD73QUM), a global leader in converting dollars into coins. It will have areas reserved for logged in users and public-facing sections. It uses Spring Boot web and Thymeleaf, and sets up an OAuth authorization code grant flow, allowing users to log in to the application. - -Find the Docker Compose file and source code for the complete application at https://github.com/FusionAuth/fusionauth-quickstart-java-springboot-web. +It uses Spring Boot web and Thymeleaf, and sets up an OAuth authorization code grant flow, allowing users to log in to the application. ## Prerequisites @@ -30,17 +31,7 @@ Find the Docker Compose file and source code for the complete application at htt ## General Architecture -While this sample application doesn't have login functionality without FusionAuth, a more typical integration will replace an existing login system with FusionAuth. - -In that case, the system might look like this before FusionAuth is introduced. - - - -The login flow will look like this after FusionAuth is introduced. - - - -In general, you would introduce FusionAuth to normalize and consolidate user data, making it consistent and up-to-date. You would also offload your login security and functionality to FusionAuth. + ## Getting Started @@ -58,29 +49,7 @@ cd fusionauth-quickstart-java-springboot-web ### Run FusionAuth Via Docker -You'll find a Docker Compose file `docker-compose.yml` and an environment variables configuration file `.env` in the root directory of the repo. - -Assuming you have Docker installed, you can start FusionAuth on your machine with the following. - -```shell -docker compose up -d -``` - -This will start three containers, one each for FusionAuth, Postgres, and Elasticsearch. - -Here you are using a bootstrapping feature of FusionAuth, called [Kickstart](/docs/get-started/download-and-install/development/kickstart). When FusionAuth starts for the first time, it will look at the `kickstart/kickstart.json` file and configure FusionAuth to your specified state. - - - -FusionAuth will be configured with these settings: - -* Your client Id is `e9fdb985-9173-4e01-9d73-ac2d60d1dc8e`. -* Your client secret is `super-secret-secret-that-should-be-regenerated-for-production`. -* Your example username is `richard@example.com` and your password is `password`. -* Your admin username is `admin@example.com` and your password is `password`. -* The base URL of FusionAuth is `http://localhost:9011/`. - -You can log in to the [FusionAuth admin UI](http://localhost:9011/admin) and look around if you want to, but with Docker and Kickstart, everything will already be configured correctly. + ## Next Steps -This quickstart is a great way to get a proof of concept up and running quickly, but to run your application in production, there are some things you're going to want to do. - -### FusionAuth Customization -FusionAuth gives you the ability to customize just about everything with the user's experience and your application's integration. This includes -* [Hosted pages](/docs/customize/look-and-feel/) such as login, registration, email verification, and many more -* [Email templates](/docs/customize/email-and-messages/email-templates) -* [User data and custom claims in access token JWTs](/articles/tokens/jwt-components-explained) - -### Security -* You may want to customize the [token expiration times and policies](/docs/lifecycle/authenticate-users/oauth/#configure-application-oauth-settings) in FusionAuth -* You can use the hosted backend pages to run this example without your own OAuth backend, but [review the hosted backend docs](/docs/apis/hosted-backend) to be aware of the limitations of this approach -* Choose [password rules](/docs/get-started/core-concepts/tenants#password) and a [hashing algorithm](/docs/reference/password-hashes) that meet your security needs - -### Tenant and Application Management -* Model your application topology using [Applications](/docs/get-started/core-concepts/applications), [Roles](/docs/get-started/core-concepts/roles), [Groups](/docs/get-started/core-concepts/groups), [Entities](/docs/get-started/core-concepts/groups), and more -* Set up [MFA](/docs/lifecycle/authenticate-users/multi-factor-authentication), [Social login](/docs/lifecycle/authenticate-users/identity-providers/), and/or [SAML](/docs/lifecycle/authenticate-users/identity-providers/overview-samlv2) integrations -* Integrate with external systems using [Webhooks](/docs/extend/events-and-webhooks/), [SCIM](/docs/lifecycle/migrate-users/scim/scim), and [Lambdas](/docs/extend/code/lambdas/) + + + +
  • You can use the hosted backend pages to run this example without your own OAuth backend, but [review the hosted backend docs](/docs/apis/hosted-backend) to be aware of the limitations of this approach.
    • +     +     + diff --git a/astro/src/content/quickstarts/quickstart-javascript-remix-web.mdx b/astro/src/content/quickstarts/quickstart-javascript-remix-web.mdx index fcaedf3076..3648bfb712 100644 --- a/astro/src/content/quickstarts/quickstart-javascript-remix-web.mdx +++ b/astro/src/content/quickstarts/quickstart-javascript-remix-web.mdx @@ -13,13 +13,14 @@ cta: EmailListCTA --- import Aside from '/src/components/Aside.astro'; -import LoginAfter from '../../diagrams/quickstarts/login-after.astro'; -import LoginBefore from '../../diagrams/quickstarts/login-before.astro'; +import DockerSpinup from '/src/components/quickstarts/DockerSpinup.astro'; +import Intro from '/src/components/quickstarts/Intro.astro'; +import LoginArchitectureWeb from '/src/components/quickstarts/LoginArchitectureWeb.astro'; +import NextSteps from '/src/components/quickstarts/NextSteps.astro'; import {RemoteCode} from '@fusionauth/astro-components'; -In this quickstart, you will build an application with Remix and integrate it with FusionAuth. The application is for [ChangeBank](https://www.youtube.com/watch?v=pkH-kD73QUM), a global leader in converting dollars into coins. It will have areas reserved for logged in users and public-facing sections. - -Find the Docker Compose file and source code for the complete application at https://github.com/FusionAuth/fusionauth-quickstart-javascript-remix-web. + ## Prerequisites @@ -30,17 +31,7 @@ For this Quickstart, you'll need: ## General Architecture -While this sample application doesn't have login functionality without FusionAuth, a more typical integration will replace an existing login system with FusionAuth. - -In that case, the system might look like this before FusionAuth is introduced. - - - -The login flow will look like this after FusionAuth is introduced. - - - -In general, you would introduce FusionAuth to normalize and consolidate user data, making it consistent and up-to-date and offloading your login security and functionality to FusionAuth. + ## Getting Started @@ -61,35 +52,7 @@ All the files you'll create in this guide already exist in the `complete-applica ### Run FusionAuth Via Docker -You'll find a Docker Compose file `docker-compose.yml` and an environment variables configuration file `.env` in the root folder of the repository. - -Assuming you have Docker installed on your machine, you can start FusionAuth on your machine with the following. - -``` -docker compose up -d -``` - -This will start three containers, one each for FusionAuth, Postgres, and Elasticsearch. - -Here you are using a bootstrapping feature of FusionAuth, called [Kickstart](/docs/get-started/download-and-install/development/kickstart). When FusionAuth starts for the first time, it will look at the `kickstart/kickstart.json` file and configure FusionAuth to your specified state. - - - -FusionAuth will be configured with these settings: - -* Your client Id is `e9fdb985-9173-4e01-9d73-ac2d60d1dc8e`. -* Your client secret is `super-secret-secret-that-should-be-regenerated-for-production`. -* Your example username is `richard@example.com` and the password is `password`. -* Your admin username is `admin@example.com` and the password is `password`. -* The base URL of FusionAuth is `http://localhost:9011/`. - -You can log in to the [FusionAuth admin UI](http://localhost:9011/admin) and look around if you want to, but with Docker and Kickstart, everything will already be configured correctly. - - + ### Create A Basic Remix Application @@ -267,25 +230,7 @@ Log in using `richard@example.com` and `password`. The change page will allow yo ## Next Steps -This quickstart is a great way to get a proof of concept up and running quickly, but to run your application in production, there are some things you're going to want to do. - -### FusionAuth Customization - -FusionAuth gives you the ability to customize just about everything to do with the user's experience and the integration of your application. This includes: -* [Hosted pages](/docs/customize/look-and-feel/) such as login, registration, email verification, and many more. -* [Email templates](/docs/customize/email-and-messages/email-templates). -* [User data and custom claims in access token JWTs](/articles/tokens/jwt-components-explained). - -### Security - -* You may want to customize the [token expiration times and policies](/docs/lifecycle/authenticate-users/oauth/#configure-application-oauth-settings) in FusionAuth. -* Choose [password rules](/docs/get-started/core-concepts/tenants#password) and a [hashing algorithm](/docs/reference/password-hashes) that meet your security needs. - -### Tenant And Application Management - -* Model your application topology using [Applications](/docs/get-started/core-concepts/applications), [Roles](/docs/get-started/core-concepts/roles), [Groups](/docs/get-started/core-concepts/groups), [Entities](/docs/get-started/core-concepts/groups), and more. -* Set up [MFA](/docs/lifecycle/authenticate-users/multi-factor-authentication), [Social login](/docs/lifecycle/authenticate-users/identity-providers/), or [SAML](/docs/lifecycle/authenticate-users/identity-providers/overview-samlv2) integrations. -* Integrate with external systems using [Webhooks](/docs/extend/events-and-webhooks/), [SCIM](/docs/lifecycle/migrate-users/scim/scim), and [Lambdas](/docs/extend/code/lambdas/). + ### Remix Authentication diff --git a/astro/src/content/quickstarts/quickstart-javascript-vue-web.mdx b/astro/src/content/quickstarts/quickstart-javascript-vue-web.mdx index 14d53842cc..ae7eca159d 100644 --- a/astro/src/content/quickstarts/quickstart-javascript-vue-web.mdx +++ b/astro/src/content/quickstarts/quickstart-javascript-vue-web.mdx @@ -9,21 +9,19 @@ language: JavaScript icon: /img/icons/vue.js.svg faIcon: fa-vue color: red -coderoot: https://raw.githubusercontent.com/FusionAuth/fusionauth-quickstart-javascript-vue-web/main +codeRoot: https://raw.githubusercontent.com/FusionAuth/fusionauth-quickstart-javascript-vue-web/main cta: EmailListCTA --- import Aside from '/src/components/Aside.astro'; -import LoginAfterSdk from '../../diagrams/quickstarts/login-after-sdk.astro'; -import LoginBefore from '../../diagrams/quickstarts/login-before.astro'; +import DockerSpinup from '/src/components/quickstarts/DockerSpinup.astro'; +import Intro from '/src/components/quickstarts/Intro.astro'; +import LoginArchitectureSdk from '/src/components/quickstarts/LoginArchitectureSdk.astro'; +import NextSteps from '/src/components/quickstarts/NextSteps.astro'; import {RemoteCode} from '@fusionauth/astro-components'; -In this quickstart you are going to build an application with Vue.js and integrate it with FusionAuth. -You'll be building it for [ChangeBank](https://www.youtube.com/watch?v=CXDxNCzUspM), a global leader in converting dollars into coins. -It'll have areas reserved for users who have logged in as well as public facing sections. - -The docker compose file and source code for a complete application are available at -[https://github.com/FusionAuth/fusionauth-quickstart-javascript-vue-web](https://github.com/FusionAuth/fusionauth-quickstart-javascript-vue-web) + ## Prerequisites * [Node v18](https://nodejs.org/en): This will be used to run the Vue.js application. @@ -33,17 +31,7 @@ This app has been tested with Node v18 and Vue.js v3.3.4. This example should wo ## General Architecture -While this sample application doesn't have login functionality without FusionAuth, a more typical integration will replace an existing login system with FusionAuth. - -In that case, the system might look like this before FusionAuth is introduced. - - - -The login flow will look like this after FusionAuth is introduced. - - - -In general, you are introducing FusionAuth in order to normalize and consolidate user data. This helps make sure it is consistent and up-to-date as well as offloading your login security and functionality to FusionAuth. + ## Getting Started @@ -58,33 +46,8 @@ cd fusionauth-quickstart-javascript-vue-web ``` ### Run FusionAuth Via Docker -In the root directory of the repo you'll find a Docker compose file (docker-compose.yml) and an environment -variables configuration file (.env). Assuming you have Docker installed on your machine, you can stand up -FusionAuth up on your machine with: - -```shell -docker compose up -d -``` - -This will start three containers, once each for FusionAuth, Postgres, and Elastic. - -Here you are using a bootstrapping feature of FusionAuth, called [Kickstart](/docs/get-started/download-and-install/development/kickstart). -When FusionAuth comes up for the first time, it will look at the `kickstart/kickstart.json` file and -configure FusionAuth to a certain initial state. - - -

    FusionAuth will be configured with these settings:

    -* Your client Id is `e9fdb985-9173-4e01-9d73-ac2d60d1dc8e`. -* Your client secret is `super-secret-secret-that-should-be-regenerated-for-production`. -* Your example username is `richard@example.com` and the password is `password`. -* Your admin username is `admin@example.com` and the password is `password`. -* The base URL of FusionAuth `http://localhost:9011/`. - -You can log into the [FusionAuth admin UI](http://localhost:9011/admin) and look around if you want, but with Docker/Kickstart you don’t need to. + ### Create A Basic Vue.js Application @@ -177,19 +140,5 @@ You can now open up an incognito window and navigate to http://localhost:5173. Y ## Next Steps -This quickstart is a great way to get a proof of concept up and running quickly, but to run your application in production, there are some things you're going to want to do. - -### FusionAuth Customization -FusionAuth gives you the ability to customize just about everything with the user's experience and your application's integration. This includes -* [Hosted pages](/docs/customize/look-and-feel/) such as login, registration, email verification, and many more -* [Email templates](/docs/customize/email-and-messages/email-templates) -* [User data and custom claims in access token JWTs](/articles/tokens/jwt-components-explained) - -### Security -* You may want to customize the [token expiration times and policies](/docs/lifecycle/authenticate-users/oauth/#configure-application-oauth-settings) in FusionAuth -* Choose [password rules](/docs/get-started/core-concepts/tenants#password) and a [hashing algorithm](/docs/reference/password-hashes) that meet your security needs - -### Tenant And Application Management -* Model your application topology using [Applications](/docs/get-started/core-concepts/applications), [Roles](/docs/get-started/core-concepts/roles), [Groups](/docs/get-started/core-concepts/groups), [Entities](/docs/get-started/core-concepts/groups), and more -* Set up [MFA](/docs/lifecycle/authenticate-users/multi-factor-authentication), [Social login](/docs/lifecycle/authenticate-users/identity-providers/), and/or [SAML](/docs/lifecycle/authenticate-users/identity-providers/overview-samlv2) integrations -* Integrate with external systems using [Webhooks](/docs/extend/events-and-webhooks/), [SCIM](/docs/lifecycle/migrate-users/scim/scim), and [Lambdas](/docs/extend/code/lambdas/) + + diff --git a/astro/src/content/quickstarts/quickstart-php-drupal-web.mdx b/astro/src/content/quickstarts/quickstart-php-drupal-web.mdx index 76f4e806c3..93c3171e22 100644 --- a/astro/src/content/quickstarts/quickstart-php-drupal-web.mdx +++ b/astro/src/content/quickstarts/quickstart-php-drupal-web.mdx @@ -10,22 +10,20 @@ icon: /img/icons/drupal.svg faIcon: fa-gem color: rose cta: EmailListCTA -coderoot: https://raw.githubusercontent.com/FusionAuth/fusionauth-quickstart-php-drupal-web/main +codeRoot: https://raw.githubusercontent.com/FusionAuth/fusionauth-quickstart-php-drupal-web/main --- import Aside from '../../components/Aside.astro'; -import LoginAfter from '../../diagrams/quickstarts/login-after.astro'; -import LoginBefore from '../../diagrams/quickstarts/login-before.astro'; -import {RemoteCode} from '@fusionauth/astro-components'; -import InlineUIElement from '../../components/InlineUIElement.astro'; -import Field from '../../components/Field.astro'; import Breadcrumb from '../../components/Breadcrumb.astro'; +import DockerSpinup from '/src/components/quickstarts/DockerSpinup.astro'; +import Field from '../../components/Field.astro'; +import InlineUIElement from '../../components/InlineUIElement.astro'; +import Intro from '/src/components/quickstarts/Intro.astro'; +import LoginArchitectureWeb from '/src/components/quickstarts/LoginArchitectureWeb.astro'; +import NextSteps from '/src/components/quickstarts/NextSteps.astro'; +import {RemoteCode} from '@fusionauth/astro-components'; -In this quickstart guide you will build a Drupal web application and integrate it with FusionAuth. - -You'll be building it for [ChangeBank](https://www.youtube.com/watch?v=CXDxNCzUspM), a global leader in converting dollars into coins. It'll have areas reserved for users who have logged in as well as public facing sections. - -The docker compose file and source code for a complete application are available at -https://github.com/FusionAuth/fusionauth-quickstart-php-drupal-web + ## Prerequisites @@ -40,15 +38,7 @@ https://github.com/FusionAuth/fusionauth-quickstart-php-drupal-web ## General Architecture -By default, Drupal has a built-in login and authentication system. As such, the application will resemble the following before FusionAuth is introduced. - - - -The login flow will look like this after FusionAuth is introduced. - - - -In general, you are introducing FusionAuth in order to normalize and consolidate user data. This helps make sure it is consistent and up-to-date as well as offloading your login security and functionality to FusionAuth. + ## Getting Started @@ -179,27 +169,7 @@ For the full list of Drush commands, visit https://www.drush.org/12.2.0/commands ### Run FusionAuth Via Docker -In the root directory of the repo, you'll find a Docker compose file `docker-compose.yml` and an environment variables configuration file `.env`. If you started the Drupal application, the FusionAuth containers will already be running. If not, you can start them with the following command: - -```shell -docker compose up -d -``` - -Here you are using a bootstrapping feature of FusionAuth, called [Kickstart](/docs/get-started/download-and-install/development/kickstart). When FusionAuth comes up for the first time, it will look at the `kickstart/kickstart.json` file and configure FusionAuth to a certain initial state. - - - -FusionAuth will be initially configured with these settings: - -* Your client Id is: `e9fdb985-9173-4e01-9d73-ac2d60d1dc8e`. -* Your client secret is: `super-secret-secret-that-should-be-regenerated-for-production`. -* Your example username is `richard@example.com` and your password is `password`. -* Your admin username is `admin@example.com` and your password is `password`. -* Your fusionAuthBaseUrl is 'http://localhost:9011/' - -You can log in to the [FusionAuth admin UI](http://localhost:9011/admin) and look around if you want, but with Docker and Kickstart, everything will already be configured correctly. + ## Authentication @@ -470,14 +440,14 @@ You will be editing the following files: In your text editor, select the `ChangebankForm.php` file located at `your-application/web/modules/changebank/src/Form/ChangebankForm.php`. Clear the existing boilerplate contents and add the following code. - #### Customize The Controller In your text editor, select the `ChangebankController.php` file located at `your-application/web/modules/changebank/src/Controller/ChangebankController.php` and replace the content with the following code. - #### Customize The Routing @@ -486,14 +456,14 @@ Next you'll set up two routes, one for the form and one for the account page. Select the `changebank.routing.yml` file located at `your-application/web/modules/changebank/changebank.routing.yml` and replace the content with the following configuration. - #### Customize The User Email Block You'll use the User Email Block to display the current user's email address in a block. Select the `UserEmailBlock.php` file located at `your-application/web/modules/changebank/src/Plugin/Block/UserEmailBlock.php` and replace the content with the following code. - #### Customize The User Login And Logout Block @@ -502,14 +472,14 @@ You'll use the User Login And Logout Block to display a login button for anonymo Select the `UserLoginLogoutBlock.php` file located at `your-application/web/modules/changebank/src/Plugin/Block/UserLoginLogoutBlock.php` and replace the content with the following code. - #### Customize The `changebank.module` File To make the blocks available to the application, you need to make some changes to the `changebank.module` file located at `your-application/web/modules/changebank/changebank.module`. Add the following. - #### Enable The Changebank Module @@ -606,14 +576,14 @@ In the templates directory, create the following files: In the page template for the front page (called `page--front.html.twig`), add the following code. - Now add markup to create a custom layout for the site logo, the user email block, and the user login and logout block. First, add the following to the `region--secondary-menu.html.twig` template. - If the user email and login and logout blocks do not display or appear broken, make sure that the Twig Tweak module is enabled as it provides the naming convention to embed the blocks in the template. @@ -622,7 +592,7 @@ Now, as the code adds the System Branding block to the secondary menu region tem Add the following to the `block--system-branding-block.html.twig` template. - This code hides the `site_name` variable by commenting it out, but you can delete it if you prefer. @@ -631,7 +601,7 @@ This code hides the `site_name` variable by commenting it out, but you can delet Next you'll add some styling to the application to make it look a little nicer. Select the `style.css` file located at `your-application/web/themes/custom/subtheme/css/style.css` and add the following. - ### Add A Menu @@ -730,15 +700,7 @@ Log in by clicking the Login with FusionAuth ## Next Steps -This quickstart is a great way to get a proof of concept up and running quickly, but to run your application in production, there are some things you're going to want to do. - -### FusionAuth Customization - -FusionAuth gives you the ability to customize just about everything with the user's experience and your application's integration. This includes: - -* [Hosted pages](/docs/customize/look-and-feel/) such as login, registration, email verification, and many more. -* [Email templates](/docs/customize/email-and-messages/). -* [User data and custom claims in access token JWTs](/articles/tokens/jwt-components-explained) + ### Drupal Customization diff --git a/astro/src/content/quickstarts/quickstart-php-laravel-api.mdx b/astro/src/content/quickstarts/quickstart-php-laravel-api.mdx index 7ce7a8c3cd..a73f5d5209 100644 --- a/astro/src/content/quickstarts/quickstart-php-laravel-api.mdx +++ b/astro/src/content/quickstarts/quickstart-php-laravel-api.mdx @@ -10,16 +10,19 @@ icon: /img/icons/laravel.svg faIcon: fa-block color: rose cta: EmailListCTA -coderoot: https://raw.githubusercontent.com/FusionAuth/fusionauth-quickstart-php-laravel-api/main +codeRoot: https://raw.githubusercontent.com/FusionAuth/fusionauth-quickstart-php-laravel-api/main --- import Aside from '../../components/Aside.astro'; import Code from 'astro/components/Code.astro'; -import Diagram from '../../diagrams/quickstarts/resource-server.astro'; +import DockerSpinup from '/src/components/quickstarts/DockerSpinup.astro'; +import Intro from '/src/components/quickstarts/Intro.astro'; +import LoginArchitectureApi from '/src/components/quickstarts/LoginArchitectureApi.astro'; +import NextStepsApi from '/src/components/quickstarts/NextStepsApi.astro'; import {RemoteCode, RemoteValue} from '@fusionauth/astro-components'; -In this tutorial, you are going to learn how to integrate a Laravel resource server with FusionAuth. You will protect an API resource from unauthorized usage. You'll be building it for [ChangeBank](https://www.youtube.com/watch?v=CXDxNCzUspM), a global leader in converting dollars into coins. - -The docker compose file and source code for a complete application are available at https://github.com/FusionAuth/fusionauth-quickstart-php-laravel-api. + ## Prerequisites @@ -28,11 +31,7 @@ The docker compose file and source code for a complete application are available ## General Architecture -A client wants access to an API resource at `/resource`. However, it is denied this resource until it acquires an access token from FusionAuth. - - - -While the access token is acquired via the Login API above, this is for simplicity of illustration. The token can be, and typically is, acquired through one of the [OAuth grants](/docs/lifecycle/authenticate-users/oauth/). + ## Getting Started @@ -49,28 +48,7 @@ cd fusionauth-quickstart-php-laravel-api ### Run FusionAuth via Docker -In the root directory of the repo you’ll find a Docker compose file (`docker-compose.yml`) and an environment variables configuration file (`.env`). Assuming you have Docker installed on your machine, you can stand up FusionAuth up on your machine with: - -```shell -docker compose up -d -``` - -Here you are using a bootstrapping feature of FusionAuth, called [Kickstart](/docs/get-started/download-and-install/development/kickstart). When FusionAuth comes up for the first time, it will look at the `kickstart/kickstart.json` file and configure FusionAuth to a certain initial state. - - - -FusionAuth will be initially configured with these settings: - -* Your client Id is -* Your client secret is . -* Your example teller username is and the password is . They will have the role of `teller`. -* Your example customer username is and the password is . They will have the role of `customer`. -* Your admin username is and the password is . -* The base URL of FusionAuth is `http://localhost:9011/`. - -You can log into the [FusionAuth admin UI](http://localhost:9011/admin) and look around if you want, but with Docker/Kickstart you don't need to. + ### Expose FusionAuth Instance @@ -136,11 +114,11 @@ Include FusionAuth's library to add JWT support to the authentication system. When installing Laravel, it will automatically make a migration to create a `users` table in the database. You'll have to edit the file `database/migrations/2014_10_12_000000_create_users_table.php` to change the default behavior and use UUID for the primary key, remove the need for a password and the remember token. - + You'll also need to edit `app/Models/User.php` to make the database changes consistent with your model. - + You may remove all other migrations, as you won't need them. @@ -168,37 +146,37 @@ mkdir -p app/FusionAuth/Providers Add a new [User Provider](https://laravel.com/docs/10.x/authentication#adding-custom-user-providers) at `app/FusionAuth/Providers/FusionAuthEloquentUserProvider.php` to create new users when receiving valid JWTs from FusionAuth. - + Now, add an [Authentication Guard](https://laravel.com/docs/10.x/authentication#adding-custom-guards) in `app/FusionAuth/FusionAuthJwtGuard.php` to call that custom method from the User Provider created above. - + Let Laravel know about these two classes by editing `config/auth.php`. First, change the `driver` for the `web` Guard to `jwt`: - + Now, change the default `provider` to `fusionauth_eloquent`: - + Finally, create a [Service Provider](https://laravel.com/docs/10.x/providers) in `app/FusionAuth/Providers/FusionAuthServiceProvider.php` to make sure Laravel will use the newly created classes instead of its defaults. - + ### Update Routes Change `routes/api.php` to add both `/api/make-change` and `/api/panic` endpoints for your ChangeBank application. - + ### Add Controllers Change the base controller at `app/Http/Controllers/Controller.php` to include a helper function to check for roles. - + Create a folder named `ChangeBank` inside `app/Http/Controllers` to hold the two controllers you're going to create. @@ -208,11 +186,11 @@ mkdir app/Http/Controllers/ChangeBank To respond the `/api/make-change` endpoint, create a file at `app/Http/Controllers/ChangeBank/MakeChangeController.php`. This controller will verify that the authenticated user has either the `teller` or `customer` role. It then takes in the URL parameter `total` to calculate which coins will be returned in the JSON payload. - + To finish, create a controller at `app/Http/Controllers/ChangeBank/PanicController.php` to handle the `/api/panic` endpoint for users with the `teller` role. - + ### Validating Issuer and Audience Claims @@ -226,11 +204,11 @@ mkdir app/FusionAuth/Claims First, create a file named `app/FusionAuth/Claims/Audience.php` that will check if the audience (`aud`) claim actually contains the Client Id for the application you created in FusionAuth. - + Now, create a file called `app/FusionAuth/Claims/Issuer.php` to check if the issuer (`iss`) is actually your FusionAuth instance address. - + ### Let Your Code Know about the FusionAuth Instance @@ -238,15 +216,15 @@ Now that you created all these files, you need to pass some details about the Fu Start by adding the environment variables below to your `.env` file, changing `https://The-Address-Ngrok-Gave-You` to the actual address you copied from ngrok. - + Now open the `config/app.php` file and browse to the `providers` section. This is a Laravel configuration to automatically load these files when booting your application. Add `App\FusionAuth\Providers\FusionAuthServiceProvider::class` to the end of the `providers` array, like shown below. - + In that same `config/app.php` file, add these lines at the end (just before the last line) to pass values from the environment variables to the application. - + To make the library available for use, publish its configuration by running the command below. @@ -260,12 +238,12 @@ To make the library available for use, publish its configuration by running the There are [several ways to acquire a token](/docs/lifecycle/authenticate-users/oauth/) in FusionAuth, but for this example you will use the [Login API](/docs/apis/login) to keep things simple. -First, try requests as the user. Based on the configuration this user has the `teller` role and should be able to use both `/api/make-change` and `/api/panic`. +First, try requests as the user. Based on the configuration this user has the `teller` role and should be able to use both `/api/make-change` and `/api/panic`. -1. Acquire an access token for by making the following request +1. Acquire an access token for by making the following request {(variables) => {(variables) => ## Troubleshooting diff --git a/astro/src/content/quickstarts/quickstart-php-laravel-web.mdx b/astro/src/content/quickstarts/quickstart-php-laravel-web.mdx index 62dffbbe79..db0d77912f 100644 --- a/astro/src/content/quickstarts/quickstart-php-laravel-web.mdx +++ b/astro/src/content/quickstarts/quickstart-php-laravel-web.mdx @@ -13,13 +13,14 @@ url: https://github.com/FusionAuth/fusionauth-quickstart-php-laravel-web codeRoot: https://raw.githubusercontent.com/FusionAuth/fusionauth-quickstart-php-laravel-web/main --- import Aside from '/src/components/Aside.astro'; -import LoginAfter from '../../diagrams/quickstarts/login-after.astro'; -import LoginBefore from '../../diagrams/quickstarts/login-before.astro'; +import DockerSpinup from '/src/components/quickstarts/DockerSpinup.astro'; +import Intro from '/src/components/quickstarts/Intro.astro'; +import LoginArchitectureWeb from '/src/components/quickstarts/LoginArchitectureWeb.astro'; +import NextSteps from '/src/components/quickstarts/NextSteps.astro'; import {RemoteCode} from '@fusionauth/astro-components'; -In this quickstart, you will build an application with {frontmatter.technology} and integrate it with FusionAuth. The application is for [ChangeBank](https://www.youtube.com/watch?v=pkH-kD73QUM), a global leader in converting dollars into coins. It will have areas reserved for logged in users and public-facing sections. - -Find the Docker Compose file and source code for the complete application at     {frontmatter.url}. + ## Prerequisites @@ -32,17 +33,7 @@ For this Quickstart, you'll need: ## General Architecture -While this sample application doesn't have login functionality without FusionAuth, a more typical integration will replace an existing login system with FusionAuth. - -In that case, the system might look like this before FusionAuth is introduced. - - - -The login flow will look like this after FusionAuth is introduced. - - - -In general, you would introduce FusionAuth to normalize and consolidate user data, making it consistent and up-to-date and offloading your login security and functionality to FusionAuth. + ## Getting Started @@ -63,35 +54,7 @@ All the files you'll create in this guide already exist in the `complete-applica ### Run FusionAuth Via Docker -You'll find a Docker Compose file `docker-compose.yml` and an environment variables configuration file `.env` in the root folder of the repository. - -Assuming you have Docker installed, you can start FusionAuth on your machine with the following. - -```shell -docker compose up -d -``` - -This will start three containers, one each for FusionAuth, Postgres, and Elasticsearch. - -Here you are using a bootstrapping feature of FusionAuth, called [Kickstart](/docs/get-started/download-and-install/development/kickstart). When FusionAuth starts for the first time, it will look at the `kickstart/kickstart.json` file and configure FusionAuth to your specified state. - - - -FusionAuth will be configured with these settings: - -* Your client Id is `e9fdb985-9173-4e01-9d73-ac2d60d1dc8e`. -* Your client secret is `super-secret-secret-that-should-be-regenerated-for-production`. -* Your example username is `richard@example.com` and the password is `password`. -* Your admin username is `admin@example.com` and the password is `password`. -* The base URL of FusionAuth is `http://localhost:9011/`. - -You can log in to the [FusionAuth admin UI](http://localhost:9011/admin) and look around if you want to, but with Docker and Kickstart, everything will already be configured correctly. - - + ### The Basic {frontmatter.technology} Application @@ -310,24 +273,7 @@ Browse to [the app](http://localhost:8000) at http://localhost:8000. Log in usin ## Next Steps -This quickstart is a great way to get a proof of concept up and running quickly, but to run your application in production, there are some things you're going to want to do. - -### FusionAuth Customization -FusionAuth gives you the ability to customize just about everything with the user's experience and your application's integration. This includes -* [Hosted pages](/docs/customize/look-and-feel/) such as login, registration, email verification, and many more -* [Email templates](/docs/customize/email-and-messages/email-templates) -* [User data and custom claims in access token JWTs](/articles/tokens/jwt-components-explained) - -### Security - -* You may want to customize the [token expiration times and policies](/docs/lifecycle/authenticate-users/oauth/#configure-application-oauth-settings) in FusionAuth -* Choose [password rules](/docs/get-started/core-concepts/tenants#password) and a [hashing algorithm](/docs/reference/password-hashes) that meet your security needs - -### Tenant And Application Management - -* Model your application topology using [Applications](/docs/get-started/core-concepts/applications), [Roles](/docs/get-started/core-concepts/roles), [Groups](/docs/get-started/core-concepts/groups), [Entities](/docs/get-started/core-concepts/groups), and more -* Set up [MFA](/docs/lifecycle/authenticate-users/multi-factor-authentication), [Social login](/docs/lifecycle/authenticate-users/identity-providers/), and/or [SAML](/docs/lifecycle/authenticate-users/identity-providers/overview-samlv2) integrations -* Integrate with external systems using [Webhooks](/docs/extend/events-and-webhooks/), [SCIM](/docs/lifecycle/migrate-users/scim/scim), and [Lambdas](/docs/extend/code/lambdas/) + ### {frontmatter.technology} Authentication diff --git a/astro/src/content/quickstarts/quickstart-php-web.mdx b/astro/src/content/quickstarts/quickstart-php-web.mdx index 38f96a4754..85dd9315c0 100644 --- a/astro/src/content/quickstarts/quickstart-php-web.mdx +++ b/astro/src/content/quickstarts/quickstart-php-web.mdx @@ -14,19 +14,20 @@ codeRoot: https://raw.githubusercontent.com/FusionAuth/fusionauth-quickstart-php --- import Aside from '/src/components/Aside.astro'; -import LoginAfter from '../../diagrams/quickstarts/login-after.astro'; -import LoginBefore from '../../diagrams/quickstarts/login-before.astro'; +import DockerSpinup from '/src/components/quickstarts/DockerSpinup.astro'; +import Intro from '/src/components/quickstarts/Intro.astro'; +import LoginArchitectureWeb from '/src/components/quickstarts/LoginArchitectureWeb.astro'; +import NextSteps from '/src/components/quickstarts/NextSteps.astro'; import {RemoteCode, RemoteValue} from '@fusionauth/astro-components'; -In this quickstart, you will build an application with {frontmatter.technology} and integrate it with FusionAuth. The application is for [ChangeBank](https://www.youtube.com/watch?v=pkH-kD73QUM), a global leader in converting dollars to coins. The app will have areas reserved for logged in users and public-facing sections. + -Find the Docker Compose file and source code for the complete application at {frontmatter.url}. - ## Prerequisites For this quickstart, you'll need: @@ -37,17 +38,7 @@ For this quickstart, you'll need: ## General Architecture -This sample application doesn't have login functionality without FusionAuth, but a more typical integration will replace an existing login system with FusionAuth. - -In that case, the system might look like this before FusionAuth is introduced. - - - -The login flow will look like this after FusionAuth is introduced. - - - -In general, you would introduce FusionAuth to normalize and consolidate user data to make it consistent and up to date, and offload your login security and functionality to FusionAuth. + ## Getting Started @@ -68,37 +59,7 @@ All the files you'll create in this guide already exist in the `complete-applica ### Run FusionAuth Via Docker -You'll find a Docker Compose file `docker-compose.yml` and an environment variables configuration file `.env` in the root directory of the repository. - -Assuming you have Docker installed, you can start FusionAuth on your machine with the following. - -```shell -docker compose up -``` - -This will start three containers, one each for FusionAuth, Postgres, and OpenSearch. - -Here you are using a bootstrapping feature of FusionAuth called [Kickstart](/docs/get-started/download-and-install/development/kickstart). When FusionAuth starts for the first time, it will look at the `kickstart/kickstart.json` file and configure FusionAuth to your specified state. - - - -FusionAuth will be configured with these settings: - -* Your client Id is . -* Your client secret is . -* Your example username is and the password is . -* Your admin username is and the password is . -* The base URL of FusionAuth is `http://localhost:9011/`. - -You can log in to the [FusionAuth admin UI](http://localhost:9011/admin) and look around if you want to, but with Docker and Kickstart, everything will already be configured correctly. - - + ### The Basic {frontmatter.technology} Application @@ -249,26 +210,7 @@ Browse to the app at http://localhost:9012. Log in using `richard@example.com` a ## Next Steps -This quickstart is a great way to get a proof of concept up and running quickly, but to run your application in production, there are some things you're going to want to do. - -### FusionAuth Customization - -FusionAuth gives you the ability to customize just about everything to do with the user's experience and the integration of your application. This includes: - -* [Hosted pages](/docs/customize/look-and-feel/) such as login, registration, email verification, and many more. -* [Email templates](/docs/customize/email-and-messages/). -* [User data and custom claims in access token JWTs](/articles/tokens/jwt-components-explained). - -### Security - -* You may want to customize the [token expiration times and policies](/docs/lifecycle/authenticate-users/oauth/#configure-application-oauth-settings) in FusionAuth. -* Choose [password rules](/docs/get-started/core-concepts/tenants#password) and a [hashing algorithm](/docs/reference/password-hashes) that meet your security needs. - -### Tenant And Application Management - -* Model your application topology using [Applications](/docs/get-started/core-concepts/applications), [Roles](/docs/get-started/core-concepts/roles), [Groups](/docs/get-started/core-concepts/groups), [Entities](/docs/get-started/core-concepts/entity-management), and more. -* Set up [MFA](/docs/lifecycle/authenticate-users/multi-factor-authentication), [Social login](/docs/lifecycle/authenticate-users/identity-providers/social/), or [SAML](/docs/lifecycle/authenticate-users/saml) integrations. -* Integrate with external systems using [Webhooks](/docs/extend/events-and-webhooks/), [SCIM](/docs/lifecycle/migrate-users/scim/), and [Lambdas](/docs/extend/code/lambdas/). + ### {frontmatter.technology} Authentication diff --git a/astro/src/content/quickstarts/quickstart-python-django-web.mdx b/astro/src/content/quickstarts/quickstart-python-django-web.mdx index 1ef715639c..d7a7afef47 100644 --- a/astro/src/content/quickstarts/quickstart-python-django-web.mdx +++ b/astro/src/content/quickstarts/quickstart-python-django-web.mdx @@ -10,16 +10,18 @@ icon: /img/icons/python.svg faIcon: fa-snake color: yellow cta: EmailListCTA +codeRoot: https://raw.githubusercontent.com/FusionAuth/fusionauth-quickstart-python-django-web/main --- import Aside from '/src/components/Aside.astro'; -import LoginAfter from '../../diagrams/quickstarts/login-after.astro'; -import LoginBefore from '../../diagrams/quickstarts/login-before.astro'; +import DockerSpinup from '/src/components/quickstarts/DockerSpinup.astro'; +import Intro from '/src/components/quickstarts/Intro.astro'; +import LoginArchitectureWeb from '/src/components/quickstarts/LoginArchitectureWeb.astro'; +import NextSteps from '/src/components/quickstarts/NextSteps.astro'; import {RemoteCode} from '@fusionauth/astro-components'; -In this quickstart, you will build an application with Python and Django and integrate it with FusionAuth. The application is for [ChangeBank](https://www.youtube.com/watch?v=pkH-kD73QUM), a global leader in converting dollars into coins. It will have areas reserved for logged in users and public-facing sections. - -Find the Docker Compose file and source code for the complete application at https://github.com/FusionAuth/fusionauth-quickstart-python-django-web. + ## Prerequisites @@ -29,17 +31,7 @@ For this Quickstart, you'll need: ## General Architecture -While this sample application doesn't have login functionality without FusionAuth, a more typical integration will replace an existing login system with FusionAuth. - -In that case, the system might look like this before FusionAuth is introduced. - - - -The login flow will look like this after FusionAuth is introduced. - - - -In general, you would introduce FusionAuth to normalize and consolidate user data, making it consistent and up-to-date and offloading your login security and functionality to FusionAuth. + ## Getting Started @@ -60,34 +52,7 @@ The files you'll create in this guide already exist in the `complete-application ### Run FusionAuth Via Docker -You'll find a Docker Compose file `docker-compose.yml` and an environment variables configuration file `.env` in the root directory of the repo. - -Assuming you have Docker installed, you can start FusionAuth on your machine with the following. - -``` -docker compose up -d -``` - -This will start three containers, one each for FusionAuth, Postgres, and Elasticsearch. - -Here you are using a bootstrapping feature of FusionAuth, called [Kickstart](/docs/get-started/download-and-install/development/kickstart). When FusionAuth starts for the first time, it will look at the `kickstart/kickstart.json` file and configure FusionAuth to your specified state. - - - -FusionAuth will be configured with these settings: -* Your client Id is `e9fdb985-9173-4e01-9d73-ac2d60d1dc8e`. -* Your client secret is `super-secret-secret-that-should-be-regenerated-for-production`. -* Your example username is `richard@example.com` and the password is `password`. -* Your admin username is `admin@example.com` and the password is `password`. -* The base URL of FusionAuth is `http://localhost:9011/`. - -You can log in to the [FusionAuth admin UI](http://localhost:9011/admin) and look around if you want to, but with Docker and Kickstart, everything will already be configured correctly. - - + ### Create A Basic Django Application @@ -228,23 +193,8 @@ Log in using `richard@example.com` and `password`. The change page will allow yo ## Next Steps -This quickstart is a great way to get a proof of concept up and running quickly, but to run your application in production, there are some things you're going to want to do. - -### FusionAuth Customization - -FusionAuth gives you the ability to customize just about everything to do with the user's experience and the integration of your application. This includes: -* [Hosted pages](/docs/customize/look-and-feel/) such as login, registration, email verification, and many more. -* [Email templates](/docs/customize/email-and-messages/email-templates). -* [User data and custom claims in access token JWTs](/articles/tokens/jwt-components-explained). - -### Security - -* Learn more about configuring the [open source OIDC library](https://github.com/mozilla/mozilla-django-oidc). -* You may want to customize the [token expiration times and policies](/docs/lifecycle/authenticate-users/oauth/#configure-application-oauth-settings) in FusionAuth. -* Choose [password rules](/docs/get-started/core-concepts/tenants#password) and a [hashing algorithm](/docs/reference/password-hashes) that meet your security needs. - -### Tenant And Application Management - -* Model your application topology using [Applications](/docs/get-started/core-concepts/applications), [Roles](/docs/get-started/core-concepts/roles), [Groups](/docs/get-started/core-concepts/groups), [Entities](/docs/get-started/core-concepts/groups), and more. -* Set up [MFA](/docs/lifecycle/authenticate-users/multi-factor-authentication), [Social login](/docs/lifecycle/authenticate-users/identity-providers/), or [SAML](/docs/lifecycle/authenticate-users/identity-providers/overview-samlv2) integrations. -* Integrate with external systems using [Webhooks](/docs/extend/events-and-webhooks/), [SCIM](/docs/lifecycle/migrate-users/scim/scim), and [Lambdas](/docs/extend/code/lambdas/). + + +
  • Learn more about configuring the [open source OIDC library](https://github.com/mozilla/mozilla-django-oidc).
    • +     +     diff --git a/astro/src/content/quickstarts/quickstart-python-flask-web.mdx b/astro/src/content/quickstarts/quickstart-python-flask-web.mdx index 83d1f22885..798715888b 100644 --- a/astro/src/content/quickstarts/quickstart-python-flask-web.mdx +++ b/astro/src/content/quickstarts/quickstart-python-flask-web.mdx @@ -10,18 +10,17 @@ icon: /img/icons/python.svg faIcon: fa-snake color: yellow cta: EmailListCTA +codeRoot: https://raw.githubusercontent.com/FusionAuth/fusionauth-quickstart-python-flask-web/main --- import Aside from '../../components/Aside.astro'; -import LoginAfter from '../../diagrams/quickstarts/login-after.astro'; -import LoginBefore from '../../diagrams/quickstarts/login-before.astro'; +import DockerSpinup from '/src/components/quickstarts/DockerSpinup.astro'; +import Intro from '/src/components/quickstarts/Intro.astro'; +import LoginArchitectureWeb from '/src/components/quickstarts/LoginArchitectureWeb.astro'; +import NextSteps from '/src/components/quickstarts/NextSteps.astro'; import {RemoteCode} from '@fusionauth/astro-components'; -In this quickstart you are going to build an application with Python and Flask, and integrate it with FusionAuth. -You'll be building it for [ChangeBank](https://www.youtube.com/watch?v=CXDxNCzUspM), a global leader in converting dollars into coins. -It'll have areas reserved for users who have logged in as well as public facing sections. - -The docker compose file and source code for a complete application are available at -https://github.com/FusionAuth/fusionauth-quickstart-python-flask-web + ## Prerequisites @@ -32,17 +31,7 @@ This app has been tested with Python 3.8. This example should work with other co ## General Architecture -While this sample application doesn't have login functionality without FusionAuth, a more typical integration will replace an existing login system with FusionAuth. - -In that case, the system might look like this before FusionAuth is introduced. - - - -The login flow will look like this after FusionAuth is introduced. - - - -In general, you are introducing FusionAuth in order to normalize and consolidate user data. This helps make sure it is consistent and up-to-date as well as offloading your login security and functionality to FusionAuth. + ## Getting Started In this section, you'll get FusionAuth up and running and use Flask to create a new application. @@ -56,29 +45,8 @@ cd fusionauth-quickstart-python-flask-web ``` ### Run FusionAuth via Docker -In the root directory of the repo you'll find a Docker compose file (docker-compose.yml) and an environment variables configuration file (.env). Assuming you have Docker installed on your machine, you can stand up FusionAuth up on your machine with: - -``` -docker compose up -d -``` -This will start three containers, once each for FusionAuth, Postgres, and Elastic. - -Here you are using a bootstrapping feature of FusionAuth, called [Kickstart](/docs/get-started/download-and-install/development/kickstart). When FusionAuth comes up for the first time, it will look at the `kickstart/kickstart.json` file and configure FusionAuth to a certain initial state. - - - -FusionAuth will be initially configured with these settings: - -* Your client Id is `e9fdb985-9173-4e01-9d73-ac2d60d1dc8e`. -* Your client secret is `super-secret-secret-that-should-be-regenerated-for-production`. -* Your example username is `richard@example.com` and the password is `password`. -* Your admin username is `admin@example.com` and the password is `password`. -* The base URL of FusionAuth `http://localhost:9011/`. - -You can log into the [FusionAuth admin UI](http://localhost:9011/admin) and look around if you want, but with Docker/Kickstart you don't need to. + ### Create your Flask Application @@ -95,7 +63,7 @@ python3.8 -m venv venv && source venv/bin/activate Next, create a `requirements.txt` file to name the project dependencies. `requirements.txt` - And then install the dependencies into your virtual env. @@ -111,13 +79,13 @@ Now create your Flask app, which for now will consist of an environment file nam Create the environment file with these contents: `.env` - In `server.py`, you'll add all of the imports you'll need, declare some constants, and initialize the OAuth library. `server.py` - @@ -133,7 +101,7 @@ In the route function, you're going to look for an access token, which is create Add the route handling function to your server.py file. `server.py` - @@ -171,11 +139,11 @@ We also set the userinfo object in the Flask session, to make it easy to use in Add the `/login` and `/callback` routes to your server code. `server.py` - - @@ -194,7 +162,7 @@ wget -O templates/account.html https://raw.githubusercontent.com/FusionAuth/fusi Next, create a route to get to that page. This checks if an access token is present. If one isn't, it forces a logout at FusionAuth. If one is, it renders the `/account` page. - @@ -205,7 +173,7 @@ Now when you log in, you should see the `/account` page! ### Add Logout Support The last step is to implement logout. When you log a user out of an application, you'll take them to FusionAuth's `/oauth2/logout` endpoint. After logging the user out, FusionAuth will redirect the user to your app's `/logout` endpoint, which you'll create now. This endpoint deletes any cookies that your application created, and clears the Flask session. - @@ -214,20 +182,5 @@ Click the `Logout` button and watch the browser first go to FusionAuth to log ou ## Next Steps -This quickstart is a great way to get a proof of concept up and running quickly, but to run your application in production, there are some things you're going to want to do. - -### FusionAuth Customization -FusionAuth gives you the ability to customize just about everything with the user's experience and your application's integration. This includes -* [Hosted pages](/docs/customize/look-and-feel/) such as login, registration, email verification, and many more -* [Email templates](/docs/customize/email-and-messages/email-templates) -* [User data and custom claims in access token JWTs](/articles/tokens/jwt-components-explained) - -### Security -* You may want to customize the [token expiration times and policies](/docs/lifecycle/authenticate-users/oauth/#configure-application-oauth-settings) in FusionAuth -* Choose [password rules](/docs/get-started/core-concepts/tenants#password) and a [hashing algorithm](/docs/reference/password-hashes) that meet your security needs - -### Tenant and Application Management -* Model your application topology using [Applications](/docs/get-started/core-concepts/applications), [Roles](/docs/get-started/core-concepts/roles), [Groups](/docs/get-started/core-concepts/groups), [Entities](/docs/get-started/core-concepts/groups), and more -* Set up [MFA](/docs/lifecycle/authenticate-users/multi-factor-authentication), [Social login](/docs/lifecycle/authenticate-users/identity-providers/), and/or [SAML](/docs/lifecycle/authenticate-users/identity-providers/overview-samlv2) integrations -* Integrate with external systems using [Webhooks](/docs/extend/events-and-webhooks/), [SCIM](/docs/lifecycle/migrate-users/scim/scim), and [Lambdas](/docs/extend/code/lambdas/) + diff --git a/astro/src/content/quickstarts/quickstart-react-native.mdx b/astro/src/content/quickstarts/quickstart-react-native.mdx index 845ce91f6f..5f3fa1f7f8 100644 --- a/astro/src/content/quickstarts/quickstart-react-native.mdx +++ b/astro/src/content/quickstarts/quickstart-react-native.mdx @@ -10,20 +10,18 @@ icon: /img/icons/react.svg faIcon: fa-r color: indigo cta: EmailListCTA +codeRoot: https://raw.githubusercontent.com/FusionAuth/fusionauth-quickstart-react-native/main/ --- import Aside from '../../components/Aside.astro'; +import DockerSpinup from '/src/components/quickstarts/DockerSpinup.astro'; import IconButton from '../../components/IconButton.astro'; -import LoginAfter from '../../diagrams/quickstarts/login-after.astro'; -import LoginBefore from '../../diagrams/quickstarts/login-before.astro'; +import Intro from '/src/components/quickstarts/Intro.astro'; +import LoginArchitectureWeb from '/src/components/quickstarts/LoginArchitectureWeb.astro'; +import NextSteps from '/src/components/quickstarts/NextSteps.astro'; import {RemoteCode, RemoteValue} from '@fusionauth/astro-components'; -export const GITHUB_URL = 'https://raw.githubusercontent.com/FusionAuth/fusionauth-quickstart-react-native/main/'; -In this quickstart you are going to build an application with React Native and integrate it with FusionAuth. -You'll be building it for [ChangeBank](https://www.youtube.com/watch?v=CXDxNCzUspM), a global leader in converting dollars into coins. -It'll have areas reserved for users who have logged in as well as public facing sections. - -The docker compose file and source code for a complete application are available at -https://github.com/FusionAuth/fusionauth-quickstart-react-native + ## Prerequisites @@ -36,17 +34,7 @@ This app has been tested with React Native 0.72.4 and Node 20. This example shou ## General Architecture -While this sample application doesn't have login functionality without FusionAuth, a more typical integration will replace an existing login system with FusionAuth. - -In that case, the system might look like this before FusionAuth is introduced. - - - -The login flow will look like this after FusionAuth is introduced. - - - -In general, you are introducing FusionAuth in order to normalize and consolidate user data. This helps make sure it is consistent and up-to-date as well as offloading your login security and functionality to FusionAuth. + ## Getting Started @@ -63,27 +51,7 @@ cd fusionauth-quickstart-react-native ### Run FusionAuth via Docker -In the root directory of the repo you'll find a Docker compose file (`docker-compose.yml`) and an environment variables configuration file (`.env`). Assuming you have Docker installed on your machine, you can stand up FusionAuth up on your machine with: - -``` -docker compose up -d -``` - -Here you are using a bootstrapping feature of FusionAuth, called [Kickstart](/docs/get-started/download-and-install/development/kickstart). When FusionAuth comes up for the first time, it will look at the `kickstart/kickstart.json` file and configure FusionAuth to a certain initial state. - - - -FusionAuth will be initially configured with these settings: - -* Your client Id is -* Your client secret is . -* Your example username is and the password is . -* Your admin username is and the password is . -* The base URL of FusionAuth `http://localhost:9011/`. - -You can log into the [FusionAuth admin UI](http://localhost:9011/admin) and look around if you want, but with Docker/Kickstart you don't need to. + ### Expose your Instance @@ -118,14 +86,14 @@ npx expo install expo-auth-session expo-crypto expo-web-browser Create a `.env` file to hold information about your FusionAuth instance and application, replacing the value in `EXPO_PUBLIC_FUSIONAUTH_URL` with the address you copied from `ngrok` when [exposing your instance](#expose-your-instance). - Replace `app.json` with the contents below to add some details about your app: - A `scheme` that will be used when redirecting back to your application after logging in and out of FusionAuth. - The package name for both Android (`expo.android.package`) and iOS (`expo.ios.bundleIdentifier`) builds. - ## App Customization @@ -142,7 +110,7 @@ npm install expo-image expo-constants react-native-currency-input Instead of using CSS, React Native has its own concept of [stylesheets](https://reactnative.dev/docs/stylesheet). Create a file named `changebank.style.js` with the contents below to style your ChangeBank app. - Run the command below to download the ChangeBank logo into the `assets` folder. @@ -155,7 +123,7 @@ wget -O assets/changebank.svg https://raw.githubusercontent.com/FusionAuth/fusio Replace the existing `App.js` to integrate `expo-auth-session`, add the ChangeBank template, and stitch everything up. - ## Run the App @@ -196,26 +164,15 @@ Wait a few seconds and Expo will build and install the app in your device. You s If it is your first time running the app, ngrok will ask if you really want to continue to that page, so click `Visit Site`. -You'll finally arrive at the FusionAuth login screen. Fill in and and click on `Submit` to be redirected back to the logged-in ChangeBank page. +You'll finally arrive at the FusionAuth login screen. Fill in and and click on `Submit` to be redirected back to the logged-in ChangeBank page. ## Next Steps -This quickstart is a great way to get a proof of concept up and running quickly, but to run your application in production, there are some things you're going to want to do. - -### FusionAuth Customization -FusionAuth gives you the ability to customize just about everything with the user's experience and your application's integration. This includes -* [Hosted pages](/docs/customize/look-and-feel/) such as login, registration, email verification, and many more -* [Email templates](/docs/customize/email-and-messages/email-templates) -* [User data and custom claims in access token JWTs](/articles/tokens/jwt-components-explained) - -### Security -* [Expo AuthSession](https://docs.expo.dev/versions/latest/sdk/auth-session/) handles token validation and refresh -* You may want to customize the [token expiration times and policies](/docs/lifecycle/authenticate-users/oauth/#configure-application-oauth-settings) in FusionAuth -* Choose [password rules](/docs/get-started/core-concepts/tenants#password) and a [hashing algorithm](/docs/reference/password-hashes) that meet your security needs - -### Tenant and Application Management -* Model your application topology using [Applications](/docs/get-started/core-concepts/applications), [Roles](/docs/get-started/core-concepts/roles), [Groups](/docs/get-started/core-concepts/groups), [Entities](/docs/get-started/core-concepts/groups), and more -* Set up [MFA](/docs/lifecycle/authenticate-users/multi-factor-authentication), [Social login](/docs/lifecycle/authenticate-users/identity-providers/), and/or [SAML](/docs/lifecycle/authenticate-users/identity-providers/overview-samlv2) integrations -* Integrate with external systems using [Webhooks](/docs/extend/events-and-webhooks/), [SCIM](/docs/lifecycle/migrate-users/scim/scim), and [Lambdas](/docs/extend/code/lambdas/) + + + +
  • [Expo AuthSession](https://docs.expo.dev/versions/latest/sdk/auth-session/) handles token validation and refresh.
    • +     +     ### Build your App for Distribution diff --git a/astro/src/content/quickstarts/quickstart-ruby-on-rails-api.mdx b/astro/src/content/quickstarts/quickstart-ruby-on-rails-api.mdx index 66f10266b6..deb204144e 100644 --- a/astro/src/content/quickstarts/quickstart-ruby-on-rails-api.mdx +++ b/astro/src/content/quickstarts/quickstart-ruby-on-rails-api.mdx @@ -10,15 +10,18 @@ icon: /img/icons/ruby-on-rails.svg faIcon: fa-gem color: red cta: EmailListCTA -coderoot: https://raw.githubusercontent.com/FusionAuth/fusionauth-quickstart-ruby-on-rails-api/main +codeRoot: https://raw.githubusercontent.com/FusionAuth/fusionauth-quickstart-ruby-on-rails-api/main --- import Aside from '../../components/Aside.astro'; -import Diagram from '../../diagrams/quickstarts/resource-server.astro'; +import DockerSpinup from '/src/components/quickstarts/DockerSpinup.astro'; +import Intro from '/src/components/quickstarts/Intro.astro'; +import LoginArchitectureApi from '/src/components/quickstarts/LoginArchitectureApi.astro'; +import NextStepsApi from '/src/components/quickstarts/NextStepsApi.astro'; import {RemoteCode} from '@fusionauth/astro-components'; -In this article, you are going to learn how to integrate a Ruby on Rails API with FusionAuth. You will protect an API resource from unauthorized usage. You'll be building it for [ChangeBank](https://www.youtube.com/watch?v=CXDxNCzUspM), a global leader in converting dollars into coins. - -The docker compose file and source code for a complete application are available at https://github.com/FusionAuth/fusionauth-quickstart-ruby-on-rails-api. + ## Prerequisites @@ -30,11 +33,7 @@ The docker compose file and source code for a complete application are available ## General Architecture -A client wants access to an API resource at `/resource`. However, it is denied this resource until it acquires an access token from FusionAuth. - - - -While the access token is acquired via the Login API above, this is for simplicity of illustration. The token can be, and typically is, acquired through one of the [OAuth grants](/docs/lifecycle/authenticate-users/oauth/). + ## Getting Started @@ -51,28 +50,7 @@ cd fusionauth-quickstart-ruby-on-rails-api ### Run FusionAuth Via Docker -In the root directory of the repo you’ll find a Docker compose file (docker-compose.yml) and an environment variables configuration file (.env). Assuming you have Docker installed on your machine, you can stand up FusionAuth up on your machine with: - -``` -docker compose up -d -``` - -Here you are using a bootstrapping feature of FusionAuth, called [Kickstart](/docs/get-started/download-and-install/development/kickstart). When FusionAuth comes up for the first time, it will look at the `kickstart/kickstart.json` file and configure FusionAuth to a certain initial state. - - - -FusionAuth will be initially configured with these settings: - -* Your client Id is: `e9fdb985-9173-4e01-9d73-ac2d60d1dc8e` -* Your client secret is: `super-secret-secret-that-should-be-regenerated-for-production` -* Your example teller username is `teller@example.com` and your password is `password`. They will have the role of `teller`. -* Your example customer username is `customer@example.com` and your password is `password`. They will have the role of `customer`. -* Your admin username is `admin@example.com` and your password is `password`. -* Your fusionAuthBaseUrl is 'http://localhost:9011/' - -You can log into the [FusionAuth admin UI](http://localhost:9011/admin) and look around if you want, but with Docker/Kickstart you don't need to. + ## Create Your Ruby on Rails Resource Server Application @@ -116,7 +94,7 @@ gem 'dotenv-rails' Your full `Gemfile` will now look like - Then, install these new gems, by issuing the following command in your terminal window. @@ -128,7 +106,7 @@ bundle install Update `/config/routes.rb` to include the two new routes that will be created for `/make-change` and `/panic`. Your `routes.rb` file should now match the below code. - ### Add Security @@ -145,7 +123,7 @@ CLIENT_ID=e9fdb985-9173-4e01-9d73-ac2d60d1dc8e Utilizing the environment variables you just added, you can now setup JSON Web Token (JWT) based authentication. Create a new file `config/initializers/jwt_rack.rb`. This initializer is used to hold configuration settings that are made after all of the frameworks and plugins are loaded. - Having this code protects your endpoints from anonymous users and passes the JWT payload to the controller. The JWT payload includes `roles` encoded in the JWT you receive from FusionAuth. The decoded payload of a JWT for a `teller` might look like this: @@ -174,12 +152,12 @@ Having this code protects your endpoints from anonymous users and passes the JWT Create a new file for the MakeChangeController `app/controllers/make_change_controller.rb`. This controller will verify that the authenticated user has either the `teller` or `customer` role. It then takes in the url parameter `total` to calculate which coins will be returned in the JSON payload. - Create a new file for the PanicController `app/controllers/panic_controller.rb`. This controller will verify that the authenticated user has only the `teller` role. It will respond with `Proper role not found for user.` if this role is not found. This route also verifies that this is a `POST` request and if this is not true it will respond with `Only POST method is supported.` If both of these tests are passed the controller will return a successful message of `We've called the police!`. - ## Run the API @@ -368,17 +346,7 @@ Enjoy your secured resource server! ## Next Steps -This quickstart is a great way to get a proof of concept up and running quickly, but to run your API in production, there are some things you're going to want to do. - -### FusionAuth Integration - -* Rather than call the Login API, you're probably going to want to use the [Authorization Code grant](/docs/lifecycle/authenticate-users/oauth/#example-authorization-code-grant), which keeps all sensitive credentials within the bounds of FusionAuth. You can customize the [hosted login pages](/docs/customize/look-and-feel/). -* You may want to generate a token using the [Client Credentials grant](/docs/lifecycle/authenticate-users/oauth/#example-client-credentials-grant) if you are calling the API from another service. - -### Security -* Customize the [token expiration times and policies](/docs/lifecycle/authenticate-users/oauth/#configure-application-oauth-settings) in FusionAuth -* [Make sure you know how to securely consume a token](/articles/tokens/building-a-secure-jwt#consuming-a-jwt) -* Secure your API [using an API gateway](/docs/extend/examples/api-gateways/) rather than at the framework layer. + ## Troubleshooting diff --git a/astro/src/content/quickstarts/quickstart-ruby-rails-web.mdx b/astro/src/content/quickstarts/quickstart-ruby-rails-web.mdx index dcbda7f645..6fc34b14c6 100644 --- a/astro/src/content/quickstarts/quickstart-ruby-rails-web.mdx +++ b/astro/src/content/quickstarts/quickstart-ruby-rails-web.mdx @@ -13,16 +13,14 @@ cta: EmailListCTA --- import Aside from '../../components/Aside.astro'; import Code from 'astro/components/Code.astro'; -import LoginAfter from '../../diagrams/quickstarts/login-after.astro'; -import LoginBefore from '../../diagrams/quickstarts/login-before.astro'; +import DockerSpinup from '/src/components/quickstarts/DockerSpinup.astro'; +import Intro from '/src/components/quickstarts/Intro.astro'; +import LoginArchitectureWeb from '/src/components/quickstarts/LoginArchitectureWeb.astro'; +import NextSteps from '/src/components/quickstarts/NextSteps.astro'; import {RemoteCode, RemoteValue} from '@fusionauth/astro-components'; -In this quickstart you are going to build an application with Ruby on Rails and integrate it with FusionAuth. -You'll be building it for [ChangeBank](https://www.youtube.com/watch?v=CXDxNCzUspM), a global leader in converting dollars into coins. -It'll have areas reserved for users who have logged in as well as public facing sections. - -The docker compose file and source code for a complete application are available at -https://github.com/FusionAuth/fusionauth-quickstart-ruby-on-rails-web + ## Prerequisites @@ -34,17 +32,7 @@ This app has been tested with Ruby 3.2.2 and Rails 7.0.4.3. This example should ## General Architecture -While this sample application doesn't have login functionality without FusionAuth, a more typical integration will replace an existing login system with FusionAuth. - -In that case, the system might look like this before FusionAuth is introduced. - - - -The login flow will look like this after FusionAuth is introduced. - - - -In general, you are introducing FusionAuth in order to normalize and consolidate user data. This helps make sure it is consistent and up-to-date as well as offloading your login security and functionality to FusionAuth. + ## Getting Started @@ -61,27 +49,7 @@ cd fusionauth-quickstart-ruby-on-rails-web ### Run FusionAuth via Docker -In the root directory of the repo you'll find a Docker compose file (docker-compose.yml) and an environment variables configuration file (.env). Assuming you have Docker installed on your machine, you can stand up FusionAuth up on your machine with: - -``` -docker compose up -d -``` - -Here you are using a bootstrapping feature of FusionAuth, called [Kickstart](/docs/get-started/download-and-install/development/kickstart). When FusionAuth comes up for the first time, it will look at the `kickstart/kickstart.json` file and configure FusionAuth to a certain initial state. - - - -FusionAuth will be initially configured with these settings: - -* Your client Id is . -* Your client secret is . -* Your example username is and the password is . -* Your admin username is and the password is . -* The base URL of FusionAuth `http://localhost:9011/`. - -You can log into the [FusionAuth admin UI](http://localhost:9011/admin) and look around if you want, but with Docker/Kickstart you don't need to. + ### Create your Ruby on Rails Application @@ -232,24 +200,12 @@ Start up the Rails application using this command: You can now open up an incognito window and visit the Rails app at http://localhost:3000 . Log in with the user account you created when setting up FusionAuth, and you’ll see the email of the user next to a logout button. ## Next Steps -This quickstart is a great way to get a proof of concept up and running quickly, but to run -your application in production, there are some things you're going to want to do. - -### FusionAuth Customization -FusionAuth gives you the ability to customize just about everything with the user's experience and your application's integration. This includes -* [Hosted pages](/docs/customize/look-and-feel/) such as login, registration, email verification, and many more -* [Email templates](/docs/customize/email-and-messages/email-templates) -* [User data and custom claims in access token JWTs](/articles/tokens/jwt-components-explained) - -### Security -* [OmniAuth OpenIDConnect](https://github.com/omniauth/omniauth) handles token validation and refresh -* You may want to customize the [token expiration times and policies](/docs/lifecycle/authenticate-users/oauth/#configure-application-oauth-settings) in FusionAuth -* Choose [password rules](/docs/get-started/core-concepts/tenants#password) and a [hashing algorithm](/docs/reference/password-hashes) that meet your security needs - -### Tenant and Application Management -* Model your application topology using [Applications](/docs/get-started/core-concepts/applications), [Roles](/docs/get-started/core-concepts/roles), [Groups](/docs/get-started/core-concepts/groups), [Entities](/docs/get-started/core-concepts/groups), and more -* Set up [MFA](/docs/lifecycle/authenticate-users/multi-factor-authentication), [Social login](/docs/lifecycle/authenticate-users/identity-providers/), and/or [SAML](/docs/lifecycle/authenticate-users/identity-providers/overview-samlv2) integrations -* Integrate with external systems using [Webhooks](/docs/extend/events-and-webhooks/), [SCIM](/docs/lifecycle/migrate-users/scim/scim), and [Lambdas](/docs/extend/code/lambdas/) + + + +
  • [OmniAuth OpenIDConnect](https://github.com/omniauth/omniauth) handles token validation and refresh.
    • +     +     ## Troubleshooting diff --git a/astro/src/content/quickstarts/quickstart-swift-ios-native.mdx b/astro/src/content/quickstarts/quickstart-swift-ios-native.mdx index 207c90f815..0d9d0c1425 100644 --- a/astro/src/content/quickstarts/quickstart-swift-ios-native.mdx +++ b/astro/src/content/quickstarts/quickstart-swift-ios-native.mdx @@ -13,17 +13,18 @@ cta: EmailListCTA codeRoot: https://raw.githubusercontent.com/FusionAuth/fusionauth-quickstart-swift-ios-native/main --- import Aside from '../../components/Aside.astro'; -import LoginAfter from '../../diagrams/quickstarts/login-after-native.astro'; -import LoginBefore from '../../diagrams/quickstarts/login-before-native.astro'; +import DockerSpinup from '/src/components/quickstarts/DockerSpinup.astro'; +import Intro from '/src/components/quickstarts/Intro.astro'; +import LoginArchitectureWeb from '/src/components/quickstarts/LoginArchitectureWeb.astro'; import IconButton from '../../components/IconButton.astro'; import Breadcrumb from '../../components/Breadcrumb.astro'; import InlineUIElement from '../../components/InlineUIElement.astro'; import Field from '../../components/Field.astro'; +import NextSteps from '/src/components/quickstarts/NextSteps.astro'; import {RemoteCode} from '@fusionauth/astro-components'; -In this quickstart, you'll build an iOS app with Swift and SwiftUI and integrate it with FusionAuth. You'll build it for [ChangeBank](https://www.youtube.com/watch?v=CXDxNCzUspM), a global leader in converting dollars to coins. It will have areas reserved for users who have logged in as well as public-facing sections. - -The Docker Compose file and source code for a complete application are available at https://github.com/FusionAuth/fusionauth-quickstart-swift-ios-native. + ## Prerequisites @@ -35,17 +36,7 @@ This app was built using [AppAuth](https://github.com/openid/AppAuth-ios), an op ## General Architecture -While this sample application doesn't have login functionality without FusionAuth, a more typical integration would replace an existing login system with FusionAuth. - -In that case, the system might look like this before FusionAuth is introduced. - - - -The login flow will look like this after FusionAuth is introduced. - - - -In general, you would introduce FusionAuth to normalize and consolidate user data so that it is consistent and up to date, and offload your login security and functionality to FusionAuth. + ## Getting Started @@ -62,25 +53,7 @@ cd fusionauth-quickstart-swift-ios-native ### Run FusionAuth Via Docker -You'll find a Docker Compose file `docker-compose.yml` and an environment variables configuration file `.env` in the root directory of the repo. Assuming you have Docker installed, you can stand up FusionAuth on your machine with the following. - -```shell -docker compose up -d -``` - -Here you are using a bootstrapping feature of FusionAuth called [Kickstart](/docs/get-started/download-and-install/development/kickstart). When FusionAuth comes up for the first time, it will look at the `kickstart/kickstart.json` file and configure FusionAuth to your specified state. - - - -FusionAuth will be initially configured with these settings: - -* Your client Id is `e9fdb985-9173-4e01-9d73-ac2d60d1dc8e`. -* Your client secret is `super-secret-secret-that-should-be-regenerated-for-production`. -* Your example username is `richard@example.com` and the password is `password`. -* Your admin username is `admin@example.com` and the password is `password`. -* The base URL of FusionAuth is `http://localhost:9011/`. + ### Create Your iOS App @@ -259,27 +232,11 @@ Note that you need to enable [developer mode](https://developer.apple.com/docume ## Next Steps -This quickstart is a great way to get a proof of concept up and running quickly, but to run your application in production, there are some things you're going to want to do. - -### FusionAuth Customization - -FusionAuth gives you the ability to customize just about everything to do with the user's experience and your application's integration. This includes: - -* [Hosted pages](/docs/customize/look-and-feel/) such as login, registration, email verification, and many more -* [Email templates](/docs/customize/email-and-messages/email-templates) -* [User data and custom claims in access token JWTs](/articles/tokens/jwt-components-explained) - -### Security - -* Implement refresh tokens using [AppAuth](https://github.com/openid/AppAuth-ios). -* Customize the [token expiration times and policies](/docs/lifecycle/authenticate-users/oauth/#configure-application-oauth-settings) in FusionAuth. -* Choose [password rules](/docs/get-started/core-concepts/tenants#password) and a [hashing algorithm](/docs/reference/password-hashes) that meet your security needs. - -### Tenant And Application Management - -* Model your application topology using [Applications](/docs/get-started/core-concepts/applications), [Roles](/docs/get-started/core-concepts/roles), [Groups](/docs/get-started/core-concepts/groups), [Entities](/docs/get-started/core-concepts/groups), and more. -* Set up [MFA](/docs/lifecycle/authenticate-users/multi-factor-authentication), [Social login](/docs/lifecycle/authenticate-users/identity-providers/), and/or [SAML](/docs/lifecycle/authenticate-users/identity-providers/overview-samlv2) integrations. -* Integrate with external systems using [Webhooks](/docs/extend/events-and-webhooks/), [SCIM](/docs/lifecycle/migrate-users/scim/scim), and [Lambdas](/docs/extend/code/lambdas/). + + + * Implement refresh tokens using [AppAuth](https://github.com/openid/AppAuth-ios). + + ## Troubleshooting diff --git a/astro/src/content/quickstarts/quickstart-wordpress-web.mdx b/astro/src/content/quickstarts/quickstart-wordpress-web.mdx index 1d916caea4..4065e97e48 100644 --- a/astro/src/content/quickstarts/quickstart-wordpress-web.mdx +++ b/astro/src/content/quickstarts/quickstart-wordpress-web.mdx @@ -14,16 +14,17 @@ codeRoot: https://raw.githubusercontent.com/FusionAuth/fusionauth-quickstart-wor --- import Aside from '../../components/Aside.astro'; +import DockerSpinup from '/src/components/quickstarts/DockerSpinup.astro'; import InlineUIElement from '../../components/InlineUIElement.astro'; +import Intro from '/src/components/quickstarts/Intro.astro'; import Breadcrumb from '../../components/Breadcrumb.astro'; import Field from '../../components/Field.astro'; -import LoginAfter from '../../diagrams/quickstarts/login-after.astro'; -import LoginBefore from '../../diagrams/quickstarts/login-before.astro'; +import LoginArchitectureWeb from '/src/components/quickstarts/LoginArchitectureWeb.astro'; +import NextSteps from '/src/components/quickstarts/NextSteps.astro'; import {RemoteCode} from '@fusionauth/astro-components'; -In this quickstart, you will build an application with {frontmatter.technology} and integrate it with FusionAuth. The application is for [ChangeBank](https://www.youtube.com/watch?v=pkH-kD73QUM), a global leader in converting dollars into coins. It will have areas reserved for logged in users and public-facing sections. - -Find the Docker Compose file and source code for the complete application at {frontmatter.url}. + ## Prerequisites @@ -33,17 +34,7 @@ For this Quickstart, you'll need: ## General Architecture -While this sample application doesn't have login functionality without FusionAuth, a more typical integration will replace an existing login system with FusionAuth. - -In that case, the system might look like this before FusionAuth is introduced. - - - -The login flow will look like this after FusionAuth is introduced. - - - -In general, you would introduce FusionAuth to normalize and consolidate user data, making it consistent and up-to-date and offloading your login security and functionality to FusionAuth. + ## Getting Started @@ -64,37 +55,7 @@ If you prefer to copy the files you’ll create in this guide, they already exis ### Run FusionAuth Via Docker -You'll find a Docker Compose file `docker-compose.yml` and an environment variables configuration file `.env` in the root directory of the repository. - -Assuming you have Docker installed on your machine, you can start FusionAuth and {frontmatter.technology} on your machine with the following. - -```shell -docker compose up -d -``` - -This will start five containers, one each for FusionAuth, Postgres, Opensearch, MySQL for {frontmatter.technology}, and {frontmatter.technology}. - -Here you are using a bootstrapping feature of FusionAuth, called [Kickstart](/docs/get-started/download-and-install/development/kickstart). When FusionAuth comes up for the first time, it will look at the `kickstart/kickstart.json` file and configure FusionAuth to a certain initial state. - - - -FusionAuth will be configured with these settings: - -* Your client Id is `e9fdb985-9173-4e01-9d73-ac2d60d1dc8e`. -* Your client secret is `super-secret-secret-that-should-be-regenerated-for-production`. -* Your example username is `richard@example.com` and the password is `password`. -* Your admin username is `admin@example.com` and the password is `password`. -* The base URL of FusionAuth is `http://localhost:9011/`. - -You can log in to the [FusionAuth admin UI](http://localhost:9011/admin) and look around if you want to, but with Docker and Kickstart, everything will already be configured correctly. - - + ### Create A Basic {frontmatter.technology} Application @@ -336,26 +297,7 @@ The demonstration application is now complete. Log out. Verify that you can't br ## Next Steps -This quickstart is a great way to get a proof of concept up and running quickly, but to run your application in production, there are some things you're going to want to do. - -### FusionAuth Customization - -FusionAuth gives you the ability to customize just about everything to do with the user's experience and the integration of your application. This includes: - -* [Hosted pages](/docs/customize/look-and-feel/) such as login, registration, email verification, and many more. -* [Email templates](/docs/customize/email-and-messages/). -* [User data and custom claims in access token JWTs](/articles/tokens/jwt-components-explained). - -### Security - -* You may want to customize the [token expiration times and policies](/docs/lifecycle/authenticate-users/oauth/#configure-application-oauth-settings) in FusionAuth. -* Choose [password rules](/docs/get-started/core-concepts/tenants#password) and a [hashing algorithm](/docs/reference/password-hashes) that meet your security needs. - -### Tenant And Application Management - -* Model your application topology using [Applications](/docs/get-started/core-concepts/applications), [Roles](/docs/get-started/core-concepts/roles), [Groups](/docs/get-started/core-concepts/groups), [Entities](/docs/get-started/core-concepts/entity-management), and more. -* Set up [MFA](/docs/lifecycle/authenticate-users/multi-factor-authentication), [Social login](/docs/lifecycle/authenticate-users/identity-providers/social/), or [SAML](/docs/lifecycle/authenticate-users/saml) integrations. -* Integrate with external systems using [Webhooks](/docs/extend/events-and-webhooks/), [SCIM](/docs/lifecycle/migrate-users/scim/), and [Lambdas](/docs/extend/code/lambdas/). + ## Troubleshooting diff --git a/astro/src/diagrams/quickstarts/login-after-sdk.astro b/astro/src/diagrams/quickstarts/login-after-sdk.astro index 4686089d46..9688334794 100644 --- a/astro/src/diagrams/quickstarts/login-after-sdk.astro +++ b/astro/src/diagrams/quickstarts/login-after-sdk.astro @@ -1,6 +1,6 @@ --- import Diagram from "../../components/mermaid/SequenceDiagram.astro"; -const { alt } = Astro.props; +const { alt = "Request flow during login after FusionAuth" } = Astro.props; //language=Mermaid const diagram = `