Developer Documentation
Platform Overview
Authentication
API Services
Overview Accounts Accounts: Associations Accounts: Metadata Accounts: Profile Appstore: Users Broker Distributions Broker Tours Consumers Consumers: Linked Agents Contacts Contacts: Activity Contacts: Export Contacts: Tags Contacts: Portal Accounts Developers: Identities Developers: Keys Developers: Authorizations Developers: Billing Summary Developers: Change History Developers: Domains Developers: News Feed Webhooks Developers: Roles Developers: Syndications Developers: Templates Developers: Usage Detail Developers: Usage Summary Devices Flexmls: Email Links Flexmls: Listing Meta Origins Flexmls: Listing Meta Translations Flexmls: Listing Meta Field List Translations Flexmls: Listing Reports Flexmls: Mapping Layers Flexmls: Mapping Shapegen IDX IDX Links Listing Carts Listing Carts: Portal/VOW Carts Incomplete Listings Incomplete Listings: Documents Incomplete Listings: Documents Metadata Incomplete Listings: Document Uploads Incomplete Listings: Floor Plans Incomplete Listings: FloPlans Incomplete Listings: Photos Incomplete Listings: Photos Metadata Incomplete Listings: Photo Uploads Incomplete Listings: Rooms Incomplete Listings: Tickets Incomplete Listings: Units Incomplete Listings: Videos Incomplete Listings: Videos Metadata Incomplete Listings: Virtual Tours Incomplete Listings: Virtual Tours Metadata Listings Listings: Clusters Listings: Documents Listings: Documents Metadata Listings: Floor Plans Listings: FloPlans Listings: Historical Listings: History Listings: Notes Listings: Search Parameters Listings: Open Houses Listings: Photos Listings: Photos Metadata Listings: Photo Uploads Listings: Document Uploads Listings: Rental Calendar Listings: Rooms Listings: Rules Listings: Tour of Homes Listings: Tickets Listings: Units Listings: Validation Listings: Videos Listings: Videos Metadata Listings: Virtual Tours Listings: Virtual Tours Metadata Listing Meta: Custom Fields Listing Meta: Custom Field Groups Listing Meta: Field Order Listing Meta: Field Relations Listing Meta: Property Types Listing Meta: Rooms Listing Meta: Standard Fields Listing Meta: Units Registered Listings Market Statistics News Feed News Feed: Curation News Feed: Events News Feed: Metadata News Feed: Restrictions News Feed: Schedule News Feed: Settings News Feed: Templates Open Houses Overlays Overlays: Shapes Portals Preferences Saved Searches Saved Searches: Provided Saved Searches: Restrictions Saved Searches: Tags Search Templates: Quick Searches Search Templates: Views Search Templates: Sorts Shared Links System Info System Info: Languages System Info: Search Templates
Supporting Documentation
Examples
RESO Web API
RETS
FloPlan
Terms of Use

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:

 

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".