Setup an Single-Page or Multi-Page Web Application
Learn more about how to setup a Single-Page or Multi-Page Web Application for use with Fusion.
Learn How To:

1) Setup an Application Policy within Fusion (using OAUTH2/OIDC)

To create an Application, follow these simple steps.
1) Start by logging into the Admin Console using an admin account.
2) From the left-hand menu, select Applications.
3) If you're just getting started with Fusion then the applications list will be empty. If any existing applications have been configured then they will be listed here.
4) To create a new application, click + Create Application button from the top right hand corner as shown below:
Click to enlarge
5) The Create Application page will now be displayed, as shown below:
Click to enlarge

General fields

Start with filling in your application's mandatory general fields:
Field Name
Description
Name
Define a name for this application. This name is displayed in the Applications listing and used to refer to this Application throughout Fusion.
Description
You can use this field to add any description or useful information that you may need for your Application.
It is also mandatory to set up an authorization standard for your application: choose between OAUTH2/OIDC or SAML. For more information on SAML see Setup a SAML Integration.
7) Next, you have the option to complete the Application Properties fields that are required to create an OAUTH2/OIDC Application integration.
The table below provides guidance on how to complete these fields:
Field Name
Description
Identity Store
Here is where you can choose which Identity Store you would like to use with this application. This is where any customer identities will be created and stored, or would authenticate from.
Adaptive MFA Policy
Here is where you can choose which Adaptive MFA Policy you would like to use with this application. See Setup and Manage Adaptive MFA for more information on creating your own.
Self-Service Policy
Here is where you can choose which Self-Service Policy you would like to use with this application. See Setup and Manage Self-Service for more information on creating your own.
Branding Policy
Here is where you can choose which Branding Policy you would like to use with this application. See Using Your Own Logo and Color Scheme for more information on creating your own branding policy.
Notification Policy
Here is where you can choose which Notification Policy you would like to use with this application. See Setup and Manage Notification Policies for more information on customizing your own customer notifications.

Application URLs

Website URL
This is an optional field where you can specify the URL to a page in your website or application that the customer is redirected back to using the 'Back to Website' links through the customer facing user interfaces.
Self-Service URL
This part contains the URL of your application where customers can register and log into their accounts
Customer Friendly Self-Service URL
This option creates a friendly self-service URL masking the parts of the URL not relevant for your customers. Enter the wording in the field you want to add to your domain.

Session management

8) If necessary you can change the session inactivity timeout. At 168 hours (7 days) by default, this is the length of time that the customer's session will persist without activity. After this duration, the customer will be forced to re-authenticate using their password.
9) If desired, you can also set the Login Session Maximum Age. This is the length of time that a session will be kept alive prior to login. If your customers complain that they are seeing the 'Session Expired' message during login, it will be because they are loading the login screen and then letting some period of time elapse that is longer than the time set here. To solve this problem, simply increase this time duration.

Login providers

10) Here, you can turn off Interactive Login and Registration when creating an API-only application.
11) The Enable Local Login option allows you to switch off local login and registration to limit your customers to external login providers.
When local login is disabled:
  • username or email address fields will not appear on the login screen
  • the forgotten username option will not be available
  • self-registration will be disabled
  • your customers will not see their remembered accounts
12) Next up, you can add Social and Enterprise providers for this application. See Setup and Manage Social Logins for further information on how to set them up.
13) Lastly, you can choose to configure any Consent Management options for this Application. For further information on setting up Consent Statements see Creating a Consent (if you do not have any created yet) or Assigning a Consent to an Application.
14) Once you've made any configuration changes to the Application Properties, click 'Save' to move on to configuring the OAUTH2/OIDC specific application settings below.

Setup OAUTH2/OIDC Application Properties

1) Next, click the OAuth2/OIDC Tab. The OAuth2/OIDC application properties screen will be displayed, as shown below:
Click to enlarge
Here is where you will complete all of the OAuth2/OIDC specific settings for integration with your Single-Page or Multi-Page Web Application.
2) The table below provides guidance on how to complete these fields:
Field Name
Description
Client ID
The Client ID is automatically generated by Fusion when you save the Application at the end of this process. This is the primary identifier used by your application to trust Fusion when it performs any services on its behalf (such as authentication). This is public.
Client Secret
The Client Secret is automatically generated by Fusion when you save the Application at the end of this process. This is a secret used by your application to trust Fusion when it performs any services on its behalf (such as authentication). This should be kept private.
Token Endpoint Authentication Method
This setting instructs Fusion on how clients will authenticate. This corresponds to OIDC token_endpoint_auth_method. Supported settings include "BASIC" or "POST". You typically do not need to change this setting.
JWT Signing Method
Fusion uses RS256 as the default algorithm for signing the JSON Web Tokens (JWTs). RS256 generates and uses and asymmetric signature.
Allowed Callback URLs
Here is where you configure the allowed callback URLs for the OIDC transaction. This typically corresponds to redirect_uri that an OIDC client would pass to Strivacity Fusion when a user wants to authenticate.
Allowed Logout URLs
Here is where you configure the allowed Logout URLs for the OIDC transaction. This typically corresponds to logout_uri that an OIDC client would pass to Strivacity Fusion when a user initiates a logout transaction.
Login URL
Here is where you configure the landing page for your application. This is where the user will end up once they finish logging in through Strivacity Fusion. For example https://yourwebsite/loginpage. Note: The Fusion hosted login page is not an entry point to the customer authentication flow.
Dialects
Here is where you can specify the claim dialect that is used by this Application. By default, the Fusion 'OpenID Connect' default claim dialect is used.
Enable Refresh Tokens
This is a customer convenience setting where you can enable or disable the use of refresh tokens, which means that any OIDC tokens can automatically refresh without requiring the customer to have to log back in.
3) Once you have completed all of these fields, click Save to complete the setup of the Application policy for your Single-Page or Multi-Page Web Application.
You can now proceed to integrating your application with OIDC using steps 2 through 5 below.

2) OIDC Support in Fusion

Fusion supports all standard OIDC flows.
  • Authorization Code Flow - This flow can be used by Single/Multi Page Applications that have access to a backend component that can be used to securely retrieve an id_token. This is the recommended flow for authenticating users.
  • Implicit Flow - This flow can be used by Single/Multi Page Applications that don't have access to a backend component.
  • Hybrid Flow - This flow is a combination of implicit and authorization code flows, as both an id_token and authorization code are returned by Fusion.
  • Client Credentials Flow - This flow is typically used for Machine-to-Machine (M2M) communications. With Fusion, this flow can be used to obtain access to Fusion REST APIs.

3) Configuring your Web Application to use Fusion (OIDC Redirection)

Developers or administrators of a web application typically only need to know a few pieces of information to redirect to Fusion for login and self-service related activities.
1) The Domain Name of the Fusion instance. In OIDC terms, this is generally referred to as the authority. This is available in the Tenant Configuration --> General section of the Fusion Admin Console.
2) The Client ID associated with the Application Configuration. This corresponds to the client_id parameter that an OIDC client would pass to Fusion when a user wants to authenticate. This tells Fusion what application configuration to associate the login or self service transaction with.
3) The Redirection URI. This corresponds to redirect_uri parameter that an OIDC client would pass to Fusion when a user wants to authenticate. This tells Fusion where to send the OIDC response containing the authorization code or id_token.
4) The Response Type. This corresponds to the response_type parameter that an OIDC client would pass to Fusion when a user wants to authenticate. This tells Fusion what type of OIDC flow is desired by the brand.
To start an OIDC flow with Fusion, a brand must construct an appropriate URL that the browser is sent to when a user clicks on to log in to the brand's web application.

For Login via Implicit Flow

To initiate a login via Implicit Flow, use the following URL template.
1
https://BRAND_DOMAIN.strivacity.com/oauth2/auth?
2
client_id=CLIENT_ID&
3
redirect_uri=REDIRECTION_URI&
4
response_type=id_token&
5
scope=openid&
6
state=<random string>&
7
nonce=<random string>
Copied!
The user will be asked to login, respecting the configured Adaptive MFA workflow. Upon successful completion of the login, the browser will be redirected to the redirect_uri specified. This will come in the form of a GET request containing the id_token and state parameters as URL fragments.
URL fragments are stripped by the browser prior to being sent to your HTTP server. This is a security feature of OIDC to prevent leaking sensitive items. This means that these parameters must be processed at the browser level, typically via javascript.

For Login via Authorization Code Flow

To initiate a login via Authorization Code Flow, use the following URL template.
1
https://BRAND_DOMAIN.strivacity.com/oauth2/auth?
2
client_id=CLIENT_ID&
3
redirect_uri=REDIRECTION_URI&
4
response_type=code&
5
scope=openid&
6
state=<random string>&
7
nonce=<random string>
Copied!
The user will be asked to login, respecting the configured Adaptive MFA workflow. Upon successful completion of the login, the browser will be redirected to the redirect_uri specified. This will come in the form of a GET request containing the code and state parameters as URL fragments.
URL fragments are stripped by the browser prior to being sent to your HTTP server. This is a security feature of OIDC to prevent leaking sensitive items. This means that these parameters must be processed at the browser level, typically via javascript.

For Login via Hybrid Flow

To initiate a login via Hybrid Flow, use the following URL template.
1
https://BRAND_DOMAIN.strivacity.com/oauth2/auth?
2
client_id=CLIENT_ID&
3
redirect_uri=REDIRECTION_URI&
4
response_type=id_token%20code&
5
scope=openid&
6
state=<random string>&
7
nonce=<random string>
Copied!
The user will be asked to login, respecting the configured Adaptive MFA workflow. Upon successful completion of the login, the browser will be redirected to the redirect_uri specified. This will come in the form of a GET request containing the id_token, code and state parameters as URL fragments.
URL fragments are stripped by the browser prior to being sent to your HTTP server. This is a security feature of OIDC to prevent leaking sensitive items. This means that these parameters must be processed at the browser level, typically via javascript.

Authorization Code Exchange

In flows involving authorization codes, the code may be exchanged for an id_token at the following endpoint:
1
https://BRAND_DOMAIN.strivacity.com/oauth2/token
Copied!
Please refer to the API Documentation for the details of this endpoint.

ID Tokens

The id_token is represented as a JSON Web Token (JWT). Once retrieved and decoded, the id_token has the following format.
1
{
2
"aud": [
3
"<string>"
4
],
5
"auth_time": <timestamp>,
6
"c_hash": "<string>",
7
"client_id": "<string>",
8
"exp": <timestamp>,
9
"iat": <timestamp>,
10
"iss": "https://BRAND_DOMAIN.strivacity.com/",
11
"jti": "<string>",
12
"nonce": "<string>",
13
"rat": <timestamp>,
14
"sid": "<string>",
15
"sub": "<string>",
16
"user_id": "<string>",
17
"username": "<string>"
18
}
Copied!
See the OpenID specification for an in depth discussion of these fields. The id_token MAY contain other claims such as the username.

4) Configuring your Web Application to use Fusion (OIDC Popup)

Brands may want to leverage Open ID Connect (OIDC) native support for authorization flows that happen via a popup window versus redirection.
Developers or administrators of a web application using an authorization code flow via popup typically only need to know a few pieces of information to redirect to Fusion for login and self-service related activities.
1) The Domain Name of the Fusion instance. In OIDC terms, this is generally referred to as the "authority." This is available in the Tenant Configuration --> General section of the Fusion Admin Console.
2) The Client ID associated with the Application Configuration. This tells Fusion what application configuration to associate the login or self service transaction with.
For this flow to work, the brand must add the following Callback URL within the Application Configuration Allowed Callback URLs list.
https://BRAND_DOMAIN.strivacity.com/login/callback/
This flow works in the following manner.
1) A customer would visit the brand portal and invoke the login flow via some method specified by the brand, such as a login button.
2) The login button would open a popup window that would load the Fusion login interface. For example, the popup could be opened up via javascript in the following manner:
1
const host = 'https://BRAND_DOMAIN.strivacity.com';
2
const clientId = 'CLIENT_ID';
3
const redirect = 'https://BRAND_DOMAIN.strivacity.com/login/callback/'
4
5
let state = <random string>
6
7
popup = window.open(
8
`${host}/oauth2/auth?response_type=code&display=popup&client_id=${clientId}&scope=openid&state=${state}&redirect_uri=${redirect}`,
9
'Strivacity',
10
'toolbar=no, menubar=no, width=600, height=700, top=100, left=100'
11
);
12
13
popup.window.focus();
Copied!
3) The customer would complete the login in the popup. The popup will automatically send its result to the opening window with no coding by the brand. Here is a snippet of the code the Fusion uses to achieve this:
1
const urlParams = new URLSearchParams(window.location.search);
2
3
let args: any = {};
4
urlParams.forEach((value, key) => args[key] = value)
5
6
if (window.opener) {
7
window.opener.postMessage(args, '*');
8
}
Copied!
The brand should hook to receive the callback message from the popup, similar to the following. The brand can also close the popup after receiving the message.
1
function onMessage(message) {
2
let data = message ? message.data : undefined;
3
4
if (popup) {
5
popup.window.close()
6
}
7
}
8
9
window.onload = function () {
10
window.addEventListener("message", onMessage, false);
11
}
Copied!
Upon successful completion of the login on the users behalf, the popup would send a message back to the parent window using this method, containing the OIDC response with the authorization code.
4) To complete the authentication, the brand portal must exchange this authorization code for an id token using the authorization code and client secret. This call should be done by the brands backend. It is advised to use a library to do this step, and not code it yourself. Here is a good list of libraries for this purpose. For example, in golang this could be achieved with the following call in the oauth2 library.
oauth2 package - golang.org/x/oauth2 - pkg.go.dev
5) Upon success, the brand portal can validate the id token as necessary and now consider this authentication complete. For example, in golang, token validation could be achieved with the following library call in the oauth2 library:
oauth2 package - golang.org/x/oauth2 - pkg.go.dev
6) The brand can create and manage its own session for the newly authenticated user.
7) The brand backend replies to the calling client with the result of the authentication and set any necessary session cookies.

5) Configure your Web Application to use Fusion (Self Service)

Fusion automatically provides brands with a URL to allow a user to navigate to the self service portal. Brands can link to this URL, directly, from their web application.
A fully constructed URL would look something like this:
1
https://BRAND_DOMAIN.strivacity.com/myaccount/oauth2/authorization/CLIENT_ID
Copied!
Please see the API Documentation for more information on the parameters in these URLs.

6) Well Known URLs

Use the table below to quickly give you the well known URLs for your Fusion instance.
Name
URL
Well Known OIDC Configuration
/.well-known/openid-configuration
Authorization Endpoint
/oauth2/auth
Token Endpoint
/oauth2/token
User Info Endpoint
/userinfo
Revocation Endpoint
/oauth2/revoke
Logout URL
/oauth2/sessions/logout

7) Error Handling

Use the table below to understand the various error codes that may be returned to your application by Fusion during an OIDC Flow. These error codes are returned to your application via a URL that looks something like this:
1
https://REDIRECTION_URI?error=<error>&error_description=<description>
Copied!
Error Code
Description
access_denied
Fusion denied the login request
invalid_client
Client authentication failed (e.g., unknown client, no client authentication included, or unsupported authentication method)
invalid_grant
The provided authorization grant (e.g., authorization code, resource owner credentials) or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client
invalid_request
The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed
invalid_scope
The requested scope is invalid, unknown, or malformed
registration_denied
Fusion denied the registration request
request_forbidden
Fusion denied the request because the session cookie was not present or was malformed
server_error
Fusion encountered an unexpected condition that prevented it from fulfilling the request
temporarily_unavailable
Fusion is currently unable to handle the request due to a temporary overloading or maintenance
unauthorized_client
The authenticated client is not authorized to use this authorization grant type
unsupported_grant_type
The authorization grant type is not supported by Fusion
unsupported_response_type
Fusion does not support obtaining an authorization code using this method