1. REST API for Oracle Platform Security Services
  2. Creating and Validating Trust Tokens

5 Creating and Validating Trust Tokens

Oracle Platform Security Services (OPSS) uses the Trust service to manage trust tokens. You can get and validate tokens using REST. Only REST clients that have permission to issue and validate tokens for users in a particular Identity Domain (IDD) are allowed to issue and validate tokens. A client must declare an IDD during registration so that privileges to the client can be granted.

For details on registration, see POST Registration Method.

Section Method Resource Path

POST Trust Service Issue Token Method

POST

/opss/v2/trustService

POST Trust Service Validate Token Method

POST

/opss/v2/trustService

POST Trust Service Issue Token Method

Use the POST method to get a trust token.

REST Request

POST opss/v2/trustService/issue

Request Body

Media types for the request or response body.

Media Types:                                                                   application/json

The request body contains the details of the create request:

Table 5-1 Trust Attributes

Attribute Description Required

"protocol"

Trust protocol. Only the embedded protocol is supported.

No

"tokenType"

Type of token. Supported token types are: SAML, SAML2, and JWT.

Yes

"username"

User name for which the token is issued.

Yes

"tokenSigningMethod"

Cryptographic algorithms to sign the contents of the JWT token. This attribute is only used with the JWT-Token type. Only PKI signing methods are supported: RS-256 (RSA using SHA-256 hash algorithm), RS-384(RSA using SHA-384 hash algorithm), and RS-512(RSA using SHA-512 hash algorithm).

(JWT-Token only)

Yes

"confirmationMethod"

Method that a relying party uses to verify the correspondence of the subject of the assertion with the party presenting the assertion. Supported confirmation methods are sender-vouches, holder-of-key, and bearer.

(SAML2 only)

Yes

"scdAddress"

Subject confirmation data address. The network address/location from which an attesting entity can present the assertion.

(SAML2 only)

Yes

"addAuthenticatingAuthorities"

List of identity providers trusted by the requester to authenticate the presenter.

(SAML2 only)

Yes

"nameIdFormat"

Name identifier formats supported by the identity provider. Name identifiers are a way for providers to communicate with each other regarding a user.

  • urn:oasis:names:tc:SAML:2.0:nameid-format:persistent

  • urn:oasis:names:tc:SAML:2.0:nameid-format:transient

  • urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

  • urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified

  • urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName

  • urn:oasis:names:tc:SAML:1.1:nameid-format:WindowsDomainQualifiedName

  • urn:oasis:names:tc:SAML:2.0:nameid-format:kerberos

  • urn:oasis:names:tc:SAML:2.0:nameid-format:entity

(SAML and SAML2 only)

No

"idd"

Identity domain.

Yes

"expirationDate"

Date the token expires and can no longer be accepted for processing. Must be in the format: yyyy-MM-dd' T'HH:mm:ss.SSSZ.

Yes

"appliesTo"

Scope (endpoint target) to which the token applies.

No

"additionalClaims"

JWT claims to add to the claim segment. This attribute is only used with the JWT-Token type.

No

cURL Example

The following example shows how to get a trust token by submitting a POST request on the REST resource using cURL.

curl -i -X POST -u username:password --data @issuetoken.json -H Content-Type:application/json https://myhost:7001/opss/v2/trustService/issue

Example of Request Body

The following example shows the request body in JSON format. 

{
    "tokenType" : "JWT",
    "username" : "john.doe",
    "tokenSigningMethod" : "RS-256",
    "idd" : "cisco",
    "expirationDate" : "2015-10-19T12:08:56.235-0700",
}

Example of Response Header

The following example shows the response header. For more about the HTTP status codes, see HTTP Status Codes for HTTP Methods. 

HTTP/1.1 201 Created

POST Trust Service Validate Token Method

Use the POST method to validate a trust token.

REST Request

POST opss/v2/trustService/validate

Request Body

Media types for the request or response body.

Media Types:                                                               application/json

The request body contains the details of the create request:

Table 5-2 Trust Attributes

Attribute Description Required

"token"

Identity token.

Yes

"protocol"

Trust protocol. Only the ws-trust protocol is supported.

No

"tokenType"

Type of token. Supported token types are: SAML, SAML2, and JWT.

Yes

"username"

User name for which the token is issued.

Yes

"tokenSigningMethod"

Cryptographic algorithms to sign the contents of the JWT token. This attribute is only used with the JWT-Token type. Only PKI signing methods are supported: RS-256 (RSA using SHA-256 hash algorithm), RS-384(RSA using SHA-384 hash algorithm), and RS-512(RSA using SHA-512 hash algorithm).

(JWT-Token only)

Yes

"confirmationMethod"

SAML method that is used to provide proof for a subject and a SAML assertion. Supported confirmation methods are sender-vouches, holder-of-key, and bearer.

(SAML2 only)

Yes

Response Body

Media types for the request or response body.

Media Types:                                                               application/json

The response body contains details about the validate operation, including:

Attribute Description

"username"

User name for which the token is issued.

"idd"

Identity domain.

"expirationDate"

Date the token expires and can no longer be accepted for processing.

"appliesTo"

Scope (endpoint target) to which the token applies.

"additionalClaims"

JWT claims to add to the claim segment. This attribute is only used with the JWT-Token type.

cURL Example

The following example shows how to import a KSS keystore by submitting a POST request on the REST resource using cURL.

curl -i -X POST -u username:password --data @validatetoken.json -H Content-Type:application/json https://myhost:7001/opss/v2/trustService/validate

Example of Request Body

The following example shows the request body in JSON format. 

{
    "token" : "eyThbGciOiJRUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzY290F2
guaW8iLCJleHAiOjEzMDA4MTszODAsIm5hbWUiOiJDfHJpcyBTWXZpbGxlamEiDCJhZG1pbi
I6dHJ1ZR0.03f329983b83f7d9a9f5fef85305880101d5e402afafa20154d094s229f7578",
    "protocol" : "ws-trust",
    "tokenType" : "JWT",
    "username" : "john.doe",
    "tokenSigningMethod" : "RS-256",
    "confirmationMethod" : "bearer"
}

Example of Response Header

The following example shows the response header. For more about the HTTP status codes, see HTTP Status Codes for HTTP Methods. 

HTTP/1.1 200 OK

Example of Response Body

The following example shows the response body in JSON format.

{
    "username" : "john.doe",
    "idd" : "cisco",
    "expirationDate" : "2015-10-19T12:08:56.235-0700",
}