The BrandShelter portal supports SSO, so it's possible to federate your identity provider with BrandShelter's single sign-on (e.g. Microsoft Azure AD or Okta).

To setup your IdP, you will find the following documentation 250610_BrandShelter_SSO_Implementation_Guide.pdf and the below attributes that will allow you to implement the IdP.

Important preamble: The connection must be started through the BrandShelter portal.

We do not support IdP-initiated sign-in and you cannot use some functionality like the “embed link” provided by Okta for that reason. Sign-in has to be started through the BrandShelter portal.

It will also be imperative to connect from the BrandShelter connection URL provided in your SSO configuration.

• If you enter "https://home.safebrands.com" in your federation data, the SSO connection must be started from this URL.
  
  
• If you enter "https://secure.brandshelter.com" in your federation data, the SSO connection must be started from this URL.

Required Setup at the IdP

Microsoft Entra ID (formerly Azure AD)

The following data needs to be configured on Azure AD:

• Identifier (Client ID) (mandatory)
• Reply URL (mandatory)
• Sign on URL (mandatory)
• Relay State (optional)

• For Microsoft Azure AD:

For the BrandShelter production environment

secure.brandshelter.com

• Client id: urn:amazon:cognito:sp:eu-central-1_FmcrLjcuB
• Reply URL: https://bs-live-auth.auth.eu-central-1.amazoncognito.com/saml2/idpresponse
• Sign on URL: https://secure.brandshelter.com/users/sign_in
• Relay State (Optional): https://secure.brandshelter.com/

• For Okta (SAML):

For the BrandShelter production environment

secure.brandshelter.com

• Single Sign On URL: https://bs-live-auth.auth.eu-central-1.amazoncognito.com/saml2/idpresponse
• Audience restriction: urn:amazon:cognito:sp:eu-central-1_FmcrLjcuB
• Default Relay State: leave blank
• In Security/API/Trusted Origins, add https://bs-live-auth.auth.eu-central-1.amazoncognito.com as a permitted “redirect”

• For Okta (OpenID Connect):

For the BrandShelter production environment

secure.brandshelter.com

• Single Sign On URL: https://bs-live-auth.auth.eu-central-1.amazoncognito.com/oauth2/idpresponse
• In Security/API/Trusted Origins, add https://bs-live-auth.auth.eu-central-1.amazoncognito.com as a permitted “redirect”

Attribute Mapping

By default, we process the following assertions to onboard users:

• For SAML:

  • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

  • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname

  • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname

  • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/workphone

• Scopes and attributes OIDC:

  • “profile” scope for given_name and family_name

  • “email” scope for email

  • “phone” scope for phone_number

We are using the “URI Reference” name format; and we assign user.email to both “name” and “emailaddress” attributes, but other mapping can work as well.

Example:

Other attributes can be mapped on request.

IMPORTANT:

The above attributes are required, and we cannot change those requirements without recreating the user pool and breaking all existing federations.

Additionally, Cognito requires phone numbers to be given in a very specific format:
“Phone numbers must follow these format rules: A phone number must start with a plus (+) sign, followed immediately by the country code. A phone number can only contain the + sign and digits. Remove any other characters from a phone number, such as parentheses, spaces, or dashes (-) before you submit the value to the service. For example, a phone number based in the United States must follow this format: +14325551212.”

If you are unable to provide that format, we recommend to map a blank attribute so users can enter that information during the onboarding process. For example in Okta, an administrator can simply map the empty string to the phone_number attribute for their BrandShelter application:

Provide federation data to BrandShelter

You must provide us with a metadata URL or document (XML file), as well as the mail domains used by their users for sign-in.

And specify the protocol used for the SSO federation, i.e. SAML or OIDC.

IMPORTANT: You can choose between 2 possible configurations for access to the BrandShelter portal after SSO activation.

1) Default Configuration 1 - BrandShelter + SSO Connection

The 2 connection methods coexist, direct connection and SSO:

• you can log in using BrandShelter direct login (username + password)
• or by using the SSO login which requires entering only your email address (or SSO username) in the "Username" field, then clicking on "Login" without entering the password to be redirected to the SSO form.

This configuration is intended to allow the addition and login of users who do not have an email address linked to SSO and who would therefore need a direct connection to the portal to access your account.

2) Configuration 2 to be enabled on demand - SSO single sign-on

We disable the BrandShelter direct connection (username + password) and only the SSO method is possible.

This makes SSO connection mandatory and inevitable to log in for all users of the account without exception.

Note 1: Each user with a username matching one of these hosts will be required to authenticate through Single Sign-On (SSO) (configuration 2). Any user of this account with a username which does not match one of these hosts will require their normal local credentials and will not be using SSO (default configuration 1). E.g. the hostname example.com will match usernames like name@example.com.

Note 2: Please note that BrandShelter does not support IdP-initiated sign-in. This means certain functionalities, such as the “embed link” provided by Okta, cannot be used for sign-in purposes, or through other authentication platforms, e.g., Azure's "My Applications" portal. All sign-ins must be initiated through the BrandShelter portal to ensure proper authentication and access.

Please ensure then that the users always start the login attempt on our portal.

Note 3: A new user will still be redirected to BrandShelter's account creation page to fill in all the information not provided by their IdP. In addition, it is important to note that an existing portal user will be redirected to the account creation page on BrandShelter to fill in and/or update all the information not provided by their IdP.

User experience after SSO activation:

A user visit the BrandShelter portal. If he is already authenticated with his corporate identity provider, he's immediately signed into BrandShelter and the process stops here.

If he's not yet authenticated, the user enters his login name into the BrandShelter sign-in form.
The user is redirected to the sign-in form of his company, this could be for example the Microsoft sign-in form. After entering his credentials, the user is redirected back to the BrandShelter portal and is signed-in there.

Additional information link:

Amazon Cognito FAQs

Common Errors

“Required String parameter 'RelayState' is not present” on the Cognito-hosted page

Wait a few minutes after entering information. We managed to reproduce the error by changing the application in AAD and immediately initiating a sign-in, but did not get a solid reproduction.

“An error was encountered with the requested page.” (no further info) on the Cognito-hosted page

This can happen when attempting to use IdP-initiated sign-in, e.g. through the “Test sign in” button in the Azure Portal, or the “My Application” portal. BrandShelter currently does not support this at the moment, but we are working on.

For the time being, please make sure to initiate sign-in through the BrandShelter portal or make sure to enter the correct sign-in URL as indicated in the preamble at the top of the page to make the IdP redirect users to our portal.

“Invalid relayState from identity provider” or “Invalid samlResponse or relayState from identity provider” on the Cognito-hosted page

This is another reaction to IdP-initiated sign-in, observed when attempting to use the Okta Embed Link.

“Invalid saml response received: client is not enabled for oauth2.0 flows “ on the BrandShelter hosted login page

This indicates an incorrect reply URL. Make sure to use the URLs given at the top of the page.

This can also be caused by the Cognito client missing the AllowedOAuthFlowsUserPoolClient flag in the application client, which was an issue in older versions of the automated setup scripts. To rectify this, a developer can simply enter the application client edit page and save it without changes.

“Could not authenticate you from OpenIDConnect because “invalid ‘state’ parameter” on the BrandShelter hosted login page

Make sure that the user initiates sign-in on the same host that it will ultimately be forwarded to (and indicated in your SSO settings). A user in an account using, e.g., home.safebrands.com cannot initiate sign-in at secure.brandshelter.com. We are working so that this no longer has an impact and that the connection can be initiated from the 2 URLs.

“Your single sign-on user <email> is not assigned to any <brand> account”

Ensure that the user in question is assigned to the appropriate group for the application client in Cognito.

“Could not authenticate you from OpenIDConnect because "Invalid SAML response received: invalid phone number format.”

Refer to the warning highlighted in yellow above in this page and check your SSO configuration: this message indicates an error in the attribute mapping of your SSO configuration, specifically on the format of the phone number.