Skip to main content

Indeavor Setup for Single Sign On with SAML 2.0

Tara Hunt
  • Updated

Indeavor  Single Sign On with SAML 2.0 Overview

This article provides client an overview of how to configure Single Sign On with SAML 2.0.

 

SSO Overview

Security Assertion Markup Language (SAML) allows customers to authenticate against their own systems when logging into Indeavor.  Our implementation uses the SAML 2.0 protocol.  

SAML is an XML-based framework for authentication and authorization between two entities: a Service Provider and an Identity Provider. The Service Provider agrees to trust the Identity Provider to authenticate users. In return, the Identity provider generates an authentication assertion, which indicates that a user has been authenticated.

SAML is a standard single sign-on (SSO) format. Authentication information is exchanged through digitally signed XML documents. It's a complex single sign-on (SSO) implementation that enables seamless authentication, mostly between businesses and enterprises.

Identity Provider (IDP)/Asserting Party:  This is the customer.  A common implementation is Microsoft Active Directory Federated Services (ADFS) or Azure.

Service Provider (SP)/Relying Party:  This is Indeavor

mceclip1.png

Indeavor Protip:  Indeavor only supports SP initiated requests.

 

Identity Provider Configuration

The customer will need our Service Provider Metadata to add Indeavor as a relying party in their IDP. 

An identity provider is a system entity that creates, maintains, and manages identity information for principals while providing authentication services to relying party applications within a federation or distributed network.

An identity provider offers user authentication as a service. Relying party applications, such as web applications, outsource the user authentication step to a trusted identity provider. Such a relying party application is said to be federated, that is, it consumes federated identity.

An identity provider is “a trusted provider that lets you use single sign-on (SSO) to access other websites.” SSO enhances usability by reducing password fatigue. It also provides better security by decreasing the potential attack surface.

Specifically, a SAML identity provider is a system entity that issues authentication assertions in conjunction with an SSO profile of SAML. A relying party that consumes these authentication assertions is called a SAML service provider.[1]

[1] https://en.wikipedia.org/wiki/Identity_provider

  

Metadata can be retrieved by a URL from Indeavor:

https://identity.[ENVIROMENTNAME].indeavor.com/saml/metadata.xml

 

Recommended Best Practices

  • SHA-256 algorithm
  • Indeavor SSO requires the unique identifier field provided by ADFS to be contained within the Attribute Statement block of the response.  Most clients find using the email address to be the best unique identifier to achieve this result.
  • “Relay State” parameter sent by Indeavor with Authentication SAML request is required to be included into Federation Service’s SAML response coming back to Indeavor.

 

Indeavor (Service Provider) Configuration

 A SAML service provider is a system entity that receives and accepts authentication assertions in conjunction with a single sign-on (SSO) profile of the Security Assertion Markup Language (SAML).

In the SAML domain model, a SAML relying party is any system entity that receives and accepts information from another system entity. Of particular interest is a SAML relying party that receives and accepts a SAML assertion issued by a SAML authority.

An important type of SAML authority is the SAML identity provider, a system entity that issues authentication assertions in conjunction with an SSO profile of SAML. A relying party that consumes such assertions is called a SAML service provider (or simply service provider if the domain is understood). Thus a SAML service provider is a system entity that receives and accepts an authentication assertion issued by a SAML identity provider.[1]

[1] https://en.wikipedia.org/wiki/Service_provider_(SAML)

 

Assertion

A SAML assertion contains a packet of security information

SAML assertions are usually transferred from identity providers to service providers. Assertions contain statements that service providers use to make access-control decisions. Three types of statements are provided by SAML:

  • Authentication statements
  • Attribute statements
  • Authorization decision statements

Authentication statements assert to the service provider that the principal did indeed authenticate with the identity provider at a particular time using a particular method of authentication. Other information about the authenticated principal (called the authentication context) may be disclosed in an authentication statement.

An attribute statement asserts that a subject is associated with certain attributes. An attribute is simply a name-value pair. Relying parties use attributes to make access-control decisions.

An authorization decision statement asserts that a subject is permitted to perform action A on resource R given evidence E. The expressiveness of authorization decision statements in SAML is intentionally limited.[1]

 

Protocol

A SAML protocol describes how certain SAML elements (including assertions) are packaged within SAML request and response elements, and gives the processing rules that SAML entities must follow when producing or consuming these elements. For the most part, a SAML protocol is a simple request-response protocol.

The following protocols are described in detail in SAML 2.0 Core:

  • Assertion Query and Request Protocol
  • Authentication Request Protocol
  • Artifact Resolution Protocol
  • Name Identifier Management Protocol
  • Single Logout Protocol
  • Name Identifier Mapping Protocol[2]

 

Binding

A SAML binding is a mapping of a SAML protocol message onto standard messaging formats and/or communications protocols. For example, the SAML SOAP binding specifies how a SAML message is encapsulated in a SOAP envelope, which itself is bound to an HTTP message.

The following bindings are described in SAML:

  • SAML SOAP Binding (based on SOAP 1.1)
  • Reverse SOAP (PAOS) Binding
  • HTTP Redirect (GET) Binding
  • HTTP POST Binding
  • HTTP Artifact Binding
  • SAML URI Binding

 

Profile

A SAML profile describes in detail how SAML assertions, protocols, and bindings combine to support a defined use case. The most important SAML profile is the Web Browser SSO Profile.

The following protocols are described in SAML:

  • SSO Profiles
    • Web Browser SSO Profile
    • Enhanced Client or Proxy (ECP) Profile
    • Identity Provider Discovery Profile
    • Single Logout Profile
    • Name Identifier Management Profile
  • Artifact Resolution Profile
  • Assertion Query/Request Profile
  • Name Identifier Mapping Profile
  • SAML Attribute Profiles

 

What we use

For login workflow we use the “Web Browser SSO Profile”, the binding that are supported is “HTTP Redirect (GET) Binding” (mobile), “HTTP POST Binding” (web).

For logout workflow we use the “Single Logout Profile”, the binding that are supported is “HTTP Redirect (GET) Binding”, “HTTP POST Binding”.
[1] https://en.wikipedia.org/wiki/Security_Assertion_Markup_Language

[2] https://en.wikipedia.org/wiki/Security_Assertion_Markup_Language

 

Metadata

SAML metadata is configuration data required to automatically negotiate agreements between system entities, comprising identifiers, binding support and endpoints, certificates, keys, cryptographic capabilities and security and privacy policies. Several SAML specifications standardize metadata structures and contents, thus supporting efficient management processes for saleable deployments.

As SAML specifications evolved over time metadata related specifications are contained in several documents. This non-normative document provides a consolidated overview and links to the normative specifications.[1]

[1] https://www.oasis-open.org/committees/download.php/51890/SAML%20MD%20simplified%20overview.pdf

 SSO must be enabled in Indeavor in order for the metadata endpoints to be available.

 

ADFS Configurations 

Endpoints

Indeavor Protip:  SSO must be turned on in your domain in order for metadata link to be available.

Web

Metadata & Endpoints

URL:  https://identity.[ENVIROMENTNAME].indeavor.com/saml/metadata.xml

Description: Returns the Service Provider Metadata (see Saml Description/Metadata). If the SAML provider is not enabled for the requested domain the endpoint return 404. 

 

Assertion Consumer Handler

Description: The endpoint that accepts assertion responses from service provider. Implements the validation of the given assertion, extracts the user name from the configured attribute and login the user if is valid Indeavor user.

Single Logout Service

Description: The endpoint that accepts logout requests/responses from service provider. Implements the validation of the given requests/ responses, and logouts the Indeavor user.

Saml Login Page

Description: The page that implements login thought the SAML identity provider. User fills the domain input, the app finds the correct service provider, creates an authentication request and redirect the user to SingleSignOnService of the identity provider.

 

 

Indeavor Configurations

Add the Indeavor certificate for encryption/signing the Saml requests

  • Create file that contains the SAML certificate, this file should be accessible from the application
  • Add the path of the file to Data/Config/SamlSSO.config <samlSSOSettings certificate="certificate path" password="file password" />

Run the application under secure connection (HTTPS) Saml provider requires HTTPS

 

Setting up Metadata and UID Pattern on a System level

 

https://support.indeavor.com/hc/en-us/articles/115001794466

 

 

Creating a User Profile for Single Sign-On

https://support.indeavor.com/hc/en-us/articles/115001796366

 

 

What to Expect

 

XMLs

Identity provider metadata

<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" entityID="https://idp.cloudroll.gr">
    <md:IDPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
        <md:KeyDescriptor use="signing">
            ...
        </md:KeyDescriptor>
        <md:KeyDescriptor use="encryption">
            ...
        </md:KeyDescriptor>
        <md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://idp.cloudroll.gr/idp/SingleLogoutService" index="0" isDefault="false"/>
        <md:NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:transient</md:NameIDFormat>
        <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://idp.cloudroll.gr/idp/SSOService" index="0" isDefault="false"/>
    </md:IDPSSODescriptor>
    </md:EntityDescriptor>

 

entityID: Identity provider unique identifier.

IDPSSODescriptor: Contains IdP information.

KeyDescriptor: Key that used by entity for responses signing and encryption.

NameIDFormat: The format of user unique identifier.

SingleSignOnService: The URL that used SSO.

SingleLogoutService: The URL that used SLO.

Location: The URL of the Binding.

Binding: The type of the binding response.

index: The index of the Binding.

isDefault: If it is the default binding service for this process

 

 

Service provider metadata

<md:EntityDescriptor entityID="https://sp.cloudroll.gr" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:mdui="urn:oasis:names:tc:SAML:metadata:ui">
    <md:SPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
        <md:KeyDescriptor use="signing">
            ...        
        </md:KeyDescriptor>
        <md:KeyDescriptor use="encryption">
            ...        
        </md:KeyDescriptor>
        <md:ArtifactResolutionService Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP" Location="https://sp.cloudroll.gr/Artifact/SOAP" index="1"   isDefault="false"/>
        <md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP" Location="https://sp.cloudroll.gr/SLO/SOAP" />
        <md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://sp.cloudroll.gr/SLO/POST" />
        <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://sp.cloudroll.gr/SAML2/POST" index="1" />
    </md:SPSSODescriptor>
</md:EntityDescriptor>

 

entityID: Identity provider unique identifier.

SPSSODescriptor: Contains SP information.

KeyDescriptor: Key that used by entity for responses signing and encryption.

NameIDFormat: The format of user unique identifier.

SingleSignOnService: The URL that used SSO.

SingleLogoutService: The URL that used SLO.

Location: The URL of the Binding.

Binding: The type of the binding response.

index: The index of the Binding.

isDefault: If it is the default binding service for this process

 

 

Authentication request

<samlp:AuthnRequest
    xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
    xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
    ID="…"
    Version="2.0"
    IssueInstant="2015-01-31T06:00:00"
    AssertionConsumerServiceIndex="0"
    ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST">
                <saml:Issuer>www.workloud.com</saml:Issuer>
                <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">...</ds:Signature>
</samlp:AuthnRequest>

 

ID: The identifier of Authentication request.

Issuer: The identifier of issuers (SP).

Signature: The signature of issuer for checking the validity of the request, if the xml is signed.

AssertionConsumerServiceIndex: The URL that the IDP returns the assertion after the user identification.

AssertionConsumerServiceURL: The URL that the IDP returns the assertion after the user identification.

ProtocolBinding: The type of the response that the assertion should be return.

 

 

Assertion

Here is an assertion example

<saml:Assertion xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" Version="2.0" IssueInstant="2015-01-31T12:00:00Z">
    <saml:Issuer>www.workloud.com</saml:Issuer>                                                           <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">...</ds:Signature>
    <saml:Subject>
        <saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"> cloudroll@example.com</saml:NameID>
    </saml:Subject>
    <saml:Conditions NotBefore="2015-01-31T12:00:00Z" NotOnOrAfter="2015-01-31T12:00:00Z"> </saml:Conditions>
    <saml:AuthnStatement
     AuthnInstant="2004-12-05T09:22:00"
     SessionIndex="b07b804c-7c29-ea16-7300-4f3d6f7928ac">
        <saml:AuthnContext>
            <saml:AuthnContextClassRef>
         urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport
            </saml:AuthnContextClassRef>
        </saml:AuthnContext>
    </saml:AuthnStatement>
    <saml:AttributeStatement>
        <saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" Name="urn:oid:1.3.6.1.4.1.5923.1.1.1.1" FriendlyName="eduPersonAffiliation">
            <saml:AttributeValue>admin</saml:AttributeValue>
        </saml:Attribute>                                                                                  </saml:AttributeStatement>
</saml:Assertion>

 

The assertion includes:

Issuer: The identifier of issuers (Idp).

Signature: The signature of issuer for checking the validity of the request, the xml is signed.

Subject: The user identifier.

AuthnStatement: The claim that describes the user's identity.

Conditions: Describes the conditions that the assertion is valid.

AuthnInstant: The moment that the assertion issued.

SessionIndex: The session index that the user is identified by IdP.

AuthnContext: The authentication context that used from IdP for identifying the user

AttributeStatement: Includes the user attributes

Name: The name of the attribute.

FriendlyName: The friendly name of the attribute.

 

 

LogoutRequest

<samlp:LogoutRequest
        xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
        xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
        ID="..."
        Version="2.0" IssueInstant="2014-07-18T01:13:06Z"
        Destination="www.workloud.com/SingleLogoutService">
    <saml:Issuer>www.workloud. com </saml:Issuer>
    <saml:NameID SPNameQualifier="www.workloud. com " Format="urn:oasis:names:tc:SAML:2.0:nameid-format:transient">......</saml:NameID>
</samlp:LogoutRequest>

ID: The identifier of Authentication request.

Issuer: The identifier of issuers (SP).

Signature: The signature of issuer for checking the validity of the request, if the xml is signed.

IssueInstant: The moment that the logout response issued.

Destination: The web service that consumes the request.

InResponseTo: The identifier of request that the response belongs.

NameID:  The user identifier that the request belongs.

 

 

LogoutResponse

<samlp:LogoutResponse
        xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
        xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
        ID="...."
        Version="2.0"
        IssueInstant="2014-07-18T01:13:06Z"
        Destination="www.workloud.gr/SingleLogoutService"
        InResponseTo="...">
    <saml:Issuer>www.workloud.gr</saml:Issuer>
    <samlp:Status>
        <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>
    </samlp:Status>
</samlp:LogoutResponse>

 

ID: The identifier of Authentication request.

Issuer: The identifier of issuers (SP).

Signature: The signature of issuer for checking the validity of the request, if the xml is signed.

IssueInstant: The moment that the logout response issued.

Destination: The web service that consumes the response.

InResponseTo: The identifier of request that the response belongs.

Status: The status of response.

 

Web login workflow

  • Go to SAML login page
  • Select the domain and hit login
  • The application creates an auto-submit form that contains these parameters
    1. RelayState is a parameter that passed to the IDP and should be passed back to our SP as is, this parameter keeps the domain name that is required from our SP.
      Example RelayState value: url=/Default.aspx&dmn=demo
    2. SAMLRequest contains the AuthnRequest Base-64 encoded. This value contains information about the issuer of the request
  • The user redirected to the service provider
  • Provider validates the authentication request
  • Prompts user for login
  • The Identity provider issues an assertion with the user information
  • The user redirected to Indeavor Assertion Consumer Handler with the SAMLResponse and the RelayState from SAML request
  • Assertion Consumer Handler validates the request (signature, expired etc.)
  • Extracts the UserName for the assertions attributes
  • User logins

Mobile login workflow

  • User Goes to login view
  • Select the domain and hit login
  • The application creates an URL that contains these parameters
    1. RelayState is a parameter that passed to the IDP and should be passed back to our SP as is, this parameter keeps the domain name that is required from our SP.
      Example RelayState value: url=/Default.aspx&dmn=demo
    2. SAMLRequest contains the AuthnRequest Base-64 encoded. This value contains information about the issuer of the request
  • The mobile app open an web view with the generated URL
  • The user redirected to the service provider
  • Provider validates the authentication request
  • Prompts user for login
  • The Identity provider issues an assertion with the user information
  • The user redirected to Indeavor Assertion Consumer Handler with the SAMLResponse and the RelayState from SAML request
  • Assertion Consumer Handler validates the request (signature, expired etc.)
  • Extracts the UserName for the assertions attributes
  • User logins

 

Related articles