Configure OAuth Providers

Introduction to OAuth

OAuth is a standard by which a client application can access secure resources without needing username and password credentials. Instead, the client application receives an access token from an OAuth provider which is then used for access to secured resources.

Roles

Resource Owner: An application or user that can grant access to a resource.
Resource Server: The API server where the resources are hosted. It can accept and respond to requests that use access tokens.
Client Application: An application that makes resource requests on behalf of the resource owner.
Authorization Server: The server that issues access tokens to the client, after the resource owner has been authenticated and authorization is obtained.

Once you have registered an application with the OAuth service, you get a unique client ID and a client secret. The client ID, which is like a username, is for public exposure. It can be included in Javascript source code or be used to create login URLs. The client secret, which is like a password, is used when an application is requesting an access token. The application must know the client secret to receive a token from the authorization server. The client secret must be kept secure.

In addition to validating tokens, access can be limited to APIs using scopes. You can also limit access per HTTP method (GET, PUT, POST, and DELETE) to specific scopes. See Applying OAuth 2.0 Policies

Which OAuth Providers does Oracle API Platform Cloud Service - Classic Support?

This release of Oracle API Platform Cloud Service - Classic can consume tokens from any OAuth provider if the format of the token is JWT, based on RFC7519.

The OAuth Policy asserts the JWT access token and validates various standard claims as defined in RFC7519. The standard claims that are validated are listed below.

“iss”: Checks that the issuer of the token is valid.
“sub”: Checks who has created the token.
“aud”: Checks for whom the token has been created.
“exp”: Checks the expiration date and time of the token.
“nbf”: Checks the effective date and time of the token, before which it is not valid.
“iat”: Checks the issue time of the token.
“jti”: Checks the unique ID of the token. This is optional.

For more information about the JWT specification, see https://tools.ietf.org/html/rfc7519#section-4.1

Oracle API Platform Cloud Service - Classic requires that the JWT token be signed per the JWS Compact Serialization format. See https://tools.ietf.org/html/rfc7515#section-3.

Configure the Provider

For any OAuth provider, you create two applications, the resource application and the client application. When you create the resource application, you add the primary audience and the scopes with which the application needs to be protected. When you create the client application, you define the various grant types, such as Resource Owner Credential, Client Credential, Authorization Code, or Implicit, then set the scopes from the Resource Server Application.

OAuth Flow

A client application is authenticated by the identity provider and receives an access token. The client application sends the token to the gateway node, which acts as an OAuth enforcer and validates the token. If the token is valid, the request is passed on to the protected resource.

Description of the illustration ouath-flow.png

OAuth Policy Enforcement

The JSON Web Token (JWT) is validated using the following:

JWT must contain an issuer (“iss”) claim.
JWT must contain an audience (“aud”) claim.
JWT must contain an issued (“iss”) and expiry (“exp”) time.
JWT should be digitally signed to ensure the integrity of the message. The expectation is that it should be signed asymetrically.
The scope should be defined in the JWT as “scope”. The scope claim is a string with scope claim values separated by spaces. If you have a customized name for the scope claim, you can use the ScopeClaimName element in the profile XML file to define it. See The OAuth Profile XML File.

Note:

A subject (“sub”) claim is optional.

Prerequisites

Basic prerequisites:

Create an OAuth app on the provider.
Create an OAuth client on the provider.

Basic Steps

To configure a provider, follow these basic general steps:

Create an OAuth resource.
Allow the client app to access the resource.
Obtain an OAuth token.

Example Using Oracle API Platform Cloud Service - Classic

If the access token is provided by Oracle Identity Cloud Service, follow these steps to protect a resource.

Create a resource server application in Oracle Identity Cloud Service with the primary audience as the endpoint of the resource server. Enter the complete API endpoint, including the load balancing URL.
Define scopes for the resource.

Description of the illustration resource-server2.png
Create a client application in Oracle Identity Cloud Service with the requisite grants.
Add scopes from the resource server application that are allowed for that particular resource. Make sure that the allowed scope that you define matches a scope defined in the application.

Description of the illustration client-configuration2.png

Gateway Configuration

Create a configuration .xml file. See The OAuth Profile XML File
Add the public key of the Oracle Identity Cloud Service instance within the configuration file and configure other mandatory claims for the Oracle Identity Cloud Service instance.

See Retrieve the Tenant's Signing Certificate in JWK Format in REST API for Oracle Identity Cloud Service to get the public key.
To protect a resource API, add an OAuth policy at the start of the policy chain. See Applying OAuth 2.0 Policies
Deploy the API.

The OAuth Profile XML File

Learn how to configure the OAuth Profile XML file. Gateway nodes use this file to authenticate access tokens clients send with requests to APIs secured by OAuth 2.0 policies.

Upload the OAuth profile to a gateway node via the updateoauthprofile gateway installer action or the Update Security Profile operation in the REST API for the Gateway Controller in Oracle API Platform Cloud Service.

Element	Description
`Name`	The type of OAuth profile to use. Supported values are `DEFAULT` and `FORGEROCK_OPENAM`. Oracle Identity Cloud Service can use the DEFAULT profile. The `FORGEROCK_OPENAM` profile is deprecated and will be removed in a future release.
`Issuer`	The identity provider issuer.
`HeaderNameIDToken`	Specify the header clients use to pass ID tokens. This is useful when your OAuth provider creates two tokens: an access token and an ID token. The `HeaderNameIDToken` is deprecated and will be removed in a future release.
`AudienceRestrictionFromConfig`	If set to `true`, audience restriction of the access token is enforced according to the items in the `Audience` element. If set to `false`, audience restriction is enforced through the URI path where the access token is consumed.
`AudienceRestrictionUsingLBR`	If set to `true`, the OAuth policy performs audience restriction validation based on the complete URL where the hostname is the load balancer URL. If set to `false`, the OAuth policy performs audience restriction validation base on the path information where the service is consumed only. It is recommended to set this flag to `true` in a production system. Note: The `AudienceRestrictionEntireUrlMatch` element must be set to true if this element is set to true.
`AudienceRestrictionEntireUrlMatch`	If this element is set to true, then the OAuth Policy performs audience restriction validation if the entire consuming URL of the API starts with the audience defined in the claimset.
`Audience`	If `AudienceRestrictionFromConfig` is `true`, the token must contain the audiences listed in this element. Separate multiple audiences with pipes ( \| ).
`MandatoryClaims`	The list of claims the JWT should contain within the access token.
`PublicCertLocation`	Includes the public key the gateway uses to authenticate the identity provider. Set the `useFormat` attribute to specify which type of key is used. `PEMFormatPubKey`, `X509FormatPubKey`, `JWKFormatPubKey`, and `NONE` are the key types supported in this release.
`PEMFormatPubKey`	The public key in PEM format. Required only when `useFormat` is set to `PEMFormatPubKey` in the `PublicCertLocation` element.
`X509FormatPubKey`	The public key in X509 format. Required only when `useFormat` is set to `X509FormatPubKey` in the `PublicCertLocation` element.
`JWKFormatPubKey`	The public key in JWK format. Required only when `useFormat` is set to `JWKFormatPubKey` in the `PublicCertLocation` element. Note: Within the `JWKFormatPublicKey` there is a `kid` attribute. This attribute is set to select the appropriate JWK for the JWK set. If this attribute is not defined, then the first JWK is used for the validation of the JWT token.
`OutOfBandVerifyAlgorithm`	This element is required to restrict JWT to have JWA to RS256 only. If a token is sent with JWA=ES256, the JWT is rejected. Set this element to RS256.
`ScopeClaimName`	This element is defined to override the default scope claim name from “scope” to a customer defined scope claim name.
`ScopeClaimDataType`	By default, scope values in JWT are space-separated. Scope claim values can also be provided as JSON structure. This element has two valid values: `SPACE_SEPARATED_VALUES` and `JSON`. By default, scope values in JWT are space-separated, so the default value is `SPACE_SEPARATED_VALUES` . If the Scope claim values has json structure, then the value of `ScopeClaimDataType` should be set to JSON..

There are three additional features to note, as described below.

Allow JWA=NONE over HTTPS channel

This feature allows JWT to be asserted without validating the signature of the JWT. To prevent Man-in-the-Middle attacks, the JWT must be sent on a secure channel only. If the JWT is not sent over a secure channel, the JWT is rejected. To allow JWT=None, the useFormat attribute of the element PublicCertLocation should be set to NONE.
```
<PublicCertLocation useFormat="NONE">
</PublicCertLocation>
```
Restrict JWA to RS256 only

This feature is required to restrict JWT to have JWA to RS256 only. If a token is sent with JWA=ES256, the JWT is rejected. To implement this feature, the OAuth Profile needs to be set the following XML element.
```
<OutOfBandVerifyAlgorithm>RS256</OutOfBandVerifyAlgorithm>
```
Within the OAuth policy, JSON web keys can be selected based on the KID (key ID) that is present in the JSON web token. If the KID is not present in the JSON web token for any reason, it is possible to set the KID as part of the OAuth profile itself. This feature can also be used to override the KID that comes as part of the JSON token.

Sample OAuth Profile

Edit this sample OAuth Profile XML file to match your OAuth implementation before uploading it to gateway nodes.

See the updateoauthprofile gateway installer action or the Update Security Profile operation in the REST API for the Gateway Controller in Oracle API Platform Cloud Service.

<OAuth2TokenLocalEnforcerConfig>
	<Name>DEFAULT</Name>
	<HeaderNameIDToken>IDToken</HeaderNameIDToken>
	<Issuer>https://identity.oraclecloud.com/</Issuer>
	<AudienceRestrictionFromConfig>true</AudienceRestrictionFromConfig>
	<Audience>http://example:8001|OAuthTestApp</Audience>
	<MandatoryClaims></MandatoryClaims>
	<!-- useFormat has 2 values  PEMFormatPubKey, X509FormatPubKey -->
	<PublicCertLocation useFormat='X509FormatPubKey'>
		<X509FormatPubKey>MIICUDCCAbmgAwIBAgIELfGcXDANBgkqhkiG9w0BAQUFADBXMRMwEQYKCZImiZPyLGQBGRYDY29tMRYwFAYKCZImiZPyLGQBGRYGb3JhY2xlMRUwEwYKCZImiZPyLGQBGRYFY2xvdWQxETAPBgNVBAMTCENsb3VkOUNBMB4XDTE1MTEyMDA5MzI0OFoXDTI1MTExNzA5MzI0OFowXzETMBEGCgmSJomT8ixkARkWA2NvbTEWMBQGCgmSJomT8ixkARkWBm9yYWNsZTEVMBMGCgmSJomT8ixkARkWBWNsb3VkMRkwFwYDVQQDDBBvcmNsTVQxMjMyMzJfaWRtMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCLVvyue+qFraxwM5LxaNLt2QH3wHn/n0+yk2jmP7mpYkz1xrKuEk2e2SCggzK8MT9jJ5VUaNlF0MwhIZ8/naxA5LPCzGEVfZ/41GPtGNADFyspqGHkdsNv+M2eCBme7MDp9L3noBtt2peqGqxSu0DHyt1wgNr6p6EXqTT4AbLdyQIDAQABoyEwHzAdBgNVHQ4EFgQU2rtogHKC0/ws2dS3Zq7s9wwMofkwDQYJKoZIhvcNAQEFBQADgYEAK1jtcbRpYFAl2Bp9X02MaA/igq3WXykizH7uQvrWgNQluf7ADbxaB7J96jaIN2GLQFxl6cbPwOvBIu7xd9a26eK6F5gq4iJKm7GeOgV5PZ4r5umvSZgA0aLOAbhZ/gwy40RauF0X+4I7JqamnV0DizM2YEDsFWKfTSvCy90ZizMwggJeMIIBx6ADAgECAgRgdcJQMA0GCSqGSIb3DQEBBQUAMFcxEzARBgoJkiaJk/IsZAEZFgNjb20xFjAUBgoJkiaJk/IsZAEZFgZvcmFjbGUxFTATBgoJkiaJk/IsZAEZFgVjbG91ZDERMA8GA1UEAxMIQ2xvdWQ5Q0EwIBcNMTUxMTE5MTIwMDQyWhgPMjExNTEwMjYxMTAwNDJaMFcxEzARBgoJkiaJk/IsZAEZFgNjb20xFjAUBgoJkiaJk/IsZAEZFgZvcmFjbGUxFTATBgoJkiaJk/IsZAEZFgVjbG91ZDERMA8GA1UEAxMIQ2xvdWQ5Q0EwgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAJeXcnReWfVIhqdedQKy+qi+tMp2NstgxHWisJ6OZf7O+KC9WzP+X+UwiQTMUzp+B4UWUEbpGNW7dv7jiyKdsgYGrnpwINl6OT4wrlKD8r2+7yQLNBsvDQjVeWmhHTqFfgqTfd/wi3MC2itft+I40O4GnSL3/VDcTSxJZMaigKizAgMBAAGjNTAzMBIGA1UdEwEB/wQIMAYBAf8CAQAwHQYDVR0OBBYEFPwqb7nQaKEVc+oSa7ohvOxIGMfXMA0GCSqGSIb3DQEBBQUAA4GBADydG93z/CGRVfUyVfD/ULT/d+RYfm3sriGgPPZlEO+idCgA6tEMcnIOFf3lP5CFAdFq6ykmFHMOf15CYvqkv7jZULiL3zMgy7OgB4I0i0WMUAAybqeiZlU90y86zd2yfAgQEM4ncUCHg+Dwf2XF0qmYK0XLF7CSb/hSEJJp4W2j</X509FormatPubKey>
	</PublicCertLocation>
</OAuth2TokenLocalEnforcerConfig>