Working with the Security Token Service

The CA API Gateway has a Security Token Service (STS) that can issue the following types of tokens:
gateway
The
Layer7 API Gateway
has a Security Token Service (STS) that can issue the following types of tokens:
  • SAML Tokens (via the Create SAML Token assertion)
  • Security Context Tokens (via the Create Security Context Token assertion)
Issued tokens can be returned in a Request Security Token Response (RSTR) using the Build RSTR SOAP Response assertion. Security Context Tokens can be cancelled using the Cancel Security Context assertion.
The Security Token Service can be published in a policy using the Publish Internal Service Wizard.
Understanding the Security Token Service Default Policy
The following table describes the default policy that is created when you publish the Security Token Service internal policy. The comments provide additional detail to help you understand the logic behind the policy.
The default policy is intended to help you get started using the Security Token Service. Though useful, this policy may or may not satisfy your security requirements. Feel free to modify it as required to suit your needs.
Policy line
Comment
Audit Messages in Policy
Set Context Variable 'Flag_Enable_Response_Decoration' as false
The flag is used to determine if enabling or disabling the RSTR response decoration
All Assertion...
Block for any Authentication/Authorization Mechanisms (so it is customizable)
At Least One...
All Assertion...
Authentication Option #1: Credentials over Message Level
At Least One...
Require Encrypted UsernameToken Profile Credentials
Require WS-Security Signature Credentials
Require SAML Token Profile
Require WS-SecureConversation
Require Signed Timestamp
At Least One...
Require Signed Element on the SOAP1.1 body
Require Signed Element on the SOAP1.2 body
Set Context Variable 'Flag_Enable_Response_Decoration' as true
Enable the RSTR response decoration
All Assertion...
Authentication Option #2: Credentials over SSL transport
Require SSL or TLS Transport
At Least One...
Require HTTP Basic Credentials
Require WS-Security UsernameToken Profile Credentials
Require SSL or TLS Transport with Client Authentication
Set Context Variable 'Flag_Enable_Response_Decoration' as false
Disable the RSTR response decoration
Comment
Add any extra authentication assertions into the "At least one ..." folder below
At Least One...
Authenticate against Internal Identity Provider
Evaluate Request XPath
Retrieve the value of RequestType in the request message and save it into a variable ${requestType.result}
At Least One...
All Assertions...
Branch for SAML token issuance
Compare Expression: ${requestType.result} contains "/Issue"
Confirm that the request is for issuing a security token
Evaluate Request XPath
Retrieve the value of TokenType in the request message and save it into the variable ${tokenType.result}
All Assertions...
Verify the TokenType if matching one of two SAML token URIs (v1.1 and v2.0).
At Least One...
All Assertions...
Compare: ${tokenType.result} contains "SAML2.0"
Create SAML Token
Create a SAML v2.0 token and save it into the context variable ${issuedSamlAssertion}
All Assertions...
Compare: ${tokenType.result} contains "SAML1.1"
Create SAML Token
Create a SAML v1.1 token and save it into the context variable ${issuedSamlAssertion}
At Least One...
Build RSTR SOAP Response
Build an RSTR SOAP response containing the issued SAML token represented by ${issuedSamlAssertion}
Continue Processing
Handle the failure of the previous assertion; enables a SOAP fault response to be passed to the Return Template Response to Requestor assertion
All Assertions...
Branch for Security Context Token issuance (SCT)
Compare Expression: ${requestType.result} contains "/Issue"
Confirm that the request is for issuing a security token
Evaluate Request XPath
Retrieve the value of TokenType in the request message and save it into the variable ${tokenType.result}
Compare Expression: ${tokenType.result} contains "/sct"
Confirm that the request is for issuing a SCT
Create Security Context Token
Create an SCT and save it to the context variable ${sctBuilder.issuedSCT}
At Least One...
Build RSTR SOAP Response
Build an RSTR SOAP response containing the issued SCT
Continue Processing
Handle the failure of the previous assertion; enables a SOAP fault response to be passed to the Return Template Response to Requestor assertion
All Assertions...
Branch for Security Context Cancellation
Compare Expression: ${request.result} contains "/Cancel"
Confirm that the request is for cancelling an SCT
Cancel Security Context
Cancel the security context identified by the cancelTarget element
At Least One...
Build RSTR SOAP Response
Build an RSTR SOAP response containing the result of the token cancellation
Continue Processing
Handle the failure of the previous assertion; enables a SOAP fault response to be passed to the Return Template Response to Requestor assertion
All Assertions...
Branch for any other requests
Stop Processing
This stops processing if any other requests are encountered
All Assertions...
Request: Require WS-Addressing
Get the message ID, which will be passed into the assertion below
Add WS-Addressing
Add WS-Addressing into the RSTR response
Return Template Response to Requestor
Make a template response; this will be decorated in the next step and sent back to the requestor
At Least One...
Decorate the RSTR response message before sending it back to the requestor
All Assertions...
Compare Expression: ${Flag_Enable_Response_Decoration} is "true"
Check if RSTR Response Decoration is enabled or disabled
All Assertions...
Comment
Add, remove, or modify decoration requirement as needed
Response: Sign Element: Body
Sign the SOAP Body
Response: Encrypt Element: Body
Encrypt the SOAP Body
Response: Configure WS-Security Decoration
Add signed Timestamp, sign WS-Addressing, and encrypt Signature
Response: Apply WS-Security
Apply all WS-Security decoration requirements
Continue Processing
If the decoration is disabled, then continue policy processing
In the sample policy shown in the above table,
wsa:Action
is used to distinguish the request type. However note that while WS-Trust uses the same
Action URI
for different request types, WS-Secure Conversation requires different
Action URIs
for different request types. As a result, if the internal service is used in a WS-Trust context, the
Action URI
alone is insufficient for verifying a request type; further verification will be needed—for example, using
TokenType
in the RST to verify what type of token will be issued.
The WS-Trust entries shown in the tables below are for WS-Trust 1.2. Requests for Security Token Services corresponding to other versions of WS-Trust will use different URIs. These URIs are used as values in the <RequestType> element of the request. The WS-SecureConversation entries in the tables below are for WS-SecureConversation 1.2, but this version can be used in regardless of the WS-Trust version.
The following table shows action URIs for request type 'issue SAML token':
Request Type
Request to issue SAML
Action URI in WS-Trust
Action URI in WS-SecureConversation
The following table shows action URIs for request type 'issue SCT':
Request Type
Request to issue Security Context Token (SCT)
Action URI in WS-Trust
Action URI in WS-SecureConversation
The following table shows action URIs for request type 'cancel token':
Request Type
Request to cancel token
Action URI in WS-Trust
Action URI in WS-SecureConversation