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"

The trust protocol. Only the embedded protocol is supported.

No

"tokenType"

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

Yes

"username"

The user name for which the token is issued.

Yes

"tokenSigningMethod"

The 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"

The 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"

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

(SAML2 only)

Yes

"addAuthenticatingAuthorities"

A list of identity providers trusted by the requester to authenticate the presenter.

(SAML2 only)

Yes

"nameIdFormat"

Defines the 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"

The identity domain

Yes

"expirationDate"

The 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"

The 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 shows an example of 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 shows an example of 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"

The identity token.

Yes

"protocol"

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

No

"tokenType"

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

Yes

"username"

The user name for which the token is issued.

Yes

"tokenSigningMethod"

The 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"

The 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"

The user name for which the token is issued

"idd"

The identity domain

"expirationDate"

The date the token expires and can no longer be accepted for processing

"appliesTo"

The 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 shows an example of 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 shows an example of 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 shows an example of the response body in JSON format.

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