4 Using the Security Token Service

As a trusted authority service, the OpenSSO Security Token Service issues and validates security tokens. As a web services security provider, the Security Token Service secures communication between the Web Service Client and the OpenSSO STS service itself. Many enhancements have been made to the Security Token Service since OpenSSO 8.0 Update 2.

This chapter includes the following sections:

Adding a WSSAuth Authentication Module
Adding an OAMAuth Authentication Module
Generating Security Tokens

4.1 Adding a WSSAuth Authentication Module

The Web Service Security authentication module enables OpenSSO to validate a UserName with a digest password received as an authentication token and contained in a service request from the web service client to a web service provider.

4.1.1 To Add a New Web Service Security Authentication Module Instance

In the OpenSSO console, go to the Access Control tab> RealmName> Authentication subtab.
In the Module Instances section, click New.
In the New Module Instance page, In the Name field, type a name for this WSSAuth authentication module instance.
For Type, choose WSSAuth.
Click OK.
Configure the WSSAuth authentication module instance.

4.1.2 To Configure a WSSAuth Authentication Module Instance

In the OpenSSO console, go to the Access Control tab> RealmName> Authentication subtab.
In the Module Instances section, click name of the WSSAuth authentication module instance you want to configure.
Provide values for the WSSAuth Authentication Module Instance Realm attributes.

The following table provides a listing and descriptions of the attributes you can configure.

User search attribute

Specify a user attribute that to be used to search for a user. Examples: uid, cn

User realm

Specify the realm the user belongs to. For OpenSSO STS it is always root realm, indicated by a forward slash / .

User password attribute

Specify a password attribute (password equivalent) for the user. The default could be userpassword, it could as well be empoyeenumber or mail.

Authentication Level

Specify a value that indicates how much to trust an authentication mechanism. The default value is 0.

The authentication level is set separately for each method of authentication. Once a user has authenticated, this value is stored in the SSOToken for the session. When the SSOToken is presented to an application the user wants to access, the application uses the stored value to determine whether the level is sufficient to grant the user access.

If the authentication level stored in an SSOToken does not meet the minimum value required, the application can prompt the user to authenticate again through a service with a higher authentication level.

0 is a low value. For example, if the user accesses the URL protocol://openssoServer:port/opensso/UI/Loin?authlevel=0, a selection menu is displayed containing all authentication module instances with an authentication level of 0 or greater, or all authentication module instances. Similarly if the user accesses the URL protocol://openssoServer:port/opensso/UI/Loin?authlevel=50, a selection menu is displayed containing authentication module instances with an authentication level of 50 or greater. Or if only one authentication module instance meets that constraint, a login screen for that authentication module instance is displayed.

If no authentication level is specified, the SSO token stores the value specified in the Core Authentication attribute Default Authentication Level.

4.2 Adding an OAMAuth Authentication Module

The Oracle authentication module enables OpenSSO to authenticate and single sign-on an administrator, who previously authenticated to Oracle Access Manager, to OpenSSO. The administrator does not have to provide credentials to OpenSSO.

4.2.1 To Add a New Oracle Authentication Module Instance

In the OpenSSO console, go to the Access Control tab> RealmName> Authentication subtab.
In the Module Instances section, click New.
In the Name field, type a name for this Oracle authentication module instance.
For Type, choose OAMAuth.
Click OK.
Configure the OAMAuth authentication module instance.

4.2.2 To Configure an Oracle Authentication Module Instance

In the OpenSSO console, go to the Access Control tab> RealmName> Authentication subtab.
In the Module Instances section, click name of the OAMAuth authentication module instance you want to configure.
Provide values for the Oracle Authentication Module Instance Realm attributes.

The following table provides a listing and descriptions of the attributes you can configure.
Remote User HeaderName

Specify the name of the REMOTE USER HEADER that is set by the Oracle Access Manager. Example: OAM_REMOTE_USER

Allowed user values
The Current Values list displays users who are allowed to access the OpenSSO STS administration console.
- To add a user to the list, in the New Value field type a username, and then click Add.
- To remove an entry from the Current Values list, select the entry and then click Remove.
Authentication level

Specify a value that indicates how much to trust an authentication mechanism. The default value is 0.

The authentication level is set separately for each method of authentication. Once a user has authenticated, this value is stored in the SSOToken for the session. When the SSOToken is presented to an application the user wants to access, the application uses the stored value to determine whether the level is sufficient to grant the user access.

If the authentication level stored in an SSOToken does not meet the minimum value required, the application can prompt the user to authenticate again through a service with a higher authentication level.

0 is a low value. For example, if the user accesses the URL protocol://openssoServer:port/opensso/UI/Loin?authlevel=0, a selection menu is displayed containing all authentication module instances with an authentication level of 0 or greater, or all authentication module instances. Similarly if the user accesses the URL protocol://openssoServer:port/opensso/UI/Loin?authlevel=50, a selection menu is displayed containing authentication module instances with an authentication level of 50 or greater. Or if only one authentication module instance meets that constraint, a login screen for that authentication module instance is displayed.

If no authentication level is specified, the SSO token stores the value specified in the Core Authentication attribute Default Authentication Level.

4.3 Generating Security Tokens

Oracle OpenSSO Security Token Service (OpenSSO STS) establishes a trust relationship between a web service client and a web service provider, and then brokers the trust between them. The web service can trust tokens issued by just one entity instead of having to communicate with several clients. In this way, OpenSSO STS significantly reduces trustpoint management overhead.

The following sections provide instructions for determining your security token needs, and for configuring the Security Token Service to generate and validate security tokens to meet those needs.

4.3.1 Registering a Web Service Provider to OpenSSO STS

When you add a new web service provider security agent profile, the web service provider is automatically registered to OpenSSO STS. See "To Create a New Agent Profile" in the Sun OpenSSO Enterprise 8.0 Administration Guide in the following library:

http://docs.oracle.com/cd/E19681-01/index.html

Once you've registered a web service provider to OpenSSO STS, you can configure OpenSSO STS to generate web client security tokens acceptable by the web service provider.

4.3.2 Requesting a Web Service Client Security Token from OpenSSO STS

First determine what kind of security token the web service provider requires. OpenSSO STS supports Liberty Alliance Project Security Tokens and Web Services-Interoperability Basic Security Profile Security Tokens.

4.3.2.1 Using the Security Token Generation Matrix

Use the Security Token Generation Matrix to help you configure OpenSSO STS to generate a web service client security token required by the web service provider. First, in the last column titled OpenSSO STS Output Token, find a description that meets the web service provider token requirements. Then use the parameter values in the same row when you configure the Security Token Service. The "Token Generation Matrix Legend" provides information about the table headings and available options. See Section 5.2.3, "To Configure the Security Token Service" for detailed configuration instructions. For general information about Web Service Security and related terminology, see:

http://www.oracle.com/technology/tech/standards/pdf/security.pdf
http://docs.oracle.com/cd/E15523_01/web.1111/b32511/intro_security.htm#CDDHHGEE

The Security Token Generation Matrix summarizes frequently-used Security Token Service parameter settings and the types of security tokens OpenSSO STS generates based on these settings.

Table 4-1 Security Token Generation Matrix

Row	Message-Level Security Binding	Web Service Client Token	KeyType	OnBehalfOf Token	Use Key	OpenSSO STS Output Token
1	Asymmetric	X509	Bearer	Yes	No	SAML Bearer, no proof key
2	Asymmetric	Username	Bearer	Yes	No	SAML Bearer, no proof key
3	Asymmetric	X509	Bearer	No	No	SAML Bearer, no proof key
4	Asymmetric	Username	Bearer	No	No	SAML Bearer, no proof key
5	Asymmetric	X509	Symmetric	Yes	No	SAML Holder-of-Key, Symmetric proof key
6	Asymmetric	Username	Symmetric	Yes	No	SAML Holder-of-Key, Symmetric proof key
7	Asymmetric	X509	Symmetric	No	No	SAML Holder-of-Key, Symme
8	Asymmetric	Username	Symmetric	No	No	SAML Holder-of-Key, Symmetric proof key
9	Asymmetric	X509	Asymmetric	No	Web Service Client public key	SAML Holder-of-Key, Asymmetric proof key
10	Asymmetric	X509	Oracle-proprietary for SAML sender-vouches	Yes	No	SAML sender-vouches, no proof key
11	Asymmetric	Username	Oracle-proprietary for SAML sender-vouches	Yes	No	SAML sender-vouches, no proof key
12	Transport	Username	Bearer	Yes	No	SAML Bearer, no proof key
13	Transport	Username	Bearer	No	No	SAML Bearer, no proof key
14	Transport	Username	Symmetric	Yes	No	SAML Holder-of-Key, Symmetric
15	Transport	Username	Symmetric	No	No	SAML Holder-of-Key, Symmetric proof key
16	Transport	Username	Oracle-proprietary for SAML sender-vouches	Yes	No	SAML sender-vouches, no proof key
17	Asymmetric	X509	Asymmetric	No	No	SAML Holder-of-Key, Asymmetric proof key
18	Asymmetric	X509	No	No	No	SAML Holder-of-Key, Asymmetric proof key
19	Asymmetric	Username	No	No	No	SAML Holder-of-Key, Symmetric proof key
20	Transport	Username	No	No	No	SAML Holder-of-Key, Symmetric proof key