Loading...
Area: Episerver B2B Commerce

Add a new Single Sign-On (SSO) client

Recommended reading 

Summary

This article provides specific information about the fields used to create a new SSO Client. It also provides a typical use case related to using SSO with an authorization code and a couple of external resources for additional information.

To fully utilize this article background knowledge about OAuth2.0 (https://oauth.net/) and Open ID Connect (http://openid.net/connect/) is strongly recommended.

It should be known that using SSO delegates authentication and authorization to B2B and allows third party applications to access resources on behalf of B2B users.

Epi B2B Commerce (ISC) uses IdentityServer (https://identityserver.github.io/Documentation/docsv2/overview/bigPicture.html) - implementation of OpenID Connect (authentication) and OAuth2 (authorization).

Note: Insite does not support functionality for Epi B2B Commerce to act as the identity provider for other external applications.

Setup in Admin Console

SSO clients are managed by navigating to the Admin ConsoleAdministration > Permissions > Single Sign On.

Epi B2B Commerce Storefront and Admin SSO Clients

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

  • isc - Gives access to the Epi B2B Commerce Storefront API.
  • admin - Gives access to the Epi B2B Commerce Admin API.
  • mobile - Gives access to the Epi B2B Commerce Mobile API.

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

Redirect Users After Login Authentication

After you redirect users from Epi B2B Commerce to a third party for authentication, you then need to redirect them back 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 a New SSO Client

The list below describes the fields found when clicking the Add Client  button on the Single Sign On page.

NOTE: The Client fields roughly correspond to the Identity Server client settings, which are made available here: https://identityserver.github.io/Documentation/docsv2/configuration/clients.html.

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

Setup Client in Admin Console

  1. Navigate to the Admin Console > Administration > Permissions > Single Sign On.
  2. Click Add Client  button to add a new client.
  3. In the Client Id field, enter "codeclient".
  4. In the Client Name field, enter "codeclient".
  5. In the Flow drop-down, select "Authorization Code".
  6. Change Enabled to "Yes".
  7. Change Require Consent to "Yes". This will require the end user to grant permission to the application requesting access. An intermediary page will be shown to allow the user to grant access.
  8. Change Access Website Api to "Yes".
  9. Change Allow Refresh Tokens to "Yes".
  10. In the Redirect Uris field, enter "http://localhost:55897/home/codecallback".
  11. In all of the Token Lifetime fields, enter "7200" (2 hours).
  12. Click Save.
  13. Click the More Optionsbutton and select Set Client Secret. Make note of the secret as it will be used to request an access token to access the Website API.

Setup ASP.NET Application

  1. In Visual Studio, create a new ASP.NET Web Application.
  2. Select the MVC template.
  3. Set the authentication scheme to No Authentication.
  4. In the Nuget package manager console, run the following commands. These packages will 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 B2B 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. In the HomeController.cs file, decorate the About action with an Authorize attribute. This will cause 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. Now, in the Nuget package manager console, run the following command. (This package makes it easier to send requests to Identity Server.)
    install-package IdentityModel
  9. Back in the HomeController.cs file, add the following code. (This code will request an access token using the authorization code, make a request to get the current B2B session, and display 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.

External Resources

 

Do you find this information helpful? Please log in to provide feedback.

Last updated: Dec 11, 2020

Recommended reading