Set up a single sign-on (SSO) client

10 min

📘 Note This feature is not available in net8.0+.

Background knowledge about OAuth2.0 and Open ID Connect is strongly recommended to fully use this article.

Using SSO delegates authentication and authorization to Configured Commerce and allows third party applications to access resources on behalf of users.

Configured Commerce uses IdentityServer - implementation of OpenID Connect (authentication) and OAuth2 (authorization).

📘 Note You must restart the application after configuring SSO.

🚧 Important You should not use Configured Commerce as the identity provider for other external applications. Optimizely recommends using an external identity provider, such as Okta. If you use Configured Commerce as the identity provider, Optimizely is not responsible for any updates that may cause issues in the future.

Setup in Admin Console

You can manage SSO clients in the Admin Console > Administration> Permissions > Single Sign On.

Configured Commerce storefront and admin SSO clients

Configured Commerce has three SSO clients available out-of-the-box that are automatically enabled and configured:

isc – Access to the Configured Commerce Storefront API.

admin – Access to the Configured Commerce Admin API.

mobile – Access to the Configured Commerce Mobile API.

You can use these SSO clients for authentication extensions or create your own clients as needed.

After you redirect users from Configured Commerce to a third party for authentication, you need to redirect them to your site to sign in. Use the following out-of-the-box SSO clients to complete these redirects:

isc_admin_ext – Add your Admin Console URL to the Redirect URIs field under this client to redirect users back to sign in to the Admin Console.

ext – Add your website URL to the Redirect URIs field under this client to redirect users back to sign in to your website (storefront).

Add and configure an SSO client

The list below describes the fields located under Single Sign On > Add Client .

📘 Note The Client fields roughly correspond to the Identity Server client settings.

Field	Description
Client Id	The Identity Server client id. Used to identify client making requests to Identity Server.
Client Name	Friendly display name for the Admin Console.
Flow	OAuth flows: Authorization Code - When an application exchanges an authorization code for an access token. This is just the code interacting, machine to machine. Implicit - When an application returns an access token immediately without an extra authorization code exchange step. Hybrid - When your application can immediately use an ID token to access information about the user while obtaining an authorization code that can be exchanged for an Access Token (therefore gaining access to protected resources for an extended period of time). Client Credentials - When the application passes along a user's Client ID and Client Secret to authenticate themselves and get a token. Resource Owner - When an application exchanges a user's credentials for an access token. Password is one we use in the mobile app from a third party. Custom - Your custom flow.
Enabled	Whether or not this client can be used for authentication or authorization.
Require Consent	Whether or not user will needs to give consent to the requesting application to access user data (e.g.
Access Admin Api	Assigns the "isc_admin" scope to this client. Allows client to use Admin OData API.
Access Website Api	Assigns the "iscapi" scope to this client. Allows client to use Storefront REST API.
Allow Refresh Tokens	Whether or not refresh tokens can be used to request new access tokens.
Allow Access Tokens Via Browser	Allows Identity Server to pass back access tokens through the browser to the requesting application (e.g. a form post).
Redirect Uris	Where Identity Server will send tokens after a successful authentication.
Access Token Lifetime	Length of time before access token expires.
Identity Token Lifetime	Length of time before identity token expires.
Authorization Code Lifetime	Length of time before authorization code expires.
Absolute Refresh Token Lifetime	Maximum length of time before refresh token expires.
Sliding Refresh Token Lifetime	Sliding lifetime of a refresh token. Works with the RefreshTokenExpiration values of: Absolute: the refresh token will expire on a fixed point in time (specified by the AbsoluteRefreshTokenLifetime) Sliding: when refreshing the token, the lifetime of the refresh token will be renewed (by the amount specified in SlidingRefreshTokenLifetime). The lifetime will not exceed AbsoluteRefreshTokenLifetime.

Use case (single sign on with authorization code)

Explanation

Similar to "Log in with Google" flow

Users log into external application using Configured Commerce account

Uses ASP.NET application as third party application wanting to access Configured Commerce data

Admin Console setup configures Identity Server client.

Setup client in Admin Console

Go to the Admin Console > Administration > Permissions > Single Sign On.

Click Add Client to add a new client.

Enter codeclient for Client Id.

Enter codeclient for Client Name.

Select Authorization Code under Flow.

Change Enabled to "Yes".

Change Require Consent to "Yes". This displays an intermediary page to the user, requesting them to grant permission to the application.

Change Access Website Api to "Yes".

Change Allow Refresh Tokens to "Yes".

Enter http://localhost:55897/home/codecallback for Redirect URLs

Enter 7200 (2 hours) for all Token Lifetime fields.

Click Save.

Click More Options and select Set Client Secret. Note the secret as it will be used to request an access token to access the Website API.

Setup ASP.NET application

Create a new ASP.NET Web Application in Visual Studio.

Select the MVC template.

Set the authentication scheme to No Authentication.

Run the following commands in the Nuget package manager console. These packages allow Open ID Connect authentication to be used in the application.

install-package Microsoft.Owin.Security.Cookies
install-package Microsoft.Owin.Security.OpenIdConnect
install-package Microsoft.Owin.Host.Systemweb

Add a Startup.cs file.

Add the following code to the file.

public class Startup
{
 public void Configuration(IAppBuilder app)
 {
     app.UseCookieAuthentication(new CookieAuthenticationOptions { AuthenticationType = "Cookies" });

     app.UseOpenIdConnectAuthentication(
             new OpenIdConnectAuthenticationOptions
             {
                 // This the endpoint in your running Configured Commerce application where Identity Server is listening
                 Authority = "http://432release.local.com/identity",
                 ClientId = "codeclient",
                 // This needs to match the value in the Admin console exactly
                 RedirectUri = "http://localhost:55897/home/codecallback",
                 ResponseType = "code",
                 Scope = "openid iscapi offline_access",
                 SignInAsAuthenticationType = "Cookies"
             });
 }
}

Decorate the About action with an Authorize attribute in the HomeController.cs file. This causes a 401 response and the application to redirect to the Identity Server login page.

public class HomeController : Controller
{
 public ActionResult Index()
 {
     return View();
 }

 [Authorize]
 public ActionResult About()
 {
     ViewBag.Message = "Your application description page.";

     return View();
 }

 public ActionResult Contact()
 {
     ViewBag.Message = "Your contact page.";

     return View();
 }
}

Run the following command in the NuGet package manage consoler. This package makes it easier to send requests to Identity Server.

install-package IdentityModel

Add the following code to the HomeController.cs file. This code requests an access token using the authorization code, requests the current Configured Commerce session, and displays the current user's username.

[HttpPost]
public ActionResult CodeCallback()
{
  var authCode = this.Request.Form["code"];
  var accessToken = this.GetToken(authCode);
  var userSession = this.GetSession(accessToken);
  return this.Json(userSession);
}
private string GetToken(string authCode)  
{  
  var client = new TokenClient(  
    "http://432release.local.com/identity/connect/token",  
    "codeclient",  
    "19d283bc-308d-795f-f0f1-c68831e0a390");
  var tokenResponse = client.RequestAuthorizationCodeAsync(authCode, "http://localhost:55897/home/codecallback").Result;

  return tokenResponse.AccessToken;
}

private UserSession GetSession(string accessToken)  
{  
  using (var client = new HttpClient())  
  {  
    client.SetBearerToken(accessToken);  
    var response = client.GetAsync(new Uri("http://432release.local.com/api/v1/sessions/current")).Result;  
    var session = response.Content.ReadAsStringAsync().Result;
   return JsonConvert.DeserializeObject<UserSession>(session);
  }
}

private class UserSession  
{  
  public bool IsAuthenticated { get; set; }
  public string UserName { get; set; }
}

Build the application.

Run the application.

Click the About link in the navigation bar.

Use the login form to sign in using an ISC Website account.

Grant access to the application by clicking Yes, Allow. Identity Server will authenticate the user and authorize the application. Then, it will redirect back to the ASP.NET application and the session response will be displayed.

You can store the access token returned from Identity Server and continue to access the Website API using the access token.