| Oracle® Communications Services Gatekeeper OAuth Guide Release 5.1 E37521-01 |
|
|
PDF · Mobi · ePub |
| Oracle® Communications Services Gatekeeper OAuth Guide Release 5.1 E37521-01 |
|
|
PDF · Mobi · ePub |
This chapter explains how to manage an Oracle Communications Services Gatekeeper (Services Gatekeeper) implementation that uses Open Authorization Protocol (OAuth) features.
This section describes the Services Gatekeeper runtime OAuth actions, explains 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_5.1/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.
See "Securing Resources with Multiple Owners" for more information.
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.
This section describes how to manage OAuth tokens using the JMX interfaces TokenManagementMBean, which you access from the OAM WebLogic interface or the Services Gatekeeper Platform Test Environment (PTE). See "Using the TokenMangementMBean" for more information.
Managed object: Container Services then OAuthService
MBean: oracle.ocsg.oauth2.management.TokenManagementMBean
This MBean supports these operations:
Scope: Cluster
Lists access tokens by the address of an end user.
Signature:
listAccessTokensByEndUser(String endUserId)
Table 3-1 describes these parameters.
Scope: Cluster
Lists refresh tokens by the address of an end user.
Signature:
listRefreshTokensByEndUser(String endUserId)
Table 3-2 describes these parameters.
Scope: Cluster
Lists access tokens by the client Id in addition to the address of an end user.
Signature:
listAccessTokensByClientIdAndEndUser(String clientId, String endUserId)
Table 3-3 describes these parameters.
Scope: Cluster
Lists refresh tokens by the client Id in addition to the address of an end user.
Signature:
listRefreshTokensByClientIdAndEndUser(String clientId, String endUserId)
Table 3-4 describes these parameters.
Scope: Cluster
Lists access tokens by the client Id.
Signature:
listAccessTokensByClientId(String clientId, int offset, int size)
Table 3-5 describes these parameters.
Scope: Cluster
Lists refresh tokens by the client Id.
Signature:
listRefreshTokensByClientId (String clientId, int offset, int size)
Table 3-6 describes these parameters.
Scope: Cluster
Lists the number of access tokens by client Id.
Signature:
countAccessTokensByClientId(String clientId)
Table 3-7 describes these parameters.
Scope: Cluster
Lists the number of refresh tokens by client Id.
Signature:
countRefreshTokensByClientId(String clientId)
Table 3-8 describes these parameters.
Scope: Cluster
Revokes an access token.
Signature:
revokeAccessToken(String token)
Table 3-9 describes these parameters.
Scope: Cluster
Revokes a refresh token.
Signature:
revokeRefreshToken(String token)
Table 3-10 describes these parameters.
Table 3-11 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 OAuth2ResourceOwnerOAuth2ScopesOAuth2AuthorizeType 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. |
OAuth2ClientIdOAuth2ResourceOwnerOAuth2GrantTypeOAuth2AuthorizationCodeOAuth2AccessTokenOAuth2TokenType If a refresh token is generated:OAuth2RefreshToken |
|
20005 |
oracle.ocsg.oauth2.ejb.server.OAuthServiceBean |
refreshToken |
Generated when an application requests a refresh token. |
OAuth2ClientIdOAuth2ResourceOwnerOAuth2GrantTypeOAuth2OrignalRefreshTokenOAuth2AccessTokenOAuth2TokenType 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. |
OAuth2ClientIdOAuth2ResourceOwnerOAuth2AccessTokenOAuth2TokenTypeOAuth2ResourceClassOAuth2ResourceMethod |
Table 3-12 describes the error conditions and resulting operation responses provided by the Services Gatekeeper OAuth 2.0 authorization server.
Table 3-12 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 FoundLocation: 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/jsonCache-Control: no-store{ "error":"500"}
|
|
 Copyright © 2012, 2013, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|
