Concept - Single Sign-On (SSO)

1. 1. 1. Table of Contents



Product Version

7.10

Product To Version


Status

Final





1 Introduction

Info

This concept is valid for ICM version 7.10.18.0 and higher.

Single sign-on allows a user to sign in to an application using his/her identity. If the user then accesses another application that accepts this identity, the user is immediately signed in without entering his/her credentials again. For ICM, this means that a once authenticated user can access all ICM applications (e.g. SMC, Operations back office, REST for storefront, inSPIRED storefront, etc.) without entering his/her credentials.

1.1 Glossary

Term

Description

SSO

Single sign-on

OAuth2

Authentication/authorization standard/protocol

OpenID Connect

Authentication/authorization standard/protocol based on OAuth2

OIDC

Abbreviation for OpenID Connect

Keycloak

Implementation of OpenID Connect

Azure AD

MS Azure Active Directory (B2B and B2C)

Auth0

https://auth0.com/

1.2 References

2 Overview

SSO is implemented using OpenID Connect. This means:

  • The ICM (role: client / resource owner) delegates authentication to a trusted identity provider which issues an (authentication) token.

  • The ICM (role: server / resource provider) accepts (authentication) tokens issued by one or many trusted identity providers.

  • The trusted identity providers have the ownership of user identities.

  • The ICM may still accept local credential data for user authentication. In that case the ICM does not provide SSO.

Note

The current implementation (7.10.27) was tested with Keycloak, Azure AD and Auth0 only. In the future additional identity providers will be supported.

The involved actors in the SSO process are as follows:

3 Organization Dependency

Every ICM user belongs to an organization. Therefore authentication always requires the user to enter the name of the organization (SMC users always belong to Operations). Since most identity providers do not have information about organizations, the name of the organization must always be entered in an ICM form. Inside the ICM the organization's name is mapped to one or many identity provider configurations (this may include local). Based on this configuration, the remaining part of the authentication is executed.

Currently the organization-to-identity-provider-configuration mapping is based on properties accessed using the configuration framework. See section Configuration for details.

4 Process

The SSO process consists of the following steps:

Actor

Description

1

User

Access the ICM.

2

ICM

If the accessed resource is protected, delegate to login page.

3

User

Enter the name of the organization (except SMC).

4

ICM

Decide which identity provider(s) and/or local authentication are enabled for this organization.

5

User

Select an identity provider or enter local credentials.

6

ICM

The ICM redirects to the (selected) identity provider's login page.

7

Identity provider

The identity provider authenticates the user.

8

Identity provider

The identity provider redirects to ICM providing a one-time-code.

9

ICM

Request an access token using the one-time-code from the identity provider (not visible to the user).

10

ICM

Treat the user as authenticated.

11

ICM

each time the user accesses the ICM, the token is validated using the identity provider if necessary.


Info

In addition, note the following:

  • Steps 4 and the following only apply if the user selects an identity provider (does not use local authentication).

  • Usually the token is cryptographically signed so the ICM may request the public key from the identity provider to validate the token's authenticity.

  • Usually the token has a limited lifetime so the ICM has to request a fresh token from the identity provider from time to time.

  • For further information refer to: https://openid.net/connect/.

4.1  Supported OpenID Claims

Standard Claims are defined at https://openid.net/specs/openid-connect-core-1_0.html

Claim

Description

sub

identifier of user defined by identifier provider

oid (Azure AD)

object identifier of user defined by root AD (that means the oid is equals at different Azure AD identity providers in case the same user is identified)

name

name of user

email

e-mail of user

preferred_username

username, email or nickname of user

unique_name (Azure AD)

usename name of user (only in v1.0 https://docs.microsoft.com/en-us/azure/active-directory/develop/id-tokens)

  • v1.0: Azure AD endpoints: https://login.microsoftonline.com/common/oauth2/authorize

  • v2.0: Microsoft identity Platform endpoints: https://login.microsoftonline.com/common/oauth2/v2.0/authorize


  • ICM doesn't support version v1.0. But "unique_name" was available at v2.0 until March 2021.


5 Configuration

5.1 Property Explanation

The necessary properties are structured as follows:

Key/Pattern

Description

Mandatory

Default Value

Type{Codomain}

intershop.authentication.oidc.jwkCacheLifetime

The public keys required to validate the ID token signature are downloaded from the identity provider. Afterwards these keys are cached. This property defines how long the keys remain inside the cache.

NO

3600000 (1 hour)

either:

number of milliseconds

or

syntax defined by java.time.Duration

intershop.authentication.oidc.maxClockSkew

The clocks of the ICM appserver and the identity provider may be slightly different. This property defines maximal difference.

NO

60000 (1 minute)

either:

number of milliseconds

or

syntax defined by java.time.Duration

intershop.authentication.oidc.minAccessTokenLifeTimeLeft

During token validation the expiration time of the access token is checked. If the expiration time is near the current time, the tokens are refreshed using the refresh token (if present). This property defines the minimal amount of time between the access token expiration time and the current time.

NO

180000 (3 minutes)

either:

number of milliseconds

or

syntax defined by java.time.Duration

intershop.authentication.oidc.stateCookieName

A state cookie is required by this implementation (removed after authentication). This property defines the name of the cookie.

NO

oidc_state

String

intershop.authentication.acceptUnsignedTokens

Normally, ID tokens are signed to ensure origin and integrity. To accept unsigned ID tokens, set this property to true.

NO

false

boolean

intershop.identityProvider.remote

Enables/disables the whole feature. If disabled, only local authentication is allowed.

NO

unsupported

Enum{supported, unsupported}

intershop.authentication.<organizationKey>.externalname

Maps ICM organization to an external name. organizationKey is the organization's name inside of ICM. The value is the external organization name. 

YES


String

intershop.authentication.<organizationKey>.identityproviders

Keys of the identity providers (string[] comma-separated, spaces removed, optional, default=string[0])

NO

local

String[], comma-separated, spaces are removed

intershop.authentication.identityprovider.<identityProviderKey>.type

Defines the type of the identity provider

YES


Enum{local, oidc}

intershop.authentication.identityproviders.<identityProviderKey>.name

Defines the (display) name of the identity provider

YES


String

intershop.authentication.identityproviders.<identityProviderKey>.configuration

Type-dependent identity provider configuration string

TYPE DEPENDENT


String (see below)

intershop.authentication.<organizationKey>.selfAdministrationPolicy

Info

This key is valid from 7.10.27.0.


Defines on organization level if user/profile data is created respectively updated using identity provider data

NO

CREATE, UPDATE

NONE or (XOR) any combination of CREATE,UPDATE,DELETE as a comma-separated list

If the list contains NONE this value overrules all other values. If the list is empty or missing the default is used.


intershop.authentication.<organizationKey>.logoutPolicy

Info

This key is valid from 7.10.28.0.


Defines the logout behavior on organization level:

  • LOCAL: user is only logged out from the ICM but stays logged in at the identity provider

  • EXTERNAL: user is logged out from the ICM and the identity provider

  • FEDERATED: user is logged out from the ICM and the identity provider and from the identity provider that is used by the identity provider (e.g. Google) known to the ICM

    Note

    FEDERATED may not be supported by each identity provider.


NO

EXTERNAL

Enum{LOCAL, EXTERNAL, FEDERATED}


Attention

The identityProviderKey is used to map identities of this identity provider to local user accounts. Do not change the identityProviderKey after going live, otherwise users will be created with a new identityProviderKey and lose their permissions.


Info

For each identity provider referenced by intershop.authentication.<organizationKey>.identityproviders, the properties intershop.authentication.identityprovider.<identityProviderKey>.* have to be present as defined above.

The syntax for the properties intershop.authentication.identityproviders.<identityProviderKey>.configuration is defined as follows:

Identity Provider Type

Syntax

oidc

JSON containing the attributes:

  • issuer: identity provider URL (issuer of the token)

  • client_id: id of the client

  • client_secret: secret of the client (optional)

  • additionalCustomScopeValues: array of custom scope value to be added to identity provider requests (optional)

local

Value is ignored

5.2 Example Configuration

#Enable the support for external/remote identity providers.
intershop.identityProvider.remote=supported

#Configure general properties, e.g. accept unsigned tokens.
intershop.authentication.oidc.jwkCacheLifetime=3600000
intershop.authentication.oidc.maxClockSkew=60000
intershop.authentication.oidc.minAccessTokenLifeTimeLeft=86400000
intershop.authentication.oidc.stateCookieName=oidc_state
intershop.authentication.acceptUnsignedTokens=true

#Define the local identity provider (ICM itself) with key localICM.
intershop.authentication.identityprovider.localICM.type=local

#Define an Azure AD provider with key oidc_ad_1 and define additional custom scope value for oidc_ad_1.
intershop.authentication.identityprovider.oidc_ad_1.type=oidc
intershop.authentication.identityprovider.oidc_ad_1.name=OpenID Connect AD 1
intershop.authentication.identityprovider.oidc_ad_1.configuration=\
{\
	"issuer": "https://login.microsoftonline.com/43566bc5-e954-4049-909f-76ce0392de31/v2.0",\
	"client_id": "24b5f295-e171-4d8e-9f27-212f645641fa",\
	"client_secret": "w55~gl-saTtuqqRX_.W_fs~1dK3py2Mr31",\
    "additionalCustomScopeValues": ["customScope1", "customScope2"]\
}

#Define a second Azure AD provider with key oidc_ad_2.
intershop.authentication.identityprovider.oidc_ad_2.type=oidc
intershop.authentication.identityprovider.oidc_ad_2.name=OpenID Connect AD 2
intershop.authentication.identityprovider.oidc_ad_2.configuration=\
{\
	"issuer": "https://login.microsoftonline.com/e9cf2bf0-d510-4293-8985-f809eea95f3a/v2.0",\
	"client_id": "62c5af81-d09d-4967-a42d-212f645641fa", \
	"client_secret": "2Lam_p-bmpbgHezn28bVqtJw_4Y5Zkq2k1" \
}

#Define a Keycloak provider with key oidc_kc_1.
intershop.authentication.identityprovider.oidc_kc_1.type=oidc
intershop.authentication.identityprovider.oidc_kc_1.name=OpenID Connect KC 1
intershop.authentication.identityprovider.oidc_kc_1.configuration=\
{\
	"issuer": "https://keycloak-local.ad.intershop.net:8443/auth/realms/ICM",\
	"client_id": "ICM",\
	"client_secret": "b94c0646-e169-4da2-a035-ad91e1433261"\
}

#Define a second Keycloak provider with key oidc_kc_2.
intershop.authentication.identityprovider.oidc_kc_2.type=oidc
intershop.authentication.identityprovider.oidc_kc_2.name=OpenID Connect KC 2
intershop.authentication.identityprovider.oidc_kc_2.configuration=\
{\
	"issuer": "https://keycloak-local.ad.intershop.net:8443/auth/realms/ICM",\
	"client_id": "ICM",\
	"client_secret": "b94c0646-e169-4da2-a035-ad91e1433261"\
}


#Assign Intershop as external name to organization Operations.
intershop.authentication.Operations.externalname=Intershop

#'Operations'-users are only logged out locally
intershop.authentication.Operations.logoutPolicy=LOCAL

#Assign identity providers oidc_kc_1, oidc_kc_2, oidc_ad_1, oidc_ad_2 and localICM to organization Operations.
intershop.authentication.Operations.identityproviders=oidc_kc_1, oidc_kc_2, oidc_ad_1, oidc_ad_2, localICM

#Assign inSPIRED as external name to organization inSPIRED.
intershop.authentication.inSPIRED.externalname=inSPIRED

#Assign identity providers oidc_kc_1 and localICM to organization inSPIRED.
intershop.authentication.inSPIRED.identityproviders=oidc_kc_1, localICM

#Assign Myers - Subdivision of inSPIRED as external name to organization Myers.
intershop.authentication.Myers.externalname=Myers - Subdivision of inSPIRED

#Assign identity providers oidc_kc_1, oidc_ad_1 and localICM to organization Myers.
intershop.authentication.Myers.identityproviders=oidc_kc_1, oidc_ad_1, localICM

#Storefront uses the anonymous organization of the channel.
intershop.authentication.inSPIRED-inTRONICS-Anonymous.externalname=inTRONICS
intershop.authentication.inSPIRED-inTRONICS-Anonymous.identityproviders=oidc_ad_1

#During SSO authentication, users will be updated but never created (users unknown to the ICM can not log in).
intershop.authentication.inSPIRED-inTRONICS-Anonymous.selfAdministrationPolicy=UPDATE

6 Customization

Info

This paragraph is valid from 7.10.27.0 (some parts may also apply to earlier versions).

Whenever possible, SSO classes delegate functionality to com.intershop.beehive.core.capi.feature.Feature, respectively to com.intershop.beehive.core.capi.feature.LocalFeature implementations. This allows a fine grained customization. Depending on the certain use case, either the feature with highest priority or all matching features sorted by priority are executed. Currently these features are used:

Feature

Description

Execution

OIDCProfileMapper

maps ID-Token claims to attributes of com.intershop.beehive.core.capi.profile.DataSheet

all

OIDCAddressMapper

maps ID-Token claims to attributes of com.intershop.beehive.core.capi.profile.Address

all

OIDCUserCreator

handles to user-/customer creation

highest

OIDCUserUpdater

handles to user-/customer update

highest

OIDCProfileAdapter

extracts external user id and external user name from ID-Token claims

highest

OIDCLoginNameProvider

generates a local login name

highest

OIDCScopeValuesSupplier

supplies the scope values to be transmitted to the identity provider

all

CustomerNoGenerator

Info

This feature is valid from 7.10.28.0.


generates a value for Customer#CustomerNo during customer creation

highest


For further details about features have a look at Concept - Features Framework and Cookbook - Features Framework.

7 Data Ownership

Since (profile) data of users who are authenticated via external identity providers are managed by these identity providers, the data of these users cannot be changed by the ICM. Therefore the user profile data manipulation inside the ICM can be configured as follows using properties:

Key/Pattern

Description

Mandatory

Default Value

Type{Codomain}

intershop.profile.attributeChange.<contextType>.<fieldName>

Configures if a profile field is:

  • HIDDEN: completely hidden from input forms

  • READONLY: displayed in input forms but not editable

  • READWRITE: displayed in input forms and editable

The contextType inside the key currently maps to the identityProvider.type defined above.

NO

READWRITE

Enum{HIDDEN, READONLY, READWRITE}



Disclaimer

The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.

Customer Support
Knowledge Base
Product Resources
Tickets