STS Service Interface Description

Introduction

EMI Security Token Service (STS) is a partial implementation of the OASIS WS-Trust specification. It is a service that can be used for transforming an existing security token into another security token format. Security token, on the other hand, is defined in the WS-Security specifications as a collection of claims that can be attached into a Web Service message.

The incoming token formats that are supported by our STS implementation include username and password that is validated against an LDAP directory, and SAML assertion. From these types of tokens, STS can issue an X.509 certificate or a proxy certificate containing the users' VO attributes.

This guide explains what kind of messages are consumed and produced by STS.

WS-Trust Interoperability profile

The WS-Trust specification employs an open content model within its request and response messages. This provides maximal extensibility but also means there is a theoretically infinite number of messages that could be produced and yet remain compliant with the specification. EMI STS uses a WS-Trust interoperabiity profile which attempts to strike a balance between the extensibility offered by the WS-Trust specification and the need to scope that functionality into a manageable set.

The profile exists from this URL: http://www.switch.ch/grid/support/documents/

The profile consist of a common profile for all tokens, and also token specific profiles for username token, SAML assertion and X.509 token. EMI STS follows these profiles, as shown in the example messages in the upcoming sections.

Incoming token formats

UsernameToken

Claims dialect: http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0

Username token is the simplest security token format. EMI STS can consume passwords in cleartext, or hashed by SHA1. However, Nonce and Created –elements cannot be included in the latter case, because only non-salted password hashes are supported.

An example of a token with a cleartext password:

<wsse:UsernameToken wsu:Id="UsernameToken">
   <wsse:Username>JohnDoe</wsse:Username>
   <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401
      -wss-username-token-profile-1.0#PasswordText">Password</wsse:Password>
</wsse:UsernameToken>

An example of a token with an SHA1-hashed password:

<wsse:UsernameToken wsu:Id="Username">
   <wsse:Username>testuser</wsse:Username>
   <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401
      -wss-username-token-profile-1.0#PasswordDigest">
      ZWR2UittVmp4YTRQWG1wOTl0ekI3bHdDNG9FPQ==
   </wsse:Password>
</wsse:UsernameToken>

SAML Assertion

Claims dialect: http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0

For obtaining the SAML authentication request to be sent to the SAML 2.0 Identity Provider, STS supports the initiation of the SAML 2.0 ECP profile. The authentication request can be obtained by sending a PAOS request to the /sts/ecp endpoint, as defined in the ECP profile specification.

An example of a SAML assertion is as follows:

<wsse:Security>
   <saml2:Assertion xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion" 
      xmlns:xs="http://www.w3.org/2001/XMLSchema"
      ID="_064090d66352b278a7cbfd95f345fec0" 
      IssueInstant="2012-10-17T10:07:47.224Z" Version="2.0">
      <saml2:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">
         https://testing/idp
      </saml2:Issuer>
      <ds:Signature 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="#_064090d66352b278a7cbfd95f345fec0">
               <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#">
                     <ec:InclusiveNamespaces 
                        xmlns:ec="http://www.w3.org/2001/10/xml-exc-c14n#" 
                        PrefixList="xs"/>
                  </ds:Transform>
               </ds:Transforms>
               <ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
               <ds:DigestValue>/C/MT8xhssw/fl8EptbB84Ry/Ug=</ds:DigestValue>
            </ds:Reference>
         </ds:SignedInfo>
         <ds:SignatureValue>value...</ds:SignatureValue>
         <ds:KeyInfo>
            <ds:X509Data>
               <ds:X509Certificate>Base64..</ds:X509Certificate>
            </ds:X509Data>
         </ds:KeyInfo>
      </ds:Signature>
      <saml2:Subject>
         <saml2:NameID 
            Format="urn:oasis:names:tc:SAML:2.0:nameid-format:transient" 
            NameQualifier="https://testing/idp">
               _059d349f24aac7dfaae74a219740d511
         </saml2:NameID>
         <saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
            <saml2:SubjectConfirmationData Address="137.138.250.61" 
               InResponseTo="f5f48f0b09a86c6dd071937a1bb6e197" 
               NotOnOrAfter="2012-10-17T09:52:47.224Z" Recipient="/soap"/>
         </saml2:SubjectConfirmation>
      </saml2:Subject>
      <saml2:Conditions 
         NotBefore="2012-10-17T10:52:47.224Z" 
         NotOnOrAfter="2012-10-17T10:55:47.224Z">
         <saml2:AudienceRestriction>
            <saml2:Audience>https://sts.example.org/saml</saml2:Audience>
        </saml2:AudienceRestriction>
      </saml2:Conditions>
      <saml2:AuthnStatement AuthnInstant="2012-08-28T07:33:47.223Z">
         <saml2:SubjectLocality Address="137.138.250.61"/>
         <saml2:AuthnContext>
            <saml2:AuthnContextClassRef>
               urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport
            </saml2:AuthnContextClassRef>
         </saml2:AuthnContext>
      </saml2:AuthnStatement>
      <saml2:AttributeStatement>
         <saml2:Attribute FriendlyName="cn" 
            Name="urn:oid:0.9.2342.19200300.100.1.1" 
            NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
            <saml2:AttributeValue 
               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
               xsi:type="xs:string">
               John Doe
            </saml2:AttributeValue>
         </saml2:Attribute>
      </saml2:AttributeStatement>
   </saml2:Assertion>
</wsse:Security>

Outgoing token formats

X.509 certificate

Token type: http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-tokenprofile-1.0#X509v3

STS can exploit the public key sent in the request to avoid transfering the private key over the network. If the public key is not sent, then a new key-pair is generated by the STS and private key is sent in the response.

The following example describes the request message containing a public key:

<wst:RequestSecurityToken wsu:Id="test0987654321"
   Context="urn:uuid:00000000-0000-0000-0000-000000000000">
   <wst:RequestType>
      http://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/Issue
   </wst:RequestType>
   <wst:TokenType>
      http://docs.oasis-open.org/wss/2004/01/oasis-200401-
      wss-x509-tokenprofile-1.0#X509v3
   </wst:TokenType>
   <wst:Claims 
      Dialect="http://docs.oasis-open.org/wss/2004/01/oasis-200401-
      wss-username-token-profile-1.0">
      <wsse:SecurityTokenReference>
         <wsse:Reference URI="#UsernameToken" />
      </wsse:SecurityTokenReference>
   </wst:Claims>
   <wst:UseKey>
      <dsig:KeyInfo xmlns:dsig="http://www.w3.org/2000/09/xmldsig#">
         <dsig:KeyValue>
            <dsig:RSAKeyValue>
               <dsig:Modulus>Base64...</dsig:Modulus>
               <dsig:Exponent>AQAB</dsig:Exponent>
            </dsig:RSAKeyValue>
         </dsig:KeyValue>
      </dsig:KeyInfo>         
   </wst:UseKey>
</wst:RequestSecurityToken>

The following example shows a response containing a reference to the certificate (included in the security headers) and its corresponding private key, which was generated by STS:

<wst:RequestSecurityTokenResponseCollection 
   xmlns:wst="http://docs.oasis-open.org/ws-sx/ws-trust/200512">
   <wst:RequestSecurityTokenResponse 
      xmlns:wst="http://docs.oasis-open.org/ws-sx/ws-trust/200512">
      <wst:RequestedSecurityToken 
         xmlns:wst="http://docs.oasis-open.org/ws-sx/ws-trust/200512">
         <wsse:SecurityTokenReference 
            xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis
            -200401-wss-wssecurity-secext-1.0.xsd">
            <wsse:Reference URI="#X509SecurityToken" 
               xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis
               -200401-wss-wssecurity-secext-1.0.xsd"/>
         </wsse:SecurityTokenReference>
      </wst:RequestedSecurityToken>
      <wst:RequestedProofToken
         xmlns:wst="http://docs.oasis-open.org/ws-sx/ws-trust/200512">
         <wst:BinarySecret 
            Type="http://docs.oasis-open.org/ws-sx/ws-trust/200512/AsymmetricKey" 
            xmlns:wst="http://docs.oasis-open.org/ws-sx/ws-trust/200512">
               base64...
            </wst:BinarySecret>
      </wst:RequestedProofToken>
   </wst:RequestSecurityTokenResponse>
</wst:RequestSecurityTokenResponseCollection>

Proxy certificate

Token type: urn:glite.org:sts:GridProxy

In addition to X.509 certificate, STS also supports issuance of the Grid proxies. For this purpose, the requestors can use the GridProxyRequest element inside the request security token message. Its schema is defined as follows:

<xs:schema targetNamespace="urn:glite.org:sts:proxy" 
   xmlns:xs="http://www.w3.org/2001/XMLSchema" 
   xmlns="urn:glite.org:sts:proxy" 
   elementFormDefault="qualified" 
   attributeFormDefault="unqualified">
   <xs:complexType name="GridProxyRequestType">
      <xs:sequence>
         <xs:element name="VomsAttributeCertificates" 
            type="VomsAttributeCertificatesType" 
            minOccurs="0" maxOccurs="1"/>
         <xs:any namespace="##other" 
            processContents="lax" minOccurs="0" maxOccurs="unbounded"/>
      </xs:sequence>
      <xs:attribute name="lifetime" type="xs:int" use="required" />
      <xs:attribute name="proxyType" type="xs:int" use="optional" />
      <xs:attribute name="delegationType" type="xs:int" use="optional" />
      <xs:attribute name="policyType" type="xs:int" use="optional" />
   </xs:complexType>
   <xs:complexType name="VomsAttributeCertificatesType">
      <xs:sequence>
         <xs:element name="FQAN" type="xs:string" 
            minOccurs="1" maxOccurs="unbounded"/>
         <xs:any namespace="##other" processContents="lax" 
            minOccurs="0" maxOccurs="unbounded"/>
      </xs:sequence>
      <xs:attribute name="ordering" type="xs:string" use="optional"/>
      <xs:attribute name="targets" type="xs:string" use="optional"/>
      <xs:attribute name="verificationType" type="xs:int" use="optional"/>
      <xs:anyAttribute namespace="##other" processContents="lax"/>
   </xs:complexType>
   <xs:element name="GridProxyRequest" type="GridProxyRequestType"/>
</xs:schema>

An example of a Grid proxy request with a desired set of VO attributes is as follows:

<wst:RequestSecurityToken wsu:Id="test0987654321" 
   Context="urn:uuid:00000000-0000-0000-0000-000000000000">
   <wst:RequestType>
      http://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/Issue
   </wst:RequestType>
   <wst:TokenType>urn:glite.org:sts:GridProxy</wst:TokenType>
   <wst:Claims 
      Dialect="http://docs.oasis-open.org/wss/2004/01/oasis-200401-
      wss-username-token-profile-1.0">
      <wsse:SecurityTokenReference>
         <wsse:Reference URI="#UsernameToken" />
      </wsse:SecurityTokenReference>
   </wst:Claims>
   <gridProxy:GridProxyRequest xmlns:gridProxy="urn:glite.org:sts:proxy" 
      lifetime="86400">
      <gridProxy:VomsAttributeCertificates>
         <gridProxy:FQAN>
            testers.eu-emi.eu:/testers.eu-emi.eu
         </gridProxy:FQAN>
      </gridProxy:VomsAttributeCertificates>      
   </gridProxy:GridProxyRequest>
</wst:RequestSecurityToken>

The following example describes a response message containing references for end-entity certificate, proxy certificate, and the private key corresponding to the proxy certificate. If public key was sent in the request message, that would be used in the proxy certificate. Private key corresponding to the end-entity certificate never leaves STS.

<wst:RequestSecurityTokenResponseCollection 
   xmlns:wst="http://docs.oasis-open.org/ws-sx/ws-trust/200512">
   <wst:RequestSecurityTokenResponse 
      xmlns:wst="http://docs.oasis-open.org/ws-sx/ws-trust/200512">
      <wst:RequestedSecurityToken 
         xmlns:wst="http://docs.oasis-open.org/ws-sx/ws-trust/200512">
         <wsse:SecurityTokenReference 
            xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis
            -200401-wss-wssecurity-secext-1.0.xsd">
            <wsse:Reference URI="#X509SecurityToken" 
               xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis
            -200401-wss-wssecurity-secext-1.0.xsd"/>
         </wsse:SecurityTokenReference>
      </wst:RequestedSecurityToken>
      <wst:RequestedSecurityToken 
         xmlns:wst="http://docs.oasis-open.org/ws-sx/ws-trust/200512">
         <wsse:SecurityTokenReference 
            xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis
            -200401-wss-wssecurity-secext-1.0.xsd">
            <wsse:Reference URI="#VOMSSecurityToken" 
               xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis
            -200401-wss-wssecurity-secext-1.0.xsd"/>
         </wsse:SecurityTokenReference>
      </wst:RequestedSecurityToken>
      <wst:RequestedProofToken 
         xmlns:wst="http://docs.oasis-open.org/ws-sx/ws-trust/200512">
         <wst:BinarySecret 
            Type="http://docs.oasis-open.org/ws-sx/ws-trust/200512/AsymmetricKey" 
            xmlns:wst="http://docs.oasis-open.org/ws-sx/ws-trust/200512">
            base64...
         </wst:BinarySecret>
      </wst:RequestedProofToken>
   </wst:RequestSecurityTokenResponse>
</wst:RequestSecurityTokenResponseCollection>