Customer Identity Access Management

# CIAM with SAML 2.0

## Setup

<div>
  <p>In order to use SAML integration, start by configuring the SAML service provider.  Navigate to the Consumer SSO page. </p>
  <aside>
    <Image align="center" width="200px" src="https://files.readme.io/f7a666c-image.png" />
  </aside>
</div>

### Initial IdP Setup

Prior to arriving here, some initial setup is required in the identity provider IdP. The output of the IdP setup will provide the necessary values to fill out this form.

In the IdP, please set up the following:

* Map the name id field to the email address.
* Map the name id format to urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
* Sign the Assertion & Response
* Add the following fields (optionally):
  * user.firstName
  * user.lastName

### Service Provider (SP) Setup

![](https://files.readme.io/aecfff5-Consumer_SSO.png)

### Final IdP Setup

Upon completion of the Consumer SAML Configuration, please Export the Metadata. This will contain the necessary information to complete the configuration. Specifically, it will contain

* IdP ID
* Assertion Consumer Service URL
* Audience URI

You are now ready to test the SAML Integration!

## Usage

### Consumer UI

After you configure the Consumer SSO integration, the page will now contain an option to *Login* in the top right. Clicking this link will bring the user to the customer identity provider. After they login, they will be returned to this page with their choices pre-populated.

<Image align="center" src="https://files.readme.io/79243e7-image.png" />

### Deep Linking

If the user is already logged in, you can provide them with a seamless navigation. The following URL can be used to deep link and transmit the single sign-on.

URL: [https://ui.upcp.wirewheel.io/sso/api/v1/auth/login](https://ui.dev.upcp.wirewheel.io/sso/api/v1/auth/login)

Required Parameters:

* apiKey - the API Key is located in the Channel Details page of the UPCP admin console, in the developer section.
* redirectUrl - this is the URL that the user will be redirected to after they are logged in.

## Appendix

### General Purpose Flow

![](https://files.readme.io/a634766-image.png)

### Embedded Consumer UI

This flow is applicable to sites that are embedding the out-of-the-box consumer user interface into their sites.  

![](https://files.readme.io/a4d88f7-Screen_Shot_2023-01-25_at_8.31.14_AM.png)

![](https://files.readme.io/717f569-Screen_Shot_2023-01-25_at_8.31.29_AM.png)

See the [Embedded Experience](embed-upcp-consumer-ui-into-website) page for details about passing the session id into the Consumer UI.

### RelayState

In an SP-initiated flow, such as those described above, a RelayState will be passed to the IdP. The IdP should return the RelayState to the SAML Assertion Consumer Service unchanged. This is standard SAML behavior and should not require any special configuration to make it work.