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 CA 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" | Confirm that the value of TokenType matches http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.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" | Confirm that the value of TokenType matches http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV1.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 |