Introduction to SAML

What is Authentication?

Authentication is the process of validating the identity of a user. This is to make sure that the user connecting to a system is authorized/allowed for the same. In the last couple of years, there has been a significant shift towards the federated authentication to centralize the authentication process by delegating the process of authentication to an identity provider. SAML is one of the ways to achieve this.

Why SAML?

SAML is the standardized format designed to be interoperable with any system. SAML is important to your organization as you move more towards relying on hosted services as it provides a single point of authentication at IDP. The credentials are not stored on multiple untrusted devices as SAML is used to assert the identity. Other benefit lies in the user experience as users do not have to remember multiple credentials to access their apps. They can access multiple applications with a single set of credentials by logging in once. It also reduces the overhead of maintaining hardware, software for authentication, adding auth mechanisms within applications.

SAML Terminology

Client	A user who is trying to access a protected resource All communication between the SP and IDP happen through the client’s browser.
Service Provider (SP)	An entity that hosts the protected resource and requests authentication information from the Identity Provider before granting the client access to the resource
Identity Provider (IDP)	A trusted entity which validates the identity of the client and provides authentication services to the SP
Assertion	XML messages exchanged between IDP and SP
SAML Request	A request the SP passes to the IDP to authenticate a client.
SAML Response	An assertion the IDP passes to the SP containing information about the client.
Assertion Consumer Service (ACS)	An HTTP resource within the SP that processes SAML protocol messages and returns a cookie representing the information extracted from the message. The IDP sends the SAML response assertion to the ACS.
Entity ID	A unique string that should match in both the IDP and SP.
Metadata	Configuration data used to provision an SP or IDP to communicate with each other. SAML 2.0 provides a well-defined, interoperable metadata format that entities can leverage to bootstrap the trust process.

SAML Processes

There are two types of SAML processes:

IDP-initiated SSO — The client connects to the identity provider, gets authenticated, and then accesses the resources from the service provider.
SP-Initiated SSO — The client connects to a service provider, which then redirects the client to the identity provider for authentication. Once successfully authenticated, the client is then redirected to the service provider. which allows access to the resource.

Note: Avi supports only SP-initiated SSO, with an Avi virtual service acting as the service provider.

SAML Bindings

The IDP and SP exchange a SAML request and a SAML response with each other through the client. The method to transport these messages is called a SAML binding. SAML supports multiple kinds of bindings.

An Avi VS acting as SP supports:

Redirect the binding to redirect the client to the IDP. The SAML request is carried directly in the URL query string of an HTTP GET request.
POST binding to send the response to the SP. The SAML response is transmitted within an HTML form using Base64-encoded content.

What is a SAML Assertion?

A SAML assertion is the XML document the IDP sends to the SP that contains the user information. There are three different types of statements in SAML assertions — authentication, attribute, and authorization.

Authentication — To prove the identity of the user.
Attribute assertion — SAML attributes are passed to SP as part of the assertion to provide information about the user.
Authorization assertion — Provides the SP information by which it can know the user is/isn’t authorized to use the service.

SAML Authentication for Clients with Avi VS as SP

Request Flow

The user tries to access the resource which is hosted on Avi, i.e., Avi is acting as a service provider: GET https://sales.avi.com/.
If the user is not authenticated already, Avi generates a SAML request and redirects the user to identity provider SSO service to get authenticated using a 302 Redirect.
Client’s browser sends a GET request to the SSO service of the IDP.SAML request is carried directly in the URL query string of an HTTP GET request.
Example:
https://idp.example.com/app/avinetworks_samlapp_1/exkfop30u1uCi2FEv0h7/sso/saml?SAMLRequest=fZJfb4IwFMW%2FCum7UBRFGyVB0cxkf8gke9iL6aDMRmhrb8Ht26%2FgYtzDfD33nJz7u%2B0caF0pEjfmIF7ZqWFgnK%2B6EkD6wQI1WhBJgQMRtGZATE528dMjGbqYKC2NzGWFbiL3ExSAacOlQM42WaD9OIzH%2FjoI%2FHC9Ccc4CKbxJJ6Es1kwXo6SYYKcN6bB%2BhfIxm0IoGFbAYYKYyXszwZ4OMBh5k8JxmQUvCMnsQxcUNOnDsYoIJ5HWy6YOUt9BFceDVWatZyd3VzWHlXqdr7vMMpTIaw%2B2vse%2BzqWUo1w4zcrPtysW3wIPQDpdT7kbKTOWX%2B%2FBSppBazbMrWgvGVXJf291JKLgovP%2B0f6uJiAPGRZOkhfdhmK5l0Z6fF11EFZpk4yFtaltr0nATX3bo3zy%2Bs%2B24ptksqK59%2FdvjU1%2F2%2Fgu36v8GJQ9lbSCFAs5yVnBXLiqpLnlWbUXOm86NL69xtFPw%3D%3D
IDP presents a form to the user to enter the credentials unless they had already authenticated into IDP in a previous session within the same browser. Once the credentials are validated, the user is authenticated on IDP level.
In either case, the SSO service at IDP returns an XHTML document after the successful authentication, which includes the information needed by the SP in a SAMLResponse parameter. The SAML response will:
- Indicate that it is indeed from the trusted IDP and hasn’t been altered.
- Indicate that the user has authenticated successfully in IDP.
- Indicate who the user is via the NameID, a standard attribute used in SAML assertions.
The SAMLResponse parameter is passed on to the Avi ACS service from the client using a POST request.
Avi validates the assertion and sets a cookie for the client
The client sends a GET request to access the resource with the cookie that the SP provided.
The client can now request the resource.

Sample Metadata

In the below, <ds:X509Certificate> and </ds:X509Certificate> surround the IDP public key.


<EntityDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata"
 entityID="https://app.onelogin.com/saml/metadata/48171389-531f-4d3f-b9e3-9d44abb23ee8">
    <IDPSSODescriptor xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
	protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
       <KeyDescriptor use="signing">
         <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
            <ds:X509Data>
               <ds:X509Certificate>
                 MIID6zCCAtOgAwIBAgIUJMCbFE2bd/6sCjz7gZr8AJXM6vswDQYJKoZIhvcNAQEF
			     BQAwSjEVMBMGA1UECgwMQXZpIG5ldHdvcmtzMRUwEwYDVQQLDAxPbmVMb2dpbiBJ
			     ZFAxGjAYBgNVBAMMEU9uZUxvZ2luIEFjY291bnQgMB4XDTE4MDkyNDEyMjE0NVoX
			     DTIzMDkyNDEyMjE0NVowSjEVMBMGA1UECgwMQXZpIG5ldHdvcmtzMRUwEwYDVQQL
			     DAxPbmVMb2dpbiBJZFAxGjAYBgNVBAMMEU9uZUxvZ2luIEFjY291bnQgMIIBIjAN
			     BgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEApOIRYePmMm+LMxgvh4PQWxhBtwzf 
			     KPbFj2LUcVZQsNHDwZp7s1b+htv3DZ6OY7yJ1Judu6BcVGJMyTRlb3eZ++5YjRyX
			     Zmabg4RQf1lBYfcdqmrIG5fMKoM9OWqQ7aRJb/KYtj/YymK0/Im3dFB7ioGkvSP0
			     b2Q5sle0HJnnpFih0LQjX0x6HaGBYvlF5tyrdKtUVXM7fLevwW0h0bB2LOhzKbgq
			     paDn/yH0zGoGdHH3MA7C6s1Wdy2YqKxf6BVDNjzor0oOstdkkKT2IBpnqI56W5xJ
			     w4rms2H6umk4G3zqKI4IWKPzQ7tPqZpsI+9zeitELOiOuyLbTO//YxRlbQIDAQAB
			     o4HIMIHFMAwGA1UdEwEB/wQCMAAwHQYDVR0OBBYEFP0c2czccqKP14DFa+NHeTni
			     3ewfMIGFBgNVHSMEfjB8gBT9HNnM3HKij9eAxWvjR3k54t3sH6FOpEwwSjEVMBMG
			     A1UECgwMQXZpIG5ldHdvcmtzMRUwEwYDVQQLDAxPbmVMb2dpbiBJZFAxGjAYBgNV
			     BAMMEU9uZUxvZ2luIEFjY291bnQgghQkwJsUTZt3/qwKPPuBmvwAlczq+zAOBgNV
			     HQ8BAf8EBAMCB4AwDQYJKoZIhvcNAQEFBQADggEBAKQQt1Goo3zeyAtjWkfxW9A8
			     o1ydzAqq7u779z9OsutbHsixy525Cs62Na/252CG39yk0Uy69ar+V9gBeBLaKNaz
			     w4JbaweFQgHlCVmT4lGEe1kmnsPwgP7nLq2SvkwTYqpcVq5KE+UfRpTixA/KJ61C
			     6yV03UCM7/T9NZ1pw/oYaweuxbtOn7rXT/NTiPIm7owA4soegDBEXIZ20KuMAkGc
			     dRAi5zoIqHsm7w/v/MT8DhTtZE2sH2mSegjUj8DOH5AcxdlNpp6VI2NApi+lTpEf
			     rqnQoDKs3BPp6SwcIvNqmSZ+R3eZkyGeJuCK4sxj2Od1plRpYihaRe32sNNjnwM=
               </ds:X509Certificate>
            </ds:X509Data>
         </ds:KeyInfo>
      </KeyDescriptor>
      <SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
	  Location="https://avi-networks-test-dev.onelogin.com/trust/saml2/http-redirect/slo/869509"/>
      <NameIDFormat>
        urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
      </NameIDFormat>
      <SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
	  Location="https://avi-networks-test-dev.onelogin.com/trust/saml2/http-redirect/sso/869509"/>
      <SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
	  Location="https://avi-networks-test-dev.onelogin.com/trust/saml2/http-post/sso/869509"/>
      <SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP"
	  Location="https://avi-networks-test-dev.onelogin.com/trust/saml2/soap/sso/869509"/>
   </IDPSSODescriptor>
</EntityDescriptor>john-doe

Sample SAML Request

The SP issues this to implicitly request an assertion containing an authentication statement.


<samlp:AuthnRequest
    xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" 
    xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" 
    ID="_B28D3D30B4D077D88FA2C7BF64CC0F8B" 
    Version="2.0" 
    IssueInstant="2018-12-13T11:31:59Z" 
    Destination="https://avi-networks-test-dev.onelogin.com/trust/saml2/http-redirect/sso/860690"
    ForceAuthn="false" 
    IsPassive="false" 
    ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST">
    <saml:Issuer>avi-saml-vs</saml:Issuer>
    <samlp:NameIDPolicy 
        Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified" 
        AllowCreate="false"/>
</samlp:AuthnRequest>

Sample SAML Response

Look for arrows <– accompanied by explanatory text in the below sample:


<samlp:Response 
    xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" 
    xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" 
    ID="R5e5c1b3cff12759e78f27c723a99963acf94fff5" 
    Version="2.0" 
    IssueInstant="2018-12-13T11:32:00Z" 
    Destination="http:/test-onelogin.auth.com/sso/acs/" 
    InResponseTo="_B28D3D30B4D077D88FA2C7BF64CC0F8B">
    <saml:Issuer>https://app.onelogin.com/saml/metadata/4e4332e8-be0f-4650-9bac-2ea85fa16d12</saml:Issuer>
    samlp:Status>
        <samlp:StatusCode 
            Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>
    </samlp:Status>
    <saml:Assertion   <-- Beginning of SAML assertion. Within assertion there can be kinds of statements: authentication statement, authorization statement and attribute statement.
        xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" 
        xmlns:xs="http://www.w3.org/2001/XMLSchema" 
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
        Version="2.0" 
        ID="pfx01cfd769-cd0d-f4dd-677c-f24b1ff887ef" 
        IssueInstant="2018-12-13T11:32:00Z">
        <saml:Issuer>https://app.onelogin.com/saml/metadata/4e4332e8-be0f-4650-9bac-2ea85fa16d12</saml:Issuer>  <-- The element which contains the identity provider's unique identifier
        <ds:Signature   <-- This shows that this is a signed assertion.
            xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
            <ds:SignedInfo>
                <ds:CanonicalizationMethod 
                    Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
                <ds:SignatureMethod 
                    Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
                <ds:Reference 
                    URI="#pfx01cfd769-cd0d-f4dd-677c-f24b1ff887ef">
                    <ds:Transforms>
                        <ds:Transform 
                            Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
                        <ds:Transform 
                            Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
                    </ds:Transforms>
                    <ds:DigestMethod 
                        Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
                    <ds:DigestValue>
                        3fAOHPB8meQtrDlQIRz5gRzUAJs=
                    </ds:DigestValue>
                </ds:Reference>
            </ds:SignedInfo>
            The below SignatureValue contains an integrity-preserving digital signature.
            ds:SignatureValue>aVpr6bjhsHW+SkkN5Fb0IMqZCBbfqucF12EhS+pO0ZrZM8qQ5LqOvNF9MY1WzO3tTscyYwsP3gScBaZzm0KHHIn/OyXj77nqT+BNBiDij7tyXfg4RvMYH6o7R36yRR8Bop9HeJ66fgRNkKA4j54sXF7BQXM+I7FFC5bT9GzXnEi47towME3kHAUlrggt+/GfA6z8Jot13a6xCmrnMaKDVOJbHqcO5LuK2zFd4VQYmpuB+0T6az19S/Hmyc89auI/dw/9uyOAC5on9b+3brKWzK1Qke54ZbQMU/
                N3BNE8fwBAYIki5j6lnw0Txzun8EsW8UosSlh1tXlSwRhA76Wwng==
            </ds:SignatureValue>
            <ds:KeyInfo>
                <ds:X509Data>                          <ds:X509Certificate>MIID6zCCAtOgAwIBAgIUJMCbFE2bd/6sCjz7gZr8AJXM6vswDQYJKoZIhvcNAQEFBQAwSjEVMBMGA1UECgwMQXZpIG5ldHdvcmtzMRUwEwYDVQQLDAxPbmVMb2dpbiBJZFAxGjAYBgNVBAMMEU9uZUxvZ2luIEFjY291bnQgMB4XDTE4MDkyNDEyMjE0NVoXDTIzMDkyNDEyMjE0NVowSjEVMBMGA1UECgwMQXZpIG5ldHdvcmtzMRUwEwYDVQQLDAxPbmVMb2dpbiBJZFAxGjAYBgNVBAMMEU9uZUxvZ2luIEFjY291bnQgMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEApOIRYePmMm+LMxgvh4PQWxhBtwzfKPbFj2LUcVZQsNHDwZp7s1b+htv3DZ6OY7yJ1Judu6BcVGJMyTRlb3eZ++5YjRyXZmabg4RQf1lBYfcdqmrIG5fMKoM9OWqQ7aRJb/KYtj/YymK0/Im3dFB7ioGkvSP0b2Q5sle0HJnnpFih0LQjX0x6HaGBYvlF5tyrdKtUVXM7fLevwW0h0bB2LOhzKbgqpaDn/yH0zGoGdHH3MA7C6s1Wdy2YqKxf6BVDNjzor0oOstdkkKT2IBpnqI56W5xJw4rms2H6umk4G3zqKI4IWKPzQ7tPqZpsI+9zeitELOiOuyLbTO//YxRlbQIDAQABo4HIMIHFMAwGA1UdEwEB/wQCMAAwHQYDVR0OBBYEFP0c2czccqKP14DFa+NHeTni3ewfMIGFBgNVHSMEfjB8gBT9HNnM3HKij9eAxWvjR3k54t3sH6FOpEwwSjEVMBMGA1UECgwMQXZpIG5ldHdvcmtzMRUwEwYDVQQLDAxPbmVMb2dpbiBJZFAxGjAYBgNVBAMMEU9uZUxvZ2luIEFjY291bnQgghQkwJsUTZt3/qwKPPuBmvwAlczq+zAOBgNVHQ8BAf8EBAMCB4AwDQYJKoZIhvcNAQEFBQADggEBAKQQt1Goo3zeyAtjWkfxW9A8o1ydzAqq7u779z9OsutbHsixy525Cs62Na/252CG39yk0Uy69ar+V9gBeBLaKNazw4JbaweFQgHlCVmT4lGEe1kmnsPwgP7nLq2SvkwTYqpcVq5KE+UfRpTixA/KJ61C6yV03UCM7/T9NZ1pw/oYaweuxbtOn7rXT/NTiPIm7owA4soegDBEXIZ20KuMAkGcdRAi5zoIqHsm7w/v/MT8DhTtZE2sH2mSegjUj8DOH5AcxdlNpp6VI2NApi+lTpEfrqnQoDKs3BPp6SwcIvNqmSZ+
                        R3eZkyGeJuCK4sxj2Od1plRpYihaRe32sNNjnwM=
                    </ds:X509Certificate>
                </ds:X509Data>
            </ds:KeyInfo>
        </ds:Signature>
        <saml:Subject>
            <saml:NameID  <-- A standard attribute used in SAML assertions
                Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">mittali@avinetworks.com
            </saml:NameID>
            <saml:SubjectConfirmation 
                Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
                <saml:SubjectConfirmationData 
                    NotOnOrAfter="2018-12-13T11:35:00Z" 
                    Recipient="http:/test-onelogin.auth.com/sso/acs/" 
                    InResponseTo="_B28D3D30B4D077D88FA2C7BF64CC0F8B"/>
            </saml:SubjectConfirmation>
        </saml:Subject>
        <saml:Conditions 
            NotBefore="2018-12-13T11:29:00Z" 
            NotOnOrAfter="2018-12-13T11:35:00Z">
            <saml:AudienceRestriction>
                <saml:Audience>jenkins-saml-vs</saml:Audience>
            </saml:AudienceRestriction>
        </saml:Conditions>
        <saml:AuthnStatement  <-- marks the beginning of authentication statement, which says the principal identified in the <saml:Subject> element was authenticated at "2018-12-13T11:31:59Z" by means of a password sent over a protected channel.
            AuthnInstant="2018-12-13T11:31:59Z" 
            SessionNotOnOrAfter="2018-12-14T11:32:00Z" 
            SessionIndex="_a16c6df0-e0f8-0136-f6b8-5b63382161ef">
            <saml:AuthnContext>
                <saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</saml:AuthnContextClassRef>
            </saml:AuthnContext>
        </saml:AuthnStatement>     <-- End of authentication statement
        <saml:AttributeStatement>  <-- Beginning of attribute statement
            <saml:Attribute 
                NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" 
                Name="User.email">
                <saml:AttributeValue 
                    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
                    xsi:type="xs:string">mittali@avinetworks.com
                </saml:AttributeValue>
            </saml:Attribute>
            <saml:Attribute 
                NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" 
                Name="User.FirstName">
                <saml:AttributeValue 
                    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
                    xsi:type="xs:string">Mittali
                </saml:AttributeValue>
            </saml:Attribute>
            <saml:Attribute 
                NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" 
                Name="PersonImmutableID">
                <saml:AttributeValue 
                    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
                    xsi:type="xs:string"/>
            </saml:Attribute>
            <saml:Attribute 
                NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" 
                Name="User.LastName">
                <saml:AttributeValue 
                    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
                    xsi:type="xs:string">Chawla
                </saml:AttributeValue>
            </saml:Attribute>
            <saml:Attribute 
                NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" 
                Name="memberOf">
                <saml:AttributeValue 
                    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
                    xsi:type="xs:string"/>
            </saml:Attribute>
        </saml:AttributeStatement>   <-- End of attribute statement
    </saml:Assertion>                <-- End of assertion
</samlp:Response>                    <-- End of SAML response