Single sign-on (SSO)

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 use 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 ISC and allows third party applications to access resources on behalf of ISC users.

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

Set up in Admin Console

SSO clients are managed by going to Admin Console > Administration > Permissions > Single Sign On.

Adding and configuring a new SSO client

The list below describes the fields found when clickingAdd Client 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 flow (such as Authorization Code, Implicit, Resource Owner)
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 (such as
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 (such as 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.

Use Case (Single Sign On with Authorization Code)

Explanation

Set up client in Admin Console

  1. Go to Admin Console > Administration > Permissions > Single Sign On.
  2. Click Add Client to add a new client.
  3. In Client Id, enter "codeclient".
  4. In Client Name, enter "codeclient".
  5. In Flow, 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 Redirect Uris, enter "http://localhost:55897/home/codecallback".
  11. In the Token Lifetime fields, enter "7200" (2 hours).
  12. Click Save.
  13. Click More Options 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.

Set up 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 ISC 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 ISC 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 About 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