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

 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

 

Identity Provider

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.

Indeavor’s Service Provider Metadata is necessary to add Indeavor as a relying party for an IdP.

 

Metadata can be retrieved by a URL from Indeavor:

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

Metadata compare & retrieval is hourly at the top of the hour. 

 

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.
  • Metadata url

 

Service Provider (Indeavor)

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 a relying party is indeed any system entity that relies on assertions issued by a SAML authority. These relying parties typically accept and consume SAML assertions to make access control decisions or to authenticate users. They trust the assertions issued by SAML authorities and use them to grant access or make other authorization decisions within their systems.

Indeavor only supports SP initiated requests.

 

Identity Provider Configurations 

Endpoints

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.

 

 

Service 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

 

What to Expect

XML Examples

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

<EntityDescriptor xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:oasis:names:tc:SAML:2.0:metadata" entityID="https://identity.[ENVIRONMENT].indeavor.com" ID="…">

<SPSSODescriptor ID="…" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">

<KeyDescriptor>

<KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">

<X509Data>

<X509Certificate>…</X509Certificate>

</X509Data>

</KeyInfo>

</KeyDescriptor>

<SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://identity.[ENVIRONMENT].indeavor.com/Saml/SingleLogoutService"/>

<SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://identity.[ENVIRONMENT].indeavor.com/Saml/SingleLogoutService"/>

<AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://identity.[ENVIRONMENT].indeavor.com/Saml/AssertionConsumerService" index="0" isDefault="true"/>

</SPSSODescriptor>

</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

<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 the web login page:  https://identity.[ENVIROMENTNAME].indeavor.com/

  • Select the Company code/name and click Continue
  • 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 is 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 assertion’s attributes
  • User is logged in

 

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 logs in

 

 

Related articles