Development Guides

SAML 2.0

Purpose: This article will walk you through best practices when using SAML 2.0 authentication to access the Orion API. 

Simple Use Case: An existing user within a customer’s Advisor portal, wants to single sign-on (SSO) into the Orion Connect platform without having to enter Orion credentials.

Scope and Outputs: Orion will need to be provided with the customer or partner’s public certificate and the issuer they will be passing for the SAML SSO. The certificate can be self-signed, but the private key must be secured and not shared with anyone else. Orion will provide the required Partner ID.

This method can be used with any user login level, but the corresponding user must be created and available in Orion for them to be linked. The SAML can authenticate using one of three methods 1) Using known Username, 2) Passing Username and password, or 3) Passing Entity ID.

Process Overview:

  1. Create users within Orion.
  2. Perform SAML POST to SSO Endpoint.
  3. Resolve to Orion Connect.

Process Steps (3 different Methods):

Method 1 – SSO with Orion Username – This requires the identity provider to know and store the Orion username and present it as part of the SAML

  1. Create users in Orion Connect using the Manage Users App or with the New User Import
  2. POST an unsolicited SAML Response to https://auth.orionadvisor.com/sso/samlconsumer

Subject: Orion username should be used for the SAML subject

Assertions: authFlow = “Trusted” & partnerId = {Orion will provide the partnerID}

  1. Resolve to Orion Connect

Method 2 – SSO with Prompt for first Login – This requires the user to know their Orion credentials and enter them in the prompt during the first login attempt with the SSO. After that, the unique identifier you pass will be mapped to that user.

  1. Create users in Orion Connect using the Manage Users App or with the New User Import
  2. POST an unsolicited SAML Response to https://auth.orionadvisor.com/sso/samlconsumer

Subject: Include a unique identifier for each user in the SAML subject. Email is most common but the Orion User ID is also a good recommendation.

Assertions: authFlow = “TrustedPrompt” & partnerId = {Orion will provide the partnerID}

  1. Resolve to Orion Connect

Method 3 – SSO to Impersonate User with ID – This method is best suited for getting clients into the client portal or representative level users into an advisor portal. Clients have Household IDs and Representatives have Rep IDs.

  1. Create users in Orion Connect using the Manage Users App or with the New User Import
  2. POST an unsolicited SAML Response to https://auth.orionadvisor.com/sso/samlconsumer

Subject: Not required – all details are handled in the asser

Assertions: 

  • authFlow = “Impersonate”\
  • impersonateEntity = [4 for representative, 5 for client]
  • impersonateEntityId = [The representative ID or client ID respectively]
  • partnerId = {Orion will provide the partnerID}
  1. Resolve to Orion Connect

Process Tips or Controls:

  1. Orion provides an advanced method with impersonation that allows for “just in time” creation of client level users the first time they utilize the SAML SSO. Note: this solution can only be used with a client level user. Contact Orion for more details. This requires use of a Service Account User and a specific database setting for ‘Allow User Impersonation to Create New User“.
  2. Trusted Example
  3. Trusted Prompt Example
  4. Be sure the Signature is on both response and assertion.
  5. Client level SSO will need a relay state of “/clientportal/” included as well as the additional assertion of firmId. Please contact the SME Integrations team if you do not have your firmId.
  6. Please see additional relay states: (you can send the relay state as an assertion: relayState)