Table of content

• Development Guide
  • The Security Token Service API
  • The Provisioning API
    • End-users provisionning API

Development Guide

The Federation Server is in charge of solving, as much as possible, the different security interoperability issues. The Federation Server is composed by two main components:

• The Security Token Service
• The Provisioning interface
  The first one is in charge of providing security between services by issuing and validating security tokens to establish trust relationships between a Web service client and a Web service provider. The second one is used to provision and manage end-user credentials.

The Security Token Service API

The STS provides Web Service operations based on the WS-Trust reference API. This API is used by the Security filter to authenticate the end-user and to map her credential for the service provider: 

• ISSUE: This first operation is used to create a valid token for the end-user. The generation of the token is realized only if the authentication of the end-user is valid at the Federation Server.
  • Input: Some few parameters are required as input, like the TokenType (SAML, X509, etc.), the claims (data information about the end-user), LifeTime (duration of validity) and the validation domain. Some authentication information is mandatory to authenticate the end-user.
  • Output: The result of this operation is a new token generated.

• RENEW: This operation is the method used to regenerate a new authentication token with new expiration information. The result of this operation is a new generated token.
  • Input: The authentication credentials of the user are required as well as the expired token.
  • Output: The result of this operation is a new token generated.

• VALIDATE: This operation is used to validate tokens previously generated by the STS.
  • Input: The required parameter is the token to validate and the validation domain.
  • Output: The result is true or false depending on the validity of the token.

• CANCEL: This last operation is used to invalidate a token previously generated by the STS. When a token is cancelled, it cannot be renewed.
  • Input: The authentication credentials of the user are required as well as the token to cancel.
  • Output: The result of this operation is just the tag RequestedTokenCandelled, if all is OK.
    Each API user different messages formats passed during the request or the response. The two main messages are the <wst:RequestSecurityToken> and <wst:RequestSecurityTokenResponse> elements.

An example of each elements are:
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
<soap:Header>
<wsse:Security
xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
env:mustUnderstand="true">
<wsse:UsernameToken wsu:Id="UsernameToken-1">
<wsse:Username>user</wsse:Username>
<wsse:Password
Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText"
xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">password</wsse:Password>
<wsse:Nonce
EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary">JpQqP2iLrH9DbvaX0GAO9g==</wsse:Nonce>
</wsse:UsernameToken>
</wsse:Security>
<Action xmlns="http://www.w3.org/2005/08/addressing"
soap:mustUnderstand="true">http://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/Issue</Action>
<MessageID xmlns="http://www.w3.org/2005/08/addressing"
soap:mustUnderstand="true">urn:uuid:9901f17a-14c4-4dc0-a639-132b96d5fd0d</MessageID>
<To xmlns="http://www.w3.org/2005/08/addressing"
soap:mustUnderstand="true">https://gazelle.ihe.net/picketlink-sts</To>
<ReplyTo xmlns="http://www.w3.org/2005/08/addressing"
soap:mustUnderstand="true">
<Address>http://www.w3.org/2005/08/addressing/anonymous</Address>
</ReplyTo>
</soap:Header>
<soap:Body>
<wst:RequestSecurityToken
xmlns:wst="http://docs.oasis-open.org/ws-sx/ws-trust/200512">
<wst:RequestType>http://docs.oasis-open.org/ws-sx/ws-trust/200512/Issue</wst:RequestType>
<wsp:AppliesTo xmlns:wsp="http://www.w3.org/ns/ws-policy">
<wsa:EndpointReference xmlns:wsa="http://www.w3.org/2005/08/addressing">
<wsa:Address>http://testHost/HelloService</wsa:Address>
</wsa:EndpointReference>
</wsp:AppliesTo>
<wst:TokenType>http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0</wst:TokenType>
</wst:RequestSecurityToken>
</soap:Body>
</soap:Envelope>

A possible response could be:
<S:Envelope xmlns:wsu="http://.../oasis-200401-wss-wssecurity-utility-1.0.xsd"
xmlns:S="http://www.w3.org/2003/05/soap-envelope">
<S:Header>
<wsse:Security xmlns:wsse11="http://.../oasis-wss-wssecurity-secext-1.1.xsd"
xmlns:wsse="http://.../oasis-200401-wss-wssecurity-secext-1.0.xsd"
S:mustUnderstand="1">
<wsu:Timestamp>
<wsu:Created>2015-11-08T11:03:20Z</wsu:Created>
<wsu:Expires>2015-11-08T11:08:20Z</wsu:Expires>
</wsu:Timestamp>
</wsse:Security>
</S:Header>
<S:Body>
<trust:RequestSecurityTokenResponseCollection
xmlns:wst="http://schemas.xmlsoap.org/ws/2005/02/trust" xmlns:wsse="http://.../oasis-200401-wss-wssecurity-secext-1.0.xsd"
xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy" xmlns:wsa="http://www.w3.org/2005/08/addressing"
xmlns:trust="http://docs.oasis-open.org/ws-sx/ws-trust/200512">
<trust:RequestSecurityTokenResponse>
<trust:TokenType>
http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0
</trust:TokenType>
<trust:RequestedSecurityToken>
<saml:Assertion xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
ID="uuid-76a197ba-c2e8-4704-97a2-147db7619f2c" IssueInstant="2015-11-08T11:03:20Z"
Version="2.0">
...
<saml:Subject>
<saml:NameID NameQualifier="STS">user</saml:NameID>
<saml:SubjectConfirmation
Method="urn:oasis:names:tc:SAML:2.0:cm:sender-vouches" />
</saml:Subject>
...
</saml:Assertion>
</trust:RequestedSecurityToken>
<trust:RequestedAttachedReference>
<wsse:SecurityTokenReference>
<wsse:KeyIdentifier
ValueType="http://.../wss/oasis-wss-saml-token-profile-1.1#SAMLID"> uuid-76a197ba-c2e8-4704-97a2-147db7619f2c </wsse:KeyIdentifier>
</wsse:SecurityTokenReference>
</trust:RequestedAttachedReference>
...
<wsp:AppliesTo>
<wsa:EndpointReference>
<wsa:Address> http://testHost/HelloService</wsa:Address>
</wsa:EndpointReference>
</wsp:AppliesTo>
<trust:Lifetime>
<wsu:Created>2015-11-08T11:03:20.344Z</wsu:Created>
<wsu:Expires>2015-11-08T11:09:20.344Z</wsu:Expires>
</trust:Lifetime>
</trust:RequestSecurityTokenResponse>
</trust:RequestSecurityTokenResponseCollection>
</S:Body>
</S:Envelope>

The Provisioning API

A rest API is exposed for end-user provisioning. In the context of Chorevolution, this end-user API is used by the Identity Manager during the self-registration phase of the end-user . 

End-users provisionning API

All methods manipulates a JSON string representing an end-user, according to the following format

End-user Management

Access

Methods

Table of Contents

User

• post /domains/{domains}/endusers
• delete /domains/{domains}/endusers/{username}
• get /domains/{domains}/endusers/{username}
• put /domains/{domains}/endusers/{username}

Users

• get /domains/{domains}/endusers

User

post /domains/{domains}/endusers

delete /domains/{domains}/endusers/{username}

get /domains/{domains}/endusers/{username}

{
  "password" : "aeiou",
  "serviceCredentials" : {
    "default" : {
      "value" : [ {
        "value" : [ "aeiou" ],
        "key" : "aeiou"
      } ],
      "key" : "aeiou"
    }
  },
  "active" : "aeiou",
  "groups" : [ "aeiou" ],
  "attributes" : {
    "default" : {
      "value" : [ "aeiou" ],
      "key" : "aeiou"
    }
  },
  "username" : "aeiou",
  "choreographies" : [ "aeiou" ]
}

put /domains/{domains}/endusers/{username}

Users

get /domains/{domains}/endusers

[ {
  "password" : "aeiou",
  "serviceCredentials" : {
    "default" : {
      "value" : [ {
        "value" : [ "aeiou" ],
        "key" : "aeiou"
      } ],
      "key" : "aeiou"
    }
  },
  "active" : "aeiou",
  "groups" : [ "aeiou" ],
  "attributes" : {
    "default" : {
      "value" : [ "aeiou" ],
      "key" : "aeiou"
    }
  },
  "username" : "aeiou",
  "choreographies" : [ "aeiou" ]
} ]

Models

Table of Contents

1. MapItem
2. MapMap
3. MapMapItem
4. MapSet
5. MapSetItem
6. User