Contents
OAuth is an open standard for authorization that enables client applications to access server resources on behalf of a specific Resource Owner. OAuth also enables Resource Owners (end users) to authorize limited third-party access to their server resources without sharing their credentials. For example, a Gmail user could allow LinkedIn or Flickr to have access to their list of contacts without sharing their Gmail user name and password.
The Oracle API Gateway can be used as an Authorization Server and as a Resource Server. An Authorization Server issues tokens to client applications on behalf of a Resource Owner for use in authenticating subsequent API calls to the Resource Server. The Resource Server hosts the protected resources, and can accept or respond to protected resource requests using access tokens.
![[Note]](../common_oracle/images/admon/note.png) |
Note |
|---|---|
|
This guide assumes that you are familiar with the terms and concepts described in the OAuth 2.0 Authorization Framework. |
The API Gateway uses the following definitions of basic OAuth 2.0 terms:
-
Resource Owner:
An entity capable of granting access to a protected resource. When the resource owner is a person, it is referred to as an end user.
-
Resource Server:
The server hosting the protected resources, and which is capable of accepting and responding to protected resource requests using access tokens. In this case, the API Gateway acts as a gateway implementing the Resource Server that sits in front of the protected resources.
-
Client Application:
A client application making protected requests on behalf of the resource owner and with its authorization.
-
Authorization Server:
The server issuing access tokens to the client application after successfully authenticating the Resource Owner and obtaining authorization. In this case, the API Gateway acts both as the Authorization Server and as the Resource Server.
-
Scope:
Used to control access to the Resource Owner's data when requested by a client application. You can validate the OAuth scopes in the incoming message against the scopes registered in the API Gateway. An example scope is
userinfo/readonly.
Assume that you are using a image printing website such as Canon to print some of your photos. You also have some photos on your Flickr account that you would like to print. However, you must download all these locally, and then upload them again to the printing website, which is inconvenient. You would like to be able to sign into Flickr from your Canon printing profile, and print your photos directly.
This problem can be solved using the example OAuth 2.0 Web Server flow shown in the following diagram:
Out of band, the Canon printing client application pre-registers with Flickr and obtains a client ID/secret.
The client application registers a callback URL to receive the authorization code from Flickr when you, as
Resource Owner, allow Canon to access the photos from Flickr. The printing application has also requested
access to an API named /flickr/photos, which has an OAuth scope of photos.
The steps in the diagram are described as follows:
-
You are using a mobile phone and are signed into the Canon image printing website. You click to print Flickr photos. The Canon client app redirects you to the Flickr OAuth Authorization Server. You must already have a Flickr account.
-
You log into your Flickr account, and the Flickr Authorization Server asks you "Do you want to allow the Canon printing app to access your photos?". You click Yes to authorize.
-
When successful, the printing app receives an authorization code at the callback URL that was pre-registered out of band.
Note You have not shared your Flickr username and password with the printing app. At this point, you as Resource Owner are no longer involved in the process.
-
The client app gets the authorization code, and must exchange this short-lived code for an access token. The client app sends another request to the Authorization Server, saying it has a code that proves the user has authorized it to access their photos, and now issue the access token to be sent on to the API (Resource Server). The Authorization Server verifies the authorization code and returns an access token.
-
The client app sends the access token to the API (Resource Server), and receives the photos as requested.
The API Gateway ships with the following features to support OAuth 2.0:
-
Web-based client application registration
-
Generation of authorization codes, access tokens, and refresh tokens
-
Support for the following OAuth flows:
-
Authorization Code
-
Implicit Grant
-
Resource Owner Password Credentials
-
Client Credentials
-
JWT
-
Refresh Token
-
Revoke Token
-
Token Information Service
-
SAML 2.0 Bearer Assertion
-
-
Sample client applications for all supported flows
The following diagram shows the roles of the API Gateway as an OAuth 2.0 Resource Server and Authorization Server:
An OAuth scope is a text string used to control access to protected resources. The resource
that the scope is associated with determines the meaning of the scope. For example, if a
customer_details scope is associated with a particular resource, and a client
application is associated with the customer_details scope, the client application
will have access to that resource. Client applications and resources can have multiple OAuth
scopes.
For example, in the following overview diagram:
-
Client application A can access the
customer_detailsscope. -
Client application B can access the
customer_detailsandphotosscopes. -
Client application C can access the
photosscope only.
You can configure the scopes that a client application can access in the Client Application Registry web interface. For more details, see Manage OAuth 2.0 client applications.
![[Tip]](../common_oracle/images/admon/tip.png) |
Tip |
|---|---|
|
In general, good OAuth design involves a finite number of OAuth scopes. You should decide on the set of scopes to be used in your system instead of creating too many scopes later on. |
The API Gateway supports the following authentication flows:
-
OAuth 2.0 Authorization Code Grant (Web Server):
The Web server authentication flow is used by applications that are hosted on a secure server. A critical aspect of the Web server flow is that the server must be able to protect the issued client application's secret.
-
OAuth 2.0 Implicit Grant (User-Agent):
The user-agent authentication flow is used by client applications residing in the user's device. This could be implemented in a browser using a scripting language such as JavaScript or Flash. These client applications cannot keep the client application secret confidential.
-
OAuth 2.0 Resource Owner Password Credentials:
This username-password authentication flow can be used when the client application already has the Resource Owner's credentials.
-
OAuth 2.0 Client Credentials:
This username-password flow is used when the client application needs to directly access its own resources on the Resource Server. Only the client application's credentials are used in this flow. The Resource Owner's credentials are not required.
-
OAuth 2.0 JWT:
This flow is similar to OAuth 2.0 Client Credentials. A JSON Web Token (JWT) is a JSON-based security token encoding that enables identity and security information to be shared across security domains.
-
OAuth 2.0 Refresh Token:
After the client application has been authorized for access, it can use a refresh token to get a new access token. This is only done after the consumer already has received an access token using the Authorization Code Grant or Resource Owner Password Credentials flow.
-
OAuth 2.0 Revoke Token:
A revoke token request causes the removal of the client application permissions associated with the particular token to access the end-user's protected resources.
-
OAuth 2.0 Token Information Service:
The OAuth Token Info service responds to requests for information on a specified OAuth 2.0 access token.
-
SAML 2.0 Bearer Assertion:
The OAuth 2.0 Access Token using SAML Assertion filter enables an OAuth Client to request an access token using a SAML assertion. This flow is used when a client wishes to utilize an existing trust relationship, expressed through the semantics of the SAML assertion, without a direct user approval step at the authorization server.
For more details on the API Gateway OAuth 2.0 support, see the following topics:
For more details on OAuth 2.0, see the OAuth 2.0 Authorization Framework.
