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
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
- 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 - SAMLRequest contains the AuthnRequest Base-64 encoded. This value contains information about the issuer of the request
- 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.
- 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
- 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 - SAMLRequest contains the AuthnRequest Base-64 encoded. This value contains information about the issuer of the request
- 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.
- 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