This chapter explains how to manage an Oracle Communications Services Gatekeeper implementation that uses Open Authorization Protocol v2.0 (OAuth) features.
This section describes the Services Gatekeeper runtime OAuth actions and token management, and lists the EDRs and errors that OAuth generates.
This section explains how Services Gatekeeper manages Oauth tokens.
Services Gatekeeper includes an authorization JSP page to enter resource owner information and validate the scope requested by an application. This page displays the scope and resource details that a resource owner uses to issue an authorization grant to an application.
The Auth.jsp that handles the default authentication is located in oauth2_service.war at the following location:
middleware_home/ocsg_6.0/applications/wlng_at_oauth2.ear
The default Subscriber Manager treats a group owner with a group URI as a normal resource owner, so a group owner with a group URI has its own password.
When Services Gatekeeper issues an authorization grant for a given group URI as a resource owner, the token can access a resource on behalf of any of the group members.
The group owner's URI and password authorize an application to access resources that are owned by all member in the group.
You enable or disabled this feature using the groupUriEnabled Mbean property in the OauthCommonMbean.
For more information on the fields and methods of OauthCommonMbean, see the "All Classes" section of Services Gatekeeper OAM Java API Reference.
Services Gatekeeper supplies an interceptor to validate access tokens. The interceptor must be configured with a minimum index value in the interceptor chain to allow validation requests to be handled properly. By default, it is the second interceptor.
The token validation interceptor checks the following:
Whether the access token is expired.
Whether the resource owner matches the end user ID in the RESTful API request.
An exact match for a resource owner.
If token is issued for group URI, then request URI should be a member of the same group.
Whether requested resource is within the scope of a token.
If the token is a MAC type, additional checks are required for the following:
Body hash
Nonce
Mac
Custom interceptors can be developed and deployed for parameter value checking and token type checking (if MAC Type) of requests.
To manage OAuth tokens, use the JMX interfaces TokenManagementMBean which you access from an MBean browser, such as the OAM WebLogic interface or the Services Gatekeeper Platform Test Environment (PTE).
For more information on the fields and methods of TokenManagementMBean, see the "All Classes" section of Services Gatekeeper OAM Java API Reference.
Table 3-1 describes the EDRs that can be generated by the OAuth service.
EDR ID | Class | Method | Description | Additional Attributes in the EDR |
---|---|---|---|---|
20001 |
oracle.ocsg.oauth2.interceptor.OAuth2AppListener |
postStart |
Generated when the OAuth service is started. |
None |
20002 |
oracle.ocsg.oauth2.interceptor.OAuth2AppListener |
preStop |
Generated when the OAuth service is stopped. |
None |
20003 |
oracle.ocsg.oauth2.ejb.server.OAuthServiceBean |
authorize |
Generated when an authorization code is issued to an application. |
OAuth2ClientId OAuth2ResourceOwner OAuth2Scopes OAuth2AuthorizeType If the response is a code: OAuth2AuthorizationCode If the response is a token: OAuth2AccessTokenOAuth2TokenType |
20004 |
oracle.ocsg.oauth2.ejb.server.OAuthServiceBean |
applyToken |
Generated when an access token is issued to an application. |
OAuth2ClientId OAuth2ResourceOwner OAuth2GrantType OAuth2AuthorizationCode OAuth2AccessTokenOAuth2TokenType If a refresh token is generated: OAuth2RefreshToken |
20005 |
oracle.ocsg.oauth2.ejb.server.OAuthServiceBean |
refreshToken |
Generated when an application requests a refresh token. |
OAuth2ClientId OAuth2ResourceOwner OAuth2GrantType OAuth2OrignalRefreshToken OAuth2AccessTokenOAuth2TokenType If a refresh token is generated:OAuth2RefreshToken |
20006 |
oracle.ocsg.oauth2.interceptor.OAuth2Interceptor |
invoke |
Generated when an application accesses a resource with an OAuth access token. |
OAuth2ClientId OAuth2ResourceOwner OAuth2AccessToken OAuth2TokenType OAuth2ResourceClass OAuth2ResourceMethod |
Table 3-2 describes the error conditions and resulting operation responses provided by the Services Gatekeeper OAuth 2.0 authorization server.
Type | Error | Response |
---|---|---|
invalid_request |
The request is missing a required parameter, includes an invalid parameter value, or is otherwise malformed. |
HTTP/1.1 400 Bad Request Content-Type: application/json Cache-Control: no-store { "error":"invalid_request" } |
invalid_realm |
No authentication header with the default Services Gatekeeper realm |
HTTP/1.1 401 Unauthorized WWW-Authenticate: realm="default" |
invalid_grant |
The provided authorization grant (for example authorization code or resource owner credentials) is invalid, expired, revoked, and does not match the redirection URI used in the authorization request, or was issued to another client. |
HTTP/1.1 400 Bad Request Content-Type: application/json Cache-Control: no-store { "error":"invalid_grant"_ } |
invalid_client |
Client authentication failed (for example, unknown client, no client authentication included, or unsupported authentication method). The authorization server may return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported. If the client attempted to authenticate using the authorization request header field, the authorization server must respond with an HTTP 401 (Unauthorized) status code, and include the WWW-Authenticate response header field matching the authentication scheme used by the client. |
HTTP/1.1 400 Bad Request Content-Type: application/json Cache-Control: no-store { "error":"invalid_client"_ } |
unauthorized_client |
The client is not authorized to request an authorization code using this method. |
HTTP/1.1 401 Unauthorized |
unauthorized_owner |
Invalid resource owner credential in the authorization request |
HTTP/1.1 401 Unauthorized |
insufficient_scope |
Insufficient scope in the authorization request |
HTTP/1.1 403 Forbidden |
invalid_token |
Invalid resource owner's credential the authorization request |
HTTP/1.1 401 Unauthorized |
invalid_token |
Duplicated authorization code in the authorize request |
HTTP/1.1 401 Unauthorized |
insufficient_scope |
Invalid scope in the refresh token request |
HTTP/1.1 403 Forbidden |
invalid_token |
Discarded refresh token in the refresh token request |
HTTP/1.1 401 Unauthorized |
invalid_token |
No authenticate header When using MAC-type access token to access resource |
HTTP/1.1 401 Unauthorized WWW-Authenticate: MAC error="invalid_token", |
invalid_token |
Invalid MAC-type access token When accessing resource |
HTTP/1.1 401 Unauthorized WWW-Authenticate: MAC |
invalid_token |
No Authenticate header When using Bearer-type access token to access resource |
HTTP/1.1 401 Unauthorized WWW-Authenticate: error="invalid_token", |
invalid_token |
Invalid Bearer-type access token when accessing resource |
HTTP/1.1 401 Unauthorized WWW-Authenticate: error="invalid_token", |
insufficient_scope |
The request requires higher privileges (scope) than provided by the access token |
HTTP/1.1 403 Forbidden |
access denied |
The resource owner or authorization server denied the request. |
HTTP/1.1 302 Found Location: https://client.example.com/cb?error=access_denied&state=xyz |
unsupported_response_type |
The authorization server does not support obtaining an authorization code using this method. |
HTTP/1.1 302 Found Location: https://client.example.com/cb?error=unsupported_response_type |
unsupported_grant_type |
The authorization grant type is not supported by the authorization server. |
HTTP/1.1 400 Location: https://client.example.com/cb?error=unsupported_grant_type |
invalid_scope |
The requested scope is invalid, unknown, or malformed. |
HTTP/1.1 302 Found Location: https://client.example.com/cb?error=invalid_scope |
server_error |
The authorization server encountered an unexpected condition which prevented it from fulfilling the request. |
HTTP/1.1 400 error="server_error", The HTTP response code for The Authorization and Grant endpoints return 302 error responses as defined by the OAuth specification. The Services Gatekeeper Token endpoint returns a 400 error response. |
temporarily_unavailable |
The authorization server is currently unable to handle the request due to a temporary overloading or maintenance of the server. |
Not Supported |
other |
Undetermined |
HTTP/1.1 500 Content-Type: application/json Cache-Control: no-store { "error":"500"} |