Configuring OAuth Providers

OAuth 2.0 is an authorization framework that enables an application or service to obtain limited access to a protected HTTP resource. Oracle Autonomous API Platform Cloud Service uses OAuth policy to enforce the access token to allow access to protected resources.

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 Support?

This release of Oracle Autonomous API Platform Cloud Service 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 Autonomous API Platform Cloud Service requires that the JWT token be signed per the JWS Compact Serialization format. See https://tools.ietf.org/html/rfc7515#section-3.

Configuring 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 ouath-flow.png follows
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 a subject (“sub”) 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.

Prerequisites

Basic prerequisites:
  1. Create an OAuth app on the provider.
  2. Create an OAuth client on the provider.

Basic Steps

To configure a provider, follow these basic general steps:
  1. Create an OAuth resource.
  2. Allow the client app to access the resource.
  3. Obtain an OAuth token.

Example Using Oracle Identity Cloud Service

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

  1. 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.

  2. Define scopes for the resource.


    Description of resource-server2.png follows
    Description of the illustration resource-server2.png
  3. Create a client application in Oracle Identity Cloud Service with the requisite grants.

  4. 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 client-configuration2.png follows
    Description of the illustration client-configuration2.png

Gateway Configuration

  1. Create a configuration .xml file. See The OAuth Profile XML File

  2. 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.

  3. To protect a resource API, add an OAuth policy at the start of the policy chain. See Applying OAuth 2.0 Policies

  4. 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 Autonomous 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.

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.

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.

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 Autonomous 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>