com.stormpath.sdk.oauth.RequestLocation Maven / Gradle / Ivy
/*
* Copyright 2014 Stormpath, Inc.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.stormpath.sdk.oauth;
/**
* The possible locations in an HTTP request where an OAuth 2 bearer token may be found and used for authenticating
* the request. By default, the SDK will only inspect the {@link #HEADER} and {@link #BODY} during a request; using
* request parameters for authentication is generally discouraged for security reasons. That being said, if you have a
* specific need for using request parameters, such as supporting a legacy HTTP client, you can configure the SDK to
* check the {@link #QUERY_PARAM} location as well. Example configuration below.
*
* Usage
*
* When you accept a known OAuth HTTP request, you can specify the request locations that will be checked when
* retrieving the OAuth Access Token used to authenticate the request. For example:
*
*
* import static com.stormpath.sdk.oauth.RequestLocation.*;
* ...
*
* application.authenticateOauth(httpRequest).{@link OauthRequestAuthenticator#inLocation(RequestLocation...) inLocation}(HEADER, BODY, QUERY_PARAM).execute();
*
*
*
* Again, by default, the SDK will automatically inspect the {@link #HEADER} and {@link #BODY}. You must explicitly
* add {@link #QUERY_PARAM} if you wish to use query parameters for authentication, as query parameters are generally
* not considered as secure as the other two locations.
*
*
* @since 1.0.RC
* @see OauthRequestAuthenticator#inLocation(RequestLocation...)
* @see ResourceRequestAuthenticator#inLocation(RequestLocation...)
*/
public enum RequestLocation {
/**
* Try to find the OAuth 2 bearer token in the the HTTP request's {@code Authorization} header. This is an option
* defined in the OAuth 2 Bearer Token
* specification, Section 2.1.
*/
HEADER,
/**
* Try to find the OAuth 2 bearer token in the HTTP request's {@code application/x-www-form-urlencoded} body as a
* {@code access_token} parameter. This is an option defined in the
* OAuth 2 Bearer Token specification, Section 2.2.
*/
BODY,
/**
* Try to find the OAuth 2 bearer token in an HTTP request {@code access_token} query parameter. This is an option
* defined in the OAuth 2 Bearer Token
* specification, Section 2.3.
* Unlike the {@link #HEADER} and {@link #BODY} locations, this location is NOT
* checked by default, as query parameters are generally perceived as less secure than the other two
* locations. If you wish to also inspect request query parameters for authenticating the OAuth request, this
* option must be configured explicitly, as shown in this enum's top-level JavaDoc.
*/
QUERY_PARAM
}