Authentication

SAML Review

About

Security Assertion Markup Language (SAML) is an open standard for exchanging authentication and authorization data between parties, in particular, between an identity provider and a service provider.

The Ultraviolet Coordinator utilizes SAML as a mean to authorize API access to implementers on behalf of users.

Types

• AuthnRequest
  • A signed message sent from a service provider to an identity provider to prompt an authentication mechanism for an end user. The AuthnRequest includes configuration such as how the user should be identified in a resulting assertion, service binding URIs, session duration, and more.
• Response
  • A signed message sent from an identity provider in response to an AuthnRequest when user identification has been completed. A Response includes an Assertion, which can be used as an authorization method.
• Assertion
  • A signed message containing any number of attributes (claims) to authorize interaction between services. An Assertion signature provides a proof of trust and verifiability to any service that consumes Assertions as it’s primary means of authorization.
• Federation
  • A use case of SAML where a service provider may request an Assertion be valid for use for another service.

Coordinator Security Host

For any node to establish a link between itself and an existing Ultraviolet user, the node must first gain authorization from a user in the form of a SAML Assertion.

The AuthnRequest (SAML Form Authentication)

A node prepares an AuthnRequest to be sent to the Coordinator to configure a link between the user and node pending the users authentication.

<saml2p:AuthnRequest xmlns:c="http://www.decellc.org/schema/2015/03/coordinator" xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" Destination="https://iot.s.uvvu.com/security/delegation/saml/loginservice/login" IssueInstant="2016-06-14T08:06:00.040231Z" ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" ID="_6ffa1e2a-943e-4acb-a734-a1936f8af5bf" AssertionConsumerServiceURL="https://staging.rpa.uvvuconnect.com/api/v1/saml/SSO">
  <saml2:Issuer>urn:dece:org:org:dece:falcon:retailer</saml2:Issuer>
  <ds:Signature Id="placeholder">...</ds:Signature>
  <saml2p:Extensions>
    <c:Language>en_US</c:Language>
    <c:PolicyList>
      <c:Policy>
        <c:PolicyClass>urn:dece:type:policy:UserLinkConsent</c:PolicyClass>
      </c:Policy>
    </c:PolicyList>
  </saml2p:Extensions>
  <saml:Subject>
    <saml:NameID Format='urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'>urn:dece:userid:org:dece:ABCDEF123456789ABCDEF123456789AB</saml:NameID>
  </saml:Subject>
</saml2p:AuthnRequest>

The node will then sign and deflate this xml, and send it to the Coordinator

POST /security/delegation/saml/loginservice/login HTTP/1.1
Content-type: application/x-www-form-urlencoded
Host: api.uvvu.com

SAMLRequest={DeflatedAuthnRequest}&RelayState={RelayState}

The Coordinator will respond with a form to authenticate the user via login credentials. Upon succesfull authentication, the Coordinator will direct the user agent back to the requesting nodes AssertionConsumerServiceURL as configured in the original AuthnRequest.

POST [AssertionConsumerServiceURL] HTTP/1.1
Content-type: application/x-www-form-urlencoded

SAMLResponse={DeflatedResponse}&RelayState={RelayState}

AuthnRequest Configuration

• AuthnRequest
  • @ProtocolBinding - Response binding type (urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST | urn:oasis:names:tc:SAML:2.0:bindings:Redirect). If this parameter is ommited, the default AssertionConsumerService binding type is used.
  • @AssertionConsumerServiceIndex - Configured AssertionConsumerService binding identified by its index. If this paramerter is ommited, the default AssertionConsumerService binding type is used.
  • Extensions
    • Language - The language to display the login form in. If this element is ommited, the Coordinator will default to the User agent language.
  • Subject
    • NameID - A unique dece:EntityIdentifier-type that can be used as a UserID in subsequent API calls. If this element is ommited, the Coordinator will assign a random identifier