JBoss Security Token Service

Version 7

    This article presents the JBoss Security Token Service (JBoss STS). We start with a brief description of the WS-Trust specification. Then we present JBoss STS and discuss its overall architecture. After that we explain how to configure and deploy the service, using an example to clearify the concepts. Finally, we show a sample client application that sends WS-Trust requests to JBoss STS, describing the steps that need to be followed in order to get everything running in JDK 6.




    The WS-Trust specification defines extensions that build on WS-Security to provide a framework for requesting and issuing security tokens. Particularly, WS-Trust defines the concept of a security token service (STS), a service that can issue, cancel, renew and validate security tokens, and specifies the format of security token request and response messages.


    A security token request message specifies, among other things, the type of the request (issue, renew, etc), the type of the token, the lifetime of the token, information about the service provider that requested the token, and information used to encrypt the generated token. An example of a WS-Trust request message can be seen bellow:


    <S11:Envelope xmlns:S11=".." xmlns:wsu=".." xmlns:wst="..">
       <S11:Body wsu:Id="body">
          <wst:RequestSecurityToken Context="context">


    As we can see, the token request message is sent in the body of the SOAP message. All information related to the token request is enclosed in the RequestSecurityToken element. The sample request contains two other WS-Trust elements: RequestType, which specifies that this request is an Issue request, and TokenType, which specifies the type of the token to be issued.


    The security token response message specifies, among other things, the type of the token that has been issued, the security token itself, the lifetime of the issued token, and information that will be used by the client to decrypt the security token. An example of a token response is shown bellow:


    <wst:RequestSecurityTokenResponse Context="context" xmlns:wst=".." xmlns:wsu="..">
          <token:SpecialToken xmlns:token="...">


    The figure above shows a WS-Trust response message that contains a custom token. The TokenType element specifies the type of the issued token, while the RequestedSecurityToken element contains the token itself. The format of the token is depends on the token type. The Lifetime element specifies when the token has been created and when it will expire.

    Web Services Trust Model


    The Web service security model defined in WS-Trust is based on a process in which a Web service can require that an incoming message prove a set of claims (e.g., name, key, permission, capability, etc.). In other words, the Web service can ask for a security token that can provide proof of such claims. A client that invokes the service without providing the token may be asked to get a token from a trusted STS first. Upon getting the token from the STS, the client retries the invocation, this time sending the obtained token in the message.


    This model is illustrated in the figure below, showing that any requestor may also be a service, and that the Security Token Service is a Web service (that is, it may express policy and require security tokens itself).




    The typical message flow is as follows:

    1. The client sends a SOAP message to the Web service.
    2. The Web service has a policy that requires a token. Upon receiving the request, the service checks if it has a security token. If the token is absent, the Web service asks the client to obtain a token from a trusted STS.
    3. The client sends a security token request message to the STS in order to obtain the token.
    4. The STS examines the request and generates the requested token, sending it back to the client.
    5. The client resends the original message to the Web service, this time including the obtained token.
    6. The Web service receives the message, extracts the token and then send a validate message to the STS in order to get the token validated.
    7. The STS validates the token ands sends a validation status back to the Web service.
    8. If the token is valid, the Web service proceed with the invocation.


    It is important to note that this is the most basic scenario in terms of trust relationships. As the STS is also a Web service, it can too have a policy that requires security tokens to be presented by clients. In this case, the client may need to obtain a different token from a second STS, and this STS may in turn require a token from a third STS and so on, creating much more complex trust relationships.

    JBoss STS


    In this section we present the JBoss Security Token Service. As the name suggests, it is an implementation of the WS-Trust Security Token Service. The JBoss STS does not issue tokens of an specific type. Instead, it defines generic interfaces that allows multiple token providers to be plugged. As a result, it can be configured to deal with various types of token, as long as a token provider exists for each token type.

    Overall Architecture


    Lets take a look at JBoss STS main classes and how they work together.


    Configuring JBoss STS


    In this section we present the configuration options that are supported by JBoss STS. With the aid of an example, we show how the service can be configured in order to process token requests for different token types.


    Deploying JBoss STS


    This section describes the steps to package, secure and deploy JBoss STS.


    Sample Client Application


    In this section we show an example of a client application that invokes JBoss STS to get a custom token.