Concept - Single Sign-On (SSO)

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

TermDescription
SSOSingle sign-on
OAuth2Authentication/authorization standard/protocol
OpenID ConnectAuthentication/authorization standard/protocol based on OAuth2
OIDCAbbreviation for OpenID Connect
KeycloakImplementation of OpenID Connect
Azure ADMS Azure Active Directory (B2B and B2C)
Auth0https://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:

SSO actors

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:

StepActorDescription
1UserAccess the ICM.
2ICMIf the accessed resource is protected, delegate to login page.
3UserEnter the name of the organization (except SMC).
4ICMDecide which identity provider(s) and/or local authentication are enabled for this organization.
5User

Select an identity provider or enter local credentials.

6ICMThe ICM redirects to the (selected) identity provider's login page.
7Identity providerThe identity provider authenticates the user.
8Identity providerThe identity provider redirects to ICM providing a one-time-code.
9ICMRequest an access token using the one-time-code from the identity provider (not visible to the user).
10ICM

Treat the user as authenticated.

11ICM

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

ClaimDescription
subidentifier 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)
namename of user
emaile-mail of user
preferred_usernameusername, 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)

5 Configuration

5.1 Property Explanation

The necessary properties are structured as follows:

Key/PatternDescriptionMandatoryDefault ValueType{Codomain}
intershop.authentication.oidc.jwkCacheLifetimeThe 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.maxClockSkewThe 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.minAccessTokenLifeTimeLeftDuring 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.stateCookieNameA state cookie is required by this implementation (removed after authentication). This property defines the name of the cookie.

NO

oidc_stateString
intershop.authentication.acceptUnsignedTokensNormally, ID tokens are signed to ensure origin and integrity. To accept unsigned ID tokens, set this property to true.

NO

falseboolean
intershop.identityProvider.remoteEnables/disables the whole feature. If disabled, only local authentication is allowed.

NO

unsupportedEnum{supported, unsupported}
intershop.authentication.<organizationKey>.externalnameMaps 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>.identityprovidersKeys of the identity providers (string[] comma-separated, spaces removed, optional, default=string[0])

NO

localString[], comma-separated, spaces are removed
intershop.authentication.identityprovider.<identityProviderKey>.typeDefines the type of the identity provider

YES


Enum{local, oidc}
intershop.authentication.identityproviders.<identityProviderKey>.nameDefines the (display) name of the identity provider

YES


String
intershop.authentication.identityproviders.<identityProviderKey>.configurationType-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

EXTERNALEnum{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 TypeSyntax
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)
localValue 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:

FeatureDescriptionExecution
OIDCProfileMappermaps ID-Token claims to attributes of com.intershop.beehive.core.capi.profile.DataSheetall
OIDCAddressMappermaps ID-Token claims to attributes of com.intershop.beehive.core.capi.profile.Addressall
OIDCUserCreatorhandles to user-/customer creationhighest
OIDCUserUpdaterhandles to user-/customer updatehighest
OIDCProfileAdapter

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

highest
OIDCLoginNameProvidergenerates a local login namehighest
OIDCScopeValuesSuppliersupplies the scope values to be transmitted to the identity providerall

CustomerNoGenerator

Info

This feature is valid from 7.10.28.0.

generates a value for Customer#CustomerNo during customer creationhighest

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/PatternDescriptionMandatoryDefault ValueType{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

READWRITEEnum{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