Dev GuideAPI Reference
Dev GuideAPI ReferenceUser GuideGitHubNuGetDev CommunitySubmit a ticketLog In
GitHubNuGetDev CommunitySubmit a ticket

Set up a single sign-on (SSO) client

Describes fields used to create a SSO Client, using SSO with an authorization code, and external resources for additional information.

🚧

Important

This topic is for SDK/On Prem customers only; it is not available to Cloud customers.

📘

Note

This feature is not available in net7+.

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.

Redirect users after login authentication

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 Sing On > Add Client .

📘

Note

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

FieldDescription
Client IdThe Identity Server client id. Used to identify client making requests to Identity Server.
Client NameFriendly display name for the Admin Console.
FlowOAuth 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.
EnabledWhether or not this client can be used for authentication or authorization.
Require ConsentWhether or not user will needs to give consent to the requesting application to access user data (e.g.
Access Admin ApiAssigns the "isc_admin" scope to this client. Allows client to use Admin OData API.
Access Website ApiAssigns the "iscapi" scope to this client. Allows client to use Storefront REST API.
Allow Refresh TokensWhether or not refresh tokens can be used to request new access tokens.
Allow Access Tokens Via BrowserAllows Identity Server to pass back access tokens through the browser to the requesting application (e.g. a form post).
Redirect UrisWhere Identity Server will send tokens after a successful authentication.
Access Token LifetimeLength of time before access token expires.
Identity Token LifetimeLength of time before identity token expires.
Authorization Code LifetimeLength of time before authorization code expires.
Absolute Refresh Token LifetimeMaximum length of time before refresh token expires.
Sliding Refresh Token LifetimeSliding 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

  1. Go to the Admin Console > Administration > Permissions > Single Sign On.
  2. Click Add Client  to add a new client.
  3. Enter codeclient for Client Id.
  4. Enter codeclient for Client Name.
  5. Select Authorization Code under Flow.
  6. Change Enabled to "Yes".
  7. Change Require Consent to "Yes". This displays an intermediary page to the user, requesting them to grant permission to the application.
  8. Change Access Website Api to "Yes".
  9. Change Allow Refresh Tokens to "Yes".
  10. Enter http://localhost:55897/home/codecallback for Redirect URLs
  11. Enter 7200 (2 hours) for all Token Lifetime fields.
  12. Click Save.
  13. 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

  1. Create a new 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 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
    
  5. Add a Startup.cs file.

  6. 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"
                 });
     }
    }
    
  7. 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();
     }
    }
    
  8. Run the following command in the NuGet package manage consoler. This package makes it easier to send requests to Identity Server.

    install-package IdentityModel
    
  9. 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; }
    }
    
  10. Build the application.

  11. Run the application.

  12. Click the About link in the navigation bar.

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

  14. 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.

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