Configure OAuth Providers
Introduction to OAuth
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 Apply OAuth 2.0 Policies
Which OAuth Providers does Oracle API Platform Cloud Service Support?
This release of Oracle 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 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.
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
- Create an OAuth app on the provider.
- Create an OAuth client on the provider.
Basic Steps
- Create an OAuth resource.
- Allow the client app to access the resource.
- Obtain an OAuth token.
Example Using Oracle API Platform Cloud Service
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 Apply 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 |
---|---|
|
The type of OAuth profile to use. Supported values are The |
|
The identity provider issuer. |
|
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 |
|
If set to true, audience restriction of the access token is enforced according to the items in the |
|
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 |
|
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. |
|
If |
|
The list of claims the JWT should contain within the access token. |
|
Includes the public key the gateway uses to authenticate the identity provider. Set the |
|
The public key in PEM format. Required only when |
|
The public key in X509 format. Required only when |
|
The public key in JWK format. Required only when 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. |
|
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. |
|
This element is defined to override the default scope claim name from “scope” to a customer defined scope claim name. |
|
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: |
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 elementPublicCertLocation
should be set toNONE
.<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>