Add FusionAuth Login to an App You Build

Your app sends users to the FusionAuth hosted login pagesThe login, registration, password recovery, and multi-factor authentication pages that FusionAuth serves. A Theme controls the look of the pages. with the Authorization Code GrantAn OAuth 2.0 grant type in which a client exchanges an authorization code for tokens.. After login, FusionAuth redirects the browser back to your app with a code, and your app exchanges the code for tokens. An OpenID Connect library builds the requests and validates the tokens, so you configure the library and FusionAuth. To add login to software you don't build, such as a SaaS product, see Add Login to an External App.

For a working sample app in your framework, start from a QuickStart instead.

Before You Begin#

You need:

• Admin access to FusionAuth.
• An OpenID Connect library for your framework, or a FusionAuth SDK.
• The URL in your app that receives the user after login, such as https://app.example.com/callback.
• A test user in the TenantA logical container for Users, Applications, and settings that is isolated from other Tenants. you plan to use.

Set the Issuer#

FusionAuth puts the Tenant Issuer in the iss claim of every token and in the discovery document. The setup wizard sets the issuer to the URL you used during setup, which might be localhost. Installs that skip the setup wizard, such as Kickstart installs, keep a placeholder such as https://example.com. New Tenants copy the issuer of the Default Tenant. A library that takes an issuer instead of a discovery URL loads the endpoints from the issuer, so the placeholder breaks login. To set the issuer to the URL your app uses to reach FusionAuth:

1. Navigate to Tenants and click next to your Tenant.
2. On the General tab, set Issuer to the FusionAuth URL, such as https://auth.example.com.
3. Click .

Create an Application#

Each app needs its own ApplicationA software program that your users log in to through FusionAuth. in FusionAuth. To create and configure the Application:

1. Navigate to Applications and click .
2. Enter a Name and select the Tenant that holds your users.
3. Select the OAuth tab.
4. Add the callback URL of your app to Authorized redirect URLs.
5. Set Logout URL to the page your app shows after logout.
6. Set PKCE to Required.
7. Set Client Authentication for your type of app:
   • For an app with a server that can keep a secret, keep the default, Required.
   • For a single-page or mobile app, select Not required when using PKCE. A browser or a device can't keep the client secret private.
8. Click .

New Applications enable the Authorization Code and Refresh Token grants and Generate refresh tokens, so your app can keep users logged in after the access token expires.

Register Users#

Any user in the Tenant can log in by default. FusionAuth adds the roles claim to the tokens only when the user has a RegistrationThe association between a User and an Application. for the Application.

To register the test user, navigate to Users , click next to the user, and click Add registration. To let users register themselves, turn on self-service registration. To block users without a registration, enable Require registration to complete OAuth authorization on the OAuth tab.

Configure Your Library#

On the Applications page, open the action menu for the Application and select View . The dialog shows the values your library needs. See OAuth2 & OpenID Connect Integration Details.

Give your library these values:

Your library then sends users to the login page and exchanges the code for tokens. The library also validates the Id TokenA JSON Web Token that contains information about the authenticated user.: the signature, the iss and aud claims, and the expiration. For the claims in each token, see Tokens. For the requests your library makes, see the Authorization Code grant example.

Store tokens on your server, or in HttpOnly cookies for a browser app. For a single-page app without a backend, the hosted backend exchanges the code and sets the cookies for your app.

Log Users Out#

To log a user out, your app ends the app session and redirects the browser to the Logout URL from the View dialog:

https://auth.example.com/oauth2/logout?client_id={clientId}

FusionAuth ends the FusionAuth session and redirects the browser to the Application's Logout URL. To send the browser to another page, add a post_logout_redirect_uri parameter, and add that page to Authorized redirect URLs. FusionAuth shows an error page for a post_logout_redirect_uri that isn't in the list.

Confirm the Login#

To confirm that login works:

1. Open your app in a private browser window and start login.
2. Confirm that the browser shows the FusionAuth login page.
3. Log in as the test user.
4. Confirm that the browser returns to the callback URL and that your app shows the test user as logged in.
5. Log out, and confirm that the browser returns to your app.
6. Start login again, and confirm that FusionAuth asks for credentials.

When the login fails, enable Enable debug logging on the OAuth tab of the Application and try again. Read the details in System -> Event Log . Turn off debug logging when you finish.