Set up a single sign-on (SSO) client

📘

Note

This feature is not available in .NET 8 and later. The Single Sign On page does not exist in those versions, so the client fields here do not apply. To set mobile app session lifetimes in .NET 8 and later, see Configure mobile app session lifetime.

SSO lets your users sign in once and reach both Configured Commerce and your third-party applications. SSO delegates authentication and authorization to Configured Commerce. Third-party applications can then access resources on behalf of your users.

Configured Commerce uses IdentityServer, an implementation of OpenID Connect for authentication and OAuth2 for authorization.

🚧

Important

Do not use Configured Commerce as the identity provider for other external applications. Optimizely recommends an external identity provider, such as Okta. If you use Configured Commerce as the identity provider, Optimizely is not responsible for updates that break your integration.

Prerequisites

Before you configure an SSO client, make sure you have the following:

• Access to the Admin Console > Administration > Permissions > Single Sign On page.
• Working knowledge of OAuth 2.0 and OpenID Connect.
• The ability to restart the application. Configured Commerce applies SSO changes only after a restart.

Configure SSO clients in Admin Console

Manage every SSO client from one page, whether Configured Commerce created it or you registered it. Go to the Admin Console > Administration > Permissions > Single Sign On. Restart the application after you change any client.

Configured Commerce storefront and admin SSO clients

Use the included clients to authenticate against a Configured Commerce API without registering a client of your own. Configured Commerce enables and configures three SSO clients automatically:

• isc – Access to the Configured Commerce Storefront API.
• admin – Access to the Configured Commerce Admin API.
• mobile – Access to the Configured Commerce Mobile API.

Use these clients for authentication extensions, or create your own.

Redirect users after authentication

Send users back to the right place after an external identity provider authenticates them. After a third party authenticates your users, redirect them to your site to sign in. Use the following included clients:

• isc_admin_ext – Add your Admin Console URL to the Redirect Uris field. Users return to the Admin Console to sign in.
• ext – Add your website URL to the Redirect Uris field. Users return to your storefront to sign in.

Add and configure an SSO client

Register your own client when the included clients do not match your integration. The following table describes the fields under Single Sign On > Add Client.

📘

Note

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

Mobile app session lifetime in .NET 8 and later

The token lifetime fields on the mobile client control how long a mobile app session lasts, but only in .NET Framework 4.8. In .NET 8 and later, two system settings replace them. See Configure mobile app session lifetime.

Use case: single sign-on with an authorization code

Follow this walkthrough to let an external ASP.NET application sign users in with their Configured Commerce account.

How the authorization code flow works

This flow works like Log in with Google. Users sign in to an external application with their Configured Commerce account. This walkthrough uses an ASP.NET application as the third-party application that wants Configured Commerce data. The Admin Console setup configures the Identity Server client.

Set up the client in Admin Console

1. Go to the Admin Console > Administration > Permissions > Single Sign On.
2. Click Add Client.
3. Enter codeclient in the Client Id field.
4. Enter codeclient in the Client Name field.
5. Select Authorization Code under Flow.
6. Set Enabled to Yes.
7. Set Require Consent to Yes. Identity Server then asks the user to grant permission to the application.
8. Set Access Website Api to Yes.
9. Set Allow Refresh Tokens to Yes.
10. Enter http://localhost:55897/home/codecallback in the Redirect Uris field.
11. Enter 7200 (two hours) in each Token Lifetime field.
12. Click Save.
13. Click More Options and select Set Client Secret.
14. Note the secret. You need it to request an access token for the Website API.
15. Restart the application.

Set up an ASP.NET application

1. Create an ASP.NET Web Application in Visual Studio.

2. Select the MVC template.

3. Set the authentication scheme to No Authentication.

4. Run the following commands in the NuGet package manager console. These packages add OpenID Connect authentication to the application.

   PowerShell

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

5. Add a Startup.cs file.

6. Add the following code to the file.

   C#

   public class Startup
   {
    public void Configuration(IAppBuilder app)
    {
        app.UseCookieAuthentication(new CookieAuthenticationOptions { AuthenticationType = "Cookies" });
   
        app.UseOpenIdConnectAuthentication(
                new OpenIdConnectAuthenticationOptions
                {
                    // This is the endpoint in your running Configured Commerce application where Identity Server is listening
                    Authority = "https://YOUR_SITE_URL/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"
                });
    }
   }

7. Decorate the About action with an Authorize attribute in the HomeController.cs file. This causes a 401 response, and the application redirects to the Identity Server sign-in page.

   C#

   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();
    }
   }

8. Run the following command in the NuGet package manager console. This package makes it easier to send requests to Identity Server.

   PowerShell

   install-package IdentityModel

9. Add the following code to the HomeController.cs file. The code requests an access token with the authorization code. It then requests the current Configured Commerce session and displays the user's username.

   C#

   [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(
       "https://YOUR_SITE_URL/identity/connect/token",
       "codeclient",
       "CLIENT_SECRET");
     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("https://YOUR_SITE_URL/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; }
   }

10. Build the application.

11. Run the application.

12. Click About.

13. Sign in with an ISC Website account.

14. Click Yes, Allow to grant access. Identity Server authenticates the user and authorizes the application. It then redirects to the ASP.NET application and displays the session response.

15. Store the access token returned from Identity Server to continue accessing the Website API.