3 Monitoring OAuth Services in Service Gatekeeper

This chapter explains how to manage an Oracle Communications Services Gatekeeper implementation that uses Open Authorization Protocol v2.0 (OAuth) features.

Understanding OAuth Runtime Actions

This section describes the Services Gatekeeper runtime OAuth actions and token management, and lists the EDRs and errors that OAuth generates.

Issuing OAuth Tokens

This section explains how Services Gatekeeper manages Oauth tokens.

Default Authentication and Authorization

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

Authorization for Group URIs

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.

Understanding Token Validation

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.

Managing Tokens

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.

EDRs Generated by the OAuth Service

Table 3-1 describes the EDRs that can be generated by the OAuth service.

Table 3-1 OAuth Service EDRs

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


OAuth/Services Gatekeeper Errors and Exceptions

Table 3-2 describes the error conditions and resulting operation responses provided by the Services Gatekeeper OAuth 2.0 authorization server.

Table 3-2 Exception Scenarios

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 server_error depends on which endpoint is responding.

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"}