SAML Service Provider Integration with flexmls Web

This documentation is intended for software vendors that wish to use flexmls as an Identity Provider (IdP) to provide a Single Sign-On (SSO) relationship with flexmls Web members.

flexmls Web SSO

MLSs: Please complete and return to FBS this MLS Approval of Third Party Vendor (PDF) document if you would like us to set up SSO with a particular vendor for your MLS.

SAML Basics

SAML 2.0 is a standard protocol for implementing single sign-on services. The basics of SAML involves a trust relationship between an Identity Provider and multiple Service Providers (SP). When a user requests access to a members only section of an SP, that site redirects the browser back to the flexmls IdP to log in. After a successful login, the browser is redirected back to the SP. Along with the redirect, the IdP passes along attributes for that user. (flexmls login name, email address, phone number, etc.) The SP can then use this information as if the user had logged in at that site. Since the SP “trusts” the IdP, the outside vendor can assume the username returned from the IdP is correct, trusted, and authenticated.

SAML Configuration

After installing a Service Provider package, a trust relationship needs to be set up using XML meta-data from both parties. The flexmls metadata will come from a URL, in the format of https://mlslogin.flexmls.com/idp/shibboleth, where mls is the short abbreviation of the MLS name. Most SP software will accept a URL instead of a plain XML file for metadata. (If the flexmls metadata data changes, the SP will automatically grab a fresh copy)

Next, the SP software will usually require an entity ID to form a trust relationship with the IdP. The entity ID for the flexmls IdP is the same as the metadata URL.

The SP software will also have metadata for its own SAML endpoints. Most packages have the capability of generating this dynamically with a URL like the flexmls IdP does. On the flexmls side, we will have to add the SP metadata and entity ID to our configuration in order to trust the SP.

This is the general procedure, as each SP package might have a different setup method.

A few extra details about the IdP:

The IdP uses Shibboleth IdP, v3.3.1 with SLO support
The principal name (A.K.A username, agent ID, etc) is in the SAML Subject tag, encoded in the Name ID format
- urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
- and the SAML attribute flexmls_user_name (This is also the pseudo user)
More information about the user is provided in SAML Attributes
The public certificate is in the IdP metadata. Look for the XML tag <ds:X509Certificate>
Sessions have a 24 hour lifetime on the IdP.
- If an SP session expires and redirects over to the IdP, that user will still have an active session. They will automatically redirect back to the SP without requiring authentication
- To do an IdP initiated log out, direct the browser to http://mlslogin.flexmls.com/idp/Logout (Note this is plain HTTP) This URL is handy if your SP package does not support logouts. Simply change your "Log Out" button to this URL and the IdP handles the rest
For most setups, assertions are signed with the SSL certification, but not encrypted

SAML Attributes

The flexmls IdP provides detailed information about the user in the <saml2:AttributeStatement> tag of the SAML2 Response. Service Provider packages have varying methods for configuring SAML attributes, so refer to outside documentation on that. The examples and information below should be enough to get started on mapping the attribute names to consumable information in your flavor of SP. (If you're using Shibboleth SP, here is a functional attribute-map.xml file to enable flexmls attributes)

Not all attributes will be populated for every login event. For example, if a user has not provided a fax number to flexmls, that attribute will not be listed in the SAML response.

A small XML example of an AttributeStatement:

<saml2:AttributeStatement>
   <saml2:Attribute Name="flexmls_user_name"
      NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
      <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:type="xs:string">
            jorealtor
      </saml2:AttributeValue>
   </saml2:Attribute>
   <saml2:Attribute Name="flexmls_tech_id"
      NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
      <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:type="xs:string">
            20110126143505724628000000
      </saml2:AttributeValue>
   </saml2:Attribute>
   <saml2:Attribute Name="flexmls_name"
      NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
      <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:type="xs:string">
            Joe Realtor
      </saml2:AttributeValue>
   </saml2:Attribute>
   <saml2:Attribute Name="flexmls_nrds_id"
      NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
      <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:type="xs:string">
         1234
      </saml2:AttributeValue>
   </saml2:Attribute>
</saml2:AttributeStatement>

Each attribute is defined as a string type, and the Name parameter corresponds to the list below:

`flexmls_user_name`

The flexmls username. (A.K.A login name, agent ID, etc) If this is a higher level access account, this attribute and all others are set to the "pseudo user" role. The NameID tag will always be set to the real user account that logged in, but the flexmls_user_name attribute may be a different user account if that person is super used to a lower level account.

Example: User janebroker logs in, and is not assuming the role of one of the agents in her office. The flexmls_user_name will also be set to janebroker. If Jane decides to super use to the account joerealtor and logs in again, then the flexmls_user_name, flexmls_tech_id, and all of the other attributes will contain values for joerealtor. The only attribute still set to janebroker will be the NameID.

This allows each SSO vendor to match the privilege levels of flexmls, and change functionality as desired for that particular product. Some applications can use this security method, but others might not. If in doubt, use the NameID username, as it will always contain the credentials of the person that physically typed in a password.

`flexmls_tech_id`

Our tech_id is a unique identifier for an account. It is the creation timestamp of the account, and will never change even if the user name changes.

`flexmls_name`

display name in flexmls (full name) This will always be present, no matter the privilege level.

`flexmls_fname`

First name of the agent. This attribute is not defined for offices.

`flexmls_mname`

Middle name of the agent. This attribute is not defined for offices.

`flexmls_lname`

Last name of the agent. This attribute is not defined for offices.

`flexmls_nrds_id`

NRDS ID (National Realtors Database System ID number)

`flexmls_office_id`

The unique identifier for the office that the member belongs to

`flexmls_office_name`

The descriptive name of the office that the member belongs to

`flexmls_mls_tech_id`

This is the unique identifier for the MLS the member belongs to

`flexmls_mls_login_name`

This is the login name of the MLS. This is used to easily identify which MLS the member belongs to with a short name identifier. (Also unique)

`flexmls_boardcode`

MLS abbreviation code

`flexmls_pf_phone`

Fax phone number

`flexmls_ph_phone`

Home phone number

`flexmls_pm_phone`

Mobile phone number

`flexmls_po_phone`

Office phone number

`flexmls_pp_phone`

Pager phone number

`flexmls_short_id`

short ID. May or may not be unique, depends on the MLS.
Usually used for internal tracking or other accounting purposes

`flexmls_street1`

address, Street line 1

`flexmls_street2`

address, Street line 2

`flexmls_city`

address, City

`flexmls_state_prov`

address, State or Province

`flexmls_zip`

address, Zip code

`flexmls_url`

Member's personal website URL

`flexmls_email_addr`

Member's email address

`flexmls_member_type`

This member type as defined by the MLS. The values vary widely depending on the MLS, but most of them determine the access or privilege level that a member has to the MLS. (Agent, Office, Appraiser, Admin, etc)

`flexmls_designations`

NAR certified designations, and special access roles or attributes for this user. The values are defined by the MLS, so they may have a special non-standard meaning. This attribute is slightly different from the others, in that it can have multiple values. (The single <saml2:Attribute> tag may have one or more <saml2:AttributeValue> tags)

Here's an example snippet of the attribute statement section:

<saml2:Attribute Name="flexmls_designations"
   NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
      <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:type="xs:string">
            CRS
      </saml2:AttributeValue>
      <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:type="xs:string">
            GRI
      </saml2:AttributeValue>
      <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:type="xs:string">
            ePro
      </saml2:AttributeValue>
      <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:type="xs:string">
            Allowed Forms Access
      </saml2:AttributeValue>
</saml2:Attribute>

In this example, the member has four designations. Three of them are standard NAR certificates. (Certified Residential Specialist, Graduate of REALTOR Institute, and e-Pro certification) The fourth is a custom attribute defined by the MLS to add role based security to the account. This particular member is allowed to use the Forms software.

Each SP package handles attributes a little differently in respect to multiple values. In Shibboleth SP, all values are concatenated into a semicolon separated string in the environment variable. In this example, the variable flexmls_designations would be set to the string "CRS;GRI;ePro;Allowed Forms Access".