Walkthrough: Creating a user and page for testing Sitecore authentication

Version: 22.x

Sitecore Services Client (SSC) includes an Authentication Service that you can invoke in JSS applications to log into Sitecore and set the .ASPXAUTH cookie using REST requests.

Note

The SSC Authentication Service requires an SSL/TLS connection, meaning, for local development, you must set up a certificate and SSL bindings for your Sitecore site. Accessing your Sitecore instance using the HTTPS protocol should work, even with a security warning, before attempting to use SSC Authentication from a JSS app.

To test/explore authentication and security with a JSS sample app, you must create a user and a protected route from within Sitecore.

Important

The following steps require that your JSS application be imported into Sitecore.

This walkthrough describes how to:

Create an extranet user
Create a protected route
Configure JSS apps to authenticate with SSC Authentication Service

Create an extranet user

To log in to Sitecore, you must create a user.

To create a user:

Log in to Sitecore and access the Launchpad.
In the Access Management section, click User Manager.
On the ribbon, click New.
Specify the following fields:
- User name - enter a user name of your choice.
- Domain - select extranet.
- Email - enter a valid email address.
- Password - enter a password of your choice.
Click Next then click Close.

Create a protected route

To test authenticating with the Sitecore Authentication Service from a JSS app, you must have at least one protected route that requires users to log in before gaining access to the content.

To create a protected route:

Log in to Sitecore and access the Launchpad.
In the Content Editing section, click Content Editor.
In the content tree, navigate to the Home item of your JSS app, for example, /sitecore/content/JssReactWeb/home.
Right-click on the Home item, then click Insert , Extended Route.
Enter a name for the route.
With the new route still selected, on the Security tab, in the Presets section, select the Require login check box.
Click OK.
Publish your changes.

Configure JSS apps to authenticate with SSC Authentication Service

You can add simple login/logout functionality to your JSS app using the SSC Authentication services.

There are three different ways to authenticate depending on where the application is running.

Authenticate while developing locally against a Sitecore instance

When running the JSS application connected to Sitecore during development, a local server serves the app and the app renders in your browser, but the SSC Auth service requests are sent to a remote Sitecore instance.

To authenticate while running the application in connected mode:

In the scjssconfig.json file, set the remote Sitecore host URL to use SSL, by changing the URL to use the HTTPS protocol. For example, https://JssReactWeb.

In your application configuration, configure the headers Access-Control-Allow-Headers and Access-Control-Allow-Credentials:

RequestResponse

<add name="Access-Control-Allow-Headers" value="Content-Type, Accept, X-Requested-With, Session" />
<add name="Access-Control-Allow-Credentials" value="true" />

Because the SSC Auth service does not support an OPTIONS preflight cross-origin requests (CORS) out of the box, resulting in a 404 response, you must ensure you send your requests to the login service using a URL-encoded body, and not JSON. For example:

RequestResponse

// an example of sending a URL-encoded body using the fetch API (JavaScript)

import queryString from 'query-string';

const payload = {
  domain: 'extranet',
  username: 'test',
  password: 'b'
}

fetch('https://site.core.local/sitecore/api/ssc/auth/login?sc_apikey={DCE1069B-36E8-4A66-946E-C1B07071C38C}', {
  headers: {
    Accept: 'application/json',
    'Content-Type': 'application/x-www-form-urlencoded',
  },
  credentials: 'include',
  method: 'POST',
  body: queryString.stringify(payload),
}).then((response) => {
  console.log(response);
});

Authenticate in an integrated JSS app

When running the application in integrated mode, the calls to the SSC Authentication Service are made against the same hostname as that of the application, requiring no further setup.

For authentication to work correctly:

Access the Sitecore host over SSL, using the HTTPS protocol. For example, by visiting https://JssReactWeb.

Authenticate in a headlessly server-side rendered JSS app

When headlessly rendering your JSS application server-side, the proxy system proxies requests to the SSC Authentication Service and the .ASPXAUTH cookie without CORS issues.

For authentication to work correctly:

In the config.js file, update the apiHost to use the HTTPS protocol. For example, https://JssReactWeb.
If proxying to a development Sitecore instance using a privately signed certificate, ensure you have the correct setup to prevent SSL certificate validation issues:
- Configure Sitecore CA certificates for Node.js.
- Alternatively, in the config.js file, disable SSL validation entirely by setting secure to false in the proxy options. For example:
  RequestResponse
  proxyOptions: { secure: false }
  Important
  
  Do not disable SSL validation in production, as it makes your solution insecure.

Do you have some feedback for us?

If you have suggestions for improving this article,