An authorization token contains a private part and an optional public part.

When there is no public part of the credential, the private part (the entire authorization token) may be stored either as the password component of an OPSS password credential (the user name component is ignored) or as an OPSS generic credential.

When there is a public part, the authorization token may be stored as an OPSS password credential with the public part as the user name component and the private part as the password component. The token can also be stored as an OPSS generic credential consisting of the public part followed by the private part, separated by newline (0x0A) or carriage return/newline (0x0D0A).

Here are the OPSS credentials that should be created for various types of authorization:

• Basic Authentication: Normally, a user name and password are provided programmatically or by the end-user, in which case no OPSS credentials should be created. However, in certain cases, a fixed user name and password may be appropriate. In this case, an OPSS credential (or credentials, if there are variants) may be created. The user name is the public part and the password is the private part.
• Bearer Token: OPSS credential(s) should be created with the bearer token as the private part. There is no public part.
• API Key: OPSS credential(s) should be created with the API key as the private part. There is no public part.
• OAuth2: OPSS credential(s) should be created with the client ID as the public part and the client secret (or client password) as the private part. Both the client ID and the client secret/password must be URL-encoded, using the URL-encoding semantics expected by the REST service.

For non-OAuth2 types of authorization, Oracle Forms does the URL-encoding of the authorization token. Although there may be more than one way of URL-encoding a specific authorization token, the expectation is that the REST service will produce the same result when it URL-decodes the URL-encoded value produced by Oracle Forms.

For OAuth2, RFC 6749 (The OAuth 2.0 Authorization Framework) recommends using Basic Authentication for Client Authentication, and it requires that the client ID and client password be URL-encoded before they are used to construct a Basic Authorization header. Only one of the possible URL-encodings will produce an acceptable Basic Authorization header, and Oracle Forms has no way of determining which one that is. Therefore, Oracle Forms requires the administrator (or application developer) to determine the correct URL-encoding when creating the OPSS credential.

So how should the administrator determine the correct URL-encoding? First of all, alphanumeric characters never require URL-encoding, so if the client ID and client password consist entirely of alphanumeric characters, no URL-encoding is required. In other cases, the administrator may be able contact the REST service to determine the URL-encoding the REST service is expecting. If that is not possible, trial and error may be required. Construct trial URL-encodings using the following guidelines:

• Underscore [ _ ], dot [.], hyphen [-], and tilde [~] almost never require URL-encoding.
• Bang [!], dollar sign [$], apostrophe ['], left and right parentheses [( and )], asterisk [*], comma [,], semicolon [;], colon [:], and the at sign [@] may or may not require URL-encoding.
• Other characters almost always require URL-encoding.

URL-encoding a character consists of producing its UTF-8 representation and then replacing each byte in this representation by its 3-byte percent-encoding (% followed by the upper-case hex digits for the byte), with the exception that certain REST services may expect a space to be URL-encoded as ‘+’ rather than ‘%20’.

Refer to the Forms References part of this guide for configuration settings that may be used when making REST calls from Forms. Specifically refer to Environment Variables and Web Configuration Parameters.