Tuesday, November 15, 2011

Oracle Secure Token Services 101

In this post I want to introduce our readers to the Oracle Secure Token Service (OSTS) product, Oracle’s solution for providing standards-based mechanisms for trust brokerage across different identity domains. I won’t cover the gory details in this first post, but I expect to give you a good overview on what the product is, the typical usage scenarios and a basic understanding of its main concepts.

OSTS facilitates secure communications between web services providers and consumers. In OSTS terminology, a web service provider is a Relying Party, while a web service consumer is a Requester. It works as a central hub where web services consumers come and get security tokens that are further propagated to web services providers. In this way, it frees clients from all the necessary infrastructure to generate tokens required for identity propagation. Whenever the client needs a token, it requests one from OSTS.

It’s important to make clear that OSTS is no security PEP (Policy Enforcement Point) for web services. This is up to other products like OWSM (Oracle Web Services Manager) and OEG (Oracle Enterprise Gateway). It can actually be used with both of them. OEG, for example, can act as an OSTS client when protecting web services. OSTS is a set of services that validate incoming token requests and issue security tokens. It does, however, check whether a Requester can ask for a token to access a Relying Party, but it stops right there.

OSTS supports both WS-Security and WS-Trust as the protocols for token transport.




OSTS is delivered as an OAM (Oracle Access Manager) add-on in Oracle’s IAM 11.1.1.5. Its management console is integrated into OAM’s. OSTS runs within the OAM managed server but it is out-of-box disabled. It is enabled in OAM’s Console System Configuration tab, Common Configuration –> Available Services menu option:

OSTSEnabling

Here are the main OSTS concepts.

1 – OSTS Endpoint

OSTS public interfaces are web services that basically understand WS-Security and WS-Trust. OSTS Endpoints are the actual URLs that clients and services use to communicate with OSTS. The out-of-box end points are protected by OWSM policies, which means requesting clients must attach the required token when making the RST (Request Secure Token) request.

2 – Web Service Endpoint

This is the web service URL for which a token should be acquired. It is typically defined as Relying Party and is given a reference name that can be used in OAM’s Token Issuance Policy (see corresponding item below) in order to trigger the token issuance process.

3 – Token Issuance Policies

These define who can request tokens from OSTS for specific Relying Parties. Once you define a Relying Party in OSTS, you can define a Token Issuance Policy along with some constraints determining who is allowed or denied asking tokens for the Relying Party.

The screenshot below shows a policy saying that only identities members of the Administrators group can request a token. It is also possible to create a condition taking into account the Requester identity (which typically identifies the client application).

Notice the policy is actually defined as part of a policy domain in OAM.

TokenIssuancePolicyConstraint

OSTS reserves two special Relying Parties when a mapping can’t be resolved by the Token Issuance Policy: UnknownRP and MissingRP.

OSTS obtains the Relying Party URL from the AppliesTo WS-Addressing element in the RST. If there’s an AppliesTo element, but no mapping, UnknownRP is used. If there’s no AppliesTo element, MissingRP is used.

4 – Validation Templates

Validation templates define how OSTS processes the RST for different types of tokens in the request , by specifying rules for validating incoming client credentials as well as for token mapping. The token in the request can be mapped directly to a user in the external data store or to a partner in OSTS internal store.

OSTS also supports attribute-based mappings, where attributes in the external data store are used to identify the user. In the case of SAML validation template, it is possible to map the user based on Name Identifiers available in the incoming SAML assertion.

In “On Behalf Of” scenarios, one would typically map the incoming token in the WSS header to a partner, so that OSTS can validate credentials before issuing a token on behalf of the user specified in the WS-Trust body.

5 – Partners

Partners are entities trusted by OSTS. There are 3 of them: Requester, Relying Party and Issuance Authority.

A Requester is a client that requests a token from OSTS. There are two types of clients supported by OSTS: the web service client application or the end user. It is important to understand that the end user is NOT characterized as a Requester for OSTS, but someone that might exist in the identity store. The web service client application is the one seen as the Requester.

A Relying Party is the web service for which a token is produced by OSTS.

An Issuance Authority represents an entity capable of issuing SAML tokens. OSTS must know and trust who issues an incoming SAML assertion before issuing a token. It applies in the cases where SAML is the token in the RST.

6 – Partner Profiles

Partner Profiles set the default options for the different types of partners. These options basically define the (default) templates to be applied when validating or issuing a token and any (default) attribute mappings.

There are 3 types of profiles: Requester Profile, Relying Party Profile and Issuing Authority Profile.

The Issuing Authority profile additionally defines (default) rules for SAML data.

7 – Issuance Templates

They define the rules on how tokens are created. Each type of token has a template, which is selected by OSTS based on the RST. In the case there’s no token type in the RST, OSTS defaults to the Relying Party profile configuration. A party is always associated with a profile that defines the party defaults.

For example, among the rules for a SAML 1.1 token are: whether the token should be encrypted, the encryption algorithm, assertion issuer, Name Identifier properties, whether to include the authentication statement and authorization statement, token validity period, whether to sign the assertion, the confirmation method and any attribute name or value mappings.

8 – Cryptographic Keys and Digital Certificates

As you might expect, OSTS has a lot to deal with signing and encryption. OSTS makes use of 3 different key stores that are used in different complementary ways depending on the interaction requirements.

a) .oamkeystore: holds OSTS key-pair used for assertion signing and data decryption. Type is JCEKS. Whenever you need to export OSTS certificate, use this service URL:

http(s)://osts-hostname:osts-port/sts/servlet/samlcert?id=<TEMPLATE_ID>&encoding=<ENCODING>

where <TEMPLATE_ID> is the Template Id as defined in Security Token Service Settings. It is NOT the key alias.


OSTS_Encryption_Key
<ENCONDING> is either pem or der, pem being the default.

Example: http://localhost:14100/sts/servlet/samlcert?id=osts_encryption&encoding=der

b) amtruststore: stores trust certificates, thus used to validate parties’ certificates.

c) default-keystore.jks: stores the certificate used by the OWSM agent to enable WSS between OSTS and Requesters.

OSTS also supports CRLs( Certificate Revocation Lists), who are stored as a jar file (amcrl.jar) in the file system (${DOMAIN_HOME}/config/fmwconfig folder). A notification listener detects changes to that file and reloads it at runtime, without requiring a server restart. The file is updated through OSTS Console.


All these concepts are visible in the OSTS Console, available in OAM’s Console System Configuration tab, Security Token Services menu option, at the bottom left.

OSTSConsole

I hope this brief introduction can can give you all an overview of OSTS and makes the familiarization process easier in case diving into the product becomes necessary.

OSTS official documentation is here.

4 comments:

  1. Hi, thanks for this writeup. Unfortunately we are having problems getting STS enabled. We have 11.1.1.5. We got OAM 11G working by following instructions from the enterprise deployment guide (http://docs.oracle.com/cd/E17904_01/core.1111/e12035/toc.htm).


    Here's a thread describing the problem with enabling STS ( we also opened an SR).
    https://forums.oracle.com/forums/thread.jspa?threadID=2328654

    Sounds like this problem shows up if we don't used the embedded LDAP? We got OAM working with OVD and don't really want to go back to embedded LDAP anymore.

    ReplyDelete
  2. vamsee,

    make sure the user you're performing login with is a member of the Administrators group in the backend LDAP server. The right group name is Administrators, not Admin.

    Andre.

    ReplyDelete
  3. By the way, Admin is the WLS role name that OOTB maps to the Administrators group.

    ReplyDelete
  4. Yes, that works. Thank you very much. I didn't have to restart anything either.

    ReplyDelete

Note: Only a member of this blog may post a comment.