Configure a Default IDP

If you're using Shopper API Access and Login (SLAS) with 3rd party identity providers (IDP) and you would like to use an IDP that is not supported by SLAS, you can use SLAS' Default IDP feature to communicate with your IDP.

This guide covers the steps required to configure a Default IDP with SLAS using either the SLAS Admin API or UI.

Depending on your IDP, there are two ways to configure it:

SLAS only supports IDPs that support OpenID Connect. SLAS does not support SAML.

Configuring a default IDP requires the same SLAS properties as supported IDPs:

  • The name, clientId, clientSecret, IDP urls, scopes, and preferenceValue are all required SLAS IDP client configuration values. For details, see Register an Identity Provider.

with the following additional requirements:

  • Provide the oidcClaimMapper property. It is used to map the IDP's token claims to SLAS' required IDP keys to get user information when the user successfully authenticates. The oidcClaimMapper property is a list of strings in which each string's format is $KEY=$VAL, where $KEY is a required SLAS IDP key and $VAL is the name of the corresponding IDP token claim. For example: accessToken=access_token. accessToken is the SLAS key, and access_token is the IDP Claim.
  • Map each of the following keys to the applicable IDP value:
    • accessToken: Value of access token.
    • accessTokenTTL: Time to live of access token.
    • refreshToken: Value of the refresh token.
    • idToken: Value of the ID token.
    • subject: The subject. This is the unique identifier of the shopper.
    • userId: Also the subject. This is the unique identifier of the shopper.
    • email: Shopper's email.
    • familyName: Shopper's family name.
    • givenName: Shopper's given name.
    • name: Shopper's full name.
  • Verify the values that are returned by your identity provider for IDP /token and /userinfo endpoints are correct.

The following example can be used as a starting point for SLAS IDP configuration:

To configure a Default IDP using the SLAS Admin user interface (UI):

  1. Navigate to the Idps tab.
  2. Select Add Idp.
  3. Select the Idp Name field and then select default from the drop down menu.
  4. Add all applicable information. In the Default IDP Claim Map field, add the oidcClaimMapper keys described in the previous section.
  5. Save your configuration information.

If the third-party IDP does not support the Open ID Connect Discovery protocol, you can use SLAS Admin API's registerIdentityProvider endpoint to configure a Default IDP. For example:

If the IDP supports the Open ID Connect Discovery protocol, the simplest way to configure a Default IDP is to use the identity provider .../well-known/openid-configuration endpoint. SLAS can then automatically configure your Default IDP.

Specify the following required properties for automated Default IDP configuration:

  • wellKnownUrl: The URL of the IDP's Open ID Connect Discovery endpoint.
  • useWellKnown: A boolean that when set to true indicates that SLAS should attempt to automatically configure the Default IDP using the Open ID Connect Discovery endpoint.

For example:

A successful third-party IDP response contains "claims_parameter_supported": true and the OIDC claim mappings for SLAS configuration. If claims_parameter_supported is not returned, then SLAS uses a default mapping. The IDP token claims for UserInfo can be found in the /.well-known/openid-configuration/ response from the claims-supported section, for example:

SLAS then uses the wellKnownUrl for configuration, and if successful, returns information similar to the following example:

SLAS takes the IDP response and applies oidcClaimMapper information. Authentication fails and a 400 response code is returned if:

  • A required mapping parameter is missing.
  • A required mapping field or mapping value is invalid, for example: an invalid URL.
  • One or more corresponding claims cannot be found in the IDP token response.

In the event of an error, review your oidcClaimMapper information for errors. Make sure that your mapping includes valid values for all required fields.